codebase-onboarding

コードベース・オンボーディング Wiki ジェネレーター

DeepWiki の形式をモデルに、あらゆるリポジトリから階層構造でソースへのリンクと図を豊富に含む Wiki を生成します。

使用する場面

• ユーザーがリポジトリ（URL、パス、アップロードされたファイル）を提示し、その内容を理解したい場合
• コードベースへの開発者のオンボーディングを依頼された場合
• コードからアーキテクチャドキュメントを生成したい場合
• 「このリポジトリはどう動くのか」や「このコードベースの構成を把握したい」と尋ねられた場合

ワークフローの概要

Phase 1: Reconnaissance ──→ Phase 2: Architecture Mapping ──→ Phase 3: Deep Docs ──→ Phase 4: Assembly
  (scripts/analyze.py)        (you + diagrams)                  (you + templates)      (final output)

フェーズ 1 — 調査（自動）

分析スクリプトを実行して、コードベースに関する構造化データを収集します。

pip install -r scripts/requirements.txt  # optional, graceful degradation
python scripts/analyze.py <repo_path> --output codebase-analysis.json

実行時のルール

モデルやハーネス間での出力のばらつきを抑えるため、以下のルールに従ってください。

必須

• リポジトリのパスが利用可能な場合は、最初に scripts/analyze.py を実行します。
• アーキテクチャに関する記述を作成する前に、JSON レポートを読みます。
• summary.capabilities_missing を確認し、それに応じて出力範囲を調整します。
• 技術的な主張にはすべて、path/to/file.ext:L45-L87 形式でソースファイルを引用します。
• 検証できない主張には [NEEDS INVESTIGATION] を付けます。コンテンツページごとに少なくとも 1 件を目標にします。コードから直接確認したのではなく、推測したアーキテクチャ上の判断に印を付けてください。[NEEDS INVESTIGATION] マーカーが 1 件もない Wiki は、ほぼ間違いなく過信しています。
• 00-index.md を除くすべてのコンテンツページに、必須の7 つのセクションを含めます。TL;DR · Relevant Source Files · アーキテクチャ図 · Key Concepts テーブル · 引用付きの詳細な説明 · Cross-references · Active Development Areas。
• インデックスページ（00-index.md）はナビゲーション専用です。TL;DR、引用、図は必要ありません。

推奨

• より優れた構造分析のため、オプションの Python 依存関係をインストールします：pip install -r scripts/requirements.txt。
• 最初に文書化する内容を選ぶ際は、key_entities と git.hotspots を優先します。
• 図やテーブルは、推測ではなく、実際に確認できたコード構造に合わせます。
• コンテンツページは少なくとも 400 語にします。多くの内容を浅く列挙するのではなく、1 つのコードパスを詳しく追います。幅より深さを重視してください。
• 主要な説明セクションごとに少なくとも 3 件の file:line 引用を含めます。ページ全体で 10 件以上を目指します。

任意

• スクリプトを実行できない場合は、手動での調査を続けます。
• 利用可能な機能が限られている場合は、範囲を縮小したオンボーディングドキュメントを作成します。

品質ティア

期待値を明確にするため、以下のティアを使用してください。

• ティア A（高信頼度）： tree_sitter、networkx、git が利用可能です。重要度でランク付けしたエンティティ、所有権、ホットスポットの分析を含む完全な Wiki を作成します。
• ティア B（中信頼度）： tree_sitter または networkx のいずれかが利用できません。完全な Wiki の作成は可能ですが、制約を説明するセクションを含めます。
• ティア C（基本）： スクリプトが利用できない、または主要な機能が不足しています。構造化された概要のみを作成し、不明点を明示します。

スクリプトは 7 つのフェーズを自動的に実行し、可能だったこととできなかったことを報告します。

1. ファイルの検出 — .gitignore を考慮した走査（pathspec）
2. 言語別統計 — 言語ごとの正確な LOC（tokei/scc）
3. マニフェストの解析 — package.json、pyproject.toml、Cargo.toml、go.mod、.csproj から依存関係を取得（正規表現ではなく適切なパーサーを使用）
4. フレームワークの検出 — ファイル名だけでなく、実際の依存関係と照合
5. コード構造 — tree-sitter による AST 解析を用いたクラス、関数、インターフェース、型の検出
6. 重要度のランク付け — ファイル間の参照グラフに対する PageRank（networkx）
7. Git の分析情報 — ホットスポットファイル、主なコントリビューター、ディレクトリごとの所有権

先に進む前に、JSON の出力を読みます。key_entities フィールドには、最も重要なコードエンティティが示されています。そこからドキュメント化を始めてください。

分析レポートの使用方法

JSON レポートの各フィールドは、ドキュメント作成における具体的な判断材料になります。以下の対応関係に従ってください。 key_entities → ページ構成と優先順位 PageRank スコア付きのシンボルから、何が最も重要かが分かります。次の用途に活用してください。

• 独自の Wiki ページを設けるべきコンポーネントを判断する（上位 10〜15 個のエンティティは、ほぼ必ず対象になります）
• ドキュメント化の順序を決める — ランクの高いエンティティから記述する
• ハブとなる抽象化を特定する：ランクが高いエンティティは多くのファイルから参照されているため、アーキテクチャを支える重要な要素です
• 上位約 10 件を使って、概要ページの「主要な概念」テーブルを作成する

例：RepomixConfigMerged が 1 位なら、コードベースの中核となるエンティティです。概要ページで目立つように配置し、独自のセクションを設け、設定に関わるすべてのページから相互参照します。

symbols.by_kind → Wiki の詳細度の判断 クラス、関数、インターフェースの分布から、コードベースのアーキテクチャスタイルが分かります。

• インターフェース／型が多い場合 → コントラクトと型階層を記述し、ER 図を使用する
• クラスが多い場合 → 継承とコンポジションを記述し、クラス関係図を使用する
• 関数が多い場合 → データフローとパイプラインを記述し、シーケンス図を使用する
• これに基づいて、references/diagram-patterns.md のどのパターンを使うかを選びます

frameworks → 適応方針 検出されたフレームワークを「コードベースの種類に応じた適応」テーブルと照合し、どの特別なページを含めるか決めます。フレームワーク固有の分析パターンについては、references/language-guides.md も参照してください（たとえば Django が検出された場合は、最初に調べるべきファイルを把握するため、Django のセクションを読みます）。

git.hotspots → 「活発な開発領域」セクション 変更頻度の高いファイルから、チームが現在どこを重点的に開発しているかが分かります。次の用途に活用してください。

• 概要ページに「現在の開発領域」のコールアウトを追加する
• ホットスポットのファイルを優先して詳しく記述する（新しい開発者が最初に触れるファイルです）
• 変更頻度が高い一方でシンボル数が少ないファイルに印を付ける — 説明が必要な設定ファイルやグルーコードの可能性があります

git.ownership → 「担当者」ガイダンス ディレクトリごとの主要な貢献者は、オンボーディングに欠かせない情報である「誰が何を担当しているか」に直結します。これを概要ページのテーブル、または専用の「チームと担当範囲」セクションに含めてください。

| Area          | Primary Contact    | Commits (12mo) |
|---------------|--------------------|----------------|
| src/core/     | Alice              | 142            |
| src/api/      | Bob                | 87             |

manifests → 依存関係とビルドのセクション 解析された依存関係データをもとに、「ビルドと開発」の Wiki ページを作成します。

• dependencies → ランタイムアーキテクチャ（アプリが実際に使用するもの）
• devDependencies → ツールチェーン（開発者が理解しておくべきもの）
• scripts → 開発ワークフローページで使用できるコマンド
• engines → バージョン要件と制約

languages + languages_source → 対象範囲と信頼度 言語の内訳から、主要な言語（最良のデータを生成した tree-sitter クエリを判断する材料）と、統計が正確な値（tokei／scc）か推定値（フォールバック）かが分かります。フォールバック統計を使用する場合は、この制限を明記してください。

capabilities_missing → レポートの制限事項 レポートに tree-sitter をスキップしたと記載されている場合は、構造を抽出するために主要なファイルを手作業で読む必要があります。networkx をスキップした場合は、重要度ランキングが得られません — エントリーポイントと README を読んで、重要な要素を判断してください。このフィールドは必ず確認し、それに応じて進め方を調整してください。

file_tree → ナビゲーションと漏れの検出 ファイル一覧全体を確認し、自動分析で見落とされた可能性のあるファイルを探します。

• 設定ファイル（.env.example、nginx.conf、terraform/）→ インフラストラクチャのドキュメント
• マイグレーションファイル → データベーススキーマの変遷
• シード／フィクスチャファイル → データモデルの把握
• 主流フレームワークの規約に沿わない、慣例的でない場所にあるファイル

スクリプトが利用できない場合、またはリポジトリがコンテキスト内のファイル内容として提供されている場合は、手動で調査してください。

1. ファイルツリーを確認する — プロジェクトの種類、言語、フレームワーク、モノレポ／ポリレポ構成を特定します
2. 基盤となるファイルを確認する：README、package.json / Cargo.toml / go.mod / pyproject.toml、Dockerfile、CI 設定、docs/ フォルダー
3. エントリーポイントを特定する：main/index ファイル、CLI コマンド、サーバーの起動処理、ルート定義
4. パターンを検出する：モノレポツール（Nx、Turborepo、Lerna）、プラグインシステム、マルチプロセスアーキテクチャ、DI コンテナー

Phase 2 — アーキテクチャのマッピング

偵察結果に基づき、Wiki のページツリーを定義します。分析レポートから次の情報を使用します。

1. key_entities（上位15件） → 上位にランクされたエンティティクラスターごとに、大きなセクションを作成します。関連するエンティティをディレクトリまたはドメインごとにグループ化します。
2. frameworks → 「コードベースの種類に応じた適応」から該当する行を選び、必須の特別ページを追加します。
3. symbols.by_kind → 図の方針を選びます：クラス中心ならコンポーネント図、関数中心ならシーケンス図、インターフェース中心ならコントラクト図／ER 図を使用します。
4. git.ownership → トップレベルディレクトリの所有権を使用して、セクションの境界がチームの境界と一致しているか検証します。

番号付きの階層を構築します。

0   - Index (navigation only — no TL;DR, no citations, no diagrams)
0.5 - Getting Started (installation, minimal working example, entry-point pointers)
1   - Overview
2   - [Major System A]
2.1 - [Subsystem A.1]
3   - [Major System B]
...
N   - Build & Development
N+1 - Testing Infrastructure

ルール：

• 最大深度：4レベル（例：3.2.1）
• 中規模のコードベースではトップレベルセクションを8～15件、大規模なコードベースでは15～25件にします
• 各トップレベルセクションにはサブセクションを2～6件設けます
• 最後の2つのセクションは必ず Build/Dev と Testing にします
• 必ず Getting Started ページ（00.5-getting-started.md）を作成します — 新しいエンジニア向けの入り口です。前提条件、インストール手順、最小限の実行可能な例（コードスニペット）、最初に読むべき最重要ファイル2～3件への案内を含めます。このページには引用や [NEEDS INVESTIGATION] マーカーは必要ありません。

ページを作成する前に、最上位のアーキテクチャ図（Mermaid graph TD）を作成します。

Phase 3 — 詳細ドキュメントの作成

各ページについて、references/page-template.md のテンプレートに従います。分析レポートを使用して、構造化されたセクションを作成します。

1. Relevant Source Files — このページの対象範囲に一致する key_entities の項目を使用します。正確なソースリンクには file と line の各フィールドを使用します。
2. TL;DR — 2～3文で記述します。開発者が続きを読む必要があるか判断できるようにします。
3. Architecture Diagram — symbols.by_kind の分布に基づき、references/diagram-patterns.md から適切な Mermaid パターンを選択します（Phase 2 の決定を参照）。
4. Key Concepts table — このセクションに属する key_entities を使用して作成します。kind フィールドを Type 列に、file:line を Source 列に使用します。
5. Component Reference table — このページのディレクトリ／ドメインで絞り込んだ symbols.items を使用します。名前、種類、file:line、実際のコードを読んで記述した簡潔な説明を含めます。
6. Source-linked claims — 技術的な主張にはすべて path/to/file.ts:L42-L87 形式で引用を付けます。symbols のデータを出発点として、実際のファイルを読んで検証し、行範囲を追加します。
7. Active areas — git.hotspots と照合し、このページ内で活発に開発されているコンポーネントを明示します。

ページを作成する前に、references/page-template.md を読んでください。 Mermaid 図を作成する前に、references/diagram-patterns.md を読んでください。

言語／フレームワーク固有の分析パターンについては、references/language-guides.md を読んでください。

Phase 4 — 組み立て

ページを最終出力にまとめます。出力形式はユーザーのニーズによって異なります。

ユーザーの依頼	出力形式
"Generate a wiki"	wiki/ ディレクトリに番号付きの .md ファイル一式
"Create an onboarding doc"	全ページをまとめた単一の .md ファイル
"Help me understand this repo"	図を含む対話形式の解説
"Make a presentation"	Wiki の内容を入力として pptx スキルに委ねます

ファイル形式で出力する場合は、次の構成にします。

wiki/
├── 00-index.md               (table of contents with links — no TL;DR/citations/diagrams)
├── 00.5-getting-started.md   (installation, minimal example, entry-point pointers)
├── 01-overview.md
├── 02-system-a.md
├── 02.1-subsystem-a1.md
├── ...
└── assets/
    └── diagrams/             (exported Mermaid if requested)

基本原則 — これらをお読みください

以下は、妥協できない品質基準です。

決して作り上げないでください。 すべての主張は、実際のコードに裏付けられている必要があります。検証できない場合は、確認が必要な具体的なファイルとともに [NEEDS INVESTIGATION] と記してください。

段階的に情報を開示してください。 TL;DR → 概要 → 詳細の順にします。すべてのセクションは、要約の段落から始めます。

システム思考を徹底してください。 アーキテクチャ → サブシステム → コンポーネント → メソッドの順にします。内部を説明する前に、つながりを整理してください。

表を活用してください。 3項目以上の構造化された情報は、すべて表にまとめます。必ず「ソース」列を含めてください。

図を最初に示してください。 3つ以上のコンポーネントが相互作用するシステムには、Mermaid 図が必要です。例外はありません。

広さより深さを優先してください。 実際のコードパスを追ってください。ファイル名から推測せず、ファイルを読んでください。

コードベースの種類に応じた適応

コードベースの種類	含める特別なページ
モノレポ	パッケージ／サービスの対応関係を示す「リポジトリ構造」；パッケージごとのサブツリー
マイクロサービス	「サービス間通信」（プロトコル、コントラクト、ディスカバリー）；サービスごとのセクション
フロントエンド SPA	ルーティング、状態管理、コンポーネント階層、ビルド／バンドル
バックエンド API	ルート定義、ミドルウェアパイプライン、データアクセス層、認証フロー、一般的なパターン（認証フロー、リクエスト検証、エラー処理）
ライブラリ／SDK	パブリック API サーフェス、拡張ポイント、利用パターン（一般的な統合パターン、設定、ライブラリの拡張）、利用例
CLI ツール	コマンド階層、引数解析、プラグインシステム
モバイルアプリ	ナビゲーション、状態管理、プラットフォーム固有のコード、ビルドバリアント

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

• ファイルツリーを説明するだけにする — ファイルを並べるだけにせず、それぞれの役割と相互のつながりを説明してください。
• README を繰り返す — 既存のドキュメントをまとめ直し、それ以上の価値を加えてください。
• 表面的な説明にとどめる — 「これは認証を処理します」だけでは役に立ちません。フローを追ってください。
• 「なぜ」を見落とす — コードからアーキテクチャ上の判断を推察してください。不明な点は疑問として示してください。
• 孤立したページを作る — すべてのページから概要にアクセスでき、関連する他のページへの相互参照もある状態にしてください。
• システムの図を省く — 3つ以上のコンポーネントが相互作用する場合、図は必須です。
• 名前から推測する — utils/helpers.ts の内容は名前だけではわかりません。まず読んでください。

依存関係とツール

アナライザー（scripts/analyze.py）はオーケストレーターパターンに従い、パーサーを再実装するのではなく、特化したツールを組み合わせます。依存関係はすべて任意です。スクリプトは、使用したものとスキップしたものを報告します。

すべてをインストールするには、次を実行します。pip install -r scripts/requirements.txt

Python パッケージ（すべて任意。利用できない場合も適切に処理します）：

パッケージ	可能になること	インストールされていない場合
tree-sitter-language-pack	165以上の言語に対応した AST 抽出：クラス、関数、インターフェース、型	コード構造のデータは取得されず、ファイル単位の統計のみ
pathspec	.gitignore を適切に考慮したファイル走査	ハードコードされた除外リストのみ
networkx	コードエンティティの PageRank 重要度ランキング	ランキングなし — すべてのシンボルを同等に扱う
tomli（Python <3.11）	pyproject.toml、Cargo.toml の適切な TOML 解析	Python 3.11 以降では標準ライブラリの tomllib を使用

CLI ツール（任意。実行時に検出します）：

ツール	可能になること	インストールされていない場合
tokei または scc	すべての言語にわたる、コメントを適切に処理した正確な LOC 統計	ファイルサイズに基づく概算
git	ホットスポットの検出、コントリビューターの対応付け、コードの所有権の把握	git の分析情報セクションなし

不要なもの：

• Mermaid CLI（mmdc） — 図は Mermaid のソースとして出力されます。レンダリングはビューアー側で行います
• 言語ツールチェーン（cargo、npm、pip） — アナライザーは適切なパーサー（JSON、TOML、XML）を使ってマニフェストを直接読み込みます
• ripgrep、jq、tree — スクリプトが検索と書式設定を内部で処理します

利用可能なスクリプト

• scripts/analyze.py — コードベースを自動で調査します。ファイルの検出、言語統計、マニフェストの解析、フレームワークの検出、AST ベースのコード構造、PageRank による重要度のランキング、Git の分析情報を含む JSON レポートを生成します。すべての依存関係は任意で、利用できない場合も適切に処理されます。
• scripts/eval.py — 複数の LLM／ハーネス実行間でオンボーディングドキュメントの出力を比較する品質評価ツールです。構成、引用の網羅率、図表、完全性、実行間の一貫性を評価します。
• scripts/requirements.txt — analyze.py 用の Python 依存関係です。pip install -r scripts/requirements.txt でインストールします。

ファイルリファレンス

ファイル	用途	読むタイミング
references/page-template.md	すべてのセクションを含むページの完全なテンプレート	Wiki ページを作成する前
references/diagram-patterns.md	シナリオ別の Mermaid 図のパターン	図を作成する前
references/language-guides.md	言語固有の分析パターン	なじみのない言語／フレームワークを分析するとき
scripts/analyze.py	コードベースの自動調査	フェーズ 1、リポジトリがローカルファイルシステム上にあるとき
scripts/eval.py	実行間のドキュメント品質と一貫性を評価	複数の LLM／ハーネス実行から出力を生成した後
scripts/requirements.txt	スクリプト用の Python 依存関係	セットアップ