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 系统，还需使用 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 阶段，对每个组件应用以下七种视角。这些视角相当于 prd-writing-guide 的七种视角在工程上的对应物。

┌──────────────────────────────────────────────────────────────────┐
│                    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 系统： 还需根据 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/Agent 组件

对于 AI 功能：ai-feature-spec.md 对于 Agent 系统：agent-system-spec.md，涵盖：

• Agent 编排（推理循环、工具调度、状态管理）
• 将系统提示词作为带版本控制的制品（含测试策略）
• 技能／工具注册和调度机制
• 记忆系统（工作记忆、会话记忆、长期存储设计）
• RAG 流水线（嵌入 → 分块 → 索引 → 检索 → 重排序）
• 评估基础设施和持续反馈循环
• 每次交互的成本模型

3.7 迁移与兼容性

如果要替换现有系统，请参见 spec-templates.md §Migration：

• 数据迁移策略（ETL 流水线、验证步骤、回滚）
• API 向后兼容性（版本控制方案、弃用时间表）
• 功能对等矩阵（旧版 → 新版映射、明确保留的差异）
• 切换计划（策略、回滚触发条件、共存期限）

---

第 4 阶段：测试规范

目标： 验证所有需求均已满足的测试。

可追溯性矩阵

需求	单元	集成	端到端	验收	性能	安全
FR-001	UT-001	IT-001	E2E-001	AT-001	-	-
NFR-001	-	-	-	-	PERF-001	-

测试类型

单元： 针对每个函数——成功路径、验证、边界情况、错误处理。 集成： 模块交互——API 契约、数据库操作、外部服务。 端到端： 完整用户旅程——包含多种情况的关键路径。 验收： 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]	Schema + 迁移	运行正常
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：组装与可复现性评审 ⭐

交叉引用检查

• 每个用户故事 → 功能需求
• 每项需求 → 技术规范章节
• 每项规范 → 测试用例
• 每项测试 → 可追溯至需求
• 记录所有外部依赖及其版本

可复现性验证

标准： 一个有能力的团队能否仅凭规范重建此系统？

• 环境： 列出所有依赖及其固定版本。提供构建和运行命令。
• 配置： 记录每个环境变量、功能标志和配置参数（类型、默认值、范围）。
• 数据： 提供 Schema 定义、种子数据规范，并引用迁移脚本。
• 基础设施： 提供部署架构、容器规范和资源要求。
• 集成： 每个外部依赖都提供连接详情、身份验证和故障处理方式。
• 业务逻辑： 不留隐含知识——把每条“显而易见”的规则都写下来。
• 安全： 完整说明身份验证流程、权限、加密和机密信息处理方式。
• 监控： 定义指标、告警和仪表板——从第一天起即可投入运维。
• 无 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 - Agent 系统工程规范 ⭐
• references/security-spec-guide.md - 安全架构规范 ⭐
• references/operations-spec.md - 运维与部署规范 ⭐
• references/worked-example.md - 端到端示例（HelpBot PRD→规范）⭐

---

重要提醒

1. 先验证 PRD——需求不完整，规范就不完整
2. 应用工程视角——通过全部 7 个视角审视每个组件
3. 确认决策——记录理由，而不只是选择
4. 追溯所有内容——需求 → 规范 → 测试 → 需求
5. 安全属于架构范畴——不能当作勾选项；要明确设计
6. 从第一天起考虑运维——部署、监控和调试规范并非可选项
7. 以可复现性为标准——如果无法依据规范重建系统，它就不完整