Docs Reverse

---
user-invocable: true
description: "[ドキュメント] リバースエンジニアリングによるドキュメント作成（俯瞰/引き継ぎ用）"
---

# [ドキュメント] リバースエンジニアリングによるドキュメント作成（俯瞰/引き継ぎ用）

## 入力: `$ARGUMENTS`（解析対象ディレクトリの相対パスを**半角スペース区切り**で複数可）
例:
    src backend/services packages/auth

---

## 🎯 目的
- AIが作ったアプリを、**人間もAIも**俯瞰/詳細で理解できるドキュメントを生成/更新する
- 新しい人が既存アプリを理解でき、開発者が「AIが何をしたか/どう作ったか」を追える状態にする
- **Google Design Doc** の構成要素を踏襲し、設計判断の背景・トレードオフを可視化する
- **SSOT（Single Source of Truth）** を守りつつ、生成物を `doc/generated/reverse/` に集約

---

## 前提/参照（SSOT）
- **SSOT**: `doc/input/rdd.md`, `doc/input/architecture.md`, `doc/input/design/*`（存在すれば）
- **生成物の出力先**: `doc/generated/reverse/`（上書き更新してよい。履歴はGitで追跡）

---

## 出力ドキュメント構成

```
doc/generated/reverse/
├── index.md              # 入口 + 読み方ガイド
├── overview.md           # 俯瞰（背景/目標/非目標/システム概要）
├── architecture.md       # アーキテクチャ（設計判断/代替案/トレードオフ）
├── database.md           # DB詳細（スキーマ/ER図/制約）
├── api.md                # API仕様（あれば）
├── security.md           # セキュリティ考慮（あれば）
├── observability.md      # 監視/メトリクス（あれば）
├── modules/              # モジュール詳細
│   └── {module}.md
└── ssot_diff.md          # SSOT差分提案（あれば）
```

---

## 各ドキュメントの定型構造

### index.md（入口）
```markdown
# {プロジェクト名} 設計ドキュメント

## このドキュメントについて
- 生成日時: YYYY-MM-DD
- 解析対象: {対象ディレクトリ}
- SSOT参照: doc/input/rdd.md, doc/input/architecture.md

## 読む順番（推奨）
1. [overview.md](overview.md) - まず全体像を把握
2. [architecture.md](architecture.md) - 設計判断の背景を理解
3. [database.md](database.md) - データ構造を確認
4. [api.md](api.md) - 外部インターフェースを確認
5. [modules/](modules/) - 必要なモジュールを深掘り

## SSOT差分（要確認）
- [ssot_diff.md](ssot_diff.md) - SSOTとの差分提案
```

### overview.md（俯瞰 - Design Doc: Overview/Background/Goals）
```markdown
# システム概要

## 背景（Background）
<!-- なぜこのシステムが存在するか。rdd.md から抽出または推測 -->

## 目標（Goals）
<!-- このシステムが達成すべきこと -->

## 非目標（Non-Goals）
<!-- 明示的にスコープ外としていること -->

## システム構成図
<!-- Mermaid: コンポーネント図/コンテキスト図 -->

## 主要な技術スタック
<!-- 使用言語/フレームワーク/インフラ -->

## 次に読むべきドキュメント
- 設計判断の詳細 → [architecture.md](architecture.md)
- データ構造 → [database.md](database.md)
```

### architecture.md（アーキテクチャ - Design Doc: Design/Alternatives/Trade-offs）
```markdown
# アーキテクチャ

## 設計方針
<!-- アーキテクチャパターン、レイヤー構成 -->

## コンポーネント図
<!-- Mermaid: C4 Component または簡易ブロック図 -->

## データフロー
<!-- Mermaid: シーケンス図またはフローチャート -->

## 設計判断（ADR-lite）
### {判断1: 例}
- **決定**: {何を選んだか}
- **理由**: {なぜ選んだか}
- **代替案**: {検討したが採用しなかった案}
- **トレードオフ**: {この決定による得失}

## 依存関係
<!-- 外部サービス/ライブラリへの依存 -->
```

### database.md（DB詳細）
```markdown
# データベース設計

## 概要
<!-- DB種別、接続情報の概要（認証情報は除く） -->

## ER図
<!-- Mermaid erDiagram: エンティティ関係図 -->

## テーブル定義

### {テーブル名}
| カラム | 型 | 制約 | 説明 |
|--------|-----|------|------|
| id | UUID | PK | 主キー |
| ... | ... | ... | ... |

**インデックス:**
- `idx_{name}`: {対象カラム} - {目的}

**制約:**
- FK: {外部キー制約の説明}
- UNIQUE: {一意制約の説明}
- CHECK: {チェック制約の説明}

## マイグレーション履歴（検出できれば）
| バージョン | 日時 | 概要 |
|------------|------|------|
| ... | ... | ... |

## データフロー
<!-- どのテーブルがどの処理で更新されるか -->
```

### api.md（API仕様）
```markdown
# API仕様

## 認証方式
<!-- JWT/Session/API Key 等 -->

## エンドポイント一覧

### {グループ名}

#### `{METHOD} {path}`
- **認証**: 要/不要
- **説明**: {概要}
- **リクエスト例**:
```json
{}
```
- **レスポンス例**:
```json
{}
```
- **エラーコード**:
  - `400`: {説明}
  - `401`: {説明}
```

### security.md（セキュリティ考慮）
```markdown
# セキュリティ考慮

## 認証・認可
<!-- 認証方式、権限モデル -->

## データ保護
<!-- 暗号化、個人情報の扱い -->

## 入力検証
<!-- バリデーション方針 -->

## 既知のリスクと対策
| リスク | 対策 | 状態 |
|--------|------|------|
| ... | ... | 対応済/TODO |
```

### observability.md（監視・メトリクス）
```markdown
# 監視・観測性

## ログ
<!-- ログレベル、出力先、フォーマット -->

## メトリクス
<!-- 収集している指標 -->

## アラート
<!-- 設定しているアラート条件 -->

## トレーシング
<!-- 分散トレーシングの有無 -->
```

### modules/{module}.md（モジュール詳細）
```markdown
# {モジュール名}

## 責務
<!-- このモジュールが担う責任 -->

## 公開インターフェース
<!-- エクスポートしている関数/クラス -->

## 依存関係図
<!-- Mermaid: このモジュールの依存 -->

## 主要な処理フロー
<!-- Mermaid: シーケンス図 -->

## 設計意図
<!-- なぜこの構造にしたか -->
```

---

## Mermaid検証（必須）

図を出力する際は、以下の手順で**描画可能性を検証**する:

1. **構文チェック**: Mermaid記法が正しいか確認
2. **検証コマンド**（`mmdc` がある場合）:
   ```bash
   # mermaid-cliでバリデーション
   echo '{mermaid_code}' | npx -y @mermaid-js/mermaid-cli -i - -o /dev/null
   ```
3. **エラー時**: 構文を修正してから出力（推測で壊れた図を出さない）
4. **検証不可時**: 「※ Mermaid構文は手動確認推奨」と注記

### Mermaid記法の注意点
- ノード名に特殊文字がある場合は `""` で囲む
- 日本語ラベルは `["日本語"]` 形式を使う
- 長いラベルは改行 `<br/>` で分割

---

## 実行仕様

### 1. コード解析
- エントリポイント（CLI/HTTP/RPC/イベント/ジョブ）を特定
- データモデル（エンティティ/DTO/スキーマ）を抽出
- 依存関係（import/require）をグラフ化
- Docコメント（JSDoc/Docstring）を抽出

### 2. DB解析（存在する場合）
- スキーマ定義ファイル（Prisma/TypeORM/Drizzle/SQL等）を検出
- マイグレーションファイルを検出
- ER図をMermaidで生成

### 3. SSOT整合チェック
- `doc/input/rdd.md`, `doc/input/architecture.md` との差分を検出
- 不一致は `ssot_diff.md` に提案として記録（勝手に上書きしない）

### 4. ドキュメント生成
- 各ドキュメントを定型構造で生成/更新
- **図と説明は同じファイルに配置**（別ファイルに分離しない）
- 各ドキュメント末尾に「次に読むべきドキュメント」を記載

---

## 品質チェックリスト

- [ ] SSOT整合（rdd.md / architecture.md との齟齬を ssot_diff.md に記録）
- [ ] Mermaid図が検証済み（構文エラーなし）
- [ ] 各ドキュメントに定型ヘッダー（目的/スコープ）あり
- [ ] 図と説明が同じファイルに配置されている
- [ ] 「次に読むべきドキュメント」が各ファイル末尾にある
- [ ] DB詳細（database.md）にER図とテーブル定義がある
- [ ] 設計判断（ADR-lite）にトレードオフが明記されている
- [ ] Docコメント不足箇所はTODOで明示

---

## 自己評価（1–10）
- 自信度: X/10
- 根拠（1行）: …
- 次の改善（2–3件）: …

---

## 変更要求（ADR-lite）テンプレ（必要時のみ）
```
Change Request: {タイトル}
- RDD参照: doc/input/rdd.md §{該当セクション}
- 現状の制約: {なぜRDD準拠だと難しいか}
- 提案差分: {スタック/設計の変更内容（最小）}
- 影響: {テスト/運用/セキュリティ/コスト}
- 代替案: {検討したが採用しない案}
- 戻し方: {ロールバック手順}
- 推奨: 承認/却下の判断材料
```

---

## 備考
- **Docコメント不足**の箇所は TODO として明示。次スプリントで補完。
- 技術スタック逸脱が必要な場合は **変更要求（ADR-lite）** を同時出力し、**承認が出るまで実装反映は行わない**。
- セキュリティ/監視の情報がコードから検出できない場合は、該当ファイルをスキップ（空ファイルを作らない）。