# Codebase Onboarding

> 既存コードベースを新規参画者向けに解説するスキル。アーキテクチャ・主要モジュールと責務・代表的な処理フロー・開発の始め方・読み進める順序を整理してオンボーディング資料を生成する。「このコードベースを解説して」「全体像を教えて」「アーキテクチャを把握したい」「どこから読めばいい」「オンボーディング資料を作って」などで発動する。人が理解するための地図づくりを行う。

- Skill: `ynitto/codebase-onboarding` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ynitto/codebase-onboarding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ynitto/codebase-onboarding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ynitto (https://skillmd.com/u/ynitto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ynitto/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: オンボーディング資料を出力する

以下の構成で出力する:

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

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

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

## ガードレール

| 制限 | 内容 |
|------|------|
| 事実性 | 実際のファイル/構成に基づく。存在しない構造・手順を書かない。不明は「要確認」 |
| 鮮度 | 推測でバージョンや手順を断定せず、設定ファイルの実値を参照する |
| 適切な粒度 | 全ファイルを列挙しない。理解に必要な主要素に絞り、深掘りは入口だけ示す |
| 機密 | 設定ファイル中の秘匿値（鍵・トークン）を資料に転記しない |