Show HN: Graft – Claude Code の grep トークンを 42% 削減するフック
Show HN: Graft – Claude Code hooks that cut grep tokens by 42% (github.com)
要約
Graftは、Claude Codeなどのコーディングエージェントの効率を向上させるツールです。コードベースのコンテキストを理解するグラフを構築し、関連情報をより速く安価に提供することで、トークン使用量とレイテンシを削減します。ベンチマークによると、Graftは効率と正確性の両方で大幅な改善をもたらします。
全文翻訳
Trail-code(旧Graft)は、コーディングエージェントのための自己学習コンテキストレイヤーです。
Trail-codeは、Claude Code、Cursor、Codexなどのコーディングエージェントに、コードのマップと、それについてチームが学んだことを提供します。
| コードマップ(旧Graft) | 学習内容 | |
|---|---|---|
| これは何ですか? | コードのインデックス:すべての関数とその呼び出し元。これにより、エージェントは変更が何に影響するかを把握できます | あなた、エージェント、チームが学んだこと、決定したこと |
| エージェントにとって何をするのですか? | 適切なファイルに直接誘導します | あなたとチームが中断したところから作業を再開できるようにします |
| どこから来るのですか? | あなたのコード、あなたのマシンで読み取られます | あなたの会話、作業中のもの |
ツール呼び出しが46%削減、時間が60%短縮、より多くの実際の問題を解決。
| エージェント(学習なし) | Graftマップを持つエージェント | |
|---|---|---|
| ツール呼び出し、162回の実行 | ベースライン | 46%削減 |
| キャッシュされていない入力トークン、162回の実行 | ベースライン | 42%削減 |
| 時間、162回の実行 | ベースライン | 60%短縮 |
| SWE-bench Verified、50件の実際の問題 | 27件解決(54%) | 33件解決(66%) |
npm install -g @trailhq/trail-code && trail init
注
GraftはTrail-codeになりました。 GraftはGraftマップとして存続し、すべてのgraftコマンドは引き続き機能します。新しいのは学習機能です。何が変わったか
[画像: Trailなし:各タスクは、記憶を持たないエージェントで新しいセッションを開始します。エージェントは盲目的に検索し、間違ったファイルを開き、コードの配線を推測し、タスクを完了させ、コンテキストは失われます。これは、すべてのタスクとチームメンバーのエージェントで繰り返されます。Trailを使用すると、エージェントはすでにコードを把握しています:trail initはGraftマップを構築し、フックが各セッションの前にエージェントをそれにポイントし、エージェントは影響範囲を持つグラフを読み取り、正確なコンテキストを取得し、タスクを完了させ、学習を保存します。1つのグラフ、すべてのエージェント、最大4倍のトークンを節約。]
エージェントでの変更点
| Trail-codeなし | Trail-codeあり |
|---|---|
| 必要なコードを見つけるために、ファイルを次々とgrepして開く | プロンプトで適切なファイルと関数を取得する |
| 先週すでに解決したコードをチームメンバーが再度調査する | チームメンバーの学習から開始する:決定事項、除外事項、注意すべき点 |
| チームメンバーの決定を覆す(その決定を知らなかったため) | PR前にtrail checkがフラグを立て、決定者とその理由を引用する |
| マージ時にチームメンバーが同じコードを変更したことを発見する | チームメンバーのオープンブランチも同じコードを変更していること、および両者が衝突するかどうかを、コードを編集した直後に通知する |
| セッションごとに同じことを伝えられる必要がある | 事前に伝えられたことから開始する:trail initは過去のセッションで複数回伝えたことを見つける |
| 手動でCLAUDE.mdを作成・更新する | 会話から学習が保存され、読み取り可能なファイルになる |
同じモデル、より多くのタスクを解決。 SWE-bench Verified(実際のGitHubの問題、メンテナー自身のテストで採点)では、Claude Sonnet 5はGraftマップなしで50件中27件を解決しましたが、Graftマップありでは50件中33件を解決しました。トークン使用量は23%削減されました。詳細
より安価で高速。 同じエージェントで同じタスクを162回実行した結果:コストは32%低下、キャッシュされていない入力トークンは42%削減、時間は60%短縮され、正解率は同等でした。PocketBaseでは、15件の実際の問題が21%安価に、14%高速に実行されました。詳細
目次
- 仕組み
- クイックスタート
- パート1:Graftマップ、あなたのコード
- パート2:学習、あなた、エージェント、チームが知っていること
- あなたのチーム
- あなたのマシンに残るもの
- ベンチマーク · SWE-bench Verified · 人気のあるリポジトリでのテスト
- FAQ
- 参考:グラフの構築方法 · サポートされている言語 · ノードの内容 · 何がどこで実行されるか · エージェント統合 · CLI · 検索とオリエンテーション · モノレポ · 視覚化 · 開発
仕組み
Trail-codeには2つの部分があります。どちらもあなたのマシンで実行されます。
- Graftマップ:あなたのコード。
trail initはtree-sitterを使用してリポジトリを解析し、すべてのファイル、関数、およびそれらを呼び出すものをマップします。モデルやAPIキーは不要です。コードが変更されると、コミットされていない編集を含めて、自動的に更新されます。エージェントは、各プロンプトで一致するファイルと関数へのポインタを取得し、ファイルを編集した直後に何が依存しているかを確認します。 - 学習:あなた、エージェント、チームが知っていること。 セッションで何かが解決されたり、やり方を修正したりすると、エージェントはそれを学習として保存します。そのコードに関する次のセッション(あなたまたはチームメンバーのもの)は、再度掘り下げるのではなく、そこから開始します。コードに関する学習はコードと共にコミットされ、あなたに関する学習はあなたのマシンに残ります。初日、
trail initは、過去のセッションでClaudeに複数回伝えたこと、およびリポジトリのマージ済みPRでレビュー担当者が指摘したことなどから開始します。
Graftマップはエージェントにどこにあるかを伝えます。学習は、なぜそのようになっているのか、そしてどのように作業が行われるのかをエージェントに伝えます。
クイックスタート
npm install -g @trailhq/trail-code # CLIをインストール(一度だけ)
trail init # リポジトリ内で:Graftマップを構築し、.trail/を設定し、エージェントを配線します
これがセットアップのすべてです。trail initは、どのコーディングエージェントを配線するかを尋ね、コードからGraftマップを構築し、リポジトリの学習用に.trail/を作成し、Claude Codeにステータスラインとフックを追加します。また、リポジトリ内の過去のClaude Codeセッションを一度読み取り、複数回伝えたことを学習として保存します。あなたのClaude Codeがこの読み取りを約1分で行います。その後は、いつものように作業してください。デーモンもサーバーも、監視するものもありません。すべてファイルです。
セットアップをコミットして、チームメンバーも利用できるようにしてください。Graftマップ自体はgraft/にあり、node_modulesのようなローカルキャッシュであり、コミットには追加されないため、コミットから除外されます。
git add .claude .mcp.json .trail .gitignore .ignore && git commit -m "set up Trail-code"
チームメンバーのClaude Codeは、彼らが何もインストールする前に.trail/内の学習を読み取り、残りを取得する方法を一度通知します。
trail init --dry-runは、書き込むエージェントの配線を表示します。trail init --agents claudeはClaude Codeのみを配線します。
Graftから移行する場合
何も壊れません。あなたが知っているコードマップは、現在Graftマップと呼ばれており、Trail-codeの2つの部分の1つです。
| 前 | 現在 | |
|---|---|---|
| 名前 | graft | Trail-code |
| コードマップ | graft | Graftマップ(同じもの) |
| コマンド | graft | trail(graftは引き続き機能します) |
| パッケージ | @nanonets/graft | @trailhq/trail-code(古いものも引き続き機能します) |
| 学習 | なし | 新機能、パート2を参照 |
graftと@nanonets/graftはtrailと同じコードを実行し、常に表示していたものを表示します。
Graftがセットアップしたリポジトリは、自分でTrailに移行します。trailコマンドがインストールされると、各リポジトリはClaude Codeを開いたときに移行します。すぐに移行するには、リポジトリ内でtrail initを実行してください。変更をコミットして、チームメンバーも移行できるようにしてください。
パート1:Graftマップ
マップがないと、コーディングエージェントはすべてのタスクを盲目的に開始します。用語をgrepし、ファイルを開き、インポートをたどり、戻ってやり直します。1時間前にマッピングしたコードベースの画像を再構築して破棄します。その再発見は、実行のツール呼び出し、トークン、時間のほとんどを消費します。人間は一度コードベースにオンボーディングします。エージェントは毎回オンボーディングします。
Graftマップは、この理解を一度構築し、最新の状態に保ちます。
- すべてのファイル、関数、呼び出し元。 tree-sitterで解析され、シンボルと呼び出し元のマップに変換されます。決定的、モデルなし、ネットワークなし、23言語。
- 各プロンプトで適切なコード。 Claude Codeでは、フックが各プロンプトに一致するファイルと関数を追加し、エージェントがファイルを編集した直後に何が依存しているか(「ブラスト半径」)を表示します。Cursor、Codex、その他のエージェントは、MCPツールとそれらの指示ファイルを通じて同じマップを取得します。
- 常に最新。 各クエリは最初に作業ツリーをチェックします(何も移動していない場合は数十ミリ秒)、変更されたものだけを再構築するため、回答は現在のコード、コミットされていない編集を含めて記述されます。
- 読み取り可能なプレーンファイル。 エージェントが他のファイルのように開いてgrepできるリンクされたMarkdownノード。埋め込みなし、ウォームアップする必要のあるインデックスなし。
- 必要に応じた要約。
trail build --deepは、モデルプロバイダーが選択したプレーンイングリッシュの要約を、独自のキーの下に追加します。
| エージェント(学習なし) | Graftマップを持つエージェント | |
|---|---|---|
| SWE-bench Verified、50件の実際の問題 | 27件解決 | 33件解決(+12ポイント) |
| 当社のベンチマーク、162回の実行 | ベースライン | 32%低コスト、42%少ないキャッシュされていない入力トークン、60%少ない時間 |
| PocketBase、15件の実際の問題 | ベースライン | 21%安価、14%高速 |
測定方法:ベンチマーク、SWE-bench Verified、および人気のあるリポジトリでのテスト。構築方法:リファレンス。
パート2:学習
セッションが終了すると、エージェントはすべてを忘れます。来週、同じコードを再度掘り下げるか、さらに悪いことに、行われた決定を覆す可能性があります。チームメンバーのエージェントも同様です。
Trail-codeは、エージェントが作業中に解決したことを学習として保存します。次のセッションは、あなた、エージェント、チームがすでに知っていることから開始します。手動で何も書く必要はありません。
4つの種類、3つの場所
すべての学習には種類(それが何であるか)と場所(誰のためか)があります。
3つの場所:
| 場所 | 内容 | どこに保存されるか | 誰が見るか |
|---|---|---|---|
| 個人 | あなたとあなたのマシンについて:セットアップ、習慣 | ~/.trail/ | あなたのみ。コミットもアップロードもされません |
| リポジトリ | コードについて:なぜそのようになっているのか、そこで作業がどのように行われるか | リポジトリの.trail/、変更と共にコミット | リポジトリをクローンするすべての人、Trail-codeをインストールする前でも |
| チーム | チーム全体がリポジトリを横断して学んだこと | Trailワークスペース(近日公開) | あなたのチーム、チームページで |
エージェントは個人とリポジトリの間で選択します:あなた自身のセットアップに関するものは個人として保存されます(「あなたのためだけに保存」)。コードに関するものはリポジトリに入ります(「あなたのチームのために保存」)。チームの場所は、ワークスペース内のすべてのリポジトリからのリポジトリ学習を収集するため、チームはそれらをまとめて表示できます。
4つの種類:
| 種類 | 例 | 個人 | リポジトリ | チーム |
|---|---|---|---|---|
| 決定:コードがそのようになっている理由 | 「リトライを4に保つ。10は却下:1回の呼び出しが1時間以上ブロックする可能性がある。」 | ✅ | ✅ | 近日公開 |
| 設定:どのように物事を実行したいか | 「npmではなくpnpmを使用する。」エージェントを修正したときに保存され、trail initによって過去のセッションで見つけられます。 | ✅ | ✅ | 近日公開 |
| スキル:ここではジョブがどのように実行されるか | 「ページ.Rotation()でローテーションを読み取る、pdfcpuは使用しない:/Rotateをドロップする。」 | 近日公開 | 近日公開 | 近日公開 |
| ガードレール:決して起こってはならないこと | 「メインにプッシュしないでください。」コマンド実行前にチェックされます。 | 近日公開 | 近日公開 | 近日公開 |
決定か設定か?特定のコードを指しているか、そのコードが変更されたときに期限切れになるかを尋ねてください。そうであれば、それは決定です。そうでなければ、それは設定です。
1つの決定、2人のチームメンバー
実際のテスト:2人の人物、hashicorp/go-retryablehttpの2つのクローン、ヘッドレスClaude Codeセッション。
1. Anirudhはリトライ回数が4である理由を解明します。 コミットする前に、エージェントは発見したことを学習として保存し、変更と共にコミットします。
✓ あなたのチームのために保存済み · .trail/learnings/2026-10-09-keep-the-default-retry-count-at-anirudh.md
返信は📝 Committed · Kumar works in this part of the codebase, and their agents now get a 27k-token head startで終わります。
2. Kumarはプルし、同じコードについて尋ねます。 KumarのClaudeは、掘り下げる前にAnirudhの学習を読み取り、11秒で10セントでそれに基づいて回答し、回答の出所を示す行で終わります。
📝 Anirudh's learningから開始 · 約27kトークンを節約
3. Kumarはそれでもリトライ回数を10に引き上げます。 PRの前に、trail checkは変更をチームが学んだすべてと比較します。
チェック中 1つの変更されたファイル vs 1つの学習と0件のスキル
✗ client.go:51
defaultRetryMax を 4 から 10 に変更
Anirudh · Oct 9: Keep defaultRetryMax = 4: ten retries with the
default backoff can hold one Do() call for over an hour.
· 衝突 1件 · 修正するか、コミットメッセージまたはPRの説明で理由を述べてください
KumarのClaudeはコミットで上書きを説明します。
4. Anirudhは同じ定数を編集します。 Kumarのブランチはまだマージされていません。編集直後、AnirudhのClaudeはKumarの変更を読み取り、次のようなことを言います。
🔀 trail · Kumar is also changing defaultRetryMax on kumar/retry. He raises it to 10 and you're lowering it, so the two clash.
これらはサーバーを必要としません。学習は、それらが関連するコードと同じように、gitを通じて移動します。
学習はファイル
決定は.trail/learnings/にある短いMarkdownファイルであり、他の変更と同様にプルリクエストでレビューされます。
---
title: Keep the default retry count at 4
author: Anirudh
date: 2026-10-09
cost: { tokens: 27400 }
touches:
- client.go
---
## Decided
- Keep defaultRetryMax = 4: ten retries with the default backoff can hold one Do() call for over an hour.
## Tried and ruled out
- Raising the default to 10 for one customer: worst case, a single Do() call blocks for over an hour.
## Watch out
- RetryWaitMax caps each wait at 30s, not the total: the waits add up with every retry.
touchesは、次のセッションがclient.goで見つける方法です。学習は、学習が解決するために費やした時間とトークンも記録します。それが「約27kトークンを節約」の由来です:学習が解決するためにかかった時間から、読み取るコストを引いたものです。
すべてが存在する場所:
your-repo/
├── .trail/learnings/ このリポジトリのコードに関する学習(コミットしてください)
└── graft/ Graftマップ、ローカルキャッシュ(gitignored)
~/.trail/ あなたの個人的な学習、このマシンのみ
エージェントが保存する
エージェントは、これらの瞬間に学習を自動的に保存および使用します。
- 初日、以前Claudeに伝えたこと。
trail initは、リポジトリの過去のClaude Codeセッションでのあなた自身のメッセージを読み取ります。ツール出力、貼り付けられたテキスト、ヘッドレス実行は除外されます。複数回言及されたもののみを保持し、機密情報をスクラブします。 - 実際の掘り下げの後、決定。 あるターンで多くの作業が行われ、何も保存されていない場合、セッションごとに一度Claudeに学習を保存するように求められます:決定されたこと、却下されたこと、注意すべきこと。要約であり、トランスクリプトではなく、機密情報はありません。
- 修正の後、学習。 ここでのやり方を修正したり、それに関するルールを述べたりすると、エージェントはそれも保存するため、誰も再度言う必要がなくなります。
- 各タスクの前に、それに関する学習。 各セッションは、リポジトリ内のすべての作業に適用される学習から始まります。各プロンプトは、前のセッションがそのコードに残した学習を、コードの上にロードします。チームメンバーの学習は、誰のものかを示します。
- PRの前、チェック。 エージェントは、コミット、プッシュ、またはプルリクエストを開く前に
trail checkを実行するように指示されます。 - 履歴を書き換えない。 エージェントは既存の学習を編集しません。それに反する場合、コミットでその理由を述べ、新しい学習を保存します。
コマンド(必要であれば):
trail note --title "<内容>" # 学習を保存(標準入力のテキスト);--personal は ~/.trail に保存
trail check # リポジトリの学習、あなた自身の学習、スキルに対してブランチをチェック(競合があれば終了コード1)
trail team # チームが今週学んだこと、作業の重複箇所
trail status # Graftマップ、学習、保存されたトークンを1画面で表示
あなたのチーム
学習はgitを通じてチームメンバーに届きます。サーバー不要です。.trail/をコミットすれば、すべてのクローンがそれらを持つようになります。チームメンバーのプッシュされたブランチ上の学習は、マージされる前に表示され、「プッシュ済みだが未マージ」とマークされ、最初の数行のみが表示されます。
trail teamは、ターミナルで過去7日間のチームの学習と作業の重複箇所を表示します。
trail team # 今週の学習と重複箇所
近日公開:Trailワークスペース。チームがリポジトリを横断して表示するためのものです。チームページには、誰が何を学んでいるか、学習がどれくらいの頻度で再利用されたか、作業がどこで重複しているかが表示されます。
あなたのマシンに残るもの
- あなたのコード。 Graftマップはtree-sitterを使用してあなたのマシンで構築されます。モデルもネットワークも不要です。オプションの
trail build --deep要約は、選択したモデルプロバイダーに、独自のキーの下で送信されます。 - 個人的な学習。
~/.trailに保存されます。コミットもアップロードもされません。 - リポジトリの学習。 リポジトリ内のファイルで、他のファイルと同様にgitで共有されます。
- あなたの過去のセッション。
trail initは、リポジトリの過去のClaude Codeセッションでのあなた自身のメッセージを読み取ります。あなたのClaude Code自体が読み取りを行い、あなたのログインでClaude Sonnetを使用するため、あなたのメッセージはAnthropicにのみ送信され、Claudeの使用量に含まれます。Trailには何も送信されません。 - あなたのPRレビュー。
ghがインストールされてサインインしている場合、trail initはそれを使用してリポジトリの過去50件のマージ済みPRのレビューコメントを読み取ります。機密情報のように見えるものはすべて削除され、あなたのClaude Codeがそれらを同様に読み取ります。Trailには何も送信されません。 - Trailワークスペースを接続した場合。 あなたが接続するまで、Trailに学習は送信されません。接続すると、選択したリポジトリの学習がTrailに送信されます。これには、チームメンバーのプッシュされたブランチ上の学習も含まれます。また、それらを使用した各検索とチェックの記録も送信されます:検索テキスト、ファイル、およびどの学習が表示されたか。これにより、チームページで再利用回数がカウントされます。
- 匿名使用統計。 バケットと固定ラベルのみ。タイトル、テキスト、学習のパスは含まれません。TELEMETRY.mdにすべてのフィールドがリストされています。
trail telemetry disableまたはDO_NOT_TRACK=1で無効にできます。
ベンチマーク
Graftマップを読み取るエージェントは、より多くの間違いを犯すことなく、より安価で高速であるべきです。それが主張全体なので、主張するのではなく測定しました。
ハーネスは、同じエージェントループの3つのバリアントをClaude Sonnet 5で、同じファイルツールを使用して実行しました:コールド(ゼロから探索)、プッシュ(事前にtrail ask --sourceバンドル)、およびプル(trail_find_codeとtrail_file_apiツール、何も注入せず、コンテキストは要求されたときにのみ支払われます)。Opus 4.8のジャッジは、必須キーワードのフロアを使用して正解率をスコアリングしたため、高速だが間違った回答が高速で勝つことはできませんでした。コストはキャッシュを考慮しています:読み取りは約0.1倍、書き込みは1.25倍、エージェントが実際に実行する請求モデルです。
162回の実行、2つのリポジトリ(このリポジトリと実際のNode/Express認証サービス)、それぞれ3回のトライアル、タスクは単一ファイルと複数ファイルの両方の質問に分割されました。
| メトリック(タスクあたりの平均) | コールドエージェント | Graftマップを持つエージェント(プッシュ) |
|---|---|---|
| コスト(ドル) | 0.0429 | 0.0292(32%低減) |
| キャッシュされていない入力トークン | 8,070 | 4,650(42%削減) |
| ツール呼び出し | 4.2 | 2.3(46%削減) |
| レイテンシ(秒) | 39.8 | 15.8(60%短縮) |
| 正解率 | 93% | 93%(同等) |
上記のプッシュ列は、その節約のために1つのコーパスで正解率を3ポイント低下させました。プルバリアントは、どのコーパスでもコールドよりも悪い回答をすることはありませんでした。そして、より大きなものを得るためにその速度のほとんどを犠牲にしました:正解率は98%にジャンプし、コールドよりも5ポイント高く、スイープで最も強力な単一の結果でした。速度が必要な場合はプッシュ、正確さがより重要な場合はプルを使用してください。
SWE-bench Verified
上記のスイープは、当社のメカニズムを測定する当社のハーネスです。そのため、業界標準のスイープも実行しました:SWE-bench Verified、実際のレポからの実際のGitHubの問題、公式swebenchハーネスで採点されます。ジャッジモデルなし、類似性スコアなし:パッチが適用され、メンテナー自身のテストが実行され、合格したテストを壊すことなく失敗したテストを切り替えるか、そうしないかのいずれかです。
50インスタンス、両方の腕で同じモデル(Claude Sonnet 5)、同じDockerイメージ、同じターン制限。唯一の違いは、Graftマップが配線されているかどうかです。
| 正解率と効率 | コールドClaude Code | Graftマップ付きClaude Code | 改善 |
|---|---|---|---|
| 正解率 | 27 / 50 (54%) | 33 / 50 (66%) | +12ポイント |
| トークン | 142.0M | 109.4M | 23%削減 |
| コスト | $52.34 | $42.43 | 19%低減 |
| ツール呼び出し | 1,370 | 1,031 | 25%削減 |
| APIリクエスト | 2,455 | 1,875 | 24%削減 |
| 壁時計時間 | 13,094秒 | 8,922秒 | 32%短縮 |
Graftマップは、コールドClaude Codeの27件に対して50インスタンス中33件を解決し、ツール呼び出しは25%削減、トークンは23%削減、壁時計時間は32%短縮されました。すべての正解率の勝利は同じ形状をしています:ベースラインパッチは1つのファイルを変更し、その兄弟を見逃します。django-11532では、修正に必要な5つのファイルのうち1つをパッチし、以前合格していた18のテストを2回壊しました。django-16263では、4つのうち1つをパッチし、102/103をスコアしました。Graftマップは残りを発見し、django-16263ではトークンと時間の半分でそれを実行しました。
2つのハーネス、2つの主張:制御されたスイープはGraftマップがより安価で高速であると述べており、SWE-benchはそれがより正確でもあると述べています。
すべてのインスタンスでの正解率。両方の腕が解決したインスタンスでのトークン、コスト、呼び出し。これは、比較可能な比較のためです。公式SWE-bench Verifiedイメージと公式swebench 4.1.0グレーダー、ネイティブx86_64。
人気のあるリポジトリでのテスト
ベンチマークはメカニズムを測定します。実際のテストは、Graftマップがエージェントが実際に実行されているコードで実際の変更を送信するのに役立つかどうか、単に質問に答えるだけではないことです。そのため、人気のあるオープンソースリポジトリでベンチマークを実行しました:各15タスク、10件の実際の開発者からの質問に加えて、5件の実際の実装タスク(実際のマージ済みプルリクエスト、それぞれベースコミットから再実装され、メンテナーが実際に変更したファイルに対してスコアリング)。同じエージェント(Claude Opus)、同じファイルツール。唯一の違いは、Graftマップが配線されているかどうかです。
PocketBaseでは、Graftマップは15タスク全体で21%安価に、14%高速に実行され、最も難しいクロスファイル質問では2.6倍安価になりました。正解率の低下はありませんでした。実際のマージ済みPRを、メンテナーが触れたのと同じファイルに触れることで再現しました。
PocketBase(Go、約350ファイル)
| 15タスクの集計 | 標準Claude Code | Graftマップ付き |
|---|---|---|
| コスト | $13.91 | $11.02(-21%) |
| 壁時計時間 | 2,044秒 | 1,762秒(-14%) |
| 再現されたPR | 5 / 5 | 5 / 5(メンテナーと同じファイル) |
正解率の低下なしに、より安価で高速になりました。Graftマップは、メンテナーと同じファイルを触って、5つのマージ済みPRすべてを再現しました。ギャップはクロスファイル理解で最も大きくなります:「OAuth2プロバイダー間の認証はどのように機能しますか」は、$2.19から$0.84に低下しました。
質問した10件の質問
- オリエンテーション:PocketBaseのアーキテクチャマップを提供してください:主要なサブシステムと、HTTPリクエストがデータベースにどのように流れるか。
- エントリーポイントトレース:クライアントがREST API経由でレコードを作成したときの、ルートハンドラーからデータベース書き込みまでのエンドツーエンドのプロセスをトレースしてください。
- 機能の場所:まったく新しいコレクションフィールドタイプを追加したいです。どこにフックし、どの部分を変更する必要がありますか?
- バグの特定:リアルタイムサブスクリプションがしばらくするとサイレントにイベント配信を停止します。どこから探し始めますか、そしてなぜですか?
- ブラスト半径:レコード検証ロジックのシグネチャを変更した場合、何がそれに依存し、何が壊れる可能性がありますか?
- クロスファイル合成:OAuth2プロバイダー間の認証はどのように機能しますか:トークンはどこで発行、検証、保存、更新されますか?
- 拡張性:カスタムルートとレコード作成後のフックを登録するために、PocketBaseをGoフレームワークとしてどのように使用しますか?
- セキュリティ検出:ユーザー入力はどこで検証され、クエリが実行される前にコレクションAPIアクセスルールはどこで強制されますか?
- 公開API:外部アプリケーションとして、認証してからREST API経由でレコードをリストおよびフィルタリングするにはどうすればよいですか?
- テスト検証:レコードCRUD APIのテストはどこにあり、アクセスルールについて何をアサートしていますか?
再実装した5件のマージ済みPR
各PRはベースコミットにリセットされ、エージェントの差分はメンテナーが変更したファイルに対してスコアリングされました。
| PR | タイプ | 内容 | メンテナーが触れたファイル |
|---|---|---|---|
| #6744 | feat | WebPサムネイルの生成と提供 | apis/file.go, tools/filesystem/filesystem.go |
| #6947 | fix | 正規表現ランダム文字列の一様文字分布 | tools/security/random_by_regex.go |
| #6690 | refactor | x/oauth2/endpointsを使用するためのPatreon OAuth2 | tools/auth/patreon.go |
| #2726 | perf | ホットミドルウェアパスでの冗長な管理者カウントクエリを削除 | apis/middlewares.go |
| #3192 | fix | 自動マイグレーションロールバック時の以前のAPIルールを復元 | plugins/migratecmd/templates.go |
方法
PocketBaseの2つのクローンを同じコミットで用意しました。1つはgraft initで配線され、もう1つは未変更でGraftマップが含まれていないことが確認されました。各タスクはヘッドレス(claude -p、Claude Opus)で、空のMCP構成で実行されました。理解に関する質問は、回答が正しいファイルと関数を指しているかどうかで採点されました。PRタスクは、エージェントの差分がマージ済みPRが触れたのと同じファイルを触ったかどうかでスコアリングされました。すべてのトランスクリプトは、Graftマップが一方の腕で実際に使用され、もう一方から欠落していたことを確認するために監査されました。
FAQ
これはGraftですか? はい。Trail-codeはGraftの新しい名前であり、GraftはGraftマップとして内部で存続しています。コマンドはtrail、パッケージは@trailhq/trail-codeです。graftと@nanonets/graftは同じコードを実行し、常に表示していたものを表示し、機能し続けます。
CLAUDE.mdやAGENTS.mdとどう違いますか? それらは手動で作成し、手動で最新の状態に保ち、エージェントはそれらをスキップできます。Trail-codeは会話から学習を保存し、作業中のコードに関するもののみをインポートし、PR前にそれらに対して変更をチェックし、コードマップを提供します。指示ファイルと並行して機能します:trail initはあなたのCLAUDE.mdに触れることはありません。
コンテキストウィンドウを埋めますか? いいえ。各プロンプトには、一致するコードへのポインタと、それに一致する学習のみが含まれ、チームメンバーの未マージの学習は最初の数行のみが表示されます。当社のベンチマークでは、キャッシュされていない入力トークンは42%減少しました。
APIキーは必要ですか? いいえ。Graftマップ、フック、学習、trail checkはすべてAPIキーなしで機能します。キーはtrail build --deepからの書き込み要約を追加するだけです。
サインインする必要がありますか? いいえ。上記のすべてはあなたのマシンで機能し、学習はgitを通じてチームに届きます。近日公開されるTrailワークスペースは、リポジトリを横断するチームページ専用です。
どのエージェントで動作しますか? Claude Codeは最も深いセットアップ(フック、ステータスライン、各プロンプトでの学習、および多くの掘り下げ後の保存要求)を取得します。Trail-codeは、Cursor、Codex、その他のAGENTS.mdリーダー、Gemini CLI、GitHub Copilot、Windsurf、Kiro、Antigravity、Grok、Hermes、AdaLも配線し、MCPを話すすべてのアージェントにサービスを提供します。
間違ったことを学習したらどうなりますか? リポジトリの学習はプルリクエスト内のファイルであり、それが関連するコードと同様にレビューされます。ファイルを削除または編集してドロップしてください。個人的な学習は~/.trail内のファイルであり、変更は簡単です。
モノレポで動作しますか? はい:多くのパッケージ、サブモジュール、および個別のリポジトリのフォルダを持つ1つのリポジトリ。モノレポを参照してください(Monorepos)。
費用はいくらですか? CLIはMITライセンスの下で無料かつオープンソースです。
グラフの構築方法
Graftマップはレイヤーで構築されます。ティア1はtree-sitterです:すべてのシンボルと呼び出しエッジ、モデルなし、キーなし。trail build --deepは、2つの言語モデルパスを上に加えます。
- 各ファイルを読み取る。 各ソースファイルは、それが何をするかの短い説明に一度要約されます。
- ノードにグループ化する。 これらの要約は、ノード(サブシステム、キーファイル、概念)のキュレーションされたセットにグループ化され、それらの間に型付きリンクが作成されます。Graftマップは、ファイルごとに1つのノードを作成するのではなく、適切な詳細レベルを選択するため、大きなリポジトリは数十個の読み取り可能なノードになります。
flowchart LR
S[Source files] --> T["ティア1:tree-sitter<br/>モデルなし、キーなし"]
S --> P1["パス1:LLMが要約<br/>各ファイル(--deep)"]
T --> W["graft/.graph/wiring.json<br/>シンボルごとのコードグラフ"]
P1 --> P2["パス2:ノードにグループ化<br/>+ 型付きリンク"]
P2 --> N["graft/*.md<br/>Markdownノードグラフ"]
ロード
各パスはコンテンツハッシュでキャッシュされます(LLMパスとtree-sitter解析の両方)。再実行は変更されたファイルのみを対象とするため、2回目のビルドは高速かつ安価です(このリポジトリでは312ファイル:コールドで約5秒、1つのファイルが編集された後または何も変更されていない場合は約0.6秒)。trail build --no-reuseは、コールド再解析を強制します。
その安価さが、すべてのクエリが回答前にグラフを更新することを可能にしています。取得呼び出しは、ツリーを最後のビルドのフィンガープリント(このリポジトリでは約50ms)に対して統計し、何も移動しなかった場合は再構築します。したがって、ask/grep/callers/skeleton/mapは、コミットされていない編集を含め、現在のコードを記述します。コミットされていない、ステージされていない、またはステージされているすべてがGraftマップにとって同じように見えます。Gitは表示されるファイルセットを決定します。鮮度チェックは、コミットまたはインデックスの状態ではなく、作業ツリーのバイトを比較します。更新は構造的で$0です。LLMを呼び出すことはありません。コマンドごと--no-refresh、またはすべてGRAFT_NO_REFRESH=1で無効にできます。
Markdownグラフと並行して、trail buildはgraft/.graph/wiring.json(シンボルごとのコードグラフ)と、ソースツリーをミラーリングするシンボルごとの配線カードを構築します。ティア1は純粋なtree-sitter(すべての関数、クラス、呼び出しエッジ。決定的、モデルなし、ネットワークなし)であり、プレーンなtrail buildがキーを必要としない理由です。--deepパスは、シンボルごとに1行の要約とcruxの抜粋を追加し、ボディハッシュでキャッシュされます。
サポートされている言語
Graftマップはtree-sitterを使用して2つの忠実度レベルで解析され、さらにオプションのコンパイラグレードレイヤーが追加されます。すべて$0で決定的です(モデルなし、キーなし)。
-
フルフィデリティ:スコープ認識、クロスファイル呼び出しおよびインポート解決を備えた手書き抽出器:TypeScript / JavaScript(JSXおよびTSXを含む)、Python、Go、Java、Kotlin、PHP、Swift(クラス、構造体、列挙型、アクター、プロトコル。拡張メンバーは拡張タイプにアタッチされます)、R(
.R/.r:プレーン関数、S3/S4/R6クラスとメソッド、roxygen@export、library()/source()インポート)、およびVueシングルファイルコンポーネント(それらの<script>ブロックはTypeScript抽出器を介して処理されます)。 -
広範:シンボル(関数、クラス、メソッド、タイプなど)と、汎用tree-sitter抽出器による名前解決された呼び出しエッジ。言語ごとに1つのグラマー:Rust、C、C++、C#、Ruby、Scala、Elixir、Solidity、Dart、Clojure、Nix、Lua、およびOCaml、Zig(シンボルのみ、現時点では呼び出しエッジなし)。
-
コンパイラグレードのエッジ(オプトイン):
trail build --lspは、言語サーバーがPATH上にある場合に正確なlsp_resolved呼び出しエッジ(静的パスが型付けできないメンバー呼び出し)を追加します。インストールされている最初のサーバーを使用します。順序は次のとおりです。1つのサーバーがビルドごとに:rust-analyzer(Rust)、clangd(C/C++)、gopls(Go)、pyright(Python)、typescript-language-server(TS/JS)。これはベストエフォートです。サーバーがインストールされていない場合、グラフは変更されません。
23言語、およびVueシングルファイルコンポーネント。リストされていない言語のファイルはスキップされ、インデックス化されません。広範ティア言語の追加は小さな貢献です。現在のセットを追加した人々については、CREDITS.mdを参照してください。
ノードの内容
ノードは単一のMarkdownファイルです。ほとんどのコードマップはアドレスで停止します:このものはそのファイル、その行にあります。それはエージェントにどこを見るかを伝えますが、何を見つけるかは伝えないため、エージェントはソースを開いて読む必要があります。Graftマップノードは、意味をインラインで保持するため、エージェントは事前に必要なものを学習し、ファイルを開くのはもっと知りたいときだけです。
各ノードには以下が含まれます。
| 部分 | 内容 |
|---|---|
| 要約 | コードが何をするかのプレーンイングリッシュの説明。モデルによって作成され、キャッシュされます。コードが文書化されているかどうかにかかわらず存在し、ソースが変更されると再生成されます。 |
| Crux | ロジックを実行する実際のコードの数行:ガード、スキップ条件、状態変更。ソースから直接抽出され、インラインで保存されるため、エージェントは何をするかだけでなく、どのように動作するかを確認できます。 |
| ソース | ノードが構築された正確なファイル。各ファイルはコンテンツハッシュで追跡されるため、Graftマップはノードがいつ古くなったかを正確に判断できます。 |
| リンク | 他のノードへの型付き接続(depends_on、part_of、uses、implements、produces)。[[ウィキリンク]]として記述され、エージェントがフォローできます。 |
| あなたのテキスト | 生成されたブロックの下にあなたが書いたもの。再生成後も保持されるため、独自のコンテキストが上書きされることはありません。 |
これは1つのファイルに3つの深さがあります:要約はコードが何をするかを述べ、cruxはどのようにを示すか、そしてソースはエージェントが必要とする場合に他のものを示します。プレーンインデックスは、1つのことを学ぶためにファイル全体を読ませます。Graftマップノードは、インラインで回答を提供し、フォローアップの読み取りはしばしば発生しません。
cruxは、意図的に行範囲ではなく、コード自体として保存されます。行番号は、上の無関係なコードがシフトするたびにずれますが、重要な行は移動しません。テキストを保持し、番号を保持しないということは、cruxが周囲のファイルが移動しても正しいままであることを意味します。
要約、ソース、リンク、およびあなたのテキストは、現在Markdownノードで提供されます。cruxはシンボルごとにコードグラフ(trail build --deep)で保存されます。それをMarkdownノードにインライン化することが次です。
何がどこで実行されるか
- あなたのマシンで、キーなし、ネットワークなし: 構造的なコードグラフ。
trail build(配線グラフ+シンボルごとのカード)、trail build --check、trail ask、学習、およびtrail checkは決定的です。モデルを呼び出すことはありません。 - あなたのプロバイダーキーを通じて: LLMで書かれた部分。
trail build --deepは、コンセプトノード(ファイル要約+ノード合成)とシンボルごとの要約/cruxを追加します。Graftマップはベンダーニュートラルです:GRAFT_PROVIDER(任意のOpenAI互換エンドポイントの場合はopenai、ネイティブAPIの場合はanthropic、またはOpenAI互換形式を話すゲートウェイの場合はlitellm/orcarouter)、GRAFT_API_KEY、GRAFT_MODEL、およびopenaiワイヤフォーマットの場合はGRAFT_BASE_URLを設定して、OpenRouter、Fireworks、Groq、ローカルサーバー、またはOpenAI自体を指します。または、コマンドラインで--provider/--model/--api-key/--base-urlを渡します。(OPENROUTER_API_KEYは非推奨のフォールバックとして、ORCAROUTER_API_KEYは2番目のフォールバックとして引き続き機能します)。 - Trailを通じて、ワークスペースを接続した場合のみ: 選択したリポジトリの学習、およびそれらを使用した検索とチェック。[What stays on your machine](https://github.com/trailhq/Trail-Code#what-stays-on-your-machine)を参照してください。
- 匿名使用統計: 毎日1回のnpmバージョンチェックと1回のバッチ処理された使用状況のping。pingはバケットと固定ラベルのみを運びます。コード、ファイルパス、リポジトリ名、シンボル、クエリ、学習、またはエラーメッセージは決して含まれません。TELEMETRY.mdは完全なリストであり、
trail telemetry debugはあなたのマシンが送信するものを正確に表示します。trail telemetry disable、DO_NOT_TRACK=1、またはtrail initのボックスをチェックしないことで無効にできます。CIおよびソースからのビルドでは無効になっています。
設定はGRAFT_名を保持します。完全なリストについては、.env.exampleを参照してください(モデル、ベースURL、グラフディレクトリ)。
エージェント統合
1つのコマンドで、使用しているコーディングエージェントにTrail-codeを配線します。
npm install -g @trailhq/trail-code && trail init
# エージェントを検出し、各エージェントのネイティブ指示ファイルを書き込みます。
# Claude Codeはさらに、ライブステータスライン+以下のフックを取得します
ターミナルで、initは認識しているすべてのエージェントを表示し、検出されたエージェント(設定ディレクトリ経由)にフラグを立て、各エージェントが書き込む正確なファイルを表示し、選択したエージェントのみを配線します。Claude Codeは事前に選択されています。それ以外は何も選択されていません。選択されたエージェントは、共有指示ファイル(Codex、OpenCode、およびそれを読み取るその他のCLIの場合はAGENTS.md、GEMINI.md、.github/copilot-instructions.md)にマーカーで囲まれたTrail-codeセクションを取得するか、それらを使用するエージェントの場合は完全に所有するルールまたはスキルファイル(例:.claude/skills/trail/SKILL.mdおよび.cursor/rules/trail.mdc)を取得します。Claude Codeは後者のグループに属します:initは独自のスキルファイルを書き込み、あなたのCLAUDE.mdには触れません。再実行はTrail-code自身のセクションのみを更新し(または所有ファイルを置き換え)、残りのコンテンツには触れません。
TTYがない場合(CI、Dockerfile、パイプされたシェル)、initは何も書き込まず、代わりに実行するコマンドを表示します。スクリプト実行を明示的に行うには、--agents <ids>または--yesを渡します。
| フラグ | 効果 |
|---|---|
--agents <ids...> | これらのみを配線、プロンプトなし。ID:agents, adal, cursor, gemini, grok, hermes, antigravity, copilot, kiro, windsurf, claude |
--yes, -y | プロンプトをスキップし、検出されたすべてのエージェントを配線 |
--dry-run | initが書き込むエージェントの配線を表示してから終了 |
--all-agents | 検出されたかどうかにかかわらず、すべての既知のエージェントの指示ファイルを書き込む |
--no-agents | Claude Code配線のみ。他のエージェントはスキップ |
--list-agents | 既知のエージェントIDを表示して終了 |
--no-mcp | Claude Code以外のエージェントのMCP登録をスキップ |
--no-hooks | Claude Code以外のエージェントのフックインストールをスキップ |
--no-statusline | Claude CodeのstatusLineの書き込みをスキップ(GRAFT_NO_STATUSLINE=1と同じ) |
--no-global | このリポジトリ外への書き込みをスキップ(~/.codex/のエントリの下) |
リポジトリ外への書き込み
一部のエージェントはユーザーレベルのファイルも取得するため、配線はワークツリーやリポジトリファイルが届かないフォルダにも追従します。
| エージェント | パス | 変更内容 |
|---|---|---|
| Claude Code | ~/.claude/settings.json | SessionStart, UserPromptSubmit, PostToolUseおよびStopフック |
| Claude Code | ~/.claude/helpers/graft-hooks.cjs | それらを呼び出すフックシム |
| Claude Code | ~/.claude.json | trail MCPサーバー |
Codex (agents)、~/.codex/が存在する場合 | ~/.codex/config.toml | trail MCPサーバー |
| Codex | ~/.codex/hooks.json | 同じ4つのフックイベント、編集後の`apply_patch |
| Codex | ~/.codex/hooks/graft/graft-hooks.cjs | フックシム |
| Antigravity | ~/.gemini/config/mcp_config.json | trail MCPサーバー |
| Antigravity | ~/.gemini/skills/trail/SKILL.md | そのスキルファイル |
これらは、このリポジトリだけでなく、そのエージェントで開くすべてのリポジトリに適用されます。ピッカーはそれらをmachine-wideとラベル付けし、--dry-runはそれらを独自のセクションにリストし、--no-globalはリポジトリ固有のファイルを配線したまま、それらすべてをスキップします。
MCPサーバー
trail initは、Trail-code MCPサーバーをエージェントがサポートするエージェントに登録するため、これらの6つのツールはネイティブに表示され、シェルは不要です。Claude Codeもこれを受け取ります:trail initはサーバーをプロジェクトの.mcp.jsonに書き込みます(ロードするにはClaude Codeを再起動してください)。手動でtrail mcp [dir]で実行します。
| ツール | 受け取るもの | 用途 |
|---|---|---|
trail_find_code | 質問 | ファイル:行、インラインソースでランク付けされたノード。通常は完全な回答で、フォローアップの読み取りは不要です。 |
trail_file_api | ファイルパス | そのファイル内のすべてのシグネチャ、ボディなし:トークンの約1/10のAPIサーフェス。 |
trail_trace_calls | シンボル | それに依存するもの、またはそれが依存するもの(direction: out、Nレベルまでブラスト半径用)。 |
trail_find_all | 正規表現 | すべてのヒット、囲むシンボルごとにグループ化され、そのシンボルがどれだけ結合されているかでランク付けされます。 |
trail_repo_map | なし | 未知のリポジトリの最初の概要:ディレクトリクラスター、ハブ、ホットスポット。 |
trail_check_freshness | なし | ローカルグラフがコードから逸脱したかどうか。 |
同じサーバーは、古いgraft_*ツール名にも応答します。エージェントが明示的に必要とする場合は、手動で登録してください。
{ "mcpServers": { "trail": { "command": "npx", "args": ["-y", "@trailhq/trail-code", "mcp"] } } }
Codexのようなユーザーレベルのhooks.jsonをサポートするCLIエージェントの場合、initはTrail-codeのフックもそこにインストールします:セッション開始、各プロンプトでのコンテキスト、編集後のブラスト半径と$0グラフの再同期、およびターン終了時の同期(--no-hooksでスキップ)。
Claude Code(ディープ統合)
Claude Codeが選択されている場合(デフォルトで選択されています)、スキルファイル以上のものが提供されます。それ以降、リポジトリで開かれたすべてのClaude Codeセッションは以下を受け取ります。
- ライブステータスライン:Graftマップのサイズ、リポジトリの学習数、コードが進んだときに
⚠ N stale警告が表示されます。 - 自動同期:各クエリは最初にグラフを最新の状態に更新するため、回答は常に現在のコード(コミットされていない編集を含む)を記述します。クエリは読み取ったものだけを更新します。
graft/下のMarkdownは、コードに触れたターンの終了時のバックグラウンド再構築によって更新されます。どちらも構造的で$0です。自動同期は、それ自体でLLMを呼び出すことはありません。 - オンデマンドコンテキスト:各プロンプトは、一致するノードとコードに残された学習をロードします。ファイルを編集すると、依存関係(「ブラスト半径」)が表示されます。新しいセッションは、リポジトリマップと学習数で開始されます。
- 学習を保存する要求:何も保存されていない多くの掘り下げターンの後、セッションごとに一度Claudeに学習を保存するように求められます。
- チームメンバーとの重複:セッション開始時、および数分ごとに、チームメンバーのオープンブランチが変更した内容を読み取ります。すでにマージまたはクローズされたものはスキップします。Claudeがそれらも変更した関数または定数を編集した場合、その変更を読み取り、両者が衝突するかどうかを通知します。
[画像: 編集後のフック:node-file.tsの編集は、インラインでブラスト半径(誰がそれに依存しているか)を表示し、ステータスラインは自動的にstale → syncing → syncedに切り替わり、ビューアでも同じ依存関係が点灯します]
編集ファイル → ブラスト半径がインラインで表示される → グラフが自動再同期される → ビューアで確認される
trail initは冪等であり、既存の.claude/settings.jsonを上書きしません。ブロックをマージし、残りはそのままにします。Trail-code以外のstatusLineはそのままにされます。initを再実行すると、すでにインストールされている場合はTrail-code自身のヘルパーコマンドが更新されます。ステータスラインをインストールしない場合は--no-statusline(またはGRAFT_NO_STATUSLINE=1)を渡します。プロジェクトレベルのstatusLineは、~/.claude/settings.jsonのカスタムステータスラインを隠してしまうためです。LLM要約も必要ですか?いつでもtrail build --deep(キー付き)を実行してください。自動同期はそれをあなたのために行うことはありません。
CLI
trail --helpは、4つのグループのコマンドを表示します。すべてのgraftコマンドも引き続き機能します。
# コード検索 · エージェントがこれらを実行します
trail ask "<タスク>" [dir] # 一致するコードと学習:ランク付けされたノード+正確なファイル:行(LLMなし、キーなし)
trail ask "<タスク>" --json # 機械可読結果
trail ask "<タスク>" --in <scope> # モノレポ/マルチレポフォルダの1つのサブプロジェクトに絞り込む(下記参照)
trail grep "<正規表現>" [dir] # インデックス化されたファイル全体での網羅的な正規表現検索、囲むシンボルごとにグループ化(LLMなし、キーなし)
trail grep "<正規表現>" --in <path> # このパスプレフィックス以下のファイルに絞り込む
trail grep "<正規表現>" -i --fixed # 大文字小文字を区別しない。パターンを正規表現ではなくリテラル文字列として扱う
trail skeleton <file> [dir] # 1つのファイル内のすべてのシグネチャ、ボディなし:約1/10のトークンでAPIサーフェス(LLMなし、キーなし)
trail callers <symbol> [dir] # シンボルを呼び出す/参照する/インポートする/実装する/拡張する(LLMなし、キーなし)
trail callers <symbol> --direction out # 逆:シンボル自体が呼び出す/参照するもの
trail callers <symbol> -d N # 深さNまで推移的にウォーク:完全なブラスト半径
trail map [dir] # トークン予算付きリポジトリオリエンテーション:ディレクトリクラスター、ハブ、ホットスポット(LLMなし、キーなし)
trail map --max-dirs N # 表示されるディレクトリの数を増減させる
# ask / skeleton / callers / grep / map / blast はすべて、作業ツリーが移動した場合にグラフを最初に更新します:
# --no-refresh # ディスク上のグラフとまったく同じものから回答する
# GRAFT_NO_REFRESH=1 # 同じ、すべてのコマンドに対して
# GRAFT_REFRESH=hash # サイズ+mtimeを信頼するのではなく、すべてのファイルをハッシュする
# チームメモリ
trail note --title "<内容>" [dir] # 決定を保存:このセッションで決定したこと、試したこと、却下したこと(標準入力のテキスト)
trail note --personal # コードではなく、あなた自身のセットアップについて:リポジトリ外の~/.trailに保存
trail check [dir] # リポジトリの学習、あなた自身の学習、スキルに対してブランチの差分をチェック(競合があれば終了コード1)
trail check --base origin/main # マージベースの代わりにこれと比較する(PRジョブが実行するもの)
trail team [dir] # チームが今週学んだこと、誰が何に取り組んでいるか、作業がどこで重複しているか
# セットアップ
trail init [dir] # 配線するエージェントを選択(ターミナルでのプロンプト。選択するまで何も書き込まない)
trail init --dry-run # 配線するエージェントの配線リストを表示してから終了
trail init --agents cursor kiro # これらのみを配線、プロンプトなし(ID:agents, adal, cursor, gemini, grok, hermes, antigravity, copilot, kiro, windsurf, claude)
trail init --yes # プロンプトなし。検出されたすべてのエージェントを配線
trail init --no-global # このリポジトリ外への書き込みをスキップ(~/.claude, ~/.claude.json, ~/.codex, ~/.gemini)
trail init --no-statusline # Claude Codeステータスラインをスキップ(GRAFT_NO_STATUSLINE=1と同じ)
trail init --no-build # ファイルのみを配線。グラフを構築しない
trail init --all-agents # 検出されたかどうかにかかわらず、すべての既知のエージェントを配線
trail init --list-agents # 既知のエージェントIDをリストして終了
trail build [dir] # graft/にGraftマップを構築:配線グラフ+シンボルごとのカード(LLMなし、キーなし)
trail build --deep # LLMレイヤーを追加:コンセプトノード+シンボルごとの要約/crux(キャッシュ済み)
trail build --check # 何も構築しない:graft/がコードから逸脱した場合(終了コード1)に失敗、CI用
trail build --deep -e .ts .py # --deepと併用:これらの拡張子のみを要約
trail build --no-reuse # 変更されていないものをキャッシュから再生するのではなく、すべてのファイルを再解析する
trail build --follow-submodules # 初期化されたサブモジュールを含める。選択をビルド+MCPリフレッシュのために永続化する
trail build --no-follow-submodules # サブモジュールを再度除外し、その選択を永続化する(デフォルト)
trail build --follow-nested-repos # インデックスが追跡していないネストされたgitクローンを含める。選択を永続化する
trail build --no-follow-nested-repos # ネストされたクローンを再度除外し、その選択を永続化する(デフォルト)
trail status [dir] # Graftマップ、学習、保存されたトークンを1画面で表示
trail upgrade # 最新の公開バージョンをnpm install -g
# 新しいバージョンは自動的にアナウンスされます(1日1回チェック)。
# アップグレード後、次のセッションでこのリポジトリの配線が自動的に更新されます
trail uninstall [dir] # ここに書き込んだすべてのファイルと設定エントリを削除します(initの逆)
trail uninstall -y # 実際に削除(-yなしでは削除するものを表示して終了)
trail uninstall --keep-cache # 配線のみ。graft/と.gitignoreエントリを残す
trail uninstall --no-global # リポジトリ外のファイルを無視する(~/.claude, ~/.claude.json, ~/.codex, ~/.gemini)
trail telemetry [status|enable|disable|debug] # 匿名使用統計。debugは送信されるものを正確に表示します
# CI
trail blast [dir] # 差分のブラスト半径:この変更が触れた行に依存するもの(LLMなし、キーなし)
trail blast --base origin/main # HEADとのマージベースと比較する(PRジョブが実行するもの)
trail blast --format markdown # PRコメント:変更が到達できる領域、シンボルごとの詳細がその下に折りたたまれている
trail blast --base origin/main --name # 完全な--deepビルドの代わりに、1回のキャッシュLLM呼び出しでこれらの領域に名前を付ける
trail blast --export-viz site/ # この半径のインタラクティブページも書き出す(PRコメントがリンクするもの)
trail blast --no-owners # 「誰にタグ付けするか」をスキップする(デフォルトでは、git履歴が各領域の背後にある人々を名前で示す)
trail blast --depth all --format json # 完全な推移閉包、機械可読
# ヘルプに記載されていないが、まだ存在するコマンド
trail viz [dir] # グラフを表示:localhostでインタラクティブビューアを提供
trail viz --export site/ --title "PR #12" # CI、GitHub Pages、またはビルド成果物のための自己完結型index.html
trail mcp [dir] # MCPサーバーを手動で実行
# グローバル
trail --dir <path> # <repo>/graft以外のコンテキストディレクトリを使用
trail --version, -v # インストールされているバージョンを表示して終了
メソッド呼び出しは、受信者の型を通じて解決されます。コンストラクタの代入(self.router = APIRouter())と型注釈を使用し、呼び出しサイト名だけでなく、メソッド名のメソッドのすべての呼び出しではなく、メソッドが多いコードで正しい型にバインドされた呼び出しを返します。
検索とオリエンテーション(trail grep / trail map)
trail grep "<正規表現>"は、すべてのインデックス化されたファイルに対して網羅的であり、ヒットを囲むシンボルごとにグループ化し、trail mapが使用するのと同じインエッジ結合でランク付けします。これは、「このパターンのすべての出現」タスク向けであり、trail askのランク付けされたトップNでは不十分です。
"NEEDLE" — 2ヒット、2シンボル、1ファイル(1つのインデックス化されたファイルを検索)
heavilyCalled · function · src/a.ts:L1-L3 · 3 in-edges
L2: console.log("NEEDLE hit in heavilyCalled");
rarelyCalled · function · src/a.ts:L4-L6 · 0 in-edges
L5: console.log("NEEDLE hit in rarelyCalled");
trail mapは、リポジトリのトークン予算付きの最初の概要です。ファイル/シンボル数を持つディレクトリクラスター、各ディレクトリのローカルハブ、およびグローバルホットスポット。すべてインデグリーでランク付けされ、LLMなし、キーなしです。
repo map — 313 files · 2349 symbols · 8148 edges · javascript, typescript
src/ 157 files · 1804 symbols hubs: wiringPath (write.ts, 48←), cmd (brand.ts, 45←), buildGraph (build.ts, 39←)
test/ 144 files · 467 symbols hubs: tmpRepo (helpers.ts, 46←), fetch (app-identity.test.ts, 7←), fakeProviders (helpers.ts, 5←)
viewer/ 5 files · 71 symbols hubs: $ (main.ts, 9←), cvar (data.ts, 6←), activeGraph (main.ts, 5←)
scripts/ 7 files · 7 symbols hubs: bump (graph-quality.mjs, 1←), defaultTranscriptDir (tally-audit.mjs, 1←), flush (tally-audit.mjs, 1←)
hotspots: wiringPath · function · src/graph/write.ts:L20-L22 · 48← tmpRepo · function · test/helpers.ts:L30-L32 · 46← cmd · function · src/brand.ts:L63-L70 · 45← ...
モノレポ、サブモジュール、マルチレポフォルダ
Graftマップはこれらのレイアウトをサポートします。
- 単一の
.gitを持つモノレポ(pnpm_workspace.yaml/package.jsonworkspaces、またはパッケージごとのgo.mod/pyproject.toml/Cargo.toml):trail buildは各サブプロジェクトをランキングスコープとして検出します。ask/mapは各スコープを独自の条件でランク付けし、結果を融合するため、最大のサブプロジェクトが小さなプロジェクトを圧倒することはありません。ヒットには[scope/]ラベルが付与され、trail mapはディレクトリクラスターを最初にスコープでグループ化します。 - 初期化されたサブモジュールを持つGitスーパープロジェクト:サブモジュールはデフォルトで除外されます。初期化されたgitリンクを1つのグラフに折り込むには
trail build --follow-submodulesを実行し、子パスをプレフィックス付けします(例:deps/parser/src/index.ts)。ただし、各サブモジュールの独自のGit無視ルールは尊重されます。表示される追跡されていないファイルも含まれます。初期化されていないサブモジュールは、git submodule update --initでチェックアウトされるまで不在のままです。この選択は.graft/config.jsonに保存されるため、後でフラグなしのビルドとMCPの自動更新は同じように動作します。デフォルトの境界に戻して永続化するには、trail build --no-follow-submodulesを実行します。未初期化のサブモジュールは、チェックアウトされるまで無視されます。 - 内部に他のリポジトリがクローンされたGitリポジトリ(gitリンクなし、インデックスエントリなし):
west、repo、gclient、tsrcのようなマニフェストツールが依存関係をチェックアウトする形状であり、アップストリームをツリーにクローンしてローカルでパッチを当てることで得られる形状です。--follow-submodulesはこれらに到達できません。それらはフォローする160000インデックスエントリを持っていません。それらを1つのグラフに折り込むにはtrail build --follow-nested-reposを実行し、子パスをプレフィックス付けします(例:external/parser/src/index.ts)。ただし、各クローンの独自のGit無視ルールは尊重されます。git無視パスのクローンは、Gitがそれを報告しないため、不在のままです。この選択は.graft/config.jsonに保存され、--follow-submodulesとは独立しています。どちらのフラグももう一方を意味しません。各リポジトリを個別にスコアリングおよび更新したい場合は、マルチリポジトリ分割よりもこちらを優先してください。それらを1つのグラフでエッジを維持したい場合は、こちらを優先してください。 - 個別のgitリポジトリのフォルダ(トップに
.gitなし):trail buildは自動的に分割します。各子は独自の(git無視された)graft/を持ち、親はgraft/workspace.jsonインデックスを持ちます。親からのクエリは、各子にフェデレートされ、常に<child>/とラベル付けされます。子内でtrail buildを実行すると、そのリポジトリのみを対象に作業できます。
すべてのレイアウトで、作業している場所がわかったら、trail ask "<タスク>" --in <scope>/を使用して1つのサブプロジェクトに絞り込みます。
マルチリポジトリフォルダの親でtrail initを実行すると、親だけでなくすべての子リポジトリも配線されます。エージェントセッションはリポジトリのルートで開き、そこから指示ファイルを読み取るため、各子には独自の指示ファイルが必要です。親で開始されたセッションはフェデレートされたビューを取得し、子で開始されたセッションはリポジトリ単独のビューを表示します。
コマンドはサブディレクトリからグラフも見つけます。[dir]引数がない場合、最も近いgraft/まで上に移動するため、trail askはリポジトリルートへのcdなしでsrc/deep/inside/から機能します。
視覚化(trail viz)
trail vizは、両方のグラフのローカルでインタラクティブなビューを開きます。インストール不要、開発サーバー不要。ビューアはパッケージ内にプリビルドされています。
[画像: グラフビューア:シンボルを検索してジャンプすると、その依存関係グラフが点灯します。琥珀色のエッジは依存しているもので、藍色は依存しているものです]
検索 → ノードにジャンプ → 依存関係グラフが点灯
- Contextタブ:
graft/*.mdからのアーキテクチャグラフ。ノードはタイプごとに色分けされ、接続性によってサイズ設定されます。 - Codeタブ:
graft/.graph/wiring.jsonからのシンボルごとのグラフ(最初にtrail buildを実行してください)。 - Outlineタブ:ファイル→クラス→メソッドの階層を折りたたみ可能なツリーとして表示します。
エッジはコードの言語を話します。各リンクは、コードを構築またはレビューする人が実際に尋ねる質問に答える、閉じた動詞のセットの1つです。
| 動詞 | それが答える質問 |
|---|---|
part_of / contains | これはどこにありますか? |
uses / calls / imports / depends_on | これを変更すると何が壊れますか? |
produces | これはどこから出力されますか? |
configures | コード変更なしで、これは何を変更しますか? |
validates | これを何がチェックまたはジャッジしますか?(テスト、ドリフトチェック、スコアリング) |
extends / implements | これは何の契約を満たす必要がありますか? |
references | これを名前で参照しますが、呼び出しません(かすかなドットとして描画されます)。 |
ノードを選択すると、そのエッジが方向を持ちます:琥珀色=依存しているもの、藍色=依存しているもの。各強調表示されたエッジに動詞が書かれています。キャンバス上のチップは動詞でフィルタリングします。パーサーが正確に解決したエッジは実線で描画され、名前のみで一致したエッジ、またはモデルによって推測されたエッジは破線で描画されます。ビューアはgraft/がディスク上で変更されるとライブリロードします。あいまいな動詞(influences、supports)を持つ古いグラフは、ロード時に正規化されるため、再生成は不要です。
開発
git clone https://github.com/trailhq/Trail-Code.git && cd Trail-Code
npm install
npm run build
npm test
npm run cli -- build --deep .
ライセンス
MIT。[LICENSE](https://github.com/trailhq/Trail-Code/blob/main/LICENSE)を参照してください。