coldstart

2 つのレイヤーを、1 つのツールで：

• ノートブック（coldstart kb）— このコードベースが実際にどのように動作するかについての、エージェントが作成する永続的なメモです。ファイルの用途、処理フローが複数ファイルにどうまたがるか、どの不変条件が成り立つかを記録します。実際のタスクの後に記録され、後のタスクが一致したときに呼び出されます。また、インデックスによって正確性が保たれます。すべてのメモは実在するファイルに根拠があり、根拠とのずれが生じたメモにはフラグが付けられ、事実として提示されることはありません。
• ナビゲーション（coldstart find / coldstart gs）— ファイルパス、シンボル名、エクスポート、インポート／呼び出しグラフを対象にした、高速な静的インデックスです。「このタスクに関連するファイルはどれですか？」という問いに、類似度スコアではなく検証可能な根拠を示して、数ミリ秒で答えます。

埋め込みは不要で、実行するモデルも、面倒を見るサービスもありません。エージェントはすでにコードの読み取りや推論が得意です。トークンを浪費しているのは、適切なファイルを_見つける_ことと、前のセッションですでに把握した内容を_再導出する_ことです。coldstart はこの 2 つを担い、あとは邪魔をしません。

---

インストール

Node.js 18 以降が必要です。

npm install -g @cstart/coldstart
cd your-project
coldstart init   # coldstart.md + client wiring + notebook + background index warm-up

coldstart init を一度実行するだけで、ナビゲーションとノートブックの両方をセットアップできます。エクスペリエンス（cli（推奨）または mcp）とクライアントの2つを尋ねた後、エージェント向けのガイダンスをクライアント独自のルールファイルに書き込み（Claude Code ではインポートされた coldstart.md として、@file 参照を解決しない Cursor と Codex では直接インラインで記述します）、クライアントを連携させ、ノートブックをセットアップします（骨組み、Git 連携、および Claude Code、Codex、Cursor ではキャプチャ／リコールフック）。プロンプトを省略するには --experience / --client を渡します。クライアントが自動検出されることはありません。必ず選択してください。

• Claude Code → coldstart.md を書き込み、CLAUDE.md から @coldstart.md をインポートするように設定します。また、find/gs 検索フック（PostToolUse のナッジと PreToolUse の find 重複防止ガード）と、ノートブックのリコール／キャプチャフック（UserPromptSubmit + Stop/SubagentStop）を .claude/settings.json に登録します。既存の設定は上書きせず、統合します。mcp エクスペリエンスでは .mcp.json も書き込みます。
• Codex → coldstart のガイダンス全体を AGENTS.md のマーク付きブロックにインラインで埋め込みます（Codex には @file インクルードがないため、独立した coldstart.md はありません）。再実行時は該当箇所を更新し、Codex 専用のナビゲーションフックとノートブックフックを .codex/hooks.json に登録します。キャプチャフックは Codex のロールアウトとサブエージェントのトランスクリプトに対応しています。mcp エクスペリエンスでは .codex/config.toml に [mcp_servers.coldstart] も書き込みます。
• Cursor → coldstart のガイダンス全体をインラインで含む、常時適用されるルール .cursor/rules/coldstart.mdc を書き込みます（Cursor のルールでは @file 参照が確実に解決されないため）。これは初期化のたびに書き換えられます。また、Cursor 専用のナビゲーションフックとノートブックフックを .cursor/hooks.json に登録します（preToolUse の find 重複防止ガード、postToolUse のナッジ、beforeSubmitPrompt のリコール、stop/subagentStop のキャプチャ。既存のフックと統合されます）。キャプチャフックは Cursor 独自の会話トランスクリプトを解析します。mcp エクスペリエンスでは .cursor/mcp.json も書き込みます。
• その他 → coldstart.md のみを書き込み、連携方法を表示します（mcp エクスペリエンスの場合は MCP サーバーのエントリーも表示します）。

どのクライアントでも、PostToolUse フックは、求められるのを待たずに 「一緒に編集」 のシグナルも通知します。エージェントが異なる2つのファイルを編集すると、Git の履歴から、それらと一緒に変更され続けているファイルの名前を知らせます。たとえば、関連する実装、別の言語で書かれたテスト、ずれが生じるドキュメントなどです。エージェントは編集前に gs を確実に実行するわけではないため、これまでは自分から探しに行った場合にしかシグナルが届きませんでした。この仕組みによって、編集時にシグナルを提示できます。あくまで参考情報です。メッセージでは、関連性はコード上の依存関係ではなく習慣的なものだと明示し、変更ではなく確認を促します。各ファイルの名前がタスク内で提示されるのは最大1回で、新しいメッセージを送るたびにリストがリセットされます。

その後、init はバックグラウンドでインデックスを準備するため、最初の検索は瞬時に完了します。init の再実行は安全です。エントリーが重複することはありません。

アップグレード

npm install -g @cstart/coldstart@latest
coldstart init   # re-run in each project to refresh coldstart.md

キーパーのロックファイルに記録されたバージョンスタンプにより、次の検索時に古いバックグラウンドキーパーが終了し、新しいバイナリから新しいキーパーが起動します。手動で再起動する必要はありません。

メモ

coldstart-mcp からの移行： 2.0.0 でパッケージ名が coldstart-mcp から @cstart/coldstart に変更されました（現在は CLI が主要なインターフェースです）。coldstart-mcp は非推奨ですが、引き続きインストールできます。npm uninstall -g coldstart-mcp && npm install -g @cstart/coldstart && coldstart init を実行して切り替えてください。coldstart-mcp というバイナリ名はエイリアスとして維持されるため、既存の MCP 設定も引き続き動作します。

coldstart の削除

init は、グローバルな npm uninstall では削除できないリポジトリごとの設定を書き込みます（npm は信頼できるアンインストールフックを実行せず、どのリポジトリで init を実行したかも記録していません）。そのため、husky と同様に、coldstart には明示的な元に戻すコマンドが用意されています。

coldstart unwire          # strip coldstart's wiring from this repo (notebook kept)
coldstart unwire --purge  # also delete .coldstart/notebook/ and its git plumbing

unwire は、init が変更したファイルから coldstart が所有するマーカーだけを削除します。対象はフックのエントリ、@coldstart.md のインポート、AGENTS.md のブロック、MCP サーバーのエントリ、および coldstart が完全に所有するファイル（coldstart.md、.cursor/rules/coldstart.mdc）です。共有ファイル内の独自のコンテンツは削除しません。4 つすべてのクライアントを対象に処理し、冪等性があるため、2 回目の実行ではすべて削除済みであることが報告されます。また、ノートブックはコミット済みの共有データであるため、デフォルトでは保持されます。まず各プロジェクトで実行し、その後 npm uninstall -g @cstart/coldstart を実行してパッケージを削除してください。

---

ノートブック

エージェントが .coldstart/notebook/ に書き込み、読み取る、リポジトリ内のナレッジベースです。

coldstart kb search tile save lifecycle   # plain task words, symbols, or file names
coldstart kb lookup src/models.py Tile    # everything known at one exact address
coldstart kb write spec.json              # the write gate (two-phase dedup)
coldstart kb commit                       # publish notes to git, nothing else rides along
coldstart kb view                         # open a single-file HTML browser of the notebook
coldstart kb repair                       # worklist of notes that are written but unfindable
coldstart kb repair-aliases                # worklist of aliases that may no longer be true
coldstart kb status / lint / render / init / migrate

ノートとは。 形は3種類あります。ファイルノート（ファイルの用途を記したもの。単一の要約、またはハブファイルのシンボルごとの側面）、フローノート（複数ファイルにまたがる一連の説明。順序付きの手順、不変条件）、レッスン（落とし穴、ルール、バグの原因、根拠、または確認済みの不在）です。すべてのノートにはアンカーがあり、主張の根拠となる具体的なファイルパスとシンボルを示します。

ノートがエージェントに届く場所。 新しい習慣を必要としない、3つの経路があります。

1. find の結果に表示される Summary: 行 — ファイルが表示される順位のすぐそばに、過去のエージェントが検証したファイルの概要が表示されます。[fresh] は、ファイルの内容が概要の検証時とバイト単位で同一であることを意味します。エージェントはファイルを読み直さずに、その概要を信頼できます。
2. プロンプト入力時のリコール（任意のフック） — 受信したプロンプトとタイトル、別名、またはアンカーが一致するノートが、タイトル＋要旨＋パスの簡潔なブロックとして表示されます。表示数には厳格な上限があり、参照データとして提示されます。一致するものがなければ、何も挿入されません。
3. kb search / kb lookup — 作業中の用語の変更に対応するノートブック検索と、ファイルを編集する前に使う正確なアドレス指定の検索（path [symbol]）です。

信頼できる理由。 ここが設計に最も手間をかけた部分です。

• 鮮度は機械的に判定され、期待に頼りません。 書き込み時にすべてのアンカーへコンテンツハッシュが記録され、コードの変更に応じてインデックスが記録内容を再確認します。内容が変わったノートには [evidence changed: <path>] と表示され、ガイダンスは再検証を促します。古くなった知識は、確信に満ちた誤りではなく、ラベル付きの仮説になります。
• ログが真実の源です。 ノートは追記専用の .raw イベントログに保存されます（ログをコミットしてください。マージは和集合になるため、並行するブランチのノートを競合なく統合できます）。Markdown ノートはそこから機械的に生成し直される派生物で、gitignore の対象です。
• 書き込みにはゲートがあります。 新しいノートの概念は、まず既存のノートと照合検索されます。エージェントは一致するノートへ明示的に統合する（--into <id>）か、新規であると宣言する（--new）必要があります。重複は後から整理するのではなく、書き込み時にゲートで防ぎます。
• 並行セッションでも安全です。 複数のエージェントが同時に書き込めます。ノートごとの追記専用ログ、新しいノート ID の排他的作成（同時に作られた重複は、暗黙に統合されることなく、2つのノートとして表示されます）、共有ファイルノートの損失のないマージ、アトミックなレンダリングにより、読み取り中に書きかけのノートが見えることはありません。
• セッション中に修正できます。 エージェントが証拠をコンテキストに持っているときにノートの誤りを見つけた場合、ガイダンスに従ってその場でノートを修正または撤回します。これ以上適切なタイミングで確認できる未来のエージェントはいません。

セットアップ： ノートブックは coldstart init に含まれているため、別途手順を実行する必要はありません。ノートブックのひな形を作成し、ログに和集合マージを設定して、（Claude Code、Codex、Cursor では）2つのフック、つまりセッション終了時の記録とプロンプト入力時のリコールを設定します。（ノートブックのフックだけを設定し直す場合は、別名の coldstart kb init も引き続き利用できます。）他のホストからは、フックを使わずに、kb CLI 全機能、またはシェルを使わないクライアント向けの kb_search / kb_lookup / kb_write / kb_status / kb_repair / kb_repair_aliases MCP ツールを通じてノートブックを利用できます。

言語に依存しません。 ノートブックの鮮度判定機能はコンテンツハッシュに基づいているため、ナビゲーションインデックスが解析しない言語を含め、あらゆるコードベースで動作します。インデックスが解析できる場合は、さらにシンボル単位の鮮度情報もノートに付与されます。

メモ

ノートブックはまだ新しいものです。 現時点で検証されていることは、実際のセッションでエージェントが書いたノートがコードと照合して正確であること、古いノートへの対応サイクル（検出 → 再読込 → 修正）が最初から最後まで機能すること、そして記録、リコール、並行書き込みが負荷をかけても安定していることです。あくまで仮説として述べる期待は、このようなコーパスはリポジトリの存続期間を通じて蓄積され、どんな質問でも2回目には再導出する代わりに、Read ひとつで答えにたどり着けるようになる、というものです。

ナビゲーション：2 つの操作

	何がわかるか	置き換えられるもの
find <terms>	「これに関するファイルはどれか？」— ファイルがクエリ語をどれだけカバーしているかに基づいて順位付けします（ファイル名、パスの各要素、エクスポートされたシンボル、およびリポジトリ全体の名前参照検索を含みます）。	構成を把握する際に何度も実行する grep／glob
gs <file>	「このファイルは何か？」— トップレベルのシンボルと行範囲、インポート元、各シンボルの呼び出し元、名前に関連する近接要素を示します。	形や使われ方を知るためだけにファイル全体を読むこと

想定される流れ：概念を find する → 最適なパスを選ぶ → そのファイルを gs で調べ、構造と利用元を確認する → メソッド本体の実装を確認する場合にのみ Read を使います。ノートブックの要約も find の結果に含まれるため、構成の把握だけで答えが見つかることもよくあります。

flowchart LR
    A["coldstart find<br/>which files?"] --> B["coldstart gs<br/>what is it? who uses it?"] --> C["Read<br/>just the method body"]
    class A,B cold
    class C warm
    classDef cold stroke:#16708f,stroke-width:2px
    classDef warm stroke:#c26714,stroke-width:2px

find — 概念に関するファイルを見つける

coldstart find auth session cookie

ヒント

タスクに関係するすべての主要な識別子を渡してください。シンボル、ドメインの名詞、うろ覚えの珍しいトークンなどです。キーワードを 1 つに絞り込む必要はありません。find は各ファイルが指定語をいくつカバーしているかに基づいて順位付けし、ファイルごとに、各語が定義されているのかインポートされているのかを示し、語が集中している行のプレビューを表示します。何も開かなくても、これで答えがわかることがよくあります。

速度の面でも、find は通常の grep に対抗できます。リポジトリ全体の参照検索では ripgrep（PATH 上のもの、同梱版、またはエディターのものを使用。COLDSTART_RG で上書き可能）を実行し、利用できない場合は git grep／grep にフォールバックします。順位付けされたページはスキャンではなく、事前構築されたインデックスから生成されます。

フラグ： --path GLOB（対象範囲。カンマで複数指定し、! で除外） · --tests（テストファイルを含める） · --via（名前参照の関係を表示） · --json

gs — 1 つのファイルを詳しく調べる

coldstart gs src/auth/service.ts

1 回の呼び出しで、ファイルのシンボル（行範囲付き）、1 ホップ先までの内部インポート、インポート元、シンボルごとのファイル横断の呼び出し元を返します。これは **「このファイルは誰に使われているか／このシンボルを呼び出しているのは誰か」**への答えであり、grep ではありません。

フラグ： --symbol a,b（指定したメソッド本体をインラインで表示） · --match TERM（巨大なファイルを 1 つの範囲に絞り込む。a|b は OR、/regex/ は正規表現） · --view symbols|imports|importers|callers · --json

graph — リポジトリ全体を一度に見る

coldstart graph

エージェントではなく、人間向けです。自己完結型の HTML ファイルを 1 つ生成して開きます。インデックスされたすべてのファイルが球体上の点として表示され、ディレクトリごとに配置されます。点をクリックすると、つながりのすべてを 2D 表示します。関係の名前もそれぞれ表示されます（imports、calls save(), load()、edited together · 13 of 42 commits、same note · <title>）。近接する点をクリックするとそのつながりが開き、さらにその中の点をクリックすると表示が沿って移動するため、際限なく広がる複雑な図ではなく、常に 2 階層を確認できます。

依存関係はありません。 ページは HTML、CSS、リポジトリのデータを埋め込んだ canvas スクリプトで構成されます。サーバーもビルド手順も不要で、マシンの外にデータが出ることもありません。メールで送ったり、gist に置いたり、飛行機の中で開いたりできます。coldstart 自身のコードベースで試してみてください。

フラグ： --out PATH（デフォルトは .coldstart/graph.html。Git では無視されます） · --no-open · --json

独立した検索を 1 回のシェル呼び出しでまとめて実行する

coldstart find auth; coldstart find 'session cookie'; coldstart gs src/auth/service.ts

---

呼び出し方法は2通り、出力は同一

coldstart は、2つの入口を備えた単一のバイナリとして提供されます。

• CLI（主な方法） — coldstart find … / coldstart gs … / coldstart kb …。シェルを使えるあらゆるエージェント（Claude Code、Cursor、ターミナルでの使用）向けです。これが最速の方法です。
• MCP（シェルを使えないクライアント向け） — find と gs のツールに加え、ノートブックを kb_search / kb_lookup / kb_write / kb_status / kb_repair / kb_repair_aliases として提供します。いずれも CLI とバイト単位で同一です。シェルを使えない Claude Desktop などのクライアント向けです。（kb commit は CLI／人間専用です。Git へのノートの公開をエージェントが行うことはありません。）

エンジンもインデックスも結果も同じです。エージェントが利用できる方を選んでください。

Claude Code、Codex、Cursor との組み合わせで最も効果を発揮します。この3つには、coldstart init によってプラットフォーム固有の find／gs フックと、ノートブックの想起／記録フックが設定されます。それ以外のクライアントには、coldstart.md と設定方法の説明が表示されます。

---

セマンティクスは自分で用意

coldstart は、埋め込みも、生成された要約も、インデックス作成時に計算されるセマンティックレイヤーも備えていません。意図的な設計です。セマンティックレイヤーを担うのはエージェントです。 利用者はすでに全員、最先端のモデルです。インデックス作成時に意味を事前計算しても、それを重複させるだけで、しかも精度が低く、古くなります。そのためインデックスには、正確な状態を保つコストが低い情報――パス、シンボル、エクスポート、インポート／呼び出しグラフ――を保持し、各ファイルがランク付けされた理由を返します。

ノートブックにも、メモリに同じ考え方を適用しています。coldstart は今も独自に意味を計算しません。エージェントが作成した意味を保存し、その根拠を示し、鮮度を確認します。全コンテキストを把握していた推論エージェントが、実際に重要だった問いについて、タスク実行時に記述した内容です。詳しい説明は PHILOSOPHY.md をご覧ください。

---

インデックスの鮮度を保つ仕組み

coldstart は、単一の管理プロセスと薄い読み取り専用プロセスで構成されます。

flowchart TD
    K["keeper — coldstart --daemon<br/>watches repo, patches/rebuilds, saves cache<br/>serves nothing"] -->|debounced save| C[("on-disk cache")]
    C --> F["coldstart find<br/>reads cache, prints"]
    C --> G["coldstart gs<br/>reads cache, prints"]
    C --> M["MCP server<br/>reads cache, stdio"]
    class K cold
    classDef cold stroke:#16708f,stroke-width:2px

• リポジトリごとに1つの 管理プロセス がファイルシステムを監視し、ディスク上のキャッシュを最新の状態に保ちます。クエリには応答しません。
• CLI の読み取りプロセス（find／gs）と MCP サーバーは、キャッシュを読み取る ステートレスなプロセス です。リポジトリに対する最初の読み取り時に管理プロセスが遅延起動するため、未コミットの編集もすぐに反映されます。
• 読み取りプロセスがインデックスを構築することはありません。 キャッシュがない場合は、管理プロセスによる構築を待ちます（進捗は stderr に出力）。数分かかる構築を処理中にひそかに開始したり、同時に3つ開始したりすることはありません。
• HTTP もポートもブリッジもありません。管理プロセスは ~/.coldstart/daemon/<root>.log にログを記録し、ロックファイルが削除されると終了します。

キャッシュに TTL はありません。 インデックスは古くなったという理由で破棄されることはありません。代わりに、常に 正確な状態 が保たれます。

• 管理プロセスの実行中： 編集はデバウンス処理（400 ms）された後、増分でパッチ適用されます（ファイルあたり約2～5 ms、最大30ファイルまたはリポジトリの20％のうち、数が多い方）。それを超える場合は バックグラウンドで全体を再構築します（切り替えが完了するまでは、最後に正常だったインデックスを提供します）。編集が落ち着いて約5秒後にキャッシュが再保存され、アトミックな世代単位で管理されます。そのため、古い内容と新しい内容が混在した状態を読み込むことはありません。
• 管理プロセスの起動時： 整合性を確認します。インデックス内のすべてのファイルについて、保存されたフィンガープリントと照合して状態を確認（16kファイルでも約150 ms）し、インデックス作成時の HEAD に対する git diff も実行します。監視されていなかった間に変更された部分だけにパッチを適用します。以前は16kファイルのリポジトリで96秒かかっていたブランチの切り替えも、現在は約3秒のパッチ適用で済みます。
• さらなる安全策： すべてのパッチでインデックスの不変条件を lint チェックします（違反がある場合は自動で再構築し、status に表示される修復ログに記録します）。また、保存後にフィンガープリントを順次監査し、監視プロセスが見逃したイベントを検出します。

管理プロセスはノートブックのアンカーの鮮度も記録します（小さなサイドカーで、派生処理は single-flight）。クエリに回答する際、ノートブックがコードインデックスを読み込むことはありません。

ライフサイクルコマンド

coldstart status              # keepers on this machine: alive? fresh? last patch/rebuild/save? repairs?
coldstart restart             # kill the current repo's keeper (respawns on next lookup)
coldstart restart --root DIR  # kill a specific repo's keeper from anywhere
coldstart restart --all       # kill every keeper
coldstart index               # build + save the cache once, up front (single-writer prep)

何かが古くなっているように感じたら、restart を実行するのが適切です。新しいキーパーは起動時に照合するため、単に稼働するだけでなく、_正しい状態_で戻ってきます。status では「インデックスは最新か、そうでない理由は何か」を確認できます。稼働状況、キャッシュの経過時間、キーパーによる最後の照合・パッチ適用・再構築・保存の各タイムスタンプ、修復ログの末尾が表示されます。ネットワークのプローブは行いません。

---

サポート対象言語

ナビゲーションインデックスの対象：TypeScript、JavaScript、JSX/TSX、Vue、Svelte、Astro、AngularJS 1.x、Java、Kotlin、Ruby（Rails の規約に対応：has_many／belongs_to の関連、routes.rb のリソース、コントローラーとビュー間のエッジ）、Python（Django の規約に基づくエッジ）、Go、Rust、C#、PHP（Laravel の規約に基づくエッジ）、C++、Groovy（Gradle DSL を含む）、GraphQL、YAML、TOML、XML、.env ファイル。

インデックス対象外： Swift、Dart — 拡張子のマッピングがないため、これらのファイルは走査も解析もされません。

ノートブックは言語にかかわらず機能します — 鮮度のタイムスタンプはコンテンツハッシュに基づくため、Swift のリポジトリに関するノートも TypeScript のリポジトリに関するノートと同じように信頼できます（ただし、シンボル単位の鮮度の詳細はありません）。

---

使用しないほうがよい場合

• ファイル本文内の文字列、フレーズ、正規表現をそのまま検索する場合 → Grep。
• 実装を読む場合 → gs で構造を把握してから Read。
• find が 「インデックス済みのファイルに […] が含まれていません」 と示した場合 → その識別子はリポジトリ内にありません。表記ゆれを grep しないでください。

---

開発

npm install
npm run build
npm test

# run a query from your build:
node dist/index.js find auth --root .

# run the MCP server in a single process (no background keeper) for debugging:
node dist/index.js --root . --no-daemon

coldstart が独自の意味解析を行わない理由については PHILOSOPHY.md、インデックスのパイプライン、プロセスモデル、ノートブックの内部構造については ARCHITECTURE.md、復旧手順については TROUBLESHOOTING.md を参照してください。

---

制限事項

1. これはルーティングレイヤーとエージェントが作成するノートブックであり、意味解析や生成コードの要約は行いません。これは意図的な設計です。利用するエージェントが意味レイヤーを担います（PHILOSOPHY.md を参照）。
2. gs の呼び出し元がたどるのは1ホップ分で、対象はファイル単位です。メンバー式の呼び出し（this.method()、api.method()）はファイルをまたいで解決されませんが、名前付き関数／定数の呼び出しは解決されます。さらに先のホップをたどるには、呼び出し元のファイルに対して gs を実行してください。
3. 動的／計算式によるインポート（import(variable)）と、実行時 DSL の参照（ポリモーフィック関連、gem／リフレクションに基づくモデル）は解決されません。
4. 隠しディレクトリと1 MBを超えるファイルはインデックスから除外されます。
5. キーパーはリポジトリごと、マシンごとに存在し、プロジェクトやホスト間で共有されません。ノートブックは持ち運べます。.raw ログはコミットされ、ブランチ間およびマシン間でユニオンマージされます。
6. ノートブックの品質は、ノートを作成するエージェントが実際に読んだ内容に左右されます。ノートに記載された内容は正確ですが、ノートが網羅性を証明するわけではありません。

測定結果

CLI を使用し、それぞれ複数回実行した 2 つのリポジトリです。各質問は、coldstart がインストールされているかどうかだけが異なる 2 つの条件で行います。ベースラインは、標準搭載の検索ツールを使う素の Claude Code です。両方とも Sonnet 5 を使用し、質問ごとに新しいセッションを 1 つ開始します。

リポジトリ	言語	ベースライン比のトークン数	再現率	質問数
Arches	Python / Django	−64%	+2 ポイント	27
JMRI	Java	−31%	同等	25

質問は、問題のある箇所を誰も知らない段階で作成されたクローズ済みのイシューレポートをもとにしています。そのため、ファイル名を挙げるのではなく、症状を説明しています。正解は、そのイシューを解決したコミットに含まれるソースファイルの集合です。つまり、正解データは誰かの判断ではなく、git の履歴に基づいています。

この 2 つの数値を平均していません。ターンあたりのコストは言語によって異なり、削減効果はターン数を減らすことで得られるため、エージェントが 2、3 ターンで解決できる質問から得られる効果はわずかです。Kafka、Django、Mastodon を対象にした以前のベンチマークは破棄しました。モデルがこれら 3 つをすでに学習しており、それによって両方の条件が汚染されていたためです。破棄した内容とその理由を含む、方法の全容は coldstartmcp.dev/benchmark にあります。ハーネス自体は独立したプロジェクトの coldbench で、プライベートなものを含め、git の履歴があるあらゆるリポジトリで動作します。2 つの質問セットは、それぞれの正解ファイル一覧と、各質問の元となったイシュー番号とともに coldbench/examples で公開されています。

執筆記事

このツールの背景にある課題、つまりエージェントのセッションに実際どれだけのコストがかかるのか、そして測定結果と計画が食い違ったとき、設計に何が起きたのかについて、詳しく紹介しています。

• エージェントセッションではトークンはどこに使われるのか — セッションコストはおおよそ「ターン数 × 常駐コンテキスト」で、出力のコストは誤差ほどです。誰かが公開した数値をうのみにするのではなく、自分のトランスクリプトを分解する方法を紹介します。
• インデックスでは同じ質問に 2 回答えられない — コードグラフは各ホップのコストを下げますが、ホップ数は減りません。また、入次数によるランキングでは、リーフファイルを構造的にランク付けできません。
• エージェントが呼び出さないツール — ツールを利用可能にし、ドキュメントを用意し、明示的に指示しても、実際に使われるとは限りません。自分たちのエージェントが自分たちのコマンドを使わなかった事例も含みます。
• 4 つのツールから 2 つへ — 削除したツール、削除に伴って実際に失われた機能、そしてその後も機能の範囲を小さく保った理由を紹介します。
• コードに関するメモは、コードを読んだ人が書くべき — トランスクリプトを後から要約するのではなく、セッション中にノートブックへ記録する理由を紹介します。

ライセンス

MIT — LICENSE をご覧ください。

---