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（入口）
# {プロジェクト名} 設計ドキュメント
## このドキュメントについて
- 生成日時: 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検証（必須）
図を出力する際は、以下の手順で描画可能性を検証する:
- 構文チェック: Mermaid記法が正しいか確認
- 検証コマンド（
mmdcがある場合）:# mermaid-cliでバリデーション echo '{mermaid_code}' | npx -y @mermaid-js/mermaid-cli -i - -o /dev/null - エラー時: 構文を修正してから出力（推測で壊れた図を出さない）
- 検証不可時: 「※ 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） を同時出力し、承認が出るまで実装反映は行わない。
- セキュリティ/監視の情報がコードから検出できない場合は、該当ファイルをスキップ（空ファイルを作らない）。