はじめに
レガシーコードの改修の話（legacy-modernization）でも、人のオンボーディングの話でもない。未知の大規模コードを「読む・理解する」スピードを上げる話だ。
新しいコードベースに参加したとき、最初の1週間は「何もできない」期間になりやすい。コードを追うだけで1日が終わり、どこから手をつければいいかすらわからない状態が続く。これは能力の問題ではなく、コンテキスト設定の問題だ——という視点から実践を整理する。
CLAUDE.md設定が「コードベース理解の壁」を取り除く
「Claude Codeは大規模コードベースで使えない」という声は、CLAUDE.mdが設定されていない状態での評価であることが多い。lowcode.agencyが複数の大規模プロジェクト（50,000行超のNode.jsなど）で検証した結果、問題はAIの能力ではなくコンテキスト設定の問題だということが分かった。
CLAUDE.mdが設定されていないと何が起きるか。開発者ごとに異なるルールが混在して整合性が崩れる。毎回「このコードベースはXXX技術を使っていて...」という説明からやり直す。Claude Codeが誤った前提でコードを生成する。
CLAUDE.mdに以下の情報を書いておくだけで、Claudeは「文脈を持った状態」で動き始める。
## アーキテクチャ概要
- バックエンド: Go（マイクロサービス）、フロントエンド: Next.js
- DBアクセス: GORMを使用、生SQLは禁止
- API設計: REST（/api/v2/以降）、gRPC（内部サービス間）
## コーディングルール
- 新規ファイルにはユニットテストを必ず追加
- エラーハンドリング: Errorsパッケージを使うこと（errors.Wrapを使用）
- ログ: zerolog（zap禁止）
## よくある罠
- user_idはUUID、int64ではない
- タイムゾーン: 全てUTC保存、表示時にJSTに変換「よくある罠」のセクションが特に重要だ。型の不整合・命名規則の例外・歴史的な理由で残っている特殊な実装——こういった暗黙知をCLAUDE.mdに書いておくことで、新メンバーが同じ穴にはまり続けるサイクルが断ち切れる。
FOR[yourname].md：新メンバーへの「入門書」を自動生成する
CLAUDE.mdがチーム全体の共通ルールを書く場所だとすると、FOR[yourname].mdは「あなた専用の入門書」だ。
CLAUDE.mdに以下を書いておくと、新メンバーが参加するたびにClaude Codeがコードベースを読んでパーソナライズされた文書を自動生成する。
## コードベースドキュメント
- 新しいエンジニアが入ったら、FOR[名前].mdを作成すること
- 内容: アーキテクチャ概要、主要モジュールの役割、
技術選定の理由、過去の重要バグと対処法生成する文書に含める内容の例として、システム全体の技術アーキテクチャと構造、技術選定の背景（「なぜRabbitMQではなくKafkaなのか」）、過去のバグ事例と原因、チームのベストプラクティスと暗黙知が挙げられる。
Anthropicのインファレンスチームでの社内実践として、通常1時間かかるコードベース調査が10〜20分程度に短縮されたという報告がある（社内実践のため外部一次出典はない）。新規メンバーが「どこから読めばいいか」を把握するまでの時間が変わると、最初の1週間の生産性が変わる。
このパターンを補完するツールとして、コミュニティスキルの Understand-Anything（github.com/Lum1104/Understand-Anything、7,200+ Stars）がある。コードベース・Dockerfile・docs全体をインタラクティブな知識グラフに変換し、ファイル・関数・クラス間の依存関係を視覚的に探索できる。ドキュメントが皆無なレガシーコードの構造把握に特に有効だ。FOR[yourname].mdで「何が重要か」を掴んだあと、Understand-Anythingで「どう繋がっているか」を確認する、という使い方が補完的に機能する。
EMの視点でもう一つ。担当エンジニアが抜けるときの引き継ぎドキュメントにも転用できる。「俺しか分からない」コードの理解をClaude Codeに抽出させ、FOR[departing-engineer].mdとして残す形だ。属人化のリスクを下げる用途としても機能する。
ただし、自動生成されたドキュメントは生成後に人間がレビューする必要がある。Claude Codeがコードを誤解釈している場合があるため、新メンバーが入ったタイミングで「これ合ってる？」と確認する習慣を作ることが大事だ。
段階的アプローチ——「バグ修正から始める」原則と探索プロンプト
CLAUDE.mdとFOR[yourname].mdが整備されていても、「どの順番でコードに入るか」は別の問いだ。大規模コードベースでの実践から得られたパターンは、段階的アプローチを取ることだ。
バグ修正とテスト生成から入るのが安定している。既存テストを通すだけでシステム全体のデータフローが理解できる。小さなバグを修正しながらClaudeとコードベースの「共通言語」が形成されていく。
習熟してきたら既存サービスへの機能追加に移る。探索→計画→実装の3フェーズで進め、関連ファイルを読んで影響範囲を把握し、実装方針をClaudeと言語化してから実装を開始する。コードベースへの理解が深まったあとで、クロスモジュールのリファクタリングに取り組む流れが安定する。
具体的な探索プロンプトをいくつか紹介する。
初日の全体把握:
このコードベースを読んで、以下を教えてください：
1. システム全体のアーキテクチャ（サービス構成・データフロー）
2. エントリーポイント（どこから実行が始まるか）
3. 最も重要な3〜5個のモジュール・ファイルとその役割
4. 「知らないとハマる」罠（型の不整合・命名規則の例外等）
新入りエンジニアが最初の1週間で理解すべき内容に絞って。変更の影響範囲把握:
このファイル（/src/services/payment.go）を変更したとき、
影響を受ける可能性があるファイル・モジュールを全て洗い出してください。
テストカバレッジがない部分も含めて教えてください。意図不明なコードの解読:
このコードは一見奇妙に見えます：
[コードを貼り付け]
過去のバグ・パフォーマンス問題・外部制約が理由になっている可能性を考慮して、
この実装になった背景を推測してください。3つ目のプロンプトが特に効く場面がある。長年運用されたコードには「なぜこう書いたのか」という背景が失われていることが多い。その意図を推測させることで、安易に削除・変更してはいけないコードを踏む前に気づける。
コンテキスト爆発には注意が必要だ。「コードベース全体を読んで」という指示は現実的でない。対象ファイル・モジュールを絞って渡すのが基本だ。また、APIキーやシークレットを含むコードをClaude Codeに渡す際はログ管理に注意する。
まとめ
「最初の1週間は何もできなくて当然」という前提は、CLAUDE.mdとFOR[yourname].mdが整備されていれば変えられる。設定の問題であって、能力の問題ではないというのが出発点だ。
新メンバーが参加するタイミングを次のCLAUDE.md改善の機会にするといい。「これが分からなかった」「これにハマった」という声を拾って「よくある罠」セクションに追加する。その積み重ねが、次のメンバーのオンボーディングを短縮していく。
コメント