2025年12月08日·1 分
Claude Code によるコードベースのオンボーディング：アプリをマップするプロンプト
Claude Code を使ったコードベースのオンボーディング：Q&A プロンプトでモジュール、主要フロー、リスクをマップし、そのメモを短いオンボーディング文書にまとめます。
Claude Code を使ったコードベースのオンボーディング：Q&A プロンプトでモジュール、主要フロー、リスクをマップし、そのメモを短いオンボーディング文書にまとめます。
ファイルをランダムに読んでいると遅く感じるのは、ほとんどのコードベースが物語のように整理されていないからです。フォルダを開いて、重要そうな名前が10個見え、1つをクリックするとヘルパーや設定、エッジケースに迷い込む。1時間経っても細かい情報は増えているのに、アプリの動きが説明できない──という状況になりがちです。
オンボーディング時にClaude Codeに求めるべきは、シンプルなメンタルマップを作ることです。その地図は次の3つに答えるべきです：
1～2日で「十分な」オンボーディングとは、全てのクラスを説明できることではありません。より現実的なのは次のような状態です：
深いリファクタリングや、すべての抽象化を完全に理解すること、古い使われないコードを読破することは、最速の実利を生み出すことが少ないため後回しで構いません。
オンボーディングを「通りの暗記」ではなく「地図作り」と考えてください。プロンプトは常に「今、システムのどこにいるか、次に何が起きるか、ここで何が壊れる可能性があるか？」に戻すように作ります。それができれば、細部は必要に応じて学べます。
質問を始める前に、通常初日に必要とする基本事項を集めておきます。Claude Codeは実際のファイルや設定、再現可能な挙動に反応できると最も効果的です。
まずはアクセスと動作確認を用意しましょう。リポジトリをクローンし、依存関係をインストールし、アプリ（あるいは最小のスライス）をローカルで起動できることを確認します。ローカルセットアップが難しければ、ステージング環境やログが見られる場所へのアクセスを得て、コードが実際に何をしているかを検証できるようにします。
次に「真実の元（source of truth）」となるドキュメントを探します。チームが実際に変更時に更新するものを探してください：README、短いアーキテクチャノート、ADR フォルダ、runbook、デプロイノートなど。乱雑でも、モジュールやフローの名前が得られるので Q&A が精度を増します。
スコープは早めに決めてください。多くのリポジトリには複数のアプリ、サービス、共有パッケージが含まれます。境界を「API と billing worker のみ」や「Web アプリとその認証フローのみ」といった形で決めると無限の寄り道を防げます。
アシスタントに勝手に推測してほしくない前提は書き出しておきましょう。小さなことに思えても、後で間違ったメンタルモデルに時間を奪われるのを防げます。
シンプルな準備チェックリスト：
何かが欠けていれば、それをチームメイトへの質問として残してください。欠けたコンテキストを推測で補うのは避けましょう。
メンタルマップは、アプリの主要パーツ、相互のやり取り、そしてどこが問題を起こしやすいかを簡潔に答えるメモ群です。うまくやれば、オンボーディングはファイル閲覧ではなく再利用できる図の構築になります。
まず出力物を定義します。モジュール一覧は実用的であれば十分です。各モジュールについて、何を担当しているか、誰がオーナーか（分かれば）、主要な依存（他モジュール、サービス、DB、外部 API）を記録します。またメインのエントリポイント（UI ルート、API エンドポイント、バックグラウンドジョブ、スケジュールタスク）もメモします。
次に、重要なユーザージャーニーを数件選びます。3～5件で十分です。お金、権限、データ変更に触れるフローを選んでください。例：サインアップとメール検証、有料プラン作成や購入、管理者によるユーザー権限変更、日常的に使われる重要なフローなど。
リスクのラベリング方法を決めてからメモを取り始めると後で見直しやすいです。シンプルなカテゴリ（セキュリティ、データ整合性、稼働時間、コスト）で十分です。リスクに印を付けたら「なぜそれが危険か」を一文で書き、何を確認すれば安全といえるか（テスト、ログ、権限チェック）も追記します。
一貫したフォーマットを使うと、メモをオンボーディング文書にそのまま変換しやすくなります：
例：Checkout が Billing を呼び、payments と invoices に書き込むなら、データ整合性とコストのリスクとしてタグ付けし、再試行の場所や二重課金を防ぐ仕組みを書きます。
新しいリポジトリに入るときは、早い段階での方針把握を目指してください。以下のプロンプトは小さく安全なステップでメンタルマップを作るのに役立ちます。
まずはリポジトリツリー（または一部）を渡してツアーを依頼します。各ラウンドは焦点を絞り、最後に次に読むべきファイルを1つだけ教えてもらうようにしてください。
1) Repo tour
"Here is the top-level folder list: <paste>. Explain what each folder likely contains and which ones matter for core product behavior."
2) Entry points
"Find the app entry points and boot process. What files start the app, set up routing, configure DI/env, and start background jobs? Name the exact files and what they do."
3) Module index
"Create a module index: module name, purpose, key files, and important external dependencies. Keep it to the modules that affect user-facing behavior."
4) Data model hints
"Based on migrations/models, list the key tables/entities, critical fields, and relationships. Call out fields that look security-sensitive or used for billing/permissions."
5) Flow trace
"Trace this flow end-to-end: <flow>. Where does the request/event start, where does it end, and what does it call in between? List the main functions/files in order."
6) Next inspection
"What should I inspect next and why? Give me 3 options: fastest clarity, riskiest area, and best long-term payoff."
具体例：ユーザーが「サインアップして最初のプロジェクトを作る」フローをマップするなら、API ルートハンドラ、バリデーション、DB 書き込み、メールやリソースプロビジョニングの非同期ジョブを順に聞きます。その後「ユーザーがプロジェクトを削除する」フローを再度トレースしてクリーンアップ漏れを探します。
回答を実行可能にするため、単なる要約ではなく特定の成果物を要求してください：
最大の勝利は、散在する Q&A を他の開発者が再利用できるノートに変えることです。自分だけにしか分からないメモだと、同じ探検を何度も繰り返すことになります。
シンプルな構造が長い文章より優れます。各探索セッションの後は、回答を5つの小さな成果物（一つのファイルやドキュメントで可）に保存してください：モジュール表、用語集、主要フロー、不明点、リスクレジスタ。
以下は貼り付けて埋めていけるコンパクトなテンプレートです：
Module table
- Module:
Owns:
Touches:
Entry points:
Glossary
- Term:
Meaning:
Code name(s):
Key flow (name)
1.
2.
3.
Unknowns
- Question:
Best person to ask:
Where to look next:
Risk register
- Risk:
Location:
Why it matters:
How to verify:
主要フローは短く保つのが意図です。例：1) ユーザーがサインイン、2) バックエンドがセッションを作成、3) クライアントがダッシュボードをロード、4) API がデータをフェッチ、5) UI がレンダリングしてエラー処理を行う。フローが5ステップに収まらない場合は（ログインとダッシュボードロードのように）分割してください。
Claude Code を使うときは、各回答の末尾に「How would I test this?（どうテストするか）」を一行追加する習慣をつけてください。受動的なメモがチェックリストに変わり、不明点とリスクが重なったときに実行できる手順になります。
もし Koder.ai のような vibe-coding プラットフォームで作業しているなら、この種のノートは生成変更の副作用を見つけるのに役立ちます。タッチポイントの多いモジュールは変更の磁石になりやすいです。
リスクはランダムではありません。認証、状態変更、外部システムとのやり取り、バックグラウンド処理の辺りに集まります。ターゲットを絞った質問と数回の検索で多くを見つけられます。
まずはアイデンティティから始めます。認証がどこで行われているか（ログイン、セッション、トークン）と、認可決定がどこにあるか（ロールチェック、フラグ、所有権ルール）を尋ねてください。よくある落とし穴はチェックが UI、API ハンドラ、DB クエリに散らばっていて一元管理されていないケースです。
次に書き込み経路をマップします。レコードを作成/更新/削除するエンドポイントや、時間とともにデータを変えるマイグレーションを見つけます。バックグラウンドジョブも含めてください。多くの謎のバグは、リクエスト後に非同期ワーカーが予期せぬ値を書き込むところから来ます。
リスクを素早く浮かび上がらせるプロンプト例：
次に設定とシークレットの扱いを確認します。環境変数、ランタイム設定ファイル、デフォルトフォールバックを探してください。デフォルトは便利ですが、値が欠けているために開発用キーが本番で使われるといったリスクを隠す場合があります。
簡単な例：Go バックエンドと PostgreSQL の構成で、失敗時にリトライする「メール送信」ジョブがあるとします。冪等性キーなしでリトライするとユーザーが重複メールを受け取るかもしれません。失敗が警告ログだけでアラートされないなら、黙って壊れる高リスク領域です。早めに記録してテストする価値があります。
1つの実際のフローを使って、システムを通る最初のスレッドを作ってください。Login は良い出発点です。ルーティング、バリデーション、セッション/トークン、DB 読み取りに触れるからです。
シナリオ：React の Web アプリが Go API を呼び、API が PostgreSQL を読み書きする。目的は「ユーザーがログインをクリックしたときに次にどのコードが実行され、どのデータが動き、何が壊れ得るか」を答えることです。これによりオンボーディングが具体的になります。
UI から前方に一歩ずつ進んでいきます。具体的なファイル名、関数、リクエスト/レスポンスの形を尋ねてください。
各回答の後にメンタルマップに短い一行を書きます： "UI component -> API endpoint -> handler -> service -> DB query -> response." 名前を具体的に含めてください。「ある関数」とかではなく実名を書きます。
経路を把握したら、小さな実行テストで検証してください。マップした経路が実際に使われる経路かをチェックします。
ブラウザのネットワークツールでリクエスト（パス、ステータスコード、レスポンスボディ）を確認します。ハンドラと DB 呼び出し周辺にログを入れ（可能ならリクエスト ID を付ける）、PostgreSQL に期待した変更があるか問い合わせます（ログインであれば last_login_at、セッション、監査行など）。故意に失敗（パスワード間違い、必須フィールド欠損）を起こして、エラーメッセージがどこで作られどこに表示されるかを確認します。成功と失敗で期待されるレスポンス（ステータスコードと主要フィールド）を記録しておくと次の人が素早く確認できます。
この一つのフローで所有権の境界（UI が信頼すること、API が検証すること、エラーがどこで消えるかなど）が露出することがよくあります。
十分なメンタルマップができたら、それを1～2ページのノートに固定化します。目的は完全であることではなく、次の開発者が「このアプリは何か、最初にどこを見るべきか、何が壊れやすいか」を5分で理解できることです。
Claude Code を使う場合、この文書はあなたの Q&A の出力と扱い、明確で具体的、読みやすくします。
文書を予測可能にして見つけやすくします。良い構成例は：
「Where things live」には「Auth は X、セッションロジックは Y、UI ルートは Z のあたり」といった具体的な指示を入れてください。ツリーを丸ごと貼るのは避け、触る可能性が高い箇所だけを選びます。
「Key flows」では各フローを4～7ステップで書き、各ステップにファイル名を添えます。
「Risky areas」では失敗モードと最速で確認する安全策（特定のテスト、スモーク実行、見るべきログ）を記載します。
最後に、新しい人が安全に貢献できる最初のタスクリストを添えます：
「リポジトリ全体の完全な説明をください」と要求するのは最速で時間を無駄にする方法です。長い要約が返ってきても曖昧なままのことが多いです。代わりに重要なスライス（1モジュール＋1ユーザーフロー）を選び、そこから広げましょう。
次に多いミスは、どの旅程が重要かを明確にしないことです。"checkout" や "login"、"admin edit" のように具体的に指定しないと、回答が一般論に流れます。各セッションは「signup フローをエンドツーエンドで理解する」といった具体的目標で始めてください。
アシスタントに推測させ続けるのも罠です。曖昧なときは、必ず不確かさをラベル付けさせてください。コードから証明できることと推測を分けるように指示します。
メモ内の主張には必ず次のタグを付けます：
構造化されていないチャットスニペットの山は役に立ちません。モジュール、エントリポイント、主要関数・ファイル、触るデータ、副作用、エラーパス、実行すべきテストをテンプレート化しておきましょう。
Claude Code の出力も草案として扱い、重要なフローは実行で検証してください。特に本番を壊し得る部分：認証、支払い、権限、バックグラウンドジョブ、マイグレーションは実際に動かして確認すること。
実用例：アシスタントが「パスワードリセットは X 経由でメールを送る」と言ったら、必ず dev 環境でリセットを実行し、ログやメールサンドボックスで確認してください。現実チェックを入れれば、真実でない物語に基づいてオンボーディングするリスクを避けられます。
リポジトリを暗記する必要はありません。安全に変更を加え、実際の問題をデバッグし、次の人にシステムを説明できる自信があれば十分です。
オンボーディング完了と呼ぶ前に、次のことを推測なしに答えられるか確認してください：
1つ足りない項目があれば、幅広く探すのではなく小さな集中パスを行ってください。1つのフローを選び、データベース境界まで追い、そこで止めて学んだことを書き留めます。不明点は段落で書くのではなく質問に変えましょう。「role X はどこで作られる？」は「auth が混乱している」より有用です。
最終確認の良いテストは、フラグの裏に小さな機能を追加するよう頼まれたときに、触るファイル、走らせるテスト、監視する失敗モードを答えられるかどうかです。答えられれば貢献するのに十分なオンボーディングができています。
メンタルマップは現実と一致している間だけ役に立ちます。挙動に影響する変更の後で更新する習慣をつけてください。大掛かりな書き換えより軽いルーチンが勝ちます。
既に行っている作業に紐づけて更新するのが最も簡単です：
オンボーディング文書はコードの近くに置き、コードと同じ運用でバージョン管理してください。小さな差分は読まれますが、大きなドキュメントの書き換えは無視されがちです。
デプロイがリスクの高い場合は、次の人が素早く復旧できるように何が変わったか、何を見ればよいか、どうロールバックするかを書き残してください。スナップショットやロールバックがサポートされているなら、スナップショット名、理由、修正後に「良好」とみなす基準を記載してください。
Koder.ai (koder.ai) を使うなら、planning mode で一貫したモジュールマップとオンボーディングノートの草案を Q&A から作り、ソースコードのエクスポートでレビュワーが結果を検証しやすくできます。
最後に、次の開発者が推測せずに従えるハンドオフチェックリストを定義してください：
うまく行えば、Claude Code によるコードベースのオンボーディングは習慣になります：各変更が次の人のためのより明確な地図を残すのです。
使えるメンタルマップを目指し、すべてを完全に理解する必要はありません。
1～2日で目指す現実的な成果は：
実際のコードを参照できる具体的な資料を渡すと、推測ではなく正確に指摘できます：
境界がはっきりした狭いスライスを選んでください。
デフォルトの良い範囲は：
「対象外」も明示しておくと、アシスタントの寄り道を防げます（他のサービスやレガシーモジュールなど）。
既知のトリガーから前方に歩いていくのが最短です：
順序どおりに「ファイルパスと関数名」を要求し、最後に「これを素早くどうテストする？」と問うと良いです。
システムが判断を下すか状態を変える場所にリスクは集まります：
続けて「何が黙って壊れるか、どう検知するか？」を問うと素早く洗い出せます。
単純なラベル付けと検証手順を添えると実行可能性が上がります。
例：
アシスタントが自信たっぷりに想像で補わないように、証拠と推測を分けさせてください。
各主張を次のいずれかでタグ付けするよう求めます：
不明点は「誰に聞くか」という形の質問に変えて、穴埋めさせないようにします（例：「role X はどこで定義されていますか？」）。
1つの軽量ファイルに下記5つのセクションを持たせるのが実用的です：
各フローに「How would I test this?（どうテストするか）」を一行追加するとチェックリストになります。
実際のチェックで検証するのが最も確実です：
これにより、あなたがマッピングした経路が実際に使われているかが確認できます。
変更の影響範囲を減らし、レビューしやすくするための機能を活用してください：
「ガードレールを追加する」「検証を厳しくする」「エラーパスを改善する」といったオンボーディング作業に有効です。
短く保てば学習に合わせて更新しやすくなります。