Codebase Onboarding

codebase-onboarding

初めてこのコードベースに触る人が、最短で全体像を掴み、自力で読み進められるようにする「地図」を作る。詳細仕様の網羅ではなく、理解の入口と道筋を与えることが目的。

code-to-specs は実装からの仕様抽出。本スキルは人間の学習順序に沿った俯瞰的ガイドを作る。

原則

• 実体に基づく — 実際のディレクトリ・ファイル・依存を調べて書く。推測で構成を語らない
• 俯瞰から詳細へ — まず全体像、次に主要モジュール、最後に深掘りポイント
• 読む順序を示す — 「まずここ、次にここ」を提示し、迷わせない
• 動かせるまで — ビルド・テスト・実行の手順をセットにする（読むだけで終わらせない）

ワークフロー

Step 1: 全体像を調査する

1. リポジトリ構成を調べる: ディレクトリ構造・エントリポイント・ビルド設定・README/CONTRIBUTING
2. 技術スタックを特定: 言語・フレームワーク・主要依存・データストア（マニフェストから）
3. 広域の把握には Explore エージェントを活用し、命名規約・レイヤ構成を掴む

Step 2: アーキテクチャを掴む

• アプリの型を判定（モノリス/マイクロサービス/ライブラリ/CLI/フロント＋API 等）
• レイヤ/モジュール分割と依存方向を把握する
• 主要な境界（API 層・ドメイン・データアクセス・外部連携）を特定する

Step 3: 主要モジュールと責務を整理する

• 重要度の高いディレクトリ/パッケージごとに「何を担うか」を1〜2行で要約する
• エントリポイントから主要な依存を辿り、中心となるモジュールを見極める

Step 4: 代表的な処理フローを辿る

• 典型的なユースケース（例: リクエスト受信→処理→応答、主要なバッチ）を1〜2本選び、関与するファイルを順に辿る
• フローは mermaid-diagrammer でシーケンス図/フローチャート化する

Step 5: 開発の始め方を整理する

• セットアップ・ビルド・テスト・ローカル実行のコマンド（実在する設定から）
• 設定/環境変数、よくあるハマりどころ
• 貢献の流れ（ブランチ運用・レビュー）。CI 構成は実ファイルから確認

Step 6: オンボーディング資料を出力する

以下の構成で出力する:

# <プロジェクト名> オンボーディングガイド

## これは何か（1段落）
## 技術スタック
## アーキテクチャ概観（+ 図）
## ディレクトリ/モジュールマップ（表: パス → 責務）
## 代表的な処理フロー（+ シーケンス図）
## 開発の始め方（セットアップ/ビルド/テスト/実行）
## 読み進める順序（おすすめルート）
## 用語集 / 注意点・落とし穴

wiki-use / obsidian-use への保存や、リポジトリの docs/・README への取り込みを提案する。

ガードレール