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


---
Source attribution: mae616
Original project: https://github.com/mae616/ai-template/blob/65af96597292445cdebc026dbc1fb1169b87f4cd/.claude/skills/docs-reverse/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2024 AI Template Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: mae616
Original project: https://github.com/mae616/ai-template/blob/65af96597292445cdebc026dbc1fb1169b87f4cd/.claude/skills/docs-reverse/SKILL.md
Attribution basis: Recovered original package and original project license at a pinned revision

Fields of work: Content & Media, Design, Product Management
Roles: Product Manager, Technical Writer, UX Writer
Specialties: Word Documents
Tools: Tool not specified
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 659f778a1224b0eb943de7cf352fd3d3b26f8934ac4409b7f6df08d088749aa4
Metadata reviewed: 2026-10-27
This metadata supersedes earlier Dave AI catalog attribution. Original instruction and supporting files are preserved.