コードベースオンボーディング は何をしますか？
未知のコードベースを体系的に分析し、構造化されたオンボーディングガイドを作成します。新しいプロジェクトに参加する開発者や、既存のリポジトリで初めてClaude Codeをセットアップする際に設計されています。
使用すべきタイミング
- 初めてClaude Codeでプロジェクトを開くとき
- 新しいチームやリポジトリに参加するとき
- ユーザーが「このコードベースを理解するのを手伝って」と尋ねたとき
- ユーザーがプロジェクトのCLAUDE.mdを生成するよう依頼したとき
- ユーザーが「オンボーディングして」または「このリポジトリを案内して」と言ったとき
仕組み
フェーズ1: 偵察
すべてのファイルを読まずに、プロジェクトに関する生のシグナルを収集します。以下のチェックを並行して実行します。
1. パッケージマニフェストの検出
→ package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle,
Gemfile, composer.json, mix.exs, pubspec.yaml
2. フレームワークのフィンガープリンティング
→ next.config.*, nuxt.config.*, angular.json, vite.config.*,
django settings, flask app factory, fastapi main, rails config
3. エントリポイントの特定
→ main.*, index.*, app.*, server.*, cmd/, src/main/
4. ディレクトリ構造のスナップショット
→ ディレクトリツリーの上位2階層を取得（node_modules, vendor,
.git, dist, build, __pycache__, .next は除外）
5. 設定とツールの検出
→ .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile,
docker-compose*, .github/workflows/, .env.example, CI設定
6. テスト構造の検出
→ tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js,
pytest.ini, jest.config.*, vitest.config.*
フェーズ2: アーキテクチャマッピング
偵察データから以下を特定します。
技術スタック
- 言語と言語バージョンの制約
- フレームワークと主要ライブラリ
- データベースとORM
- ビルドツールとバンドラー
- CI/CDプラットフォーム
アーキテクチャパターン
- モノリス、モノレポ、マイクロサービス、またはサーバーレス
- フロントエンド/バックエンドの分離またはフルスタック
- APIスタイル: REST、GraphQL、gRPC、tRPC
主要ディレクトリ 最上位ディレクトリをその目的にマッピングします。
src/components/ → React UIコンポーネント
src/api/ → APIルートハンドラー
src/lib/ → 共有ユーティリティ
src/db/ → データベースモデルとマイグレーション
tests/ → テストスイート
scripts/ → ビルド/デプロイスクリプト
データフロー 1つのリクエストをエントリからレスポンスまでトレースします。
- リクエストはどこに入るか？（ルーター、ハンドラー、コントローラー）
- どのように検証されるか？（ミドルウェア、スキーマ、ガード）
- ビジネスロジックはどこにあるか？（サービス、モデル、ユースケース）
- データベースへの到達方法は？（ORM、生クエリ、リポジトリ）
フェーズ3: 規約の検出
コードベースが既に従っているパターンを特定します。
命名規則
- ファイル命名: kebab-case, camelCase, PascalCase, snake_case
- コンポーネント/クラス命名パターン
- テストファイル命名:
*.test.ts,*.spec.ts,*_test.go
コードパターン
- エラーハンドリングスタイル: try/catch、Result型、エラーコード
- 依存性注入または直接インポート
- 状態管理アプローチ
- 非同期パターン: コールバック、Promise、async/await、チャネル
Git規約
- 最近のブランチからのブランチ命名
- 最近のコミットからのコミットメッセージスタイル
- PRワークフロー（squash、merge、rebase）
- リポジトリにまだコミットがない場合や、浅い履歴しかない場合（例：
git clone --depth 1）、このセクションはスキップし、「Git履歴が利用できないか、規約を検出するには浅すぎます」と注記します。
フェーズ4: オンボーディング成果物の生成
2つの出力を生成します。
出力1: オンボーディングガイド
# オンボーディングガイド: [プロジェクト名]
## 概要
[2-3文: このプロジェクトが何をするのか、誰のためにあるのか]
## 技術スタック
<!-- Next.jsプロジェクトの例 — 検出されたスタックに置き換えてください -->
| レイヤー | 技術 | バージョン |
|---------|------|----------|
| 言語 | TypeScript | 5.x |
| フレームワーク | Next.js | 14.x |
| データベース | PostgreSQL | 16 |
| ORM | Prisma | 5.x |
| テスト | Jest + Playwright | - |
## アーキテクチャ
[コンポーネント間の接続図または説明]
## 主要エントリポイント
<!-- Next.jsプロジェクトの例 — 検出されたパスに置き換えてください -->
- **APIルート**: `src/app/api/` — Next.jsルートハンドラー
- **UIページ**: `src/app/(dashboard)/` — 認証済みページ
- **データベース**: `prisma/schema.prisma` — データモデルの信頼できる情報源
- **設定**: `next.config.ts` — ビルドとランタイム設定
## ディレクトリマップ
[最上位ディレクトリ → 目的のマッピング]
## リクエストライフサイクル
[1つのAPIリクエストをエントリからレスポンスまでトレース]
## 規約
- [ファイル命名パターン]
- [エラーハンドリングアプローチ]
- [テストパターン]
- [Gitワークフロー]
## 一般的なタスク
<!-- Node.jsプロジェクトの例 — 検出されたコマンドに置き換えてください -->
- **開発サーバーの起動**: `npm run dev`
- **テストの実行**: `npm test`
- **リンターの実行**: `npm run lint`
- **データベースマイグレーション**: `npx prisma migrate dev`
- **プロダクションビルド**: `npm run build`
## 参照場所
<!-- Next.jsプロジェクトの例 — 検出されたパスに置き換えてください -->
| 目的 | 参照場所 |
|------|----------|
| APIエンドポイントを追加する | `src/app/api/` |
| UIページを追加する | `src/app/(dashboard)/` |
| データベーステーブルを追加する | `prisma/schema.prisma` |
| テストを追加する | `tests/`（ソースパスと一致） |
| ビルド設定を変更する | `next.config.ts` |
出力2: スターターCLAUDE.md
検出された規約に基づいてプロジェクト固有のCLAUDE.mdを生成または更新します。既にCLAUDE.mdが存在する場合は、まずそれを読み込み、拡張します。既存のプロジェクト固有の指示は保持し、追加または変更された点を明確に示します。
# プロジェクト指示
## 技術スタック
[検出されたスタックの概要]
## コードスタイル
- [検出された命名規則]
- [従うべき検出されたパターン]
## テスト
- テストの実行: `[検出されたテストコマンド]`
- テストパターン: [検出されたテストファイル規約]
- カバレッジ: [設定されている場合、カバレッジコマンド]
## ビルドと実行
- 開発: `[検出された開発コマンド]`
- ビルド: `[検出されたビルドコマンド]`
- リンター: `[検出されたリンターコマンド]`
## プロジェクト構造
[主要ディレクトリ → 目的マップ]
## 規約
- [検出可能な場合、コミットスタイル]
- [検出可能な場合、PRワークフロー]
- [エラーハンドリングパターン]
ベストプラクティス
- すべてを読まない — 偵察にはReadではなく、GlobとGrepを使用します。曖昧なシグナルの場合にのみ、選択的にReadします。
- 推測せず検証する — 設定からフレームワークが検出されても、実際のコードが別のものを使っている場合は、コードを信頼します。
- 既存のCLAUDE.mdを尊重する — 既に存在する場合は、置き換えずに拡張します。新しい情報と既存の情報を明確に区別します。
- 簡潔さを保つ — オンボーディングガイドは2分でスキャン可能であるべきです。詳細はコード内に属し、ガイド内には属しません。
- 不明点はフラグを立てる — 規約を確信を持って検出できない場合は、推測せずにその旨を明記します。間違った答えよりも「テストランナーを特定できませんでした」の方が優れています。
避けるべきアンチパターン
- 100行を超えるCLAUDE.mdを生成する — 焦点を絞ってください
- すべての依存関係をリストアップする — コードの書き方を形成するものだけを強調してください
- 明白なディレクトリ名を説明する —
src/は説明を必要としません - READMEをコピーする — オンボーディングガイドはREADMEにない構造的洞察を追加します
例
例1: 新しいリポジトリを初めて使う場合
ユーザー: 「このコードベースにオンボーディングして」
アクション: 完全な4フェーズワークフローを実行 → オンボーディングガイド + スターターCLAUDE.mdを生成
出力: 会話に直接出力されるオンボーディングガイドと、プロジェクトルートに書き込まれるCLAUDE.md
例2: 既存プロジェクト用のCLAUDE.mdを生成する場合
ユーザー: 「このプロジェクト用のCLAUDE.mdを生成して」
アクション: フェーズ1〜3を実行し、オンボーディングガイドをスキップし、CLAUDE.mdのみを生成
出力: 検出された規約を含むプロジェクト固有のCLAUDE.md
例3: 既存のCLAUDE.mdを拡張する場合
ユーザー: 「現在のプロジェクト規約でCLAUDE.mdを更新して」
アクション: 既存のCLAUDE.mdを読み込み、フェーズ1〜3を実行し、新しい発見をマージ
出力: 追加内容が明確にマークされた更新済みCLAUDE.md