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

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

目的

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

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

強み（活用する）

•大量情報の構造化要約 → 読む負荷を下げる
•散在断片の統合 → 共通言語を作る

弱み（対策が必要）

•根拠なき補完 → 「整っている嘘」を作りやすい
•ハッピーパス偏重 → 境界条件・例外が落ちる

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

3パスアプローチ概要

code

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

詳細: references/

実行手順

1. スコープ確定

code

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

2. Pass 1: Fact Index 作成

入力整形

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

事実抽出ルール

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

副作用リスト（継続性の急所）

•DB書込み, 外部API呼出し, イベント発行, ジョブ投入, キャッシュ更新

詳細: 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

4. Pass 3: 検証

Evidence Gate（根拠ゲート）

code

重要な断定文 → 根拠参照あり？
  YES → 維持
  NO  → 表現を弱める or 「未確認」として隔離

Consistency Gate（矛盾ゲート）

•Pass 1の事実 ⟷ Pass 2の説明の整合性チェック
•矛盾があれば修正 or フラグ

Task-based Verification

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

詳細: references/30-pass3-verification.md

5. Feedback Loop

指摘を分類:

•事実誤認 → Pass 1に戻す
•カバレッジ不足 → Pass 2で補完
•読みにくさ → 構造・粒度調整

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

詳細: 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間の矛盾を解消したか
- [ ] 開発者タスクで検証したか

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