prd-to-engineering-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PRD to Engineering Spec

PRD转工程规格说明书

Overview

概述

Transform product requirements into engineering specifications so complete that developers can implement the entire system step-by-step without ambiguity, and the resulting system can be replicated or migrated without information loss.

将产品需求转化为工程规格说明书，确保开发人员可以毫无歧义地逐步实现整个系统，且最终系统可以无信息损失地被复制或迁移。

Skill Workflow Context

技能工作流上下文

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ 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
└─────────────────┘

Input: Complete PRD (from

prd-writing-guide

ai-agent-prd

) Output: Engineering specifications at replicability-grade detail

Core Principle: Validate PRD first, design second. Incomplete requirements → incomplete specs.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ prd-writing-    │────►│ prd-to-         │     │ reverse-        │
│ guide           │     │ engineering-    │     │ engineering-    │
│ Write PRD       │     │ spec            │     │ spec            │
│                 │     │ [THIS SKILL]   │     │ Code→Spec       │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │
         ▼  针对AI Agent产品:
┌─────────────────┐
│ ai-agent-prd    │────► 本技能同样支持Agent PRD转换
└─────────────────┘

输入: 完整的PRD（来自

prd-writing-guide

或

ai-agent-prd

） 输出: 达到可复制级别的详细工程规格说明书

核心原则: 先验证PRD，再进行设计。需求不完整→规格不完整。

Quick Start

快速开始

Validate PRD against prd-validation-checklist.md
For Agent systems, also validate with agent-system-spec.md
Generate defect report; do NOT proceed until all ❌ resolved
Run
```
bash scripts/generate_spec_skeleton.sh
```
Apply the Engineering Lenses to every component
Fill specs using spec-templates.md
Validate with
```
bash scripts/validate_spec.sh
```

根据prd-validation-checklist.md验证PRD
对于Agent系统，还需根据agent-system-spec.md进行验证
生成缺陷报告；所有❌问题解决前请勿继续
运行
```
bash scripts/generate_spec_skeleton.sh
```
对每个组件应用工程视角
使用spec-templates.md填充规格内容
运行
```
bash scripts/validate_spec.sh
```
进行验证

The Engineering Lenses

工程视角

Apply these seven lenses to every component during Phases 2-3. They are the engineering equivalent of

prd-writing-guide

's Seven Lenses.

┌──────────────────────────────────────────────────────────────────┐
│                    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?     │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

For every major component (service, module, API, data store, integration):

Lens	Key Question	Spec Output
Architecture	Where does it sit? What depends on it?	Module diagram, dependency graph
Data	What data does it own? Shape? Consistency?	Entity definitions, schemas
Contract	What's the interface? What can't change?	API specs, event schemas
Failure	What can go wrong? What then?	Error catalog, retry policies
Security	Who accesses? How protected?	Auth rules, encryption spec
Operations	How deployed and observed?	Config, metrics, alerts
Replicability	Any implicit knowledge not captured?	Env setup, all dependencies

在第2-3阶段，对每个组件应用以下七个视角。它们相当于

prd-writing-guide

中的七大视角的工程版。

┌──────────────────────────────────────────────────────────────────┐
│                    工程视角                                      │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. 架构  定位如何？分层、模块、通信方式。                         │
│  2. 数据  如何建模、验证、存储、迁移？                           │
│  3. 契约  接口定义？版本控制？哪些内容不可变更？                 │
│  4. 故障  可能出现哪些故障？如何检测、恢复、避免级联故障？       │
│  5. 安全  认证、授权、加密、审计、密钥管理？                     │
│  6. 运维  部署、配置、监控、扩容、回滚？                         │
│  7. 可复制性  所有配置、依赖、假设是否都已文档化？               │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

对于每个核心组件（服务、模块、API、数据存储、集成）：

视角	核心问题	规格输出
架构	它的定位？依赖它的组件有哪些？	模块图、依赖关系图
数据	它管理哪些数据？数据结构？一致性要求？	实体定义、数据Schema
契约	接口是什么？哪些内容不能变更？	API规格、事件Schema
故障	可能出现哪些问题？如何处理？	错误目录、重试策略
安全	谁可以访问？如何保护？	认证规则、加密规格
运维	如何部署和监控？	配置说明、指标、告警规则
可复制性	是否有未记录的隐含信息？	环境搭建说明、所有依赖清单

Workflow

工作流

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

Phase 0: PRD验证 ──────► 缺陷报告 ──────► PRD完整
         ↓
Phase 1: 需求分解 ──► 用户故事、需求矩阵
         ↓
Phase 2: 技术设计（交互式） ──► 决策日志
         ↓
Phase 3: 详细规格 ──► 对每个组件应用工程视角
         ↓
Phase 4: 测试规格 ──► 单元测试、集成测试、E2E测试、验收测试
         ↓
Phase 5: 任务分解 ──► 任务、里程碑、风险
         ↓
Phase 6: 组装与可复制性评审

Phase 0: PRD Validation

阶段0：PRD验证

Goal: Ensure PRD completeness before technical work begins.

Review against prd-validation-checklist.md
Agent systems: Also validate against agent-system-spec.md §PRD Validation
Mark: ✅ Present | ⚠️ Unclear | ❌ Missing
Do NOT proceed until all ❌ resolved

目标: 在开展技术工作前确保PRD的完整性。

根据prd-validation-checklist.md进行评审
Agent系统: 同时根据agent-system-spec.md的§PRD验证部分进行检查
标记：✅ 已提供 | ⚠️ 不明确 | ❌ 缺失
所有❌问题解决前请勿继续

Defect Report Template

缺陷报告模板

markdown

undefined

markdown

undefined

PRD Validation Report

PRD验证报告

PRD: [title] | Status: [PASS / NEEDS REVISION]

PRD: [标题] | 状态: [通过 / 需要修订]

Critical Gaps (Must Fix)

关键缺口（必须修复）

#	Category	Issue	Impact	Resolution

序号	分类	问题	影响	解决方案

Warnings (Should Clarify)

警告（需要澄清）

Assumptions (Document explicitly with risk-if-wrong)

假设（需明确记录，同时标注假设错误的风险）

---

---

Phase 1: Requirements Decomposition

阶段1：需求分解

Goal: Break PRD into structured, implementable requirements.

目标: 将PRD拆解为结构化、可落地的需求。

User Story Format

用户故事格式

markdown

undefined

markdown

undefined

US-001: [Title]

US-001: [标题]

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

undefined

优先级: P0/P1/P2 作为[角色]，我希望[执行操作]，以便[获得收益]。 验收标准: (Given/When/Then格式) 业务规则: BR-001, BR-002 依赖: US-002

undefined

Requirements Matrix

需求矩阵

ID	Requirement	Source	Type	Priority
FR-001	[description]	US-001	CRUD/Logic	P0
NFR-001	API response <200ms P95	PRD §7	Performance	P0

ID	需求描述	来源	类型	优先级
FR-001	[描述]	US-001	CRUD/逻辑	P0
NFR-001	API响应时间P95 <200ms	PRD第7节	性能	P0

Phase 2: Technical Design (Interactive)

阶段2：技术设计（交互式）

Goal: Make architectural decisions with explicit user confirmation.

目标: 在用户确认下做出架构决策。

Decision Process

决策流程

For each significant decision:

Present 2-3 options with pros, cons, effort, risk, and operational cost
Recommend with rationale
Wait for user confirmation
Record in Decision Log

对于每个重要决策：

提供2-3个选项，包含优缺点、工作量、风险和运维成本
给出推荐方案及理由
等待用户确认
记录到决策日志

Decision Log

决策日志

ID	Decision	Options	Chosen	Rationale	Trade-offs	Date
D-001	Database	PG, Mongo	PostgreSQL	ACID, JSON support	Higher ops complexity	[date]

ID	决策内容	可选方案	最终选择	理由	权衡	日期
D-001	数据库选择	PG, Mongo	PostgreSQL	支持ACID和JSON	运维复杂度更高	[日期]

Tech Stack

技术栈

Component	Choice	Version	Rationale	Alternatives
Language
Framework
Database
Cache
Queue
Infra

组件	选择	版本	理由	备选方案
编程语言
框架
数据库
缓存
消息队列
基础设施

Phase 3: Detailed Specification

阶段3：详细规格

Goal: Specs detailed enough for implementation without questions. Apply Engineering Lenses to every component.

Templates: spec-templates.md, feature-spec-template.md

目标: 规格详细到无需额外询问即可实现。对每个组件应用工程视角。

模板参考：spec-templates.md、feature-spec-template.md

3.1 Data Model

3.1 数据模型

Per entity: purpose, all fields (type, nullable, default, constraints, description), indexes with rationale, relationships with cascade rules, validation rules, lifecycle (create/update/delete behavior).

针对每个实体：用途、所有字段（类型、是否可为空、默认值、约束、描述）、索引及理由、关联关系与级联规则、验证规则、生命周期（创建/更新/删除行为）。

3.2 API Specification

3.2 API规格

Per endpoint: method + path, auth/authz, request (params, body, validation rules), response (structure, all status codes with conditions), business logic steps, side effects, rate limits, idempotency.

针对每个接口：方法+路径、认证/授权、请求（参数、请求体、验证规则）、响应（结构、所有状态码及触发条件）、业务逻辑步骤、副作用、速率限制、幂等性。

3.3 Business Logic

3.3 业务逻辑

Per complex rule: interface (inputs/outputs/errors), algorithm in pseudocode, decision table for branching, concrete edge case examples, transaction boundaries, rollback behavior.

针对每个复杂规则：接口（输入/输出/错误）、伪代码算法、分支决策表、具体边缘用例、事务边界、回滚行为。

3.4 Security Architecture ⭐

3.4 安全架构 ⭐

See security-spec-guide.md. Specify:

Area	Must Document
Authentication	Protocol (OAuth2/JWT/session), token lifecycle, refresh flow, MFA
Authorization	Permission model (RBAC/ABAC), role-permission matrix, enforcement points
Data Security	Classification levels, encryption (at-rest, in-transit), PII handling
Input Security	Validation strategy, injection prevention, file upload rules
Audit	Events to log, format, retention period, tamper protection
Secrets	Storage method, rotation policy, access control

参考security-spec-guide.md。需明确：

领域	必须文档化的内容
认证	协议（OAuth2/JWT/会话）、令牌生命周期、刷新流程、MFA
授权	权限模型（RBAC/ABAC）、角色-权限矩阵、执行点
数据安全	数据分类级别、加密（静态/传输中）、PII处理规则
输入安全	验证策略、注入防护、文件上传规则
审计	需记录的事件、格式、保留周期、防篡改措施
密钥管理	存储方式、轮换策略、访问控制

3.5 Operations & Deployment ⭐

3.5 运维与部署 ⭐

See operations-spec.md. Specify:

Area	Must Document
Environments	Dev, staging, prod differences; how to provision
Deployment	CI/CD pipeline, container spec, rollout strategy
Configuration	Every env var / config param with type, default, description, allowed values
Monitoring	Key metrics, alert thresholds, dashboard definitions
Logging	Format, levels, correlation IDs, PII redaction
Scaling	Triggers, resource limits, auto-scale rules
Recovery	Backup schedule, RTO/RPO, failover procedure, data restore process

参考operations-spec.md。需明确：

领域	必须文档化的内容
环境	开发、 staging、生产环境的差异；如何部署
部署	CI/CD流水线、容器规格、发布策略
配置	所有环境变量/配置参数的类型、默认值、描述、允许值
监控	核心指标、告警阈值、仪表盘定义
日志	格式、级别、关联ID、PII脱敏规则
扩容	触发条件、资源限制、自动扩容规则
恢复	备份计划、RTO/RPO、故障转移流程、数据恢复步骤

3.6 AI/Agent Components

3.6 AI/Agent组件

For AI features: ai-feature-spec.md For Agent systems: agent-system-spec.md, covering:

Agent orchestration (reasoning loop, tool dispatch, state management)
System prompt as versioned artifact (with testing strategy)
Skills/Tools registration and dispatch mechanism
Memory system (working, session, long-term storage design)
RAG pipeline (embedding → chunking → indexing → retrieval → reranking)
Evaluation infrastructure and continuous feedback loops
Cost model per interaction

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

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

3.7 Migration & Compatibility

3.7 迁移与兼容性

If replacing existing system. See spec-templates.md §Migration:

Data migration strategy (ETL pipeline, validation steps, rollback)
API backward compatibility (versioning scheme, deprecation timeline)
Feature parity matrix (old → new mapping, intentional gaps)
Cutover plan (strategy, rollback trigger, coexistence period)

如果是替换现有系统，参考spec-templates.md的§Migration部分：

数据迁移策略（ETL流水线、验证步骤、回滚方案）
API向后兼容性（版本化方案、弃用时间线）
功能 parity矩阵（新旧系统映射、有意保留的差异）
切换计划（策略、回滚触发条件、共存周期）

Phase 4: Test Specification

阶段4：测试规格

Goal: Tests that verify all requirements are met.

目标: 确保所有需求都被测试覆盖。

Traceability Matrix

可追溯性矩阵

Requirement	Unit	Integration	E2E	Acceptance	Performance	Security
FR-001	UT-001	IT-001	E2E-001	AT-001	-	-
NFR-001	-	-	-	-	PERF-001	-

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

Test Types

测试类型

Unit: Per function—happy path, validation, edge cases, error handling. Integration: Module interactions—API contracts, DB operations, external services. E2E: Complete user journeys—critical paths with variations. Acceptance: Given/When/Then—maps to acceptance criteria. Performance: Load/stress under specified conditions—verify NFRs. Security: Auth bypass, injection, permission escalation—verify security spec.

Templates in spec-templates.md.

单元测试: 针对每个函数——正常流程、验证、边缘用例、错误处理。 集成测试: 模块间交互——API契约、数据库操作、外部服务集成。 E2E测试: 完整用户流程——关键路径及变体。 验收测试: Given/When/Then格式——对应验收标准。 性能测试: 指定条件下的负载/压力测试——验证非功能需求。 安全测试: 认证绕过、注入、权限提升——验证安全规格。

模板参考spec-templates.md。

Phase 5: Task Breakdown

阶段5：任务分解

Task Template

任务模板

markdown

undefined

markdown

undefined

TASK-001: [Title]

TASK-001: [标题]

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

undefined

实现需求: FR-001, US-001 | 预估工时: 4h 描述: [需要完成的工作] 完成标准: 验证方式 依赖: TASK-000 | 阻塞: TASK-002

undefined

Milestones

里程碑

Milestone	Tasks	Target	Deliverable	Verification
M1: Data	001-003	[date]	Schema + migrations	Runs clean
M2: API	004-008	[date]	Endpoints + tests	Integration tests pass
M3: Security	009-011	[date]	Auth + audit	Security review pass
M4: Deploy	012-014	[date]	CI/CD + monitoring	Health checks green

里程碑	包含任务	目标日期	交付物	验证方式
M1: 数据层	001-003	[日期]	Schema + 迁移脚本	可正常运行
M2: API层	004-008	[日期]	接口 + 测试	集成测试通过
M3: 安全层	009-011	[日期]	认证 + 审计	安全评审通过
M4: 部署	012-014	[日期]	CI/CD + 监控	健康检查正常

Risk Register

风险登记册

Risk	Prob	Impact	Mitigation	Contingency
[risk]	H/M/L	H/M/L	[prevent]	[if happens]

风险	概率	影响	缓解措施	应急预案
[风险描述]	高/中/低	高/中/低	[预防措施]	[风险发生后的处理]

Phase 6: Assembly & Replicability Review ⭐

阶段6：组装与可复制性评审 ⭐

Cross-Reference Check

交叉引用检查

Replicability Verification

可复制性验证

The bar: Could a competent team rebuild this system from the spec alone?

Environment: All dependencies listed with pinned versions. Build + run commands.
Configuration: Every env var, feature flag, config param documented (type, default, range).
Data: Schema definitions, seed data specs, migration scripts referenced.
Infrastructure: Deploy architecture, container specs, resource requirements.
Integrations: Every external dep has connection details, auth, failure handling.
Business Logic: No implicit knowledge—every "obvious" rule written down.
Security: Auth flow, permissions, encryption, secrets handling fully specified.
Monitoring: Metrics, alerts, dashboards defined—operable from day one.
No TODOs/TBDs: Every placeholder resolved.

Run:

bash scripts/validate_spec.sh <spec_root>

标准: 专业团队仅通过该规格就能重建整个系统吗？

环境: 所有依赖都已列出并锁定版本。包含构建+运行命令。
配置: 所有环境变量、功能开关、配置参数都已文档化（类型、默认值、范围）。
数据: Schema定义、种子数据规格、迁移脚本都已引用。
基础设施: 部署架构、容器规格、资源需求都已明确。
集成: 所有外部依赖的连接细节、认证、故障处理都已记录。
业务逻辑: 无隐含信息——所有"显而易见"的规则都已书面记录。
安全: 认证流程、权限、加密、密钥管理都已完整规格化。
监控: 指标、告警、仪表盘都已定义——从第一天起即可运维。
无TODO/TBD: 所有占位符都已解决。

运行：

bash scripts/validate_spec.sh <spec_root>

Output Structure

输出结构

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

engineering-spec/
├── 00_概述/
│   ├── SUMMARY.md, REQUIREMENTS_MATRIX.md, DECISION_LOG.md, TECH_STACK.md
├── 01_需求/
│   ├── USER_STORIES.md, FUNCTIONAL_REQS.md, NON_FUNCTIONAL_REQS.md
├── 02_技术设计/
│   ├── ARCHITECTURE.md, DATA_MODEL.md, API_SPEC.md
│   ├── BUSINESS_LOGIC.md, AI_COMPONENTS.md（如适用）
├── 03_安全/
│   ├── AUTH_DESIGN.md, DATA_SECURITY.md, AUDIT_SPEC.md
├── 04_运维/
│   ├── DEPLOYMENT.md, CONFIGURATION.md, MONITORING.md, RUNBOOK.md
├── 05_测试/
│   ├── TEST_PLAN.md, ACCEPTANCE_TESTS.md
├── 06_实施/
│   ├── TASK_BREAKDOWN.md, MILESTONES.md, RISKS.md, MIGRATION.md
└── SPEC_INDEX.md

Resources

资源

```
scripts/generate_spec_skeleton.sh
```
- Create output structure
```
scripts/validate_spec.sh
```
- Validate spec completeness
```
references/prd-validation-checklist.md
```
- PRD validation checklist
```
references/spec-templates.md
```
- Specification templates
```
references/feature-spec-template.md
```
- Feature spec template
```
references/ai-feature-spec.md
```
- AI feature specification
```
references/agent-system-spec.md
```
- Agent system engineering spec ⭐
```
references/security-spec-guide.md
```
- Security architecture spec ⭐
```
references/operations-spec.md
```
- Operations & deployment spec ⭐
```
references/worked-example.md
```
- End-to-end worked example (HelpBot PRD→Spec) ⭐

```
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→规格） ⭐

Critical Reminders

重要提醒

Validate PRD first — Incomplete requirements = incomplete specs
Apply Engineering Lenses — Every component through all 7 lenses
Confirm decisions — Document rationale, not just choices
Trace everything — Requirement → Spec → Test → Requirement
Security is architecture — Not a checkbox; design it explicitly
Operations from day one — Deploy/monitor/debug specs are not optional
Replicability is the bar — If it can't be rebuilt from the spec, it's incomplete

先验证PRD — 需求不完整=规格不完整
应用工程视角 — 每个组件都要经过7个视角的检查
确认决策 — 记录决策理由，而非仅记录选择
全链路追溯 — 需求→规格→测试→需求
安全是架构的一部分 — 不是勾选框，需明确设计
从第一天开始考虑运维 — 部署/监控/排障规格是必需的
可复制性是标准 — 如果仅通过规格无法重建系统，说明规格不完整 ",