コードベース・オンボーディング

コードベース・オンボーディング は何をしますか？

未知のコードベースを体系的に分析し、構造化されたオンボーディングガイドを生成します。新しいプロジェクトに参加する開発者や、既存のリポジトリで初めて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ワークフロー]
- [エラーハンドリングパターン]

ベストプラクティス

1. すべてを読まない — 偵察ではGlobとGrepを使用し、すべてのファイルをReadしないでください。あいまいなシグナルの場合にのみ選択的に読み取ります。
2. 推測せず、検証する — 設定からフレームワークが検出されたが、実際のコードが異なるものを使用している場合は、コードを信頼します。
3. 既存のCLAUDE.mdを尊重する — すでに存在する場合は、置き換えるのではなく拡張します。新しい内容と既存の内容を明確に示します。
4. 簡潔に保つ — オンボーディングガイドは2分でスキャン可能であるべきです。詳細はコードに属し、ガイドには属しません。
5. 不明な点を明記する — 規約を確信を持って検出できない場合は、推測するのではなくそのように明記します。「テストランナーを特定できませんでした」は、間違った答えよりも優れています。

避けるべきアンチパターン

• 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