コードベース入門ガイド

未知のコードベースを体系的に分析し、構造化された入門ガイドを生成します。新しいプロジェクトに参加する開発者や、既存のリポジトリで初めて 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

主要ディレクトリ トップレベルディレクトリを用途にマッピング：

<!-- Example for a React project — replace with detected directories -->

src/components/  → React UI コンポーネント
src/api/         → API ルートハンドラー
src/lib/         → 共有ユーティリティライブラリ
src/db/          → データベースモデルとマイグレーション
tests/           → テストスイート
scripts/         → ビルドおよびデプロイスクリプト

データフロー エントリーポイントからレスポンスまでのリクエストパスを追跡：

• リクエストはどこから入る？（ルーター、ハンドラー、コントローラー）
• どのように検証される？（ミドルウェア、スキーマ、ガード）
• ビジネスロジックはどこ？（サービス、モデル、ユースケース）
• データベースにアクセスする方法？（ORM、生クエリ、リポジトリ）

フェーズ 3: 規約検出

コードベースが従っているパターンを特定：

命名規約

• ファイル命名: kebab-case、camelCase、PascalCase、snake_case
• コンポーネント/クラス命名パターン
• テストファイル命名: *.test.ts、*.spec.ts、*_test.go

コードパターン

• エラー処理スタイル: try/catch、Result 型、エラーコード
• 依存性注入 vs 直接インポート
• 状態管理アプローチ
• 非同期パターン: コールバック、Promise、async/await、チャネル

Git 規約

• 最新のブランチから推測するブランチ命名
• 最新のコミットから推測するコミットメッセージスタイル
• PR ワークフロー（スカッシュマージ、マージ、リベース）
• リポジトリがまだコミット履歴がないか履歴が浅い場合（例：git clone --depth 1）は、このセクションをスキップして「Git 履歴が利用不可または浅すぎるため、規約を検出できません」と記載

フェーズ 4: オンボーディング成果物の生成

2 つの出力を生成：

出力 1: オンボーディングガイド

# 入門ガイド: [プロジェクト名]

## 概要
[2～3文: 本プロジェクトの目的と対象ユーザーを説明]

## テクノロジースタック
<!-- Example for a Next.js project — replace with detected stack -->
| レイヤー | テクノロジー | バージョン |
|-------|-----------|---------|
| 言語 | TypeScript | 5.x |
| フレームワーク | Next.js | 14.x |
| データベース | PostgreSQL | 16 |
| ORM | Prisma | 5.x |
| テスト | Jest + Playwright | - |

## アーキテクチャ
[コンポーネント接続方法の図表または説明]

## 主要エントリーポイント
<!-- Example for a Next.js project — replace with detected paths -->
- **API ルート**: `src/app/api/` — Next.js ルートハンドラー
- **UI ページ**: `src/app/(dashboard)/` — 認証済みページ
- **データベース**: `prisma/schema.prisma` — データモデルの単一の真実源
- **設定**: `next.config.ts` — ビルドおよびランタイム設定

## ディレクトリ構造
[トップレベルディレクトリ → 用途マッピング]

## リクエストライフサイクル
[API リクエストがエントリーポイントからレスポンスまでの全過程を追跡]

## 規約
- [ファイル命名パターン]
- [エラー処理方法]
- [テストパターン]
- [Git ワークフロー]

## 一般的なタスク
<!-- Example for a Node.js project — replace with detected commands -->
- **開発サーバーを実行**: `npm run dev`
- **テストを実行**: `npm test`
- **lint を実行**: `npm run lint`
- **データベース マイグレーション**: `npx prisma migrate dev`
- **本番ビルド**: `npm run build`

## 探す場所
<!-- Example for a Next.js project — replace with detected paths -->
| 実行したいこと | 確認する場所 |
|--------------|-----------|
| API エンドポイントを追加 | `src/app/api/` |
| UI ページを追加 | `src/app/(dashboard)/` |
| データベーステーブルを追加 | `prisma/schema.prisma` |
| テストを追加 | `tests/` （ソースパスに一致） |
| ビルド設定を変更 | `next.config.ts` |

出力 2: 初期 CLAUDE.md

検出された規約に基づいて、プロジェクト固有の CLAUDE.md を生成または更新します。CLAUDE.md が既に存在する場合は、最初にそれを読み込んで拡張してください。既存のプロジェクト固有の指示を保持し、新しい内容または変更内容を明確にマークします。

# プロジェクト説明

## テクノロジースタック
[検出されたテクノロジースタックのサマリー]

## コードスタイル
- [検出されたネーミング規約]
- [検出された従うべきパターン]

## テスト
- テストを実行: `[detected test command]`
- テストパターン: [検出されたテストファイル規約]
- カバレッジ: [設定されている場合はカバレッジコマンド]

## ビルドと実行
- 開発: `[detected dev command]`
- ビルド: `[detected build command]`
- Lint: `[detected lint command]`

## プロジェクト構造
[主要ディレクトリ → 用途マッピング]

## 規約
- [検出されたコミットスタイル]
- [検出された PR ワークフロー]
- [エラーハンドリングパターン]

ベストプラクティス

1. すべてを読まない — 偵察フェーズは各ファイルを読むのではなく、Glob と Grep を使用します。シグナルが不明確な場合のみ、選別して読み込みます。
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。新しい内容を明確にマーク