CAPHTECH Doc-Gen: コードベースドキュメント生成
3パス読み取りによる根拠ベースのドキュメント生成。
目的
- 対象: プロダクトコード
- 読者: 開発者（新規参加者・継続メンテナ）
- 課題: 開発の継続性・属人化の解消
- 成果物: 参照され続ける検証可能なドキュメント
設計方針
生成AIは根拠なき補完（「整っている嘘」）とハッピーパス偏重に陥りやすいため、生成ではなく根拠・検証・更新に寄せて設計する。
3パスアプローチ概要
Pass 1: 事実索引（Fact Index）
↓ 根拠リンク付きの事実を蓄積
Pass 2: 横断統合（Integration）
↓ 地図・代表フロー・変更ガイドに統合
Pass 3: 検証（Verification）
↓ 根拠ゲート・矛盾ゲートで信頼性獲得
Feedback: フィードバックを制約として蓄積
詳細: references/
実行手順
1. スコープ確定
対象リポジトリ: [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（根拠ゲート）
重要な断定文 → 根拠参照あり？
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
# Codebase Map
## 概要
[1-2文でシステムの目的]
## モジュール構成
| モジュール | 責務 | 主要依存 |
|-----------|------|---------|
| auth/ | 認証 | db, redis |
## エントリポイント
- HTTP: src/api/routes.ts
- CLI: src/cli/main.ts
## 外部境界
| 外部システム | 用途 | 設定 |
|-------------|------|------|
| PostgreSQL | 永続化 | DATABASE_URL |
代表フロー
# フロー: ユーザー登録
## 成功シナリオ
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
# 変更ガイド: 認証ロジック
## 影響範囲
- auth/ を変更 → sessions/, permissions/ を確認
## 破壊的変更の境界
- JWTクレームの構造変更 → 全クライアント影響
## 必須テスト
- tests/integration/auth_flow.test.ts
- tests/e2e/login.spec.ts
## レビュー観点
- [ ] セッション無効化の整合性
- [ ] トークン有効期限の妥当性
危険領域（人間判断必須）
| 領域 | 理由 | 扱い方 |
|---|---|---|
| 意図・理由の断定 | コードに書いていない | 「草案」として隔離、ADRで決裁 |
| 性能・SLA | 実測が必要 | 「測定が必要」と明記 |
| 非同期・分散の細部 | 実行時に決まる | 代表失敗シナリオ必須 |
| セキュリティ保証 | 攻撃パターンは無限 | リスク示唆のみ、保証は不可 |
品質チェックリスト
### Pass 1
- [ ] 事実と推測を分離したか
- [ ] 根拠参照（file:line）を付けたか
- [ ] 副作用を列挙したか
### Pass 2
- [ ] 代表フローは境界条件を含むか
- [ ] 成功+失敗2件をセットにしたか
- [ ] 変更ガイドは具体的か（一般論でないか）
### Pass 3
- [ ] 根拠のない断定を弱めたか
- [ ] Pass 1/2間の矛盾を解消したか
- [ ] 開発者タスクで検証したか
### 全体
- [ ] 更新コストを考慮した粒度か
- [ ] 日本語で記述されているか
- [ ] 参照され続ける見込みがあるか