Claude Codeで新メンバー向けアーキテクチャ概要を書く — 根拠つきで残す

新メンバーの手元で最初に詰まるのは、設計思想ではなく「どこから読み始めるか」「設定はどこにあるか」「テストはどう回すか」の3点です。Claude Codeに「このコードベースの概要を教えて」と頼めば説明は返ってきますが、その場で消える会話を、リポジトリに残るdocs/architecture.mdに変えるには、もうひと手間かけます。

この記事では、Claude Codeに下書きを書かせ、主張ごとにファイルパスを添えさせ、コマンドで検算してから残す手順をまとめます。探索そのものの進め方は大規模コードベースを探索するコツにあり、ここでは「探索の結果を他人が読める文書にする」側を扱います。

新メンバー向けの文書には、Claude Codeの組み込みコマンドで作れるものもあります。/team-onboardingは、直近30日の利用履歴から「Claude Codeの使い方とチームの作業習慣」を伝えるガイドを作るコマンドで、詳しくは/team-onboardingの使い方にあります。この記事のdocs/architecture.mdは役割が違い、コードの入口・設定・テストの回し方を、根拠のパスつきでリポジトリに残す文書です。

新メンバーの迷いは3点に絞れる

アーキテクチャ概要というと、レイヤー図やデータモデルの全体を描きたくなります。ただ、初週に読み手が実際に手を止めるのは、次の3点です。

ディレクトリ構成と依存の向きは、この3点を読み解く地図として添えます。網羅しようとすると文書が長くなり、更新されなくなります。

docs/architecture.mdの骨子を先に決める

Claudeに白紙から書かせると、一般論の多い文書になりがちです。節の見出しと、各節に必要な根拠の種類を先に固定しておくと、下書きの質が揃います。

「落とし穴」の節は、公式のベストプラクティスがCLAUDE.mdに残すべきものとして挙げる「コードが誤解を招く箇所」と同じ性質です。コードを読めば分かることは書かず、読んでも分からないことに紙面を使います。

手順: 根拠つきの下書きを書かせる

Claude Codeはプロジェクトのルートで起動します。公式のプロンプト例にある「give me an overview of this codebase」や「explain the main architecture patterns used here」に近い質問から入り、ここでは出力形式を指定して文書化まで進めます。

下書きを頼むプロンプトは、たとえば次の形です。

docs/architecture.md の下書きを作って。読み手は入社1週間のメンバー。
節は「入口」「ディレクトリ構成」「依存の向き」「設定」「テスト」「落とし穴」。
どの主張にも、根拠になるファイルパスを括弧で添えて。
コードで確認できなかったことは書かず、末尾に「未確認」として列挙して。
テストのコマンドは実際に実行して、通ったものだけを書いて。

最後の2行が効きます。確認できなかった項目を「未確認」として分けさせると、憶測が本文に混ざりません。テストコマンドを実際に走らせるのは、公式が勧める「合否が返るチェックを持たせる」やり方と同じ考え方です。ベストプラクティスは、Claudeに「実行したコマンドとその出力」という証拠を求めることも勧めています。

出来上がる文書は、例えば次のような形になります。これは架空のTypeScript製APIを想定した例示で、実在するリポジトリの出力ではありません。

## 入口
- HTTPサーバーは `src/server.ts` で起動し、ルーティングは `src/routes/index.ts` に集約(根拠: 同ファイル)
- バッチは `scripts/nightly.ts`。cronから呼ばれる(根拠: `.github/workflows/nightly.yml`)
 
## 依存の向き
- `routes/` → `services/` → `repositories/` の一方向(根拠: `.dependency-cruiser.cjs` の forbidden ルール)
 
## テスト
- 全件: `pnpm test`
- 1ファイル: `pnpm vitest run src/services/user.test.ts`
- 統合テストは `DATABASE_URL` が要る(根拠: `.env.example`)
 
## 未確認
- `src/legacy/` を今も呼ぶ箇所があるか

根拠がパスで書かれていれば、読み手は疑った瞬間に自分で開いて確かめられます。

根拠を検算してから残す

Claudeの下書きは、読んで自然でも、パスや関数名が1文字違うことがあります。検算は機械的にできます。まず、文書中のパスが実在するかを一括で調べます。

grep -o '`[A-Za-z0-9_./-]*/[A-Za-z0-9_.-]*`' docs/architecture.md \
  | tr -d '`' | sort -u \
  | while read p; do [ -e "$p" ] || echo "MISSING: $p"; done

MISSINGと出たパスは、その主張ごと見直します。パスがあっても内容が合っているとは限らないので、「入口」と「テスト」の2節だけは、書かれたとおりに操作します。

1. 入口に書かれた起動コマンドを実行し、起動することを見る
2. テストの3種類のコマンド(全件・1ファイル・1ケース)を順に実行する
3. 設定の節にある必須の環境変数を外して起動し、書かれたエラーになるかを見る

3つ目は、手順の抜けを拾うのに有効です。必須と書かれた変数を外しても動くなら、その記述は古いか誤りです。

依存の向きは機械で確かめてから書く

アーキテクチャ概要で最も崩れやすいのが「依存の向き」です。「routesはservicesだけを呼ぶ」といった記述は、Claudeがコードを読んで推測した結果に過ぎず、実際には層をまたぐimportが残っていることがあります。

import文を数えたり、依存検査ツールの出力を貼ったりして裏を取ります。循環依存や層またぎの検出と修正は、dependency-cruiserの循環依存と層またぎ違反の手順がそのまま使えます。違反が残っているなら、概要には「原則はこの向きだが、次の箇所が例外」と例外ごと書きます。違反を伏せた綺麗な図は、読み手が最初に例外へ当たった時点で信頼を失います。

入口についても同じです。タスクの入口をJustfileのようなファイルに寄せているリポジトリなら、Justfileを入口にする方法でjust --listの出力をそのまま「入口」の節の根拠にできます。

CLAUDE.mdに写さず、場所だけを指す

docs/architecture.mdができると、CLAUDE.mdに@docs/architecture.mdと書いてClaudeにも常に読ませたくなります。ただし、@pathのimportは、取り込んだファイルをCLAUDE.mdと一緒にコンテキストへ読み込みます。公式のメモリ解説は、importが長いファイルの整理には役立つ一方で、コンテキストの消費は減らさないと説明しています。

しかもCLAUDE.mdの目安は1ファイル200行未満で、「Claudeがコードから読み取れないこと」だけを置くのが推奨です。数百行の概要を丸ごと取り込むと、毎回のセッションで全員分のコストを払います。

/initが作るのは、ビルドコマンドやテスト手順、規約といった、Claudeへの短い指示を並べたCLAUDE.mdの初版です。人が読む根拠つきの概要を担うのはdocs/architecture.mdで、2つは目的が別です。

そこで、CLAUDE.mdには場所と使いどころだけを書きます。

# Docs
- 構成・入口・テストの回し方は `docs/architecture.md` を参照(必要なときだけ読む)

パスをバッククォートで囲むと、importではなくただの文字列になります。メモリ解説にも、importを避けてパスだけ書くにはバッククォートで囲むとあります。Claudeは必要になった時点で、自分でそのファイルを開きます。新メンバーが人間として読む用途と、Claudeが参照する用途を、1つのファイルで両立できる形です。

CLAUDE.mdが長くなりすぎた場合の切り分けはCLAUDE.md is too long警告の直し方にまとめています。

古くなる文書を保つ

アーキテクチャ文書は、書いた翌月から古くなります。人が気づく前に拾う仕組みを、2つ入れておきます。

1つは、前節のパス実在チェックを定期的に回すことです。MISSINGが出たら、リネームや削除が文書に反映されていません。もう1つは、構成を変えるPRの作成時に、Claudeへ差分の確認を頼む運用です。

このブランチの差分で、docs/architecture.md の記述が事実と合わなくなる箇所はある？
パスの変更、依存の向きの変更、テストコマンドの変更に絞って確認して。

テストコマンドの記述は、VitestのコマンドをCLAUDE.mdに書くのように、フレームワーク別の書き方に合わせておくと、変更時の差分も追いやすくなります。

つまずきやすい点

もう1つ、@でディレクトリを参照すると渡されるのはファイル一覧であって、中身ではありません。@src/componentsのように指して構成を聞くのは目次づくりには向きますが、各ファイルの責務は読まれないまま答えが返ります。責務まで書かせるなら、代表的なファイルを@で個別に指すか、読んで説明するよう頼みます。

起動場所も効きます。サブディレクトリからclaudeを起動すると、その配下しか見えません。リポジトリ全体の概要を書かせるなら、ルートから起動します。

まとめ

アーキテクチャ概要は、広さより「読み手が疑ったときに確かめられること」で価値が決まります。主張にはパスを添え、依存の向きは検査ツールで裏を取り、テストコマンドは実際に走らせたものだけを残します。CLAUDE.mdには中身を写さず、場所だけを指しておくと、人にもClaudeにも同じ文書が使えます。まず「入口」「設定」「テスト」の3節だけでも、新メンバーの初日に渡せる状態にするのが現実的な出発点です。