contextatlas

クイックスタート → · ベンチマーク結果 → · グラフベースではない理由 → · アーキテクチャ → · ADR →

---

ContextAtlas には、CLI と Claude Code Skills という同等の 2 つの利用方法があり、どちらも同じ atlas.json を生成します。セットアップについてはクイックスタートをご覧ください。

問題

現在、Claude Code は力ずくでコードベースを理解します。セッションは毎回、新しい状態から始まります。「X はどこ？」と尋ねるたびに複数の grep 呼び出しが発生します。「Y に依存しているものは？」と尋ねれば、さらに大量のファイル読み取りが発生します。中規模のコードベースでは、アーキテクチャに関する 1 つの質問に答えるだけで、Claude が十分なコンテキストを得て適切に推論できるようになるまでに、40 回以上のツール呼び出しと 100,000 以上のトークンを消費することがあります。

さらに厄介なのは、コードを支配するアーキテクチャ上の意図 — ADR、設計上の決定、「こうしたのは、こういう理由があったから」という背景 — が Claude には見えないことです。OrderProcessor を冪等にしなければならないというルールは docs/adr/ にあります。Claude が変更を提案するとき、その制約が存在することを知る方法はありません。

昨日の理解は今日に引き継がれません。会話は毎回、ゼロから始まります。ADR、コミット履歴、テストカバレッジ — そのどれもエージェントの前にはありません。

インデックス作成時に時間のかかる理解を一度だけ行い、あらゆるクエリを辞書検索にできるとしたらどうでしょう？

それが ContextAtlas です。

ContextAtlas とは

ContextAtlas は、Claude Code にコードベースの厳選されたアトラスを提供する MCP サーバーです。LSP レベルの構造的な精度と、ADR、ドキュメント、git の履歴から抽出したアーキテクチャ上の意図を融合し、単一の呼び出しでコンテキストバンドルを Claude に届けます。

Claude が受け取る各バンドルには、シンボルに関する4つの独立したシグナルが組み合わされています。

1. 構造データ：言語サーバーから取得する定義、参照、型、診断情報。コンパイラー級の精度です。
2. アーキテクチャ上の意図：ADR、README、設計ドキュメントから取得します。インデックス作成時に Opus 4.7 が抽出した構造化された主張を、特定のコードシンボルに関連付けます。
3. 履歴コンテキスト：git から取得する、シンボルに触れた最近のコミット、変更頻度の指標、同時変更パターンです。
4. テストとの関連付け：どのテストがシンボルを参照しているか、カバレッジがどこにあるかを示します。

1回の MCP 呼び出しで、4つすべてを統合して返します。リポジトリに ADR がまだなくても、15回ではなく1回の呼び出しで LSP ＋ git ＋テストの情報を取得でき、実質的なベースラインの改善になります。ADR を追加すると、バンドルはさらに充実します。どのシグナルを組み合わせても価値が生まれるように設計されています。

OrderProcessor はべき等でなければならないと記載された ADR がある場合、get_symbol_context("OrderProcessor") を呼び出すと、次の情報が返されます。

SYM OrderProcessor@src/orders/processor.ts:42 class
  SIG class OrderProcessor extends BaseProcessor<Order>
  INTENT ADR-07 hard "must be idempotent"
    RATIONALE "All order processing must be safely retryable."
  INTENT ADR-12 soft "prefer async base class for new processors"
  REFS 23 [billing:14 admin:9]
    TOP ref:ts:src/billing/charges.ts:88
    TOP ref:ts:src/admin/orders.ts:12
  GIT hot last=2026-03-14
    RECENT "Fix idempotency bug in retry path" a3f2c1d
  TESTS src/orders/processor.test.ts (+11)

Claude に OrderProcessor の変更を依頼すると、変更案を提示する前にべき等性の制約を確認できます。ユーザーのレビューで違反が発覚した後ではありません。

対象ユーザー。 ContextAtlas は、500,000ファイルのモノレポを扱う大企業のエンジニアだけでなく、実際のコードベースで Claude Code を使う一般的な開発者向けに構築されています。トークン消費の削減効果はコードベースの規模に応じて高まり、200ファイルのフレームワークでは大きく、30ファイルのライブラリでは控えめです。しかし、アーキテクチャ上の意図を捉える価値は規模に左右されません。 30ファイルのライブラリにも、共有する価値のある重要なアーキテクチャ上の決定がある場合があり、Claude がそれらを尊重することは、大規模なコードベースの場合と同じくらい重要です。

トークンの先へ：設計との整合性に関するケーススタディ

効率と品質は必要ですが、それだけでは十分ではありません。コンテキストを根拠にする実質的な価値は、複雑なコード変更タスクでの設計上の選択に表れます。

v0.3 開発時の A/B 試験。 2つの ContextAtlas クローンに同一の3段落のプロンプトを与え、既知のバグ修正を実施しました。バグの特定、修正の設計と実装、テストの作成、ADR による文書化を行います。セットアップ上の違いは MCP が利用可能かどうかだけでした。

群	MCP	選択されたアプローチ
A（標準）	なし	リコール優先のアプローチ（より広い一致を探し、ノイズによってプロジェクトの精度重視の方針と衝突）
B（CA 支援あり）	ContextAtlas	精度最適化のアプローチ（事前抽出された主張と構造的な帰属を重視する、プロジェクトの方針に沿う）

群 B のアプローチが main に採用されました。 両群とも、実時間とトークン消費が同程度で、機能上はバグを修正しました。実質的な違いはプロジェクトの設計方針との整合性でした。CA 支援ありの群は、アトラスから関連する ADR と過去のアーキテクチャ上の作業を参照でき、プロジェクトに適合する選択をしました。標準の群はそのコンテキストを確認できず、機能はするもののアーキテクチャと衝突するアプローチを選びました。

群 A が検討した重要な内容は失われませんでした。今後の作業で調査を開始するきっかけとして記録されています。リコールと精度のトレードオフは維持されています。

全体の統合結果は「v0.3 Round 3 dogfood evidence」をご覧ください。

試験数 N=1 のため、これはベンチマークではなく逸話的な事例です。 体系的なベンチマークスイート（hono / httpx / cobra）では効率と品質を測定します（以下の「数値」を参照）。この A/B 試験では、実質的に異なる設計との整合性という軸を測定します。この軸は、コード変更タスクがそれぞれのリポジトリに固有であるため、ベンチマークスイートの手法には適合しません。しかし、実際のコードベースを基盤として開発する対象ユーザーにとって、これは実質的な価値提案です。

数値

現実的な開発者の作業負荷を反映するよう選定した3つのリポジトリで、ContextAtlasをベースラインのClaude Codeと比較してベンチマークします。

リポジトリ	言語	ソースファイル数	役割
honojs/hono	TypeScript	186	中規模フレームワーク
encode/httpx	Python	23	用途を絞った本番用ライブラリ
spf13/cobra	Go	19	CLI フレームワーク

方法論。 リポジトリごとに24個のプロンプト、6つのタスク区分、条件を伏せた手動評価、事前登録済みの評価基準を用い、恣意的な結果の選別は行いません。方法論の全容は RUBRIC.mdをご覧ください。

効率：アーキテクチャ関連のプロンプトでツール呼び出しを50～71％削減

honoでのフェーズ5参照実行。事前登録済みの6つのプロンプト：

プロンプト	区分	Alpha 呼び出し	CA 呼び出し	Δ	Alpha $	CA $
h1-context-runtime	勝ち	18	9	−50%	$2.36	$1.52
h2-router-contract	勝ち	11	5	−55%	$0.60	$0.53
h3-middleware-onion	勝ち	5	5	0%	$0.38	$0.47
h4-validator-typeflow	勝ち	21	6	−71%	$2.95	$0.52
h5-hono-generics	引き分け	11	13	+18%	$0.79	$1.17
h6-fetch-signature	ひっかけ	3	4	+33%	$0.17	$0.29
合計		69	42	−39%	$7.25	$4.50 (−38%)

注目すべきケースは、h4-validator-typeflowの実行コストが7.3分の1（$2.95 → $0.52）になり、回答の深さは同等だったことです。CAは該当するADRを番号で特定して最初に開きますが、ベースラインはソースからアーキテクチャを再構築します。評価基準が予測したとおり、引き分けとひっかけの区分（h5、h6）ではCAの差し引きがマイナスになります。アーキテクチャ上の意図が重要でない質問に対して、CAは過剰に設計してしまいます。区分を考慮した方法論により、予想されるこれらのケースを埋もれさせずに明らかにできます。

多言語での再現でも、アーキテクチャ上の意図に関する勝利の仕組みは同様に確認されました。Python（フェーズ6 — httpx）とGo（フェーズ7 — cobra）でも同じ結果が得られています。フェーズ8では、ロック済みのプロンプトセットを、同じ固定ターゲットSHAに対してv0.3で精緻化したアトラスを使って再実行しました。その結果、3つすべての対象言語で、アーキテクチャ上の意図に関するプロンプトのトークン数を45～72％削減しました。結果の全容は phase-8-v0.3-reference-run.mdをご覧ください。

品質：条件を伏せた評価、信頼区間付きの対応ありt検定

v0.5では、対応モードで匿名化したLLM評価者の方法論を導入しました（ADR-19に準拠）。全セルをまとめた対応ありt検定では、各軸の差分はN=27です（アンカーセル5つ × n=5試行 × 2条件。hono h1は自動的にn=8へ拡張）。

品質軸	平均 Δ（0～3の尺度）	95% CI	区分
事実の正確性	+0.370	[0.176, 0.565]	明確
ハルシネーション	+0.296	[0.032, 0.561]	境界域
実行可能性	+0.148	[0.005, 0.291]	境界域
網羅性	+0.037	[-0.039, 0.113]	判別不能

閾値の事前登録： 3段階の分類（≥0.05は明確、0.001～0.05は境界域、≤0は判別不能）は、精度の値を算出する前に固定しました。データを見た後に基準を変更していません。76％の引き分け率は匿名化が機能したことを示しています。評価者は比較の4分の3で、どちらの条件かを判別できませんでした。

軸ごとの全数値と9つの名称付き分析結果は、フェーズ9の参照ドキュメントをご覧ください。方法論の限界については、以下の§方法論と正直な限界に記載しています。

ContextAtlas と代替ツールの比較

周辺ツールとの違いを踏まえ、ContextAtlas が何であり、何ではないのかを意図的に整理します。

グラフベースのコードインテリジェンス（Graphify など）との比較。 どちらも、MCP 経由で LLM エージェントが利用できるよう、コードベースの事前計算済みインデックスを構築するという同じカテゴリに属します。これは実質的なカテゴリの重なりであり、その点を率直にお伝えします。異なる点は次のとおりです。

• LSP に基づく方式と、ヒューリスティックに抽出する方式。 ContextAtlas は構造に関するすべての質問を言語サーバー（tsserver、Pyright、gopls、ruby-lsp、csharp-ls）に委ねます。Graphify は解析と抽出によって構造を導き出します。
• 事前構成済みのバンドルと、グラフプリミティブ。 ContextAtlas の MCP ツールは、1 回の呼び出しで統合されたバンドルを返します。Graphify は、呼び出し側が組み合わせて使うグラフ操作（graph_query、get_neighbors、shortest_path）を公開します。
• 限定的な範囲と、広範な範囲。 ContextAtlas はコード＋文章＋git をインデックス化します。Graphify はドキュメント、図、研究論文などを取り込みます。
• クレーム優先と、グラフ優先。 ContextAtlas は重大度ラベル付きの個別のクレームを保存し、「このシンボルには何が制約となっているか？」という問いに最適化されています。Graphify は世界をノードとエッジとしてモデル化し、「このノードと何がつながっているか？」という問いに最適化されています。

特定のワークロードでどちらがより良い結果をもたらすかは、実証的な問いです。上記の数値をご覧ください。

セッションメモリツール（claude-mem、engram、anamnesis）との比較。 これらのツールは、Claude が過去の会話で学んだことや行ったことなど、蓄積されたセッション履歴を記録します。ContextAtlas は、コード、ADR、ドキュメントから抽出した静的なアーキテクチャ上の基準情報を提供します。情報源は異なり、セッションでの議論が ADR やコミットになる場合には一部重なりますが、根本的に異なる課題を扱っています。また、セッションメモリツールはリポジトリにコミットするのが実質的に困難ですが、ContextAtlas のアトラスはコミットできます。

LSP-in-MCP（LSP-AI など）との比較。 ContextAtlas は、構造上の正確な情報源として LSP を使用します。LSP-in-MCP だけが必要であれば、そうしたプロジェクトがその課題をうまく解決しています。ContextAtlas はその上に、アーキテクチャ上の意図と git の履歴を重ねます。

埋め込みベースの検索との比較。 これを評価した結果、シンボルをキーとするクレームを採用しました。埋め込みはあいまいですが、LSP のシンボルは正確です。埋め込みベースのランキングは、効果を示すベンチマークの証拠が得られた場合に限り、MVP 後の拡張として検討します。詳しい根拠については、ADR-09をご覧ください。

コミット済みアトラスのパターン

ContextAtlas は、atlas.json というコミット可能なチーム成果物を生成します。これはコードや ADR とともにリポジトリに保存されます。これによって、ContextAtlas は個人の生産性向上ツールからチームの資産へと変わります。

• 新しいチームメンバーがリポジトリをクローンする場合： ほかのファイルと一緒に atlas.json も取得します。初回実行時に、ContextAtlas はコミット済みのアトラスをそのままローカルキャッシュにインポートします。抽出 API の呼び出しも、10 分の待ち時間もありません。Claude Code を開いた瞬間から作業を始められます。
• コントリビューターが PR を作成する場合： コードの変更がアーキテクチャ上の主張に影響する場合は、コミットの一部として atlas.json を再生成します。レビュー担当者は、PR でコード変更とアトラスの差分の両方を確認できます。
• 開発者が複数のマシンを行き来する場合： アトラスの状態はバージョン管理されるため、1 台のノート PC に閉じ込められません。
• 数か月ぶりにプロジェクトに戻る場合： 最新の main をプルすれば、不在中にチームが行ったすべての作業がアトラスに反映されます。前回プルした後に変更されたファイルだけを段階的に再インデックスすれば十分です。
• オープンソースプロジェクトの場合： 気軽に参加するコントリビューターも、セットアップコストを負担せずにすぐ恩恵を受けられます。プロジェクトに蓄積されたアーキテクチャの知識が、自動的に共有されます。

アトラスをコミットできないチームは、設定で atlas.committed: false を指定してください。各開発者がそれぞれ抽出を実行します。チーム成果物としてのメリットは失われますが、ContextAtlas は引き続き個人向けツールとして利用できます。

このモデルは、クエリのパフォーマンス向上のためにローカルキャッシュを使いつつ、チーム成果物をコミットするものであり、セッションメモリーツールやナレッジグラフツールとは本質的に異なります。詳細は ADR-06 をご覧ください。

アーキテクチャ

                INDEX TIME (once per source change)
                ──────────────────────────────────────
                ADRs ──────────┐
                Docstrings ────┤
                Git commits ───┼──► Opus 4.7 extraction
                LSP symbols ───┘              │
                                              ▼
                              atlas.json (committed to repo)
                                              │
                                              ▼
                              SQLite + FTS5 BM25 (local cache)

                QUERY TIME (every Claude call, zero API)
                ──────────────────────────────────────
                Claude Code:  get_symbol_context("X")
                                              │
                                              ▼
                              One fused bundle, sub-100ms
                              (LSP refs + intent + git + tests)

5 つのレイヤーがあり、それぞれに役割があります。

1. MCP インターフェース。 get_symbol_context、find_by_intent、impact_of_change の各ツールを Claude に公開します。
2. クエリの融合。 クエリごとに、各シグナルソースの結果を組み合わせます。
3. シグナルソース。 LSP（tsserver／Pyright／gopls／ruby-lsp／csharp-ls 経由）、SQLite のインテントレジストリ、git、テスト。
4. 抽出パイプライン。 Opus 4.7 が説明文書を読み、シンボルに関連付けた構造化された主張を出力します。
5. ストレージ。 SQLite インデックスを使用し、SHA をキーとして段階的な再インデックスを行います。

クエリ時のシグナル融合は、実質的に低コストなルックアップとして機能します。Claude が get_symbol_context("OrderProcessor") を呼び出すと、MCP ハンドラーは LSP から動的な構造情報（定義、参照、型）を取得し、SQLite からシンボルについて事前に抽出されたインテントの主張を読み込み、さらに git の変更頻度とテスト情報を組み合わせます。Claude に返される情報は、クエリ時に計算されるのではなく、あらかじめ組み立てられたものです。実質的な結合処理はインデックス作成時に行われます。これは、呼び出し側がクエリ時に組み合わせるプリミティブ（get_neighbors、shortest_path）を公開するグラフベースの代替手段との本質的な違いです。

アーキテクチャ上の約束は、**コストのかかる理解処理はインデックス作成時に一度だけ行い、クエリは API 呼び出しゼロのローカル辞書検索にすることです。**これにより、コスト、レイテンシー、予測不能性を抑えます。これは最適化ではなく、厳守すべき不変条件です。

設計の詳細は DESIGN.md をご覧ください。

データフローとプライバシー

ContextAtlas がお使いのマシンの外部に送信するものと、送信しないもの：

Anthropic の API に送信されるもの（インデックス作成時のみ）：

• .contextatlas.yml の adrs.path と docs.include に一致するすべてのファイルの全文。デフォルトでは、ADR、README、その他の Markdown ドキュメントです。ソースファイルに一致する docs.include の glob（たとえば docs/examples/*.ts に一致する docs/**）を指定すると、コードも含めてそれらのファイル全体が送信されます。これを避けるには、glob をドキュメントファイルに絞り込んでください
• ソースファイル内のエクスポートされたシンボルの docstring テキスト（コードではなくコメントテキストのみ）。リクエストごとに 1 つのシンボルを送信します
• コミットフィルターを通過したコミットのメッセージ（件名と本文。差分は含みません）。リクエストごとに 1 つのコミットを送信します
• これは変更のたびにソースごとに 1 回行われます。初回のインデックス作成時と、変更されたファイルおよび新しいコミットの増分再インデックス時です。コミットは 1 回だけ送信されます。
• contextatlas index はデフォルトですべての 3 種類を送信します（v1.2 以降）。ADR とドキュメントのみを送信するには、.contextatlas.yml で extraction.streams: [adr] を設定してください。/index-atlas スキルは Claude Code セッション内で ADR、docstring、コミットメッセージを同様に処理しますが、docs.include のページは抽出しません。
• contextatlas generate-adrs（CLI）は、代わりに構造情報を送信します。ソースファイルのパスと、言語サーバーが各ファイルについて列挙するシンボル名（トップレベルの宣言に加え、エクスポートの有無を問わずクラス、インターフェース、名前空間のメンバー）、さらに README.md、DESIGN.md、CLAUDE.md の全文と、--reference-context ドキュメントが送信されます。

どこにも送信されないもの：

• 上記の docstring テキストと、docs.include の glob に一致する（上記のとおり全文が送信される）ソースファイルを除く、ソースコード
• 上記のフィルター済みコミットメッセージを除く、Git の履歴
• LSP の参照情報と型情報
• 実行時のクエリ内容

ローカルにのみ保存されるもの：

• 抽出されたクレームのデータベース（デフォルトでは .contextatlas/index.db）
• 実行時のクエリ解決はすべて、このローカルの SQLite ファイルに対して行われます

クエリ時、つまり作業中に Claude が get_symbol_context を呼び出すたびに、ContextAtlas はローカルで SQLite を検索し、ローカルの LSP を呼び出します。ネットワーク通信はありません。モデル呼び出しもありません。通常の使用中に、コードがお使いのマシンの外部に出ることはありません。

インデックス作成時の抽出では、標準的な API 利用規約に従って Anthropic API を使用します。ADR、docstring、コミットメッセージに機密性の高いアーキテクチャ上の決定が含まれている場合、ほかの API 送信コンテンツと同様に、それらの規約に基づいて処理されます。

3 つのツール

3 つの MCP ツールは、並列に動作する 3 つの機能ではありません。3 つのアクセスパターンを備えた、統合されたコンテキスト基盤です。

get_symbol_context — 基本ツールです。「シンボルは分かっています。すべてください。」署名、ADR のクレーム、参照情報、Git の変更頻度、テスト、型をまとめた完全な情報を、1 回の呼び出しで返します。複数シンボルモードでは、1 回のリクエストで最大 10 個のシンボルを処理します（ADR-15 に基づきます）。

find_by_intent — セマンティッククエリの複合ツールです。「シンボルは分かりません。何をするものかで見つけてください。」ローカル SQLite FTS5 にインデックス化されたクレームテキストを対象に、BM25 で順位付けします。埋め込みサービスも外部呼び出しも不要で、決定論的な結果が得られます（ADR-09 に基づきます）。

impact_of_change — 影響範囲を調べる複合ツールです。「これを変更しようとしています。何が壊れますか？」基本ツールに加えて、Git の同時変更パターンとテストへの影響を示します。

発見しやすさの向上

ContextAtlas のアトラスは、一度構築し、コードや ADR の変更後に更新する基盤です。コホートの各パスには、標準のエントリーポイントを 1 つだけ設けます。動作は基盤の状態に応じて変わります。

	CLI	スキル
初回構築	contextatlas index（全抽出）	/index-atlas（全抽出）
更新	contextatlas index（Phase 4 SHA 差分増分処理）	/index-atlas（更新対応ワークフロー）

ADR-12 に基づく SHA 差分の増分更新は、初回構築より実質的に低コストです。変更されていない ADR と docstring ソースはスキップされ、すでに抽出済みのコミットが再抽出されることはありません。変更されたソースのみが再抽出されます。v1.2 以降、CLI の index はスキルと同様に、3 つのストリームすべて（ADR／ドキュメント、docstring、コミットメッセージ）を対象にします。設定の extraction.streams を参照してください。

クイックスタート

ステータス： v0.9.0 は 2026-05-16 にリリースされました。v1.0 の一般公開に向けた基盤は完成しています。パッケージはまだ npm に公開されていません。以下のインストール手順は、公開後の想定形式です。

実行要件：

• Node.js 20 以降。
• 設定する各言語の言語サーバー：
  • TypeScript — typescript-language-server（直接の依存関係ではなくピア依存関係として宣言されているため、バージョンを管理できます）。ContextAtlas と一緒にインストールしてください（例：npm i -D typescript-language-server typescript@6）。バージョン 4～6 がサポートされています。ネイティブ移植版の TypeScript 7 には tsserver.js が含まれていないため、typescript-language-server は実行できません。リポジトリでは TypeScript 5 または 6 を使用してください。
  • Python — PATH 上の Pyright（ピア依存関係でもあります）。
  • Go — PATH 上の gopls（go install golang.org/x/tools/gopls@latest でインストール）。
  • Ruby — ruby-lsp 0.26.x。プロジェクトの Gemfile で Bundler を使ってインストールする方法を推奨します（group :development の中に gem 'ruby-lsp', '~> 0.26.0', require: false を追加）。Rails プロジェクトでは、ruby-lsp-rails 0.4.x も有用です。Ruby 3.3 以降が必要です（4.0 以降を推奨）。
  • C# / .NET — PATH 上の csharp-ls 0.24.x（Roslyn LSP ラッパー）。dotnet tool install --global csharp-ls でインストールしてください。.NET SDK 8 以上が必要です（コホートのバックエンドの固定バージョンに合わせて、10 以降を推奨）。Windows では %USERPROFILE%\.dotnet\tools ディレクトリを PATH に含める必要があります。SDK のインストーラーが PowerShell の設定しか行わない場合でも、アダプターが Bash／Git-Bash 用に PATH を自動で補完します。

パス A — Claude Code スキル（60 秒、API キー不要）

npm install -g contextatlas
contextatlas init

続いて Claude Code で：

/generate-adrs   # Skip if you already have ADRs (any path; see Using existing ADRs below)
/index-atlas     # Build the atlas
/prime-atlas     # Verify connection (once per session)

パス B — CLI（90 秒、API キーが必要）

npm install -g contextatlas
export ANTHROPIC_API_KEY=sk-...
contextatlas init
contextatlas generate-adrs   # Skip if you already have ADRs (any path; see Using existing ADRs below)
contextatlas index
contextatlas doctor          # Verify health

既存の ADR とドキュメントを使用する

ContextAtlas は、すでにある ADR やドキュメントからアーキテクチャ上の意図を抽出します。generate-adrs は、既存の ADR 基盤がないリポジトリ向けです。

• docs/adr/ に既存の ADR がありますか？ generate-adrs はスキップしてください。ContextAtlas が既存の ADR を自動的に抽出します。
• ADR が別のパスにありますか？ .contextatlas.yml で adrs.path を設定してください（デフォルト：docs/adr/）。
• README、設計ドキュメント、その他の文章がありますか？ ContextAtlas は docs.include（デフォルト：README.md + docs/**/*.md）を通じて、これらも抽出します。追加のドキュメントを抽出するには、カスタムパスを追加してください。

抽出パイプラインは、設定で指定されたあらゆる文章ソースから構造化された主張を生成するため、既存の基盤が無駄になることはありません。スキーマの全容については、以下の設定を参照してください。

アトラスを最新の状態に保つ

contextatlas hooks install      # once per clone (init offers it; --yes accepts)
contextatlas hooks status       # hooks, run in progress, pending sources, last run
contextatlas index --structural # by hand: refresh symbols + git signal, no model calls
contextatlas index              # extract the pending sources (paid; preview first)
contextatlas refresh-claims     # or extract them on your Claude subscription (Tier 1)

フックは、各コミット、マージ、ブランチのチェックアウト後にバックグラウンドで contextatlas index --structural --no-export を実行します。これにより、モデルを呼び出したり atlas.json を変更したりせずに、ローカルキャッシュのシンボル、行番号、Git シグナルを最新の状態に保ちます。変更されたソースは、モデルを呼び出す index が抽出するまで .contextatlas/local/pending.json に記録されます（コミットされません）。実行中の MCP サーバーは、更新されたキャッシュをすぐに提供し、pull または index の実行によって atlas.json が変更されると、自動的に再読み込みします（atlas.committed: true）。

Tier 1（クレーム、サブスクリプションを利用）。 pre-push フックは、バックグラウンドで contextatlas refresh-claims --if-due を開始します。保留中のソースがある場合、ヘッドレスの Claude Code（claude -p、サブスクリプションのログインのみ。API キーに課金される場合は実行を停止）を通じて /refresh-atlas スキルを実行します。再抽出するソースは refresh.max_sources_per_run で指定した数までです。すべての docstring に変更がないソースは再抽出されません。自動実行では refresh.min_interval_minutes と refresh.max_utilization（前回の実行時に確認されたサブスクリプション使用量）が適用されます。refresh.auto_claims: false にすると、自動実行が無効になります。すべての実行は .contextatlas/local/refresh-log.jsonl に記録されます。push 時の実行に代えて、または push 時の実行に加えて、スケジュールに従って実行するには、次のようにします。

# cron (Linux/macOS): nightly at 02:30
30 2 * * * cd /path/to/repo && contextatlas refresh-claims --if-due

# Windows Task Scheduler
schtasks /Create /SC DAILY /ST 02:30 /TN "ContextAtlas refresh" ^
  /TR "cmd /c cd /d C:\path\to\repo && contextatlas refresh-claims --if-due"

MCP サーバーの登録

Claude Code の設定で ContextAtlas を MCP サーバーとして構成します。contextatlas が PATH 上にあるかどうかに応じて選択してください。

オプション A — PATH 上のグローバルバイナリ（例：npm install -g または npm link でインストール）：

{
  "mcpServers": {
    "contextatlas": {
      "command": "contextatlas"
    }
  }
}

オプション B — dist を直接呼び出す（グローバルインストールは不要）：

{
  "mcpServers": {
    "contextatlas": {
      "command": "node",
      "args": ["/absolute/path/to/contextatlas/dist/index.js"]
    }
  }
}

初回実行時の動作

• atlas.json がすでにコミットされている場合（チームメイトが先に実行した場合、またはリポジトリに含まれていた場合）、ContextAtlas は即座にインポートします。API 呼び出しはありません。数秒で使用できるようになります。
• まだアトラスがない場合、ContextAtlas は完全な抽出を実行します。ADR の数とサイズに応じて、1～10 分かかり、Opus API クレジット（CLI 経由）またはセッショントークン（Skills 経由）を数ドル分消費します。生成された atlas.json をコミットしておけば、以降のコントリビューターはこの手順を省略できます。
• 初回実行には docstring とコミットの処理も追加されます（v1.2 以降）。 CLI の index は、ドキュメントが付いたエクスポート済みシンボルごとに 1 回、フィルターを通過したコミットごとに 1 回、API を呼び出します。最初の呼び出しの前に、ストリームごとの呼び出し回数と入力トークン数、および費用の範囲を stderr に表示します。このリポジトリで最初に 3 ストリームを実行する場合、コミット 9d2bf4c 時点で API を呼び出さずに算出した予定数は 479 回（ADR／ドキュメントファイル 13 件、docstring 461 件、コミット 5 件）で、費用の見積もりは 4.42～10.35 ドルでした。 extraction.streams: [adr] を設定すると、抽出対象を ADR とドキュメントに限定できます。また、--budget-warn <usd> は、実行時の費用がしきい値を超えると警告します。
• 費用予測に関する注記。 v1.2 までは、プロンプトキャッシュの割引により、プラットフォーム上で請求される実費はスクリプトが報告する費用の約 3 分の 1 になることが多いと記載していました（v0.4：cobra 5.44 ドル → 1.82 ドル、httpx 5.53 ドル → 1.85 ドル、hono 10.89 ドル → 3.65 ドル）。この説明は誤りである可能性が非常に高いです。v0.4 のスクリプトが算出した費用には、古い 100 万トークンあたり 15 ドル／75 ドルの料金が使われており、実際の 5 ドル／25 ドルのちょうど 3 倍でした（v0.6 で修正）。また、抽出リクエストではプロンプトキャッシュを使用しません。5 ドル／25 ドルで算出される cost_usd は、請求額と一致することが見込まれます。これを 3 分の 1 にしたり、プレビューの費用範囲を 3 分の 1 にしたりしないでください。
• 2 回目以降の実行では、前回のインデックス作成から SHA が変わったファイルのみが再処理されます。通常は数秒です。

設定

リポジトリのルートに .contextatlas.yml を作成します。

version: 1
languages:
  - typescript
  - python
  - go
  - ruby
  - csharp
adrs:
  path: docs/adr/
  format: markdown-frontmatter
docs:
  include:
    - README.md
    - docs/**/*.md
git:
  recent_commits: 5
atlas:
  committed: true    # default; commits atlas.json to your repo
# extraction:
#   streams: [adr]   # CLI `index`: ADRs/docs only. Default: all three
#                    # (adr, docstring, commit). Must include adr.

全項目については、DESIGN.md の設定スキーマを参照してください。

方法論と誠実な限界

主張しないことを明示することで、信頼性を築きます。

統計的方法論。 すべての品質測定には、95％信頼区間を伴う対応のある t 検定を使用しており、p 値は使用していません。n=5 での NHST には統計的な意味がありません。信頼区間によって効果量を把握できるようにしています。閾値の事前登録は文面どおりに遵守しました（精度値の算出前に、オプション α の厳格な三段階の枠組みを確定）。

単一評価者モデル。 v0.5 の品質測定では、評価者として Sonnet 4.6 を使用し、軸ごとの評価者内一貫性は 80％以上です（pass-1 対 pass-2）。評価者パネルのベンダー横断での本格導入は v1.0 以降の作業です。

ベンチマーク対象リポジトリは3つ。 定量的な主張の対象は、hono（TypeScript、186 ファイル）、httpx（Python、23 ファイル）、cobra（Go、19 ファイル）、および自社でのドッグフーディングに限定されます。これらを超える一般化は、ローンチ後のコホートで検証します。

v0.5 の基盤範囲。 品質軸の測定は、5つのアンカーセル × n≥5 の試行 × 2つの条件です（hono h1 は自動的に n=8 まで拡張）。完全なマトリックスでの再現ではありません。マトリックスの全項目を完了させる段階への移行は v1.0 以降です。

v0.6 のサイクル横断再現に関する注意点。 v0.6 で対象を絞ったマトリックス再現サブセット（8セル × n=5）では、v0.5 のアンカーセルと比べ、4つの品質軸のうち2つで効果の減衰が見られました（factual_correctness は CLEAN から BORDERLINE に、actionability は BORDERLINE から判別不能に変化）。根本原因は、v0.5 の測定が以前のアトラスバージョンを対象としており、サイクル横断の方法論でアトラス基盤バージョンを統制していなかったことです。因果関係の全面的な調査はローンチ後に行います。詳細はフェーズ10の参考ドキュメントをご覧ください。

v0.3 の単一実行方法論。 フェーズ8ではセルごとに n=1 を報告しています。品質軸のブラインド評価測定は v0.5 で追加されました。フェーズ8での Beta 対 Beta+CA の報告には、アトラスファイルの可視性に関する注意点があります（バイアスの方向は保守的であり、CA の実際の貢献は公表値が示すより大きい可能性があります）。

ドッグフーディングは測定済みのベンチマークではありません。 開発期間を通じて、ContextAtlas は自らの ADR をインデックス化し、ContextAtlas 自体の開発作業で Claude Code とともに使用しています。これは開発上の実践であり、4条件マトリックスには含まれません。マトリックスの実行対象は、3つの外部ターゲットのみです。

有利な結果も不利な結果も公開しています。 フェーズ7のハーネス間の非対称性に関する仮説は、v0.3 の基盤で反証されました。v0.6 のアトラス基盤バージョンの交絡要因も明らかにし、開示しました。Tie と trick のバケットでは、CA の差し引き効果がマイナスになることが常に確認されています。こうした結果は埋もれさせず、該当箇所で報告しています。

ステータスとロードマップ

現在: v0.9.0（2026-05-16 リリース）。v1.0 の一般公開に向けた基盤が完成しました。公開に向けた実行作業は、個別の v0.9.1 タグを作成せず、v1.0.0 に組み込まれます。

最近のサイクルの主な成果（各サイクルの全スコープについては docs/release-history.md を参照してください）：

• v0.9（5月16日）： Ruby アダプターをリリース — ADR-21 に基づき、ruby-lsp + ruby-lsp-rails を使用して、4つ目の対応言語を追加しました。リポジトリの公開基盤（MIT ライセンス + コミュニティ向け基盤 + サイクルドキュメントを docs/cycles/v0_X/ に移行）が完成しました。公開に向けたポジショニング作業は進行中です。
• v0.8（5月14日）： 基盤の同等性 + パスの比較可能性 + BM25 の有効化。hono/httpx/cobra ベンチマークで、主張比率 65～83% を達成し、CLI に対する Skill 基盤の同等性を確立しました。
• v0.7（5月12日）： 公開に向けたサイクル — エントリーポイントで決定する Path-3 アーキテクチャ（ADR-02 の正式採用に基づく CLI/Skills の同等性）+ generate-adrs 機能に、validate-adrs による標準的な深さの下限チェックを追加しました。
• v0.6（5月9日）： パイプラインの仕組み + 対象を絞ったマトリックス再現のサブセット（8セル × n=5 × 2条件）。F1 の主要な交絡要因として、アトラス基盤のバージョンが明らかになりました。完全な因果関係の調査は公開後に延期されました。
• v0.5（5月4日）： 品質評価手法のサイクル — LLM 判定ハーネス + ADR-19 に基づくペアモードの匿名化 + ペア t 検定の統計プリミティブ（ADR-19 §4 の改訂）。V1.0 のリリースゲート基準 #1 の括弧内項目が完了しました。
• v0.4（4月29日）： 基盤の堅牢化 — 2つのレディネスシグナル（ADR-18）による LSP のタイミング競合への耐性 + コスト予測に関する免責事項 + ドッグフードの基礎整備 + doctor 診断スクリプト。
• v0.3（4月28日）： アトラス精度向上サイクル — ADR-15 に基づく、より限定的な帰属範囲 + 複数シンボル API + contextatlas_commit_sha を含むアトラススキーマ v1.3 + Phase 8 のクロスターゲット検証（45～72% の範囲）。
• v0.2（4月25日）： 3言語のベースライン — ADR-14 に基づく gopls 経由の Go アダプター + 言語横断的な cobra/httpx の参照実行。
• v0.1（初期 MVP）： 3つの MCP ツール + TS/Python アダプター + Opus 4.7 抽出パイプライン + SQLite による増分再インデックス + Phase 5 の hono 参照実行（アーキテクチャ上の優位性があるプロンプト群で、ツール呼び出しを 50～71% 削減）。

ロードマップ（v1.0 以降）：

• 引き継いだ募集基盤を活用したコホートへの提供（v1.0 リリースゲート基準 #3）
• ベンチマークマトリックスの完全な完了 + ベンダー横断型の判定パネル
• find_by_intent 向けのセマンティック埋め込みレイヤー（エビデンスに基づいて導入）
• タスクに応じたバンドルクエリ：why_does_this_fail、 onboard_to_feature、audit_change
• 需要に応じて言語アダプターを追加：Rust、Java、Kotlin
• Markdown 以外の意図ソース：RST、AsciiDoc

マイルストーンの詳細な経緯と各サイクルのスコープについては、 ROADMAP.md、docs/cycles/、 docs/release-history.md、および research/v1.1-candidates.md を参照してください。

言語サポート

言語アダプターのインターフェースは安定したプラグイン向け拡張ポイントです。新しい言語はそれぞれ、コアを変更せずに追加できます。貢献者向けのオンボーディング手順については、 docs/language-adapter-guide.md を参照してください。

言語	アダプター	LSP サーバー	リリース
TypeScript	TypeScriptAdapter	typescript-language-server	v0.1
Python	PyrightAdapter	Pyright	v0.1
Go	GoAdapter	gopls	v0.2
Ruby	RubyAdapter	ruby-lsp (+ ruby-lsp-rails)	v0.9
C# / .NET	CsharpAdapter	csharp-ls (Roslyn)	v1.1

貢献

ContextAtlas は MIT ライセンスで公開されており、貢献を歓迎しています。特に、次の分野での貢献が役立ちます。

• 新しい言語アダプター。 LanguageAdapter インターフェースは小規模で安定しています。Java、.NET、Rust、Kotlin などの言語サポートの追加は、独立して取り組めるプロジェクトです。docs/language-adapter-guide.md をご覧ください。
• Markdown 以外の意図ソース。 現在は YAML フロントマター付きの Markdown 形式の ADR をサポートしています。RST、AsciiDoc、その他の形式も歓迎します。
• ベンチマーク用リポジトリ。 より多くのコードベースでベンチマークの範囲を広げることで、評価の強化につながります。

ベンチマークと方法論

ベンチマークと方法論は、別のリポジトリで管理されています。 github.com/traviswye/ContextAtlas-benchmarks。 このリポジトリには、ハーネスコード、固定されたプロンプトセット、公開済みの測定結果、そして方法論の全容を記したドキュメント（RUBRIC.md）が含まれています。ハーネスをこのリポジトリから分離することで、ベンチマークは内部のモノレポビルドではなく、公開されている contextatlas パッケージの実際の動作を測定できます。

クレジット

「Build anything with Opus 4.7」ハッカソンで開発されました。

ContextAtlas は次のものを使用しています。

• インデックス作成時の意図抽出に Claude Opus 4.7
• TypeScript のシンボル解決に typescript-language-server
• Python のシンボル解決に Pyright
• Go のシンボル解決に gopls
• Ruby のシンボル解決に ruby-lsp
• C# / .NET のシンボル解決に csharp-ls（Roslyn LSP ラッパー）
• インデックスストアに better-sqlite3
• MCP サーバーの実装に @modelcontextprotocol/server（MCP TypeScript SDK v2）

ライセンス

MIT。LICENSE をご覧ください。