コードベースコンテキストドキュメント は何をしますか？
リポジトリルートにコンパクトな CLAUDE.md を生成し、.claude/docs/ 配下に詳細なファイル群を作成します。
目的は「プロジェクトを文書化すること」ではありません。目的は次のとおりです：将来のエージェントが初回のターンから効果的に動作し、かつトークンを可能な限り節約できるようにすること。 CLAUDE.md は毎回のターンで常にコンテキストに読み込まれます。その中のすべての行は「税金」です。ある行が価値を持つのは、それによってエージェントがまだ見たことのないタスクに対する行動が変わる場合のみです。それ以外のものはすべて .claude/docs/ に属し、関連する場合にのみ読み込まれます。
このトレードオフが、以下のすべてのルールを駆動します。
ワークフロー
以下の順序に従ってください。最初に CLAUDE.md を書くことは最も一般的な失敗です。もっともらしく聞こえる推測だらけのファイルができ、ドキュメントはコードに合わせるのではなく、その推測に合わせて書かれることになります。
- 調査 — リポジトリを機械的に調べます（以下のコマンドを使用）。
- 読み取り — エントリポイント、設定、代表的なソースコードの一部を読みます。
.claude/docs/*.mdを作成 — 詳細はここに記述します。- 最後に
CLAUDE.mdを作成 — これは、学習した内容の索引です。 - 検証 — 行数、各コマンド、各
file:lineを確認します。
ステップ1 — 調査
何かを読む前に、これらを実行してください。コストは低く、サイズ、言語構成、ツールに関する誤った推測を防ぎます。
# 形状と規模
git ls-files | wc -l
git ls-files | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -40
git ls-files | grep -oE '\.[a-z0-9]+$' | sort | uniq -c | sort -rn | head -20
# ツールとエントリポイント（見つかったすべてのファイルを読むこと）
ls -a
git ls-files | grep -iE '(package\.json|pyproject\.toml|setup\.py|requirements.*\.txt|Cargo\.toml|go\.mod|pom\.xml|build\.gradle|Gemfile|composer\.json|pubspec\.yaml|Makefile|justfile|Taskfile|docker-compose|Dockerfile)'
git ls-files '.github/workflows/*' '.gitlab-ci.yml' '.circleci/*'
# 既存のドキュメント — これらを読むと、コードからは推測できない意図がわかる
git ls-files | grep -iE '(readme|contributing|architecture|adr|docs/)' | head -30
# 最近の活動は、リポジトリのどの部分が実際にアクティブかを示す
git log --oneline -15
git log --pretty=format: --name-only -n 200 | sort | uniq -c | sort -rn | head -20
調査で 見つからなかった ものに注意してください。CI設定やテストディレクトリがないリポジトリは、埋めるべきギャップではなく、実際の発見事項です。
ステップ2 — 読み取り
以下の順序で読んでください：
- マニフェストファイル（
package.json、pyproject.toml、…） — スクリプト/タスクセクションを含め、端から端まで。実際のコマンドはここにあります。 - CIワークフローファイル — CIが実行するコマンドは、実際に動作するコマンドです。
README.mdおよびCONTRIBUTING.md/docs/— コードからはわからない 理由 のため。- アプリケーションのエントリポイント、次に主要ディレクトリに分散した5～15個の代表的なソースファイル。
リポジトリが大きく、サブエージェントが利用可能な場合は、ソースコード読み取りパスに並列サブエージェントを使用してください。主要ディレクトリごとに1つずつ、各ディレクトリの役割、使用パターン、それらのパターンの file:line アンカーを報告させます。これにより高速化され、生のファイルダンプがメインコンテキストに入るのを防げます。
読み取り中は、各パターンを見つけた正確な場所 path/to/file.ts:142 とともに、候補パターンの実行リストを保持してください。後でこれらのアンカーが必要になり、後から見つけ直すのはコストがかかります。
ステップ3 — .claude/docs/ を作成
コードベースが実際にサポートするファイルのみを作成してください。空または水増しされたドキュメントは、存在しないよりも悪質です。なぜなら、エージェントにセット全体を信用しないよう教えてしまうからです。
| ファイル | 作成する条件 | 内容 |
|---|---|---|
architectural_patterns.md | 常に（リポジトリがごく小規模でない限り） | 繰り返される構造的決定：DI、状態管理、エラーハンドリング、モジュール境界、API設計規則、レイヤリングルール |
testing_strategy.md | テストが存在する場合 | フレームワーク、テストの場所、フィクスチャ/ファクトリの規則、1つのテストとスイート全体の実行方法、モック対象と実際の対象 |
build_and_deploy.md | ビルドツールやCIが自明でない場合 | ビルドパイプライン、環境変数とその宣言場所、成果物、リリース/デプロイフロー、ローカル開発セットアップの注意点 |
data_model.md | 永続データ、スキーマ、またはマイグレーションが存在する場合 | コアエンティティとリレーションシップ、スキーマ/マイグレーションの場所とワークフロー、バリデーションレイヤー |
api_reference.md | プロジェクトが重要なAPIを公開または利用している場合 | ルート/エンドポイントの構成、リクエスト/レスポンスの規則、認証、バージョニング、エラーの形式 |
コードベースにこれらのカテゴリに当てはまらない大規模なサブシステムがある場合、ドメイン固有のファイル（realtime_sync.md、billing.md など）を追加しても構いません。多数の薄いファイルよりも、少数の実質的なファイルを優先してください。
複数ファイルの証拠ルール
これは、有用なパターンドキュメントと幻覚を見たドキュメントを区別するルールです。
少なくとも3つの異なるファイルでパターンを見た場合にのみ文書化し、そのうち少なくとも2つを引用すること。 1つの巧妙な抽象化はトリビアに過ぎません。コードベース全体で繰り返される規則こそ、新しいエージェントが適合するコードを書くために従わなければならないものです。
パターンのように見えるが1回しか出現しないものを見つけた場合、それを削除するか、grepで一般化を確認してください：
rg -n 'useAppDispatch' --stats # どの程度普及しているか？
rg -l 'implements Repository' | head # どのファイルがこの形状を共有しているか？
規則が一貫して適用されていない場合（コードベースの半分が一方の方法、もう半分が別の方法）、その旨を明示的に述べ、どちらが新しいかを記してください（ファイルの git log でわかります）。コードベースが移行途中であることを知っているエージェントは、均一性を仮定するものよりも良いコードを書きます。
スニペットではなくアンカーで参照
クラスを貼り付けるのではなく、src/services/base.py:34 を参照してください。スニペットは誰かがファイルを編集した瞬間に古くなり、古くなったスニペットは積極的に誤解を招きます。一方、古くなった行番号は明らかに再確認する価値があります。また、これによりドキュメントが短く保たれ、読める状態が維持されます。
シンボル名を行と一緒に含めることで、軽微な編集に対してアンカーが耐性を持ちます：PaymentProcessor.execute — src/billing/processor.py:88。
コードスタイルはそのままに
ユーザーはリンターやフォーマッターを実行します。インデント、引用符のスタイル、行の長さ、インポート順序、命名のケーシングについては文書化しないでください。これらは機械的に強制されるものであり、常に読み込まれるファイルに記述することは、ツールを複製するためにコンテキストを消費することになります。リンターが強制できない規則（どのレイヤーがどのレイヤーをインポートしてよいか、いつマイグレーションを追加すべきか、新しいルートがどこで自身を登録するか）は文書化してください。
ステップ4 — CLAUDE.md を作成
厳守：150行未満。以下の構造を使用してください：
# <プロジェクト名>
<2～4文：このプロジェクトが何であり、誰/何にサービスを提供するか。WHY —
それが解決する問題。これはコードから推測できない部分なので、最も注意深く書く価値があります。>
## 技術スタック
<コンパクトなリスト：言語 + バージョン、フレームワーク、データベース、主要インフラ。
コードの書き方に影響を与えるもののみ。推移的な依存関係のダンプは省略。>
## プロジェクト構造
<トップレベルディレクトリのテーブルまたはリスト。各行に、そこに何があるか、そして
自明でない場合に何が*ない*かを記述。>
## コマンド
<検証済みで広く有用なコマンドのみ：install、dev、build、test、
test-a-single-file、lint、typecheck。エコシステムのデフォルトでない場合はパッケージマネージャーを記載。>
## 規則
<3～8行。リポジトリ全体に適用され、リンターではキャッチできないルールのみ。
特定のサブシステムに固有のルールは、代わりにドキュメントファイルに属します。>
## 追加ドキュメント
タスクが必要とする場合にこれらを読んでください — 予防的に読み込まないでください。
- `.claude/docs/architectural_patterns.md` — <いつ読むか>
- `.claude/docs/testing_strategy.md` — <いつ読むか>
「追加ドキュメント」セクションが機能するか失敗するかは、2つのことにかかっています：
- 各エントリは、何を含むかではなく、いつ読むべきかを記載します。「エンドポイントを追加したりレスポンス形式を変更する前に読む」はエージェントを正しく導きますが、「APIを文書化する」はそうではありません。
- このリストは、専門的な詳細が参照される唯一の場所です。もしテスト設定の説明を
CLAUDE.mdとtesting_strategy.mdの両方に書いていることに気づいたら、CLAUDE.mdから削除してください。
CLAUDE.md と各ドキュメントファイルの完成例については、references/templates.md を参照してください。
ステップ5 — 検証
このステップを省略しないでください。このタスクのすべての失敗モードは、自信に満ちた口調の虚偽であり、そしてそのどれもが安価に発見できます。
wc -l CLAUDE.md # 150未満でなければならない
次に：
- 書き留めたすべてのコマンドを実行するか、少なくともそれぞれがマニフェスト/CI設定に存在することを確認します。
package.jsonにないnpm testがCLAUDE.mdにあると、将来のセッションごとにエージェントの時間を無駄にします。コマンドを実行できない場合は、「検証済み」ではなく「ソースから読み取った」とマークしてください。 - すべての
file:lineをスポットチェック — いくつかを開き、引用されたシンボルがそこにあることを確認します。 CLAUDE.mdを新たな気持ちで読み直します。このリポジトリを初めて見るエージェントとして。自分の行動を変えない行はすべて削除します。一般的なアドバイス（「クリーンなコードを書け」、「エラーを適切に処理せよ」）はよくある違反者です。- 最終的な行数と作成したファイルのリストを報告します。
CLAUDE.md が150行を超える場合は、圧縮するのではなく削減します。セクション全体をドキュメントファイルに移動し、1行の索引を残します。収まるように散文を詰め込むと、誰も解析しない密集したファイルになります。
既存のCLAUDE.mdを扱う
既に存在する場合は、盲目的に上書きしないでください。まずそれを読み、次に現在のコードに対して検証します。存在しなくなったコマンド、名前が変更されたディレクトリ、移行されたパターンなどです。コードからは導き出せない人間の好みをエンコードした手書きの指示（「ベンダーSDKには決して触れるな」、「依存関係を追加する前に確認せよ」）は保持してください。それらはファイルの中で最も価値の高い行であり、最も破壊されやすいものです。実質的なものを削除する前に、何を削除するのか、なぜ削除するのかをユーザーに示してください。