# Doc Gen

> コードベースから開発者向けドキュメントを生成する。3パス読み取りアプローチで根拠に基づく信頼性の高いドキュメントを作成。「ドキュメント生成」「コードからドキュメント」「codebase map作成」「代表フロー抽出」「変更ガイド作成」と言われた時に使用。生成するのはコードベースマップ、代表フロー（成功+失敗）、変更プレイブック、設定/外部I/F台帳、検証レポート。継続的開発の属人化を防ぎ、変更の安全性を高めるドキュメントを目指す。

- Skill: `majiayu000/doc-gen` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/doc-gen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/doc-gen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/doc-gen

---


# Doc-Gen: コードベースドキュメント生成

3パス読み取りによる根拠ベースのドキュメント生成。

## 目的

- **対象**: プロダクトコード
- **読者**: 開発者（新規参加者・継続メンテナ）
- **課題**: 開発の継続性・属人化の解消
- **成果物**: 参照され続ける検証可能なドキュメント

## 生成AIの限界を前提とした設計

### 強み（活用する）
- 大量情報の構造化要約 → 読む負荷を下げる
- 散在断片の統合 → 共通言語を作る

### 弱み（対策が必要）
- 根拠なき補完 → **「整っている嘘」を作りやすい**
- ハッピーパス偏重 → **境界条件・例外が落ちる**

→ 生成ではなく**根拠・検証・更新**に寄せる設計

## 3パスアプローチ概要

```
Pass 1: 事実索引（Fact Index）
  ↓ 根拠リンク付きの事実を蓄積
Pass 2: 横断統合（Integration）
  ↓ 地図・代表フロー・変更ガイドに統合
Pass 3: 検証（Verification）
  ↓ 根拠ゲート・矛盾ゲートで信頼性獲得
Feedback: フィードバックを制約として蓄積
```

詳細: [references/](references/)

## 実行手順

### 1. スコープ確定

```
対象リポジトリ: [path]
読者タイプ: 新規参加者 / 継続メンテナ / 両方
優先成果物: Map / Flows / Playbook / Registry / All
```

### 2. Pass 1: Fact Index 作成

**入力整形**
1. エントリポイント特定（CLI, HTTPハンドラ, イベント購読, ジョブ起点）
2. シンボル単位でチャンク化（行数分割ではなく意味単位）
3. 静的解析・メタデータ優先収集
   - OpenAPI/GraphQL/マイグレーション/設定定義/依存関係/テスト一覧

**事実抽出ルール**
- 断定できるもの: シグネチャ, HTTPパス, 例外型, 設定キー, 依存先
- 断定しないもの: 意図・理由（原則「不明」扱い）
- 必須: 根拠参照（ファイルパス:行範囲）

**副作用リスト**（継続性の急所）
- DB書込み, 外部API呼出し, イベント発行, ジョブ投入, キャッシュ更新

詳細: [references/10-pass1-fact-index.md](references/10-pass1-fact-index.md)

### 3. Pass 2: 横断統合

**Codebase Map**
- モジュール責務・依存関係・入口・主要データ・外部境界
- 新規参加者が最初の変更を成立させられる情報

**代表フロー選定** (2-5本)

| 評価軸 | 説明 |
|--------|------|
| 変更頻度 | 頻繁に触る部分をカバー |
| 境界条件 | 認証/DB/非同期/外部連携/削除・退会 |
| 不変条件 | 冪等性/整合性/権限/監査/状態遷移 |
| 被害規模 | 障害時のインパクト |
| 追跡可能性 | ログ/トレースの有無 |

各フローは **成功 + 代表失敗2件** をセットで記述

**Change Playbook**
- 「Aを変えるならB/Cも確認」
- 破壊的変更になりやすい境界
- 追加すべきテスト

詳細: [references/20-pass2-integration.md](references/20-pass2-integration.md)

### 4. Pass 3: 検証

**Evidence Gate（根拠ゲート）**
```
重要な断定文 → 根拠参照あり？
  YES → 維持
  NO  → 表現を弱める or 「未確認」として隔離
```

**Consistency Gate（矛盾ゲート）**
- Pass 1の事実 ⟷ Pass 2の説明の整合性チェック
- 矛盾があれば修正 or フラグ

**Task-based Verification**
- 「ローカルで動かす」手順は実行可能か？
- 「変更する」ときに必要な情報は揃っているか？
- 「影響範囲を見る」ときに追えるか？

詳細: [references/30-pass3-verification.md](references/30-pass3-verification.md)

### 5. Feedback Loop

指摘を分類:
1. **事実誤認** → Pass 1に戻す
2. **カバレッジ不足** → Pass 2で補完
3. **読みにくさ** → 構造・粒度調整

→ 指摘を**次回の出力制約**として記録

詳細: [references/40-feedback-loop.md](references/40-feedback-loop.md)

## 成果物フォーマット

### Codebase Map

```markdown
# Codebase Map

## 概要
[1-2文でシステムの目的]

## モジュール構成
| モジュール | 責務 | 主要依存 |
|-----------|------|---------|
| auth/     | 認証 | db, redis |

## エントリポイント
- HTTP: src/api/routes.ts
- CLI: src/cli/main.ts

## 外部境界
| 外部システム | 用途 | 設定 |
|-------------|------|------|
| PostgreSQL  | 永続化 | DATABASE_URL |
```

### 代表フロー

```markdown
# フロー: ユーザー登録

## 成功シナリオ
1. POST /users → UsersController.create (src/api/users.ts:45)
2. UserService.register (src/services/user.ts:78)
3. DB INSERT → users table
4. Event: user.created → NotificationService

## 失敗シナリオ1: 重複メール
- 条件: 既存ユーザーと同一メール
- 発生箇所: UserService.register:92
- 結果: DuplicateEmailError → 409 Conflict

## 失敗シナリオ2: DB接続エラー
- 条件: DBタイムアウト
- 発生箇所: UserRepository.insert:34
- 結果: リトライ3回 → 500 Internal Error

## 不変条件
- メールアドレスはシステム内で一意
- パスワードはハッシュ化して保存（平文保存禁止）
```

### Change Playbook

```markdown
# 変更ガイド: 認証ロジック

## 影響範囲
- auth/ を変更 → sessions/, permissions/ を確認

## 破壊的変更の境界
- JWTクレームの構造変更 → 全クライアント影響

## 必須テスト
- tests/integration/auth_flow.test.ts
- tests/e2e/login.spec.ts

## レビュー観点
- [ ] セッション無効化の整合性
- [ ] トークン有効期限の妥当性
```

## 危険領域（人間判断必須）

| 領域 | 理由 | 扱い方 |
|------|------|--------|
| 意図・理由の断定 | コードに書いていない | 「草案」として隔離、ADRで決裁 |
| 性能・SLA | 実測が必要 | 「測定が必要」と明記 |
| 非同期・分散の細部 | 実行時に決まる | 代表失敗シナリオ必須 |

## 品質チェックリスト

```markdown
### Pass 1
- [ ] 事実と推測を分離したか
- [ ] 根拠参照（file:line）を付けたか
- [ ] 副作用を列挙したか

### Pass 2
- [ ] 代表フローは境界条件を含むか
- [ ] 成功+失敗2件をセットにしたか
- [ ] 変更ガイドは具体的か（一般論でないか）

### Pass 3
- [ ] 根拠のない断定を弱めたか
- [ ] Pass 1/2間の矛盾を解消したか
- [ ] 開発者タスクで検証したか

### 全体
- [ ] 更新コストを考慮した粒度か
- [ ] 日本語で記述されているか
- [ ] 参照され続ける見込みがあるか
```