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
or
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

快速开始

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

  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
    进行验证

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):
LensKey QuestionSpec Output
ArchitectureWhere does it sit? What depends on it?Module diagram, dependency graph
DataWhat data does it own? Shape? Consistency?Entity definitions, schemas
ContractWhat's the interface? What can't change?API specs, event schemas
FailureWhat can go wrong? What then?Error catalog, retry policies
SecurityWho accesses? How protected?Auth rules, encryption spec
OperationsHow deployed and observed?Config, metrics, alerts
ReplicabilityAny 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.
  1. Review against prd-validation-checklist.md
  2. Agent systems: Also validate against agent-system-spec.md §PRD Validation
  3. Mark: ✅ Present | ⚠️ Unclear | ❌ Missing
  4. Do NOT proceed until all ❌ resolved
目标: 在开展技术工作前确保PRD的完整性。
  1. 根据prd-validation-checklist.md进行评审
  2. Agent系统: 同时根据agent-system-spec.md的§PRD验证部分进行检查
  3. 标记:✅ 已提供 | ⚠️ 不明确 | ❌ 缺失
  4. 所有❌问题解决前请勿继续

Defect Report Template

缺陷报告模板

markdown
undefined
markdown
undefined

PRD Validation Report

PRD验证报告

PRD: [title] | Status: [PASS / NEEDS REVISION]
PRD: [标题] | 状态: [通过 / 需要修订]

Critical Gaps (Must Fix)

关键缺口(必须修复)

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

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

需求矩阵

IDRequirementSourceTypePriority
FR-001[description]US-001CRUD/LogicP0
NFR-001API response <200ms P95PRD §7PerformanceP0

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

Phase 2: Technical Design (Interactive)

阶段2:技术设计(交互式)

Goal: Make architectural decisions with explicit user confirmation.
目标: 在用户确认下做出架构决策。

Decision Process

决策流程

For each significant decision:
  1. Present 2-3 options with pros, cons, effort, risk, and operational cost
  2. Recommend with rationale
  3. Wait for user confirmation
  4. Record in Decision Log
对于每个重要决策:
  1. 提供2-3个选项,包含优缺点、工作量、风险和运维成本
  2. 给出推荐方案及理由
  3. 等待用户确认
  4. 记录到决策日志

Decision Log

决策日志

IDDecisionOptionsChosenRationaleTrade-offsDate
D-001DatabasePG, MongoPostgreSQLACID, JSON supportHigher ops complexity[date]
ID决策内容可选方案最终选择理由权衡日期
D-001数据库选择PG, MongoPostgreSQL支持ACID和JSON运维复杂度更高[日期]

Tech Stack

技术栈

ComponentChoiceVersionRationaleAlternatives
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.mdfeature-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:
AreaMust Document
AuthenticationProtocol (OAuth2/JWT/session), token lifecycle, refresh flow, MFA
AuthorizationPermission model (RBAC/ABAC), role-permission matrix, enforcement points
Data SecurityClassification levels, encryption (at-rest, in-transit), PII handling
Input SecurityValidation strategy, injection prevention, file upload rules
AuditEvents to log, format, retention period, tamper protection
SecretsStorage 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:
AreaMust Document
EnvironmentsDev, staging, prod differences; how to provision
DeploymentCI/CD pipeline, container spec, rollout strategy
ConfigurationEvery env var / config param with type, default, description, allowed values
MonitoringKey metrics, alert thresholds, dashboard definitions
LoggingFormat, levels, correlation IDs, PII redaction
ScalingTriggers, resource limits, auto-scale rules
RecoveryBackup 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

可追溯性矩阵

RequirementUnitIntegrationE2EAcceptancePerformanceSecurity
FR-001UT-001IT-001E2E-001AT-001--
NFR-001----PERF-001-
需求单元测试集成测试E2E测试验收测试性能测试安全测试
FR-001UT-001IT-001E2E-001AT-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

里程碑

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

Risk Register

风险登记册

RiskProbImpactMitigationContingency
[risk]H/M/LH/M/L[prevent][if happens]

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

Phase 6: Assembly & Replicability Review ⭐

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

Cross-Reference Check

交叉引用检查

  • Every user story → functional requirement(s)
  • Every requirement → technical spec section(s)
  • Every spec → test case(s)
  • Every test → traces back to requirement
  • All external dependencies documented with versions
  • 每个用户故事都对应到功能需求
  • 每个需求都对应到技术规格章节
  • 每个规格都对应到测试用例
  • 每个测试用例都可追溯到需求
  • 所有外部依赖都已记录版本

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

重要提醒

  1. Validate PRD first — Incomplete requirements = incomplete specs
  2. Apply Engineering Lenses — Every component through all 7 lenses
  3. Confirm decisions — Document rationale, not just choices
  4. Trace everything — Requirement → Spec → Test → Requirement
  5. Security is architecture — Not a checkbox; design it explicitly
  6. Operations from day one — Deploy/monitor/debug specs are not optional
  7. Replicability is the bar — If it can't be rebuilt from the spec, it's incomplete
  1. 先验证PRD — 需求不完整=规格不完整
  2. 应用工程视角 — 每个组件都要经过7个视角的检查
  3. 确认决策 — 记录决策理由,而非仅记录选择
  4. 全链路追溯 — 需求→规格→测试→需求
  5. 安全是架构的一部分 — 不是勾选框,需明确设计
  6. 从第一天开始考虑运维 — 部署/监控/排障规格是必需的
  7. 可复制性是标准 — 如果仅通过规格无法重建系统,说明规格不完整 ",