prd-to-spec

prd-to-spec — PRD から技術仕様書へ

プロダクト要件定義書（PRD）を、エンジニアや AI エージェントが実装に利用できる詳細な技術仕様書（SPEC）に変換します。PRD では何を作るかを定め、SPEC ではどのように作るかを定めます。

---

使用する場面

• /prd が生成されており、実装までのギャップを埋める必要がある
• コーディングを始める前に、アーキテクチャの決定事項を文書化したい
• 複数の開発者やエージェントが機能を実装するため、共通の契約が必要である
• PRD に合意する前に、技術的な実現可能性を検証したい
• コードを書く前に、設計上の問題を早期に発見したい

---

作業内容

1. PRD の特定 — PRD ドキュメントを見つけるか、受け取ります
2. コンテキストの分析（任意） — コードベースがある場合はスキャンし、現在のアーキテクチャ、パターン、制約を把握します
3. 確認事項の質問 — 技術的な曖昧さを解消します（質問は最大 3～5 件）
4. SPEC の生成 — 構造化された技術仕様書を作成します
5. レビュー — ユーザーに提示し、フィードバックを受けて反復します
6. 保存 — 最終版の SPEC を合意した場所に書き込みます

---

ステップ 1：PRD の特定

次のいずれかの方法で入力 PRD を見つけます。

Provide the PRD to convert:

A. File path (e.g., tasks/prd-priority-system.md)
B. GitHub Issue URL
C. Paste PRD content directly
D. Auto-detect: scan tasks/ directory for recent PRDs

自動検出する場合は、利用可能な PRD の一覧を表示し、ユーザーに選択してもらいます。

Found PRDs in tasks/:
  1. tasks/prd-priority-system.md (2024-03-15)
  2. tasks/prd-user-auth.md (2024-03-10)

Which PRD should I convert? [1/2]

---

ステップ 2：コンテキストの分析（任意）

コードベースがまだない場合（グリーンフィールドプロジェクト）は、このステップを省略します。 その場合、SPEC では PRD の要件と確認事項に基づいて、アーキテクチャをゼロから提案します。

コードベースがある場合は、次の項目を把握するためにスキャンします。

• 既存のアーキテクチャ — 現在のシステムがどのように構成されているか
• 技術スタック — すでに使用されている言語、フレームワーク、ライブラリ
• パターン — 命名規則、ファイル構成、エラー処理の方針
• データベース — 現在のスキーマ、マイグレーションツール、ORM
• API スタイル — REST／GraphQL／gRPC、認証方式、レスポンス形式
• テスト — テストフレームワーク、カバレッジのパターン、テストユーティリティ

これにより、互換性のない解決策を提案するのではなく、既存のシステムに沿った SPEC を作成できます。

---

ステップ 3：確認事項

PRD で技術的な決定が曖昧な場合に限り、質問します。次の点に重点を置きます。

• アーキテクチャの選択 — この機能はどこに配置しますか？ 新しいサービスを作成しますか、それとも既存のものを拡張しますか？
• データストレージ — 新しいテーブルが必要ですか？ 既存のテーブルを拡張しますか？ キャッシュ戦略はどうしますか？
• API 設計 — 新しいエンドポイントを作成しますか？ 既存のものを拡張しますか？ 互換性を損なう変更がありますか？
• 依存関係 — 新しいライブラリが必要ですか？ バージョンの制約はありますか？
• パフォーマンス — 想定される負荷はどの程度ですか？ レイテンシ要件はありますか？ バッチサイズの上限はありますか？

形式：

Technical questions before I generate the SPEC:

1. Where should the priority logic live?
   A. Extend existing TaskService
   B. New PriorityService
   C. Inline in controller
   D. Let me decide based on the codebase

2. Database migration approach?
   A. Add column to existing tasks table
   B. New priority table with FK
   C. JSON field on tasks
   D. Let me decide based on current schema

3. API versioning concern?
   A. Add to existing v1 endpoints
   B. New v2 endpoints
   C. No versioning needed

ユーザーが「自分で決める」選択肢を選んだ場合は、コードベースの分析に基づいて最適な選択を行い、その根拠を SPEC に記載します。

---

ステップ 4：SPEC ドキュメントの構成

# SPEC: [Feature Name]

> Technical specification derived from: [PRD filename/link]
> Generated: [date] | Target branch: [branch] | Commit: [short-hash]

## 1. Summary

### 1.1 What This SPEC Covers
[One paragraph: what feature this specifies and the scope of implementation]

### 1.2 PRD Reference
- Source: [path or URL to PRD]
- User Stories covered: [US-001, US-002, ...]
- Functional Requirements covered: [FR-1, FR-2, ...]

### 1.3 Design Decisions Summary
| Decision | Choice | Rationale |
|----------|--------|-----------|
| ... | ... | ... |

---

## 2. Architecture

### 2.1 System Context
[Where this feature fits in the overall system — diagram or description]

### 2.2 Component Design
[New components/modules introduced, their responsibilities, and boundaries]

### 2.3 Module Interactions
[How new components interact with existing ones — sequence or data flow]

### 2.4 File Structure
[New files to create and existing files to modify]

src/ ├── services/ │ └── priority.service.ts [NEW] ├── controllers/ │ └── task.controller.ts [MODIFY: add priority endpoints] ├── models/ │ └── priority.model.ts [NEW] └── migrations/ └── 20240315_add_priority.ts [NEW]

---

## 3. Data Model

### 3.1 Schema Changes
[New tables, columns, indexes — with SQL or ORM notation]

### 3.2 Entity Definitions
[TypeScript interfaces / Go structs / Python dataclasses for new entities]

### 3.3 Relationships
[How new entities relate to existing ones — FK, embedded, reference]

### 3.4 Migration Plan
[Migration steps, backward compatibility, rollback strategy]

---

## 4. API Design

### 4.1 Endpoints

| Method | Path | Description | Auth | Request | Response |
|--------|------|-------------|------|---------|----------|
| ... | ... | ... | ... | ... | ... |

### 4.2 Request/Response Schemas
[Detailed shapes with field types, validation rules, and examples]

### 4.3 Error Responses
[Error codes, messages, and HTTP status codes for each failure mode]

### 4.4 Breaking Changes
[Any backward-incompatible changes and migration path for consumers]

---

## 5. Business Logic

### 5.1 Core Algorithms
[Step-by-step logic for key operations — pseudocode or structured description]

### 5.2 Validation Rules
[Input validation, business rule validation, with specific constraints]

### 5.3 State Machine
[If applicable: states, transitions, guards, and side effects]

### 5.4 Edge Cases
[Known edge cases and how they should be handled]

---

## 6. Error Handling

### 6.1 Error Taxonomy
| Error Code | HTTP Status | Condition | User Message |
|------------|-------------|-----------|--------------|
| ... | ... | ... | ... |

### 6.2 Retry Strategy
[Which operations are retryable, backoff policy, max attempts]

### 6.3 Failure Modes
[What happens when dependencies fail — graceful degradation plan]

---

## 7. Security

### 7.1 Authentication & Authorization
[Who can access what, permission model, role checks]

### 7.2 Input Validation
[Sanitization rules, injection prevention, size limits]

### 7.3 Data Protection
[Sensitive fields, encryption at rest/transit, audit logging]

---

## 8. Performance

### 8.1 Expected Load
[Estimated QPS, data volume, growth projection]

### 8.2 Optimization Strategy
[Caching, pagination, lazy loading, batch processing]

### 8.3 Database Considerations
[Index strategy, query patterns, N+1 prevention]

---

## 9. Testing Strategy

### 9.1 Unit Tests
[What to test, test boundaries, mock strategy]

### 9.2 Integration Tests
[API tests, database tests, service interaction tests]

### 9.3 Edge Case Tests
[Specific scenarios to cover based on Section 5.4]

### 9.4 Acceptance Criteria Mapping
| US/FR | Test | Type | Description |
|-------|------|------|-------------|
| US-001 | ... | unit | ... |
| FR-2 | ... | integration | ... |

---

## 10. Implementation Plan

### 10.1 Phases
[Order of implementation — what to build first, dependencies between steps]

### 10.2 Issue Mapping
[Map SPEC sections to PRD Issues for implementation tracking]

| Issue | SPEC Sections | Priority | Depends On |
|-------|--------------|----------|------------|
| #1 | 3.1, 3.4 | high | — |
| #2 | 4.1, 4.2, 5.1 | high | #1 |
| ... | ... | ... | ... |

### 10.3 Incremental Delivery
[How to ship incrementally — feature flags, dark launches, gradual rollout]

---

## 11. Open Questions & Risks

### 11.1 Unresolved Questions
- [Questions that need product/engineering input before implementation]

### 11.2 Technical Risks
| Risk | Impact | Mitigation |
|------|--------|-----------|
| ... | ... | ... |

### 11.3 Assumptions
- [Technical assumptions made during SPEC creation — validate before implementing]

---

ステップ 5：レビューと反復

SPEC を生成した後、提示して次のように尋ねます。

SPEC generated from PRD. Please review:

- Are the architecture choices appropriate?
- Are there missing edge cases or error scenarios?
- Is the API design consistent with existing patterns?
- Should any section have more/less detail?

Reply OK to save, or provide feedback for iteration.

---

ステップ 6：保存

保存先をユーザーに尋ねます。

Where should I save the SPEC?

A. tasks/spec-[feature-name].md (alongside PRD, recommended)
B. docs/spec-[feature-name].md
C. Custom path: [specify]

---

マッピング戦略：PRD → SPEC

PRD の各要素を SPEC の各セクションに変換する方法：

PRD のセクション	SPEC のセクション	変換内容
ユーザーストーリー	5. ビジネスロジック、9.4 受け入れ基準との対応	ストーリー → アルゴリズム＋テストケース
機能要件	4. API 設計、5. ビジネスロジック	FR → エンドポイント＋ロジック
受け入れ基準	9. テスト戦略	基準 → 具体的なテストシナリオ
対象外の項目	11.1 未解決の質問	明示的に除外する内容を明確化
技術的な考慮事項	2. アーキテクチャ、8. パフォーマンス	制約 → 設計上の決定
成功指標	8.1 想定負荷、10.3 デリバリー	指標 → モニタリング＋段階的なリリース計画

---

品質基準

優れた SPEC は、以下のチェック項目を満たす必要があります。

• すべての PRD ユーザーストーリーに、対応する SPEC のセクションがある
• すべての機能要件が、API エンドポイントまたはビジネスロジックのルールに対応している
• すべての受け入れ基準が、少なくとも 1 つのテストケースに対応している
• アーキテクチャの選択が、根拠とともに説明されている
• API スキーマが、クライアントコードを生成できるほど具体的である
• エラー処理が、特定されているすべての障害モードを網羅している
• 実装の順序が、依存関係を考慮している
• 「TBD」や「TODO」の項目がない — 解決するか、未解決の質問に移す

---

エッジケースとフォールバック

シナリオ	対応
PRD が曖昧または不完全	可能な範囲で選択肢を判断して SPEC を作成し、前提条件をセクション 11.3 に記載する
PRD が既存のコードと矛盾している	矛盾を明確に示し、セクション 11.1 で解決策を提案する
機能が 1 つの SPEC には大きすぎる	複数の SPEC に分割し（サービス境界ごとに 1 つ）、相互にリンクする
既存のコードベースがない（グリーンフィールド）	ステップ 2 を省略し、PRD と確認質問に基づいてアーキテクチャをゼロから提案する
PRD にユーザーストーリーがなく、箇条書きだけがある	構成を推定し、箇条書きを SPEC の各セクションに対応付け、概要にその旨を記載する
コードベースを読まずに SPEC を作成したい	ステップ 2 を省略し、既存コードに関する前提が検証されていないことを記載する
複数の PRD を 1 つの SPEC にまとめる必要がある	PRD の入力内容を統合し、要件の重複をなくして、それぞれの出典を記載する

---

避けるべきアンチパターン

• PRD を言い換えて繰り返さないでください。 SPEC では要件を別の言葉でコピーするのではなく、技術的な詳細を加えます。
• 単純な操作を過度に仕様化しないでください。 特別なロジックを伴わない CRUD に、詳細なアルゴリズムのセクションは必要ありません。
• 背景を考慮せずにテクノロジーを選ばないでください。 新しいツールを提案する前に、プロジェクトで現在何が使われているかを必ず確認してください。
• 既存のシステムと切り離して設計しないでください。 SPEC は、既存のパターン、規約、スタイルに沿ってシステムに適合させる必要があります。
• 決定事項を暗黙のままにしないでください。 選択した内容（例：「既存のテーブルに列を追加する」）を明記し、その理由も説明してください。
• 実装コードを書かないでください。 SPEC が記述するのは契約と振る舞いであり、コードではありません。複雑なアルゴリズムでは、擬似コードを使用できます。

---

他のスキルとの関係

/prd  →  /prd-to-spec  →  /goal  →  /review-it  →  /ship-it
 │              │              │
 │  Requirements │  Technical   │  Implementation
 │  (what)       │  (how)       │  (code)

• /prd は PRD を作成します（このスキルへの入力）
• /prd-to-spec は SPEC を作成します（このスキル）
• /goal は SPEC を技術的な参照情報として Issues を実装します
• /code-to-spec は既存のコードから SPEC をリバースエンジニアリングします（相補的な役割 — フォワードとリバース）