はじめに
Claude Codeを使えば新入りエンジニアが3日で戦力化する、という話を目にすることがある。正直に言うと、完全な自走には現実的に1〜2週間程度は必要だ。ただし「シニアエンジニアへの依存度」と「立ち上がりまでの孤独感」は大きく改善できる——これが実態に近い。
新入りエンジニアが参加するたびに繰り返されるパターンがある。シニアエンジニアがアーキテクチャを1時間かけて説明し、「あのファイルはどこにある？」という質問が毎日来て、コードの背景が伝わらないまま、2〜3ヶ月経ってようやく自走できるようになる。
Claude Codeはこの問題に対して、2つの軸から解決策を提供する。1つは新入りエンジニアへの武器として（コードベース全体を理解したナビゲーターとして機能する）、もう1つはチームの標準化として（`/team-onboarding`でClaude Code活用手順を文書化する）。
Claudeも毎回「新入り」として始まる
CLAUDE.mdの設計を考える前に、まずClaude Code自体の制約を理解しておく必要がある。Claude Code公式ドキュメントには、セッションをまたぐと記憶を持ち越せないという制約が明記されている。
セッションをまたぐと記憶を失う。毎回、新入り社員として始まる。これはオンボーディングのコスト問題と同じ構造だ。
CLAUDE.mdを書いたのはそこへの対処だった。一度書いておくと、次のセッションからClaude Codeがプロジェクトを把握した状態で始まる。「今日書いた内容が全ての将来のセッションを改善する」というのは、使い始めて実感できた。
チームオンボーディング向けCLAUDE.mdテンプレート
## このプロジェクトについて
アーキテクチャ概要
- 認証: Firebase Auth（JWTで管理）
- API: FastAPI + PostgreSQL（SQLAlchemy ORM）
- フロントエンド: Next.js 15 App Router + Tailwind
- インフラ: Vercel（フロント）+ Railway（バックエンド）
コードを読む際の入り口
1. src/api/routes/ → APIエンドポイント一覧
2. src/models/ → データモデル定義
3. src/core/config.py → 設定・環境変数
4. ARCHITECTURE.md → 設計判断の経緯
よく聞かれること（Q&A）
Q: なぜORMにSQLAlchemyを選んだ？
A: Djangoからの移行時にPrismaに変えるより学習コストが低かったため（2024年3月決定）
Q: テストはどこで動かす？
A: pytest。`make test`で全テスト実行。CIは.github/workflows/test.ymlを参照
新入りエンジニアが最初にやること
1. SETUP.mdを読む（環境構築）
2. 「認証フローを説明して」とClaude Codeに聞く
3. 「直近のPR一覧を見て、何に取り組んでいるか教えて」と聞く
個人的に一番効いたのが「よく聞かれること（Q&A）」のセクションだ。シニアが毎回口頭でやっていた説明をここに書き下しておくと、新入りからの同じ質問がほぼなくなる。
/team-onboarding コマンド：チームの立ち上がりガイドを自動生成
Claude Codeには`/team-onboarding`コマンドが提供されている。自分のClaude Code利用パターン（セッション履歴・使っているスキル・よく参照するファイル）からチームメンバー向けの立ち上がりガイドを自動生成する機能だ。
生成されるONBOARDING.mdの例は以下のとおりだ（生成例・プロジェクトにより異なる）。
# プロジェクト名 - Claude Code Onboarding Guide
このプロジェクトでよく使うコマンド
- `/create-spec {機能名}` : 新機能の仕様書を作成
- `/techdebt` : セッション終了時の重複コード除去
- `/test` : テスト実行とカバレッジ確認
よく参照されるファイル
1. src/api/routes/auth.py（認証フロー）
2. src/models/user.py（ユーザーモデル）
3. ARCHITECTURE.md（設計判断の記録）
チームのプロンプトパターン
- バグ修正時: 「このエラーのスタックトレースを分析して、原因と修正案を提示して」
- 設計時: 「まずplan.mdに設計を書いて。承認してから実装に入って」
推奨する活用法は3ステップだ。プロジェクトを最も熟知しているエンジニアが`/team-onboarding`を実行し、生成されたONBOARDING.mdをレビュー・補完してからリポジトリにコミットする。チームメンバー全員が実行してそれぞれの使い方をマージすれば、チーム全体の知恵を集約したガイドができる。
Understand Anything：コードベースを知識グラフにする
大規模なコードベースでは「どこから読めばいいかわからない」という問題が起きる。Understand Anything（GitHub: Lum1104/Understand-Anything）はClaude Codeプラグインとして動作するマルチエージェントパイプラインで、コードベース全体をインタラクティブな知識グラフに変換する。
プロジェクト全体をスキャンして全ファイル・関数・クラス・依存関係を抽出し、インタラクティブなWebダッシュボードとして可視化する。新入りエンジニアの典型的な使い方はこうだ。
「この認証モジュールを変更したいのですが、影響するファイルを教えてください」
→ /understand-diff src/auth/authService.ts
→ 影響範囲: 12ファイル・依存する関数一覧・テスト対象を自動特定
Claude Codeの1Mトークンコンテキストウィンドウと組み合わせることで、数万行規模のコードベースでも「全体を把握した状態」で質問に答えられる。
AIをオンボーディングする逆転の発想
「新入りエンジニアのオンボーディング」だけが問題ではない。Claude Code自体も、セッションが始まるたびにコンテキストを失った状態からスタートする。この構造に気づくと、CLAUDE.mdの設計がまったく違う意味を持ってくる。
AIオンボーディングの4層構造をCLAUDE.mdに書くと良い。
| 層 | 内容 | 例 |
|---|---|---|
| 1. 事業理解 | プロダクトの目的・顧客・強み | 「BtoBのSaaSで、主要顧客は製造業の中堅企業」 |
| 2. 人を知る | チームメンバーの役割・得意分野 | 「Aさん: インフラ担当。DB設計はAさんに確認」 |
| 3. ルールを知る | 絶対に守ること・やってはいけないこと | 「本番DBに直接接続しない」 |
| 4. 動き方を知る | ツール・ファイル保存先・委任ルール | 「新機能は必ず /create-spec から始める」 |
副次的な効果として、AIのために整理することが「チームの暗黙知の棚卸し」になる。「当たり前だと思っていたが実は文書化されていなかったルール」が浮かび上がる。
Anthropic自身の活用事例
Anthropic自身がClaude Codeを社内オンボーディングツールとして活用している。InfrastructureチームではCLAUDE.mdを読み込んだClaude Codeがデータパイプラインの依存関係を説明し、どのアップストリームソースがダッシュボードにフィードされているかを示す。従来のデータカタログツールを代替できるという。Product Engineeringチームでは「調べるべきファイルを特定させること」で、新機能開発前のコンテキスト収集という時間のかかるプロセスを排除している。
まとめ
「3日で戦力化」はさすがに盛りすぎだが、立ち上がりの孤独感がかなり変わるのは本当だと思っている。シニアが毎回口頭でやっていた説明をCLAUDE.mdに書き下しておくだけで、次の新入りから同じ時間を繰り返さなくて済む。
今すぐ（10分）：Claude Codeを最新版にアップデートし、最も使い込んでいるプロジェクトで`/team-onboarding`を実行してONBOARDING.mdを生成する。
今日中：CLAUDE.mdに「よく聞かれるQ&A」セクションを追加する。コードの「なぜ」を3〜5つ書くだけで良い。口頭で何度も説明してきた内容が文書化されていれば、それで十分だ。
次のオンボーディング時：新入りエンジニアに「最初の1日はClaude Codeとコードベースを会話する時間にしてください」という指示を加えてみる。シニアエンジニアへの質問量がどう変わるかを計測することが、チームへの展開を推進する根拠になる。
コメント