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

入力:

$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（入口）

# {プロジェクト名} 設計ドキュメント

## このドキュメントについて
- 生成日時: 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）

# システム概要

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

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

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

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

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

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

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

# アーキテクチャ

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

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

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

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

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

database.md（DB詳細）

# データベース設計

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

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

## テーブル定義

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

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

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

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

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

api.md（API仕様）

# API仕様

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

## エンドポイント一覧

### {グループ名}

#### `{METHOD} {path}`
- **認証**: 要/不要
- **説明**: {概要}
- **リクエスト例**:
```json
{}

• レスポンス例:

{}

• エラーコード:

  • 400

    : {説明}

  • 401

    : {説明}

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

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

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

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

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

observability.md（監視・メトリクス）

# 監視・観測性

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

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

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

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

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

# {モジュール名}

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

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

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

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

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

---

Mermaid検証（必須）

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

1. 構文チェック: Mermaid記法が正しいか確認
2. 検証コマンド（

   mmdc

   がある場合）:

   # 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） を同時出力し、承認が出るまで実装反映は行わない。
• セキュリティ/監視の情報がコードから検出できない場合は、該当ファイルをスキップ（空ファイルを作らない）。