prd-to-engineering-spec

PRD からエンジニアリング仕様書へ

概要

プロダクト要件を、開発者が 曖昧さなく段階的にシステム全体を実装できる ほど完全で、完成したシステムを 情報を失わずに複製または移行できる エンジニアリング仕様書に変換します。

スキルのワークフローコンテキスト

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ prd-writing-    │────►│ prd-to-         │     │ reverse-        │
│ guide           │     │ engineering-    │     │ engineering-    │
│ Write PRD       │     │ spec            │     │ spec            │
│                 │     │ [THIS SKILL]   │     │ Code→Spec       │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │
         ▼  For AI Agent products:
┌─────────────────┐
│ ai-agent-prd    │────► This skill handles Agent PRD conversion too
└─────────────────┘

入力： 完全な PRD（prd-writing-guide または ai-agent-prd から） 出力： 複製可能な詳細度のエンジニアリング仕様書

基本原則： まず PRD を検証し、その後に設計します。不完全な要件からは、不完全な仕様しか生まれません。

クイックスタート

1. prd-validation-checklist.md に照らして PRD を検証します
2. エージェントシステムの場合は、agent-system-spec.md でも検証します
3. 欠陥レポートを作成します。❌ がすべて解消されるまで先に進まないでください
4. bash scripts/generate_spec_skeleton.sh を実行します
5. すべてのコンポーネントに エンジニアリングの視点 を適用します
6. spec-templates.md を使って仕様を記入します
7. bash scripts/validate_spec.sh で検証します

---

エンジニアリングの視点

フェーズ 2～3 では、すべてのコンポーネントに次の 7 つの視点を適用します。これは prd-writing-guide の「7 つの視点」に相当するエンジニアリング版です。

┌──────────────────────────────────────────────────────────────────┐
│                    The Engineering Lenses                         │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. ARCHITECTURE  How does it fit? Layers, modules, comms.       │
│  2. DATA          How modeled, validated, stored, migrated?      │
│  3. CONTRACT      Interfaces? Versioning? What breaks?           │
│  4. FAILURE       How does it fail? Detect, recover, cascade?    │
│  5. SECURITY      Auth, authz, encryption, audit, secrets?       │
│  6. OPERATIONS    Deploy, configure, monitor, scale, rollback?   │
│  7. REPLICABILITY All configs, deps, assumptions documented?     │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

すべての主要コンポーネント（サービス、モジュール、API、データストア、連携）について確認します。

視点	主な質問	仕様の出力
アーキテクチャ	どこに位置しますか？何が依存していますか？	モジュール図、依存関係グラフ
データ	どのデータを所有しますか？データの形状は？整合性は？	エンティティ定義、スキーマ
契約	インターフェースは何ですか？変更できないものは何ですか？	API 仕様、イベントスキーマ
障害	何が問題になり得ますか？その場合どうしますか？	エラーカタログ、再試行ポリシー
セキュリティ	誰がアクセスしますか？どのように保護しますか？	認証ルール、暗号化仕様
運用	どのようにデプロイし、状態を把握しますか？	設定、メトリクス、アラート
複製可能性	記録されていない暗黙知はありますか？	環境のセットアップ、すべての依存関係

---

ワークフロー

Phase 0: PRD Validation ──────► Defect Report ──────► PRD Complete
         ↓
Phase 1: Decomposition ──► User Stories, Requirements Matrix
         ↓
Phase 2: Technical Design (Interactive) ──► Decision Log
         ↓
Phase 3: Detailed Specs ──► Engineering Lenses on every component
         ↓
Phase 4: Test Specs ──► Unit, Integration, E2E, Acceptance
         ↓
Phase 5: Task Breakdown ──► Tasks, Milestones, Risks
         ↓
Phase 6: Assembly & Replicability Review

---

フェーズ 0：PRD の検証

目標： 技術作業を開始する前に、PRD が完全であることを確認します。

1. prd-validation-checklist.md に照らして確認します
2. エージェントシステム： agent-system-spec.md の §PRD Validation も確認します
3. 次のようにマークします：✅ 記載あり | ⚠️ 不明確 | ❌ 欠落
4. ❌ がすべて解消されるまで先に進まないでください

欠陥レポートのテンプレート

# PRD Validation Report
**PRD:** [title] | **Status:** [PASS / NEEDS REVISION]

## Critical Gaps (Must Fix)
| # | Category | Issue | Impact | Resolution |
|---|----------|-------|--------|------------|

## Warnings (Should Clarify)
## Assumptions (Document explicitly with risk-if-wrong)

---

フェーズ 1：要件の分解

目標： PRD を構造化された、実装可能な要件に分解します。

ユーザーストーリーの形式

## US-001: [Title]
**Priority:** P0/P1/P2
As a [role], I want [action], so that [benefit].
**Acceptance Criteria:** (Given/When/Then)
**Business Rules:** BR-001, BR-002
**Dependencies:** US-002

要件マトリクス

ID	要件	出典	種類	優先度
FR-001	[説明]	US-001	CRUD/ロジック	P0
NFR-001	API 応答 <200ms P95	PRD §7	パフォーマンス	P0

---

フェーズ 2：技術設計（対話形式）

目標： ユーザーの明示的な確認を得ながら、アーキテクチャ上の判断を行います。

判断プロセス

重要な判断ごとに、次の手順を実施します。

1. 利点、欠点、工数、リスク、運用コスト を含む選択肢を 2～3 個提示します
2. 根拠とともに推奨案を示します
3. ユーザーの確認を待ちます
4. 決定ログに記録します

決定ログ

ID	決定事項	選択肢	採用案	根拠	トレードオフ	日付
D-001	データベース	PG、Mongo	PostgreSQL	ACID、JSON のサポート	運用の複雑さが増す	[日付]

技術スタック

コンポーネント	選択	バージョン	根拠	代替案
言語
フレームワーク
データベース
キャッシュ
キュー
インフラ

---

フェーズ 3：詳細仕様

目標： 質問せずに実装できるほど詳細な仕様を作成します。すべてのコンポーネントに エンジニアリングの視点 を適用します。

テンプレート：spec-templates.md、feature-spec-template.md

3.1 データモデル

エンティティごとに、目的、すべてのフィールド（型、NULL 許容、デフォルト値、制約、説明）、インデックスとその理由、カスケードルールを含む関連、検証ルール、ライフサイクル（作成／更新／削除時の動作）を記載します。

3.2 API 仕様

エンドポイントごとに、メソッドとパス、認証／認可、リクエスト（パラメーター、本文、検証ルール）、レスポンス（構造、条件を含むすべてのステータスコード）、ビジネスロジックの手順、副作用、レート制限、冪等性を記載します。

3.3 ビジネスロジック

複雑なルールごとに、インターフェース（入力／出力／エラー）、擬似コードによるアルゴリズム、分岐の決定表、具体的なエッジケースの例、トランザクション境界、ロールバック時の動作を記載します。

3.4 セキュリティアーキテクチャ ⭐

security-spec-guide.mdを参照してください。以下を記載します。

領域	記載必須事項
認証	プロトコル（OAuth2/JWT/セッション）、トークンのライフサイクル、更新フロー、多要素認証
認可	権限モデル（RBAC/ABAC）、ロールと権限のマトリックス、適用箇所
データセキュリティ	分類レベル、暗号化（保存時、転送時）、PII の取り扱い
入力セキュリティ	検証戦略、インジェクション防止、ファイルアップロードのルール
監査	ログに記録するイベント、形式、保存期間、改ざん防止
シークレット	保存方法、ローテーションポリシー、アクセス制御

3.5 運用とデプロイ ⭐

operations-spec.mdを参照してください。以下を記載します。

領域	記載必須事項
環境	開発、ステージング、本番環境の違いとプロビジョニング方法
デプロイ	CI/CD パイプライン、コンテナ仕様、ロールアウト戦略
設定	すべての環境変数／設定パラメーターについて、型、デフォルト値、説明、許容値
モニタリング	主要メトリクス、アラートしきい値、ダッシュボードの定義
ロギング	形式、レベル、相関 ID、PII のマスキング
スケーリング	トリガー、リソース制限、自動スケーリングのルール
復旧	バックアップスケジュール、RTO/RPO、フェイルオーバー手順、データ復元プロセス

3.6 AI／エージェントのコンポーネント

AI 機能については、ai-feature-spec.mdを参照してください。
エージェントシステムについては、以下を扱うagent-system-spec.mdを参照してください。

• エージェントのオーケストレーション（推論ループ、ツールのディスパッチ、状態管理）
• バージョン管理された成果物としてのシステムプロンプト（テスト戦略を含む）
• スキル／ツールの登録とディスパッチの仕組み
• メモリシステム（作業用、セッション、長期保存の設計）
• RAG パイプライン（埋め込み → チャンク化 → インデックス作成 → 検索 → 再ランキング）
• 評価インフラストラクチャと継続的なフィードバックループ
• インタラクションごとのコストモデル

3.7 移行と互換性

既存システムを置き換える場合。spec-templates.mdの§Migrationを参照してください。

• データ移行戦略（ETL パイプライン、検証手順、ロールバック）
• API の後方互換性（バージョニング方式、非推奨化のスケジュール）
• 機能同等性マトリックス（旧 → 新の対応関係、意図的な差分）
• 切り替え計画（戦略、ロールバックのトリガー、共存期間）

---

フェーズ 4：テスト仕様

目標： すべての要件が満たされていることを検証するテストを作成します。

トレーサビリティマトリックス

要件	単体	統合	E2E	受け入れ	パフォーマンス	セキュリティ
FR-001	UT-001	IT-001	E2E-001	AT-001	-	-
NFR-001	-	-	-	-	PERF-001	-

テストの種類

単体： 関数ごとに、正常系、検証、エッジケース、エラー処理をテストします。
統合： モジュール間の連携として、API コントラクト、DB 操作、外部サービスをテストします。
E2E： さまざまなパターンを含む重要な経路について、ユーザーの一連の操作をテストします。
受け入れ： Given/When/Then 形式で受け入れ基準に対応付けます。
パフォーマンス： 指定条件下で負荷／ストレステストを行い、NFR を検証します。
セキュリティ： 認証の回避、インジェクション、権限昇格をテストし、セキュリティ仕様を検証します。

テンプレートはspec-templates.mdにあります。

---

フェーズ 5：タスクの分解

タスクテンプレート

## TASK-001: [Title]
**Implements:** FR-001, US-001 | **Estimate:** 4h
**Description:** [what to do]
**Done Criteria:** [how to verify]
**Dependencies:** TASK-000 | **Blocks:** TASK-002

マイルストーン

マイルストーン	タスク	目標	成果物	検証
M1: データ	001-003	[date]	スキーマ + マイグレーション	正常に実行
M2: API	004-008	[date]	エンドポイント + テスト	統合テストに合格
M3: セキュリティ	009-011	[date]	認証 + 監査	セキュリティレビューに合格
M4: デプロイ	012-014	[date]	CI/CD + モニタリング	ヘルスチェックが正常

リスク一覧

リスク	確率	影響	軽減策	緊急時対応
[risk]	H/M/L	H/M/L	[prevent]	[if happens]

---

フェーズ 6：組み立てと再現性レビュー ⭐

相互参照の確認

• すべてのユーザーストーリー → 機能要件
• すべての要件 → 技術仕様のセクション
• すべての仕様 → テストケース
• すべてのテストが要件にさかのぼれる
• すべての外部依存関係がバージョン付きで文書化されている

再現性の検証

基準： 有能なチームが仕様だけをもとにこのシステムを再構築できますか？

• 環境： すべての依存関係が固定バージョン付きで記載されている。ビルドおよび実行コマンド。
• 設定： すべての環境変数、機能フラグ、設定パラメーターが文書化されている（型、デフォルト値、範囲）。
• データ： スキーマ定義、シードデータの仕様、マイグレーションスクリプトが参照されている。
• インフラストラクチャ： デプロイアーキテクチャ、コンテナ仕様、リソース要件。
• インテグレーション： すべての外部依存関係に接続の詳細、認証、障害時の処理が含まれている。
• ビジネスロジック： 暗黙の知識をなくし、「自明」なルールもすべて明記されている。
• セキュリティ： 認証フロー、権限、暗号化、シークレットの取り扱いがすべて明確に仕様化されている。
• モニタリング： メトリクス、アラート、ダッシュボードが定義され、初日から運用できる。
• TODO/TBD なし： すべてのプレースホルダーが解決されている。

実行：bash scripts/validate_spec.sh <spec_root>

---

出力構成

engineering-spec/
├── 00_Overview/
│   ├── SUMMARY.md, REQUIREMENTS_MATRIX.md, DECISION_LOG.md, TECH_STACK.md
├── 01_Requirements/
│   ├── USER_STORIES.md, FUNCTIONAL_REQS.md, NON_FUNCTIONAL_REQS.md
├── 02_Technical_Design/
│   ├── ARCHITECTURE.md, DATA_MODEL.md, API_SPEC.md
│   ├── BUSINESS_LOGIC.md, AI_COMPONENTS.md (if applicable)
├── 03_Security/
│   ├── AUTH_DESIGN.md, DATA_SECURITY.md, AUDIT_SPEC.md
├── 04_Operations/
│   ├── DEPLOYMENT.md, CONFIGURATION.md, MONITORING.md, RUNBOOK.md
├── 05_Testing/
│   ├── TEST_PLAN.md, ACCEPTANCE_TESTS.md
├── 06_Implementation/
│   ├── TASK_BREAKDOWN.md, MILESTONES.md, RISKS.md, MIGRATION.md
└── SPEC_INDEX.md

---

リソース

• scripts/generate_spec_skeleton.sh - 出力構成を作成
• scripts/validate_spec.sh - 仕様の完全性を検証
• references/prd-validation-checklist.md - PRD 検証チェックリスト
• references/spec-templates.md - 仕様テンプレート
• references/feature-spec-template.md - 機能仕様テンプレート
• references/ai-feature-spec.md - AI 機能仕様
• references/agent-system-spec.md - エージェントシステムのエンジニアリング仕様 ⭐
• references/security-spec-guide.md - セキュリティアーキテクチャ仕様 ⭐
• references/operations-spec.md - 運用およびデプロイ仕様 ⭐
• references/worked-example.md - エンドツーエンドの作成例（HelpBot PRD→仕様）⭐

---

重要な注意事項

1. まず PRD を検証する — 要件が不完全なら、仕様も不完全になります
2. エンジニアリングの観点を適用する — すべてのコンポーネントを 7 つの観点すべてから確認する
3. 決定を確認する — 選択肢だけでなく、その根拠も文書化する
4. すべてを追跡する — 要件 → 仕様 → テスト → 要件
5. セキュリティはアーキテクチャの一部 — チェック項目ではありません。明示的に設計してください
6. 初日から運用を考慮する — デプロイ、モニタリング、デバッグの仕様は必須です
7. 再現性が基準 — 仕様から再構築できないなら、不完全です