code-to-prd

Name

Code → PRD

Description

フロントエンド、バックエンド、またはフルスタックのあらゆるコードベースをリバースエンジニアリングし、完全な製品要件定義書（PRD）を作成します。ルート、コンポーネント、モデル、API、ユーザーインタラクションを分析し、エンジニアやAIエージェントがすべてのページとエンドポイントを完全に再構築できるほど詳細で、ビジネス関係者にも読みやすいドキュメントを生成します。

Code → PRD：あらゆるコードベースをリバースエンジニアリングして製品要件に変換

機能

• 3段階のワークフロー：全体スキャン → ページごとの分析 → 構造化ドキュメントの生成
• フロントエンド対応：React、Vue、Angular、Svelte、Next.js（App + Pages Router）、Nuxt、SvelteKit、Remix
• バックエンド対応：NestJS、Express、Django、Django REST Framework、FastAPI、Flask
• フルスタック対応：フロントエンドとバックエンドをまとめて分析し、統合されたPRDを出力
• モック検出：実際のAPI連携とモック／フィクスチャデータを自動で判別
• 列挙型の抽出：すべてのステータスコード、型マッピング、定数を漏れなく列挙
• モデルの抽出：Djangoモデル、NestJSエンティティ、Pydanticスキーマを解析
• 自動化スクリプト：スキャン用の codebase_analyzer.py、ディレクトリ生成用の prd_scaffolder.py
• 品質チェックリスト：完全性、正確性、読みやすさを検証するチェックリスト

使用方法

# Analyze a project and generate PRD skeleton
python3 scripts/codebase_analyzer.py /path/to/project -o analysis.json
python3 scripts/prd_scaffolder.py analysis.json -o prd/ -n "My App"

# Or use the slash command
/code-to-prd /path/to/project

例

フロントエンド（React）

/code-to-prd ./src
# → Scans components, routes, API calls, state management
# → Generates prd/ with per-page docs, enum dictionary, API inventory

バックエンド（Django）

/code-to-prd ./myproject
# → Detects Django via manage.py, scans urls.py, views.py, models.py
# → Documents endpoints, model schemas, admin config, permissions

フルスタック（Next.js）

/code-to-prd .
# → Analyzes both app/ pages and api/ routes
# → Generates unified PRD covering UI pages and API endpoints

---

役割

あなたは、シニアプロダクトアナリスト兼テクニカルアーキテクトです。フロントエンドのコードベースを読み、各ページのビジネス上の目的を理解し、プロダクトマネージャーにわかりやすい言葉で完全なPRDを作成してください。

対象読者は2種類

1. プロダクトマネージャー／ビジネス関係者 — システムの仕組みではなく、システムが何をするかを理解する必要があります
2. エンジニア／AIエージェント — すべてのページのフィールド、インタラクション、関連性を完全に再構築するために十分な詳細が必要です

ドキュメントでは、技術的でない言葉で機能を説明しつつ、ビジネス上の詳細を一切省略しないでください。

対応スタック

スタック	フレームワーク
フロントエンド	React、Vue、Angular、Svelte、Next.js（App/Pages Router）、Nuxt、SvelteKit、Remix、Astro
バックエンド	NestJS、Express、Fastify、Django、Django REST Framework、FastAPI、Flask
フルスタック	Next.js（API routes + pages）、Nuxt（server/ + pages/）、Django（views + templates）

バックエンドのみのプロジェクトでは、「ページ」という概念をAPIリソースグループまたは管理画面に置き換えます。同じ3段階のワークフローを適用します。ルートはエンドポイントに、コンポーネントはコントローラー／ビューに、インタラクションはリクエスト／レスポンスのフローに対応します。

---

ワークフロー

フェーズ1 — プロジェクト全体のスキャン

ページの詳細な調査に入る前に、プロジェクト全体のコンテキストを把握します。

1. プロジェクト構造を特定する

ルートディレクトリをスキャンし、構成を把握します。

Frontend directories:
- Pages/routes (pages/, views/, routes/, app/, src/pages/)
- Components (components/, modules/)
- Route config (router.ts, routes.ts, App.tsx route definitions)
- API/service layer (services/, api/, requests/)
- State management (store/, models/, context/)
- i18n files (locales/, i18n/) — field display names often live here

Backend directories (NestJS):
- Modules (src/modules/, src/*.module.ts)
- Controllers (*.controller.ts) — route handlers
- Services (*.service.ts) — business logic
- DTOs (dto/, *.dto.ts) — request/response shapes
- Entities (entities/, *.entity.ts) — database models
- Guards/pipes/interceptors — auth, validation, transformation

Backend directories (Django):
- Apps (*/apps.py, */views.py, */models.py, */urls.py)
- URL config (urls.py, */urls.py)
- Views (views.py, viewsets.py) — route handlers
- Models (models.py) — database schema
- Serializers (serializers.py) — request/response shapes
- Forms (forms.py) — validation and field definitions
- Templates (templates/) — server-rendered pages
- Admin (admin.py) — admin panel configuration

package.json（Node.jsフレームワークの場合）またはプロジェクトファイル（Djangoの場合は manage.py、Pythonの場合は requirements.txt／pyproject.toml）からフレームワークを特定します。ルーティング、コンポーネントのパターン、状態管理はフレームワークによって大きく異なります。特定することで、正確に解析できるようになります。

2. ルートとページの一覧

ルート設定からすべてのページを抽出し、完全なページ一覧を作成します。

項目	説明
ルートパス	例：/user/list、/order/:id
ページタイトル	ルート設定、パンくずリスト、またはページコンポーネントから取得
モジュール／メニュー階層	ナビゲーション上の配置
コンポーネントのファイルパス	このページを実装するソースファイル

ファイルシステムルーティング（Next.js、Nuxt）の場合は、ディレクトリ構造から推定します。

バックエンドプロジェクトの場合、ページ一覧はエンドポイント／リソース一覧になります。

項目	説明
エンドポイントパス	例：/api/users、/api/orders/:id
HTTP メソッド	GET、POST、PUT、DELETE、PATCH
コントローラー／ビュー	このルートを処理するソースファイル
モジュール／アプリ	所有する NestJS モジュールまたは Django アプリ
認証の要否	認証／権限が必要かどうか

NestJS の場合：@Controller と @Get/@Post/@Put/@Delete デコレーターから抽出します。 Django の場合：urls.py の urlpatterns と viewsets.py のルーター登録から抽出します。

3. グローバルコンテキストを把握する

個々のページを分析する前に、以下を記録します。

• グローバル状態 — ユーザー情報、権限、機能フラグ、設定
• 共有コンポーネント — レイアウト、ナビゲーション、認証ガード、エラーバウンダリー
• 列挙型と定数 — ステータスコード、型マッピング、ロール定義
• API のベース設定 — ベース URL、インターセプター、認証ヘッダー、エラー処理
• データベースモデル（バックエンド）— エンティティ間の関係、フィールドの型、制約
• ミドルウェア（バックエンド）— 認証ミドルウェア、レート制限、ロギング、CORS
• DTO／シリアライザー（バックエンド）— リクエストの検証形式、レスポンス形式

これらはページ／エンドポイントの分析全体で参照します。

---

フェーズ 2 — ページごとの詳細分析

一覧内のすべてのページを分析します。各ページについて、個別の Markdown ファイルを作成します。

分析項目

各ページについて、以下に回答します。

A. ページ概要

• このページの役割（1 文）
• システム内での位置付け
• ユーザーがこのページを開く状況

B. レイアウトと領域

• 主な領域：検索エリア、テーブル、詳細パネル、アクションバー、タブなど
• 空間的な配置：上下、左右、入れ子構造

C. フィールド一覧（中心となる項目 — 漏れなく網羅）

フォームページの場合、すべてのフィールドを列挙します。

フィールド名	型	必須	デフォルト値	バリデーション	業務上の説明
ユーザー名	テキスト入力	はい	—	最大 20 文字	システムへのログインアカウント

テーブル／一覧ページの場合、以下を列挙します。

• 検索／フィルターフィールド（型、必須、列挙型の選択肢）
• テーブル列（名前、形式、ソート可能か、フィルター可能か）
• 行のアクションボタン（それぞれの機能）

フィールド名の抽出優先順位：

1. コード内のハードコードされた表示テキスト
2. i18n の翻訳値
3. コンポーネントの placeholder／label／title プロパティ
4. 変数名（最後の手段として、妥当な表示名を付ける）

D. インタラクションロジック

**「ユーザーの操作 → システムの応答」**の形式で記述します。

[Action]     User clicks "Create"
[Response]   Modal opens with form fields: ...
[Validation] Name required, phone format check
[API]        POST /api/user/create with form data
[Success]    Toast "Created successfully", close modal, refresh list
[Failure]    Show API error message

以下のすべてのインタラクション種別を網羅します。

• ページの読み込み／初期化（デフォルトのクエリ、事前読み込みデータ）
• 検索／フィルター／リセット
• CRUD 操作（作成、読み取り、更新、削除）
• テーブル：ページネーション、ソート、行選択、一括操作
• フォーム送信とバリデーション
• ステータス遷移（例：承認フロー：保留 → 承認済み → 却下）
• インポート／エクスポート
• フィールド間の依存関係（フィールド A の値を選ぶとフィールド B の選択肢が変わる）
• 権限制御（特定のロールにのみボタン／フィールドを表示）
• ポーリング／自動更新／リアルタイム更新

E. API 依存関係

ケース 1：API が統合済み（コード内で実際の HTTP 呼び出しを行っている）

API 名	メソッド	パス	トリガー	主なパラメーター	備考
ユーザーを取得	GET	/api/user/list	読み込み、検索	page、size、keyword	ページネーション対応

ケース 2：API が未統合（モックデータ／ハードコードされたデータ）

ページでモックデータ、ハードコードされたフィクスチャ、setTimeout によるシミュレーション、または Promise.resolve() のスタブを使用している場合、API はまだ実装されていません。ページの機能とデータ構造から、必要な API 仕様をリバースエンジニアリングしてください。

必要な API ごとに、以下を記録します。

• メソッド、推奨パス、トリガー
• 入力パラメーター（名前、型、必須かどうか、説明）
• 出力フィールド（名前、型、説明）
• コアとなるビジネスロジックの説明

検出シグナル：

• データを返す setTimeout ／ Promise.resolve() → モック
• コンポーネントまたは *.mock.* ファイルで定義されたデータ → モック
• 実際のパスを使った HTTP 呼び出し（axios、fetch、サービスレイヤー） → 統合済み
• __mocks__ ディレクトリ → モック

F. ページ間の関係

• 流入元：どのページからここにリンクしていますか？どのようなパラメーターを渡しますか？
• 遷移先：ここからユーザーはどこへ移動できますか？どのようなパラメーターを渡しますか？
• データ連携：どのページがデータを共有したり、相互に更新をトリガーしたりしますか？

---

フェーズ 3 — ドキュメントの生成

出力構成

プロジェクトのルート（またはユーザー指定のディレクトリ）に prd/ を作成します。

prd/
├── README.md                     # System overview
├── pages/
│   ├── 01-user-mgmt-list.md      # One file per page
│   ├── 02-user-mgmt-detail.md
│   ├── 03-order-mgmt-list.md
│   └── ...
└── appendix/
    ├── enum-dictionary.md         # All enums, status codes, type mappings
    ├── page-relationships.md      # Navigation map between pages
    └── api-inventory.md           # Complete API reference

README.md テンプレート

# [System Name] — Product Requirements Document

## System Overview
[2-3 paragraphs: what the system does, business context, primary users]

## Module Overview

| Module | Pages | Core Functionality |
|--------|-------|--------------------|
| User Management | User list, User detail, Role mgmt | CRUD users, assign roles and permissions |

## Page Inventory

| # | Page Name | Route | Module | Doc Link |
|---|-----------|-------|--------|----------|
| 1 | User List | /user/list | User Mgmt | [→](./pages/01-user-mgmt-list.md) |

## Global Notes

### Permission Model
[Summarize auth/role system if present in code]

### Common Interaction Patterns
[Global rules: all deletes require confirmation, lists default to created_at desc, etc.]

ページごとのドキュメントテンプレート

# [Page Name]

> **Route:** `/xxx/xxx`
> **Module:** [Module name]
> **Generated:** [Date]

## Overview
[2-3 sentences: core function and use case]

## Layout
[Region breakdown — text description or ASCII diagram]

## Fields

### [Region: e.g. "Search Filters"]
| Field | Type | Required | Options / Enum | Default | Notes |
|-------|------|----------|---------------|---------|-------|

### [Region: e.g. "Data Table"]
| Column | Format | Sortable | Filterable | Notes |
|--------|--------|----------|-----------|-------|

### [Region: e.g. "Actions"]
| Button | Visibility Condition | Behavior |
|--------|---------------------|----------|

## Interactions

### Page Load
[What happens on mount]

### [Scenario: e.g. "Search"]
- **Trigger:** [User action]
- **Behavior:** [System response]
- **Special rules:** [If any]

### [Scenario: e.g. "Create"]
- **Trigger:** ...
- **Modal/drawer content:** [Fields and logic inside]
- **Validation:** ...
- **On success:** ...

## API Dependencies

| API | Method | Path | Trigger | Notes |
|-----|--------|------|---------|-------|
| ... | ... | ... | ... | ... |

## Page Relationships
- **From:** [Source pages + params]
- **To:** [Target pages + params]
- **Data coupling:** [Cross-page refresh triggers]

## Business Rules
[Anything that doesn't fit above]

---

重要な原則

1. まずビジネス用語を使う

「ローディング状態の管理に useState を呼び出す」とは書かないでください。「検索ボタンにスピナーを表示して、重複送信を防ぐ」と書いてください。

「マウント時に useEffect がデータを取得する」とは書かないでください。「ページを開くと、最初の結果ページが自動的に読み込まれる」と書いてください。

技術的な詳細を含めるのは、プロダクトの動作に直接影響する場合に限ります。例：API パス（エンジニアに必要）、バリデーションルール（UX に影響）、権限条件（表示／非表示に影響）。

2. 隠れたロジックを見落とさない

コードには、PM が存在に気づいていない可能性のあるロジックが含まれています。

• フィールド間の依存関係（タイプ A ではフィールド X を表示し、タイプ B ではフィールド Y を表示）
• 条件付きのボタン表示
• データのフォーマット（小数点以下 2 桁の通貨、日付形式、ステータスラベルのマッピング）
• デフォルトの並び順とページサイズ
• ユーザー入力に対するデバウンス／スロットルの効果
• ポーリング／自動更新の間隔

3. 列挙値を漏れなく列挙する

コードで列挙値（ステータスコード、タイプコード、ロールタイプ）が定義されている場合、すべての値とその意味を列挙してください。これらは多くの場合、定数ファイル、コンポーネントの valueEnum 設定、または API レスポンスのマッパーに分散しています。

4. 不確かな点を明記する — 推測しない

フィールドやロジックのビジネス上の意味をコードから判断できない場合（例：省略形の変数名、複雑すぎる条件分岐）は、[TBC] と記し、確認できた内容と不確かな理由を説明してください。ビジネス上の意味を決して捏造しないでください。

5. ページのファイルを自己完結させる

各ページの Markdown は単独で完結させてください。そのファイルだけを読めば、内容を完全に理解できるようにします。他のページや付録の項目を参照する場合は、相対リンクを使用してください。

---

ページタイプ別の方針

フロントエンドページ

ページタイプ	注目する項目
一覧／テーブル	検索条件、列、行の操作、ページネーション、一括操作
フォーム／作成・編集	すべてのフィールド、バリデーション、相互依存関係、送信後の動作
詳細／表示	表示情報、タブ／セクションの構成、利用可能な操作
モーダル／ドロワー	個別ファイルではなく、起動元のページの一部として説明します。ただし、内容は漏れなく記録してください
ダッシュボード	データカード、グラフ、指標の意味、フィルターの軸、更新頻度

バックエンドエンドポイント (NestJS / Django / Express)

エンドポイント種別	注目すべき領域
CRUD リソース	すべてのフィールド (DTO/シリアライザー由来)、バリデーションルール、権限、ページネーション、フィルタリング、ソート
認証エンドポイント	ログイン/登録フロー、トークン形式、リフレッシュロジック、パスワードリセット、OAuth プロバイダー
ファイルアップロード	許可される種類、サイズ制限、保存先、処理パイプライン
Webhook / イベント	トリガー条件、ペイロードの形状、リトライポリシー、冪等性
バックグラウンドジョブ	トリガー、スケジュール、入力/出力、障害処理、モニタリング
管理ビュー (Django)	登録済みモデル、list_display、search_fields、フィルター、インラインモデル、カスタムアクション

---

実行ペース配分

大規模プロジェクト (15 ページ超): モジュールごとに 3〜5 ページのバッチで作業します。まずシステム全体の概要とページ一覧を完成させます。各バッチを出力してユーザーのレビューを受けてから次に進みます。

小規模プロジェクト (15 ページ以下): すべての分析を 1 回で完了させます。

---

よくある落とし穴

落とし穴	修正方法
コンポーネント名をページ名として使う	UserManagementTable → 「ユーザー管理一覧」
モーダルとドロワーを省略する	重要なビジネスロジックが含まれています — 完全に文書化してください
i18n フィールド名の欠落	コンポーネントの JSX だけでなく、翻訳ファイルを確認してください
動的ルートパラメータの無視	/order/:id = ページの読み込みに注文 ID が必要です
権限管理の見落とし	どのロールがどのボタン/ページを表示できるかを文書化してください
すべての API が実在すると仮定する	エンドポイントを文書化する前にモックデータのパターンを確認してください
Django 管理画面のカスタマイズを省略する	admin.py には重要なビジネスルール (リストフィルター、カスタムアクション、インライン) が含まれていることがよくあります
NestJS のガード/パイプの欠落	@UseGuards、@UsePipes には動作に影響する認証およびバリデーションロジックが含まれています
データベース制約の無視	モデルフィールドの制約 (unique、max_length、choices) は PRD のバリデーションルールです
ミドルウェアの見落とし	認証ミドルウェア、レートリミッター、CORS 設定はシステム全体の動作を定義します

---

ツール

スクリプト

スクリプト	目的	使用方法
scripts/codebase_analyzer.py	コードベースをスキャン → ルート、API、モデル、enum、構造を抽出	python3 codebase_analyzer.py /path/to/project
scripts/prd_scaffolder.py	分析 JSON から PRD ディレクトリのスケルトンを生成	python3 prd_scaffolder.py analysis.json

推奨ワークフロー:

# 1. Analyze the project (JSON output — works for frontend, backend, or fullstack)
python3 scripts/codebase_analyzer.py /path/to/project -o analysis.json

# 2. Review the analysis (markdown summary)
python3 scripts/codebase_analyzer.py /path/to/project -f markdown

# 3. Scaffold the PRD directory with stubs
python3 scripts/prd_scaffolder.py analysis.json -o prd/ -n "My App"

# 4. Fill in TODO sections page-by-page using the SKILL.md workflow

どちらのスクリプトも stdlib のみ を使用しています — pip install は不要です。

リファレンス

ファイル	内容
references/prd-quality-checklist.md	完全性、正確性、可読性のための検証チェックリスト
references/framework-patterns.md	ルート、状態、API、フォーム、権限のためのフレームワーク固有のパターン

---

帰属

このスキルは @lihanglogan による code-to-prd に触発されたものです。同氏は PR #368 でオリジナルのコンセプトと方法論を提案しました。中核となる 3 フェーズのワークフロー (グローバルスキャン → ページごとの分析 → 構造化ドキュメントの生成) はその作業に由来します。このバージョンは英語でゼロから再構築され、追加のツール (分析スクリプト、スキャフォールダー、フレームワークリファレンス、品質チェックリスト) が加えられています。