前任者が一人だけ知っていたプロジェクトを、ある日「明日から君が見てね」と引き渡されたことがあります。README は古く、テストは半分赤で、本番は動いています。こういう状況で焦って機能追加に手を付けると、数週間後に必ず痛い目に遭います。
私は個人開発と受託の両方で、こうした「知らないコードベースを引き継ぐ」場面を何度も経験してきました。Claude Code が手元にある今、このプロセスは以前より確実に短縮できます。ただし、Claude Code に丸投げする使い方では効果が薄く、むしろ間違った自信を与えてしまいます。ここでは私が実際に使っている1週間のプロトコルを共有します。
Day 1 — コードベースの「地図」を描くための質問
最初の日は、エディタで個別ファイルを開く前に、Claude Code との対話でプロジェクトの全体像を言語化します。ここで大事なのは、細部に降りていく誘惑を断つことです。
私がまず打つプロンプトはこの形です。
このリポジトリ全体を読んで、次の質問に答えてください。
1. このプロジェクトは何のために存在するか（ユーザーから見た価値）
2. 主要なエントリポイント（起動スクリプト・API ルート・バッチなど）は何か
3. 外部依存（DB、API、キュー、ストレージ）は何で、それぞれどのファイルで初期化されているか
4. ビルドとデプロイのパイプラインはどこに書かれているか
5. あなたが読んでいて「意図が分からない」と感じた箇所を3つだけ挙げてください
推測で答えず、該当するファイルパスと行番号を必ず添えてください。最後の「推測で答えず」は重要です。Claude Code は親切で、情報が足りなくても筋の通った回答を作ってきます。引き継ぎの文脈では、それが一番危険です。 ファイルパスと行番号を必ず引用させることで、ハルシネーションを事前に封じます。
回答が返ってきたら、「意図が分からない3箇所」を自分の目でも読みます。ここが翌日以降の深掘りの起点になります。
Day 2 — ドメイン語彙と境界を確定させる
2日目は、プロジェクト固有の「言葉」を整理します。User、Order、Invoice のような単語が、このプロジェクトで何を意味しているかを明確にするフェーズです。言葉が揃わないまま機能追加に入ると、他人の用語で書いた自分のコードが混ざって一貫性が崩れます。
Claude Code にはこう尋ねます。
コードベースから「ドメイン用語集」を作ってください。
対象は src/ 以下のモデル/エンティティ/DTO で使われている主要な名詞です。
各用語について:
- 定義（このコードでの役割）
- 主な関連クラス/関数
- 他の用語との関係（composition, aggregation, reference）
表形式で不要です。Markdown の見出しと段落で書いてください。表形式を避けてもらうのは、レンダリング環境によっては Markdown テーブルがそのまま表示されてしまうことがあるからですが、それ以上に、段落で書かせる方がモデルが省略せずに説明する傾向がある からです。
ここで出てきた用語集は、チームに共有する Notion ページや docs/domain.md にそのまま保存します。後日、新しく誰かがジョインしてきたときに、この文書が私自身を助けます。
Day 3 — 「触ってはいけない場所」を特定する
3日目が、このプロトコルの中で最も重要な日です。機能追加の前に、壊したら即本番障害になる場所 を Claude Code と一緒に洗い出します。
このコードベースの中で、以下のいずれかに該当する箇所を指摘してください。
A. グローバル副作用を持つ初期化処理（モジュールトップレベルで DB 接続、
シングルトン生成、環境変数読み込みを行っている箇所）
B. 暗黙の契約に依存している関数（戻り値の形、エラーの型、例外の種類が
呼び出し側で前提となっているが、型で表現されていないもの）
C. テストがない、または非常に薄いテストしかない、ビジネスクリティカルな関数
各指摘にはファイルパス、行番号、「なぜ危険か」の一文を添えてください。B の「暗黙の契約」は、Claude Code が特に得意な分析です。TypeScript でも any を経由するコードや、Ruby や Python のような動的型付け言語では、呼び出し側と実装の間にある暗黙の合意がしばしば崩壊寸前になっています。ここに手を入れる前に、まず型やテストで「契約」を固定してから変更するのが、私のルールです。
Day 4 — 最初の変更を「安全な範囲」で当てる
4日目にして初めて、私はコードに手を入れ始めます。ただし、いきなり機能追加はしません。以下の順番を守ります。
- 足りないテストを1つ書く（3日目で洗い出した危険箇所から）
- そのテストが実装のバグや仕様の曖昧さを炙り出したら、それを記録する
- 明らかな dead code があれば削除する（Claude Code に dead code の候補を挙げてもらう）
- 型注釈や docstring を追加する（挙動を変えない範囲で）
この「挙動を変えない範囲」の変更だけを4日目に押し切ることで、コードベースの制御感 が一気に上がります。Claude Code に以下のように頼みます。
次の関数 X を読んで、外部挙動を一切変えずにリファクタできる箇所を
提案してください。提案は以下の形式で:
- 変更前の該当行
- 変更後のコード
- なぜ外部挙動が変わらないと言えるか（根拠）
根拠が「一般的にそうだから」ではなく、このコードの文脈に基づいた
ものだけを提案してください。最後の条件を忘れると、教科書的な一般論（命名規則、早期リターン、etc）で埋め尽くされます。そういう提案は後からでもできるので、この日は実害に直結する場所だけに絞ります。
Day 5 — 依存関係と外部境界の検証
5日目は、外部との接続点を検証します。外部 API、DB、キュー、環境変数は、ローカルで動いていても本番では微妙に違う挙動を見せることがあります。
このコードベースが依存する外部リソース（API、DB、キュー、環境変数）を
すべて列挙してください。各項目について:
1. アクセスしているファイルパス
2. ローカル開発環境でどう差し替えられているか
3. 本番環境と開発環境で挙動が異なる可能性のある箇所
4. タイムアウト、リトライ、サーキットブレーカーの有無
特に 3 と 4 に気を配ってください。この結果を見て、タイムアウトが未設定の HTTP クライアントや、エラーを握りつぶしているコードを発見することが多いです。見つかったら、その場で修正するのではなく、issue か TODO 付きの PR としてキューに積みます。いきなり全部直そうとすると、元の挙動に依存している他のコードと衝突します。
Day 6 — ドキュメントの種を残す
6日目は、これまでの5日間で学んだことを、未来の自分と他人 のために残します。Claude Code にドキュメントの雛形を作らせて、それを自分の言葉で修正するのが速いです。
ここまでの対話で把握した内容をもとに、新しいメンバー向けの
オンボーディングドキュメント（Markdown）を生成してください。
構成:
1. このプロジェクトの目的と価値
2. アーキテクチャの概要（主要コンポーネントと依存関係）
3. ローカルでの起動手順
4. よくある作業（機能追加、バグ修正、デプロイ）のチェックリスト
5. 触る前に必ず読むべきファイル一覧
6. 既知の「地雷」（Day 3 で洗い出した内容）
私の立場は保守の引き継ぎを受けた側なので、新人の不安に共感する
トーンで書いてください。ここで重要なのは「6. 既知の地雷」を必ず入れること。こういう情報は通常のドキュメントには書かれませんが、保守を引き継いだ人間にとっては一番価値のある情報です。
Day 7 — 自分なりの「運用ルール」を明文化する
最終日は、自分がこのコードベースを今後どう扱うかのルールを言語化します。チームが複数人いるなら、このルールを共有してレビュー対象にします。
私が毎回書くのはこの3点です。
- このコードベースでの私の役割の境界（どこまで直し、どこから先はチームに相談するか）
- レビュー依頼をする前に自分でチェックする項目（Day 3 の危険箇所リストに触れていないか等）
- この後3ヶ月で改善したい負債のトップ5（優先度と根拠つき）
この3点を書き出すと、Claude Code を使う上でのプロンプトも安定します。たとえば「Day 3 の危険箇所リストに触れていないか確認してください」という問いは、毎回のコード変更前に使える定型プロンプトになります。
Claude Code を信じすぎないための運用ルール
ここまでの手順で Claude Code を多用してきましたが、私は次の3つのルールを常に守っています。
- Claude Code の回答を「仮説」として扱う。必ずファイルを開いて検証する
- 「知らない」と答えさせる。プロンプトの最後に「確信が持てない場合は『分からない』と答えてください」と添える
- 長いセッションを1本で回さない。コンテキストが劣化するので、1日1〜2回はセッションを切って要約を残す
この3点を守れば、Claude Code は「優秀だが検証が必要な同僚」として扱えます。逆にこれを守らないと、「それっぽい嘘を自信満々で言う同僚」に変わってしまいます。
このプロトコルを使った後に残るもの
7日間を終えると、手元に残るのは次のような資産です。
- コードベースの地図（Day 1）
- ドメイン用語集（Day 2）
- 危険箇所リスト（Day 3）
- 小さな改善の履歴（Day 4）
- 外部境界の一覧と既知の問題（Day 5）
- オンボーディングドキュメント（Day 6）
- 自分の運用ルール（Day 7）
これだけあれば、「引き継ぎ1週間目」の不安は大きく減ります。私は個人開発でも、久しぶりに戻ってきた自分のプロジェクトに対して、このプロトコルの短縮版（2〜3日）を回します。3年前に書いた自分のコードは、他人のコードと何も変わらないので。
引き継ぎに直面したら、まず Day 1 の質問プロンプトから始めてみてください。1週間後、手元には「知らないコードベース」ではなく「触れるコードベース」が残っているはずです。