Back to Details

doc-prd

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-prd

PRD文档创建指南

Purpose

目的

Create Product Requirements Documents (PRD) - Layer 2 artifact in the SDD workflow that defines product features, user needs, measurable success criteria, and KPIs.
Layer: 2
Upstream: BRD (Layer 1)
Downstream Artifacts: EARS (Layer 3), BDD (Layer 4), ADR (Layer 5)
创建产品需求文档（PRD）——SDD工作流中的第2层工件，用于定义产品功能、用户需求、可衡量的成功标准以及KPI。
层级：2
上游工件：BRD（第1层）
下游工件：EARS（第3层）、BDD（第4层）、ADR（第5层）

Prerequisites

前置条件

Upstream Artifact Verification (CRITICAL)

上游工件验证（关键）

Before creating this document, you MUST:
  1. List existing upstream artifacts:
    bash
    ls docs/BRD/ docs/PRD/ 2>/dev/null
  2. Reference only existing documents in traceability tags
  3. Use 
    null
     only when upstream artifact type genuinely doesn't exist
  4. NEVER use placeholders like 
    BRD-XXX
    or 
    TBD
  5. Do NOT create missing upstream artifacts - skip functionality instead
Before creating a PRD, read:
  1. Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. Upstream BRD: Read the BRD that drives this PRD Note on Sectioned BRDs: If BRD is split into multiple section files (0-18), read ALL files as ONE logical document. See 
    PRD_CREATION_RULES.md
    Section 22.
  3. Template: 
    ai_dev_flow/02_PRD/PRD-MVP-TEMPLATE.md
  4. Creation Rules: 
    ai_dev_flow/02_PRD/PRD_CREATION_RULES.md
  5. Validation Rules: 
    ai_dev_flow/02_PRD/PRD_VALIDATION_RULES.md
创建本文档前，必须完成以下操作：
  1. 列出已有的上游工件：
    bash
    ls docs/BRD/ docs/PRD/ 2>/dev/null
  2. 在可追溯性标签中仅引用已存在的文档
  3. 只有当确实不存在对应类型的上游工件时，才使用
    null
  4. 绝对不能使用
    BRD-XXX
    或
    TBD
    这类占位符
  5. 不要创建缺失的上游工件——而是跳过相关功能
创建PRD前，请阅读以下内容：
  1. 共享标准：
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. 上游BRD：阅读驱动本PRD的BRD文档 分段BRD说明：如果BRD被拆分为多个分段文件（0-18），请将所有文件视为一个逻辑文档阅读。详情请见
    PRD_CREATION_RULES.md
    第22节。
  3. 模板：
    ai_dev_flow/02_PRD/PRD-MVP-TEMPLATE.md
  4. 创建规则：
    ai_dev_flow/02_PRD/PRD_CREATION_RULES.md
  5. 验证规则：
    ai_dev_flow/02_PRD/PRD_VALIDATION_RULES.md

When to Use This Skill

何时使用本技能

Use 
doc-prd
when:
  • Have completed BRD (Layer 1)
  • Need to define product features and user requirements
  • Translating business needs to product specifications
  • Establishing KPIs and success metrics
  • You are at Layer 2 of the SDD workflow
在以下场景使用
doc-prd
：
  • 已完成BRD（第1层）
  • 需要定义产品功能和用户需求
  • 将业务需求转化为产品规格
  • 建立KPI和成功指标
  • 处于SDD工作流的第2层

PRD-Specific Guidance

PRD专属指导

1. Required Sections (21 Total)

1. 必备章节（共21个）

PRD documents follow the MVP template structure (17 sections). See 
ai_dev_flow/02_PRD/PRD-MVP-TEMPLATE.md
for complete structure.
Note: MVP template is the framework default. It uses ≥85% score thresholds (vs ≥90% for full template). Full template (21 sections) is available for enterprise/regulatory projects.
Section 1. Document Control (MANDATORY - First section):
  • Status, Version, Date Created, Last Updated
  • Author, Reviewer, Approver
  • BRD Reference (
    @brd: BRD.NN.EE.SS
    )
  • SYS-Ready Score: >=90% required (format: 
    XX% (Target: >=90%)
    )
  • EARS-Ready Score: >=90% required (format: 
    XX% (Target: >=90%)
    )
  • Template Variant (Standard/Agent-Based/Automation-Focused)
  • Document Revision History table
All 21 Sections (in order):
  1. Document Control: Metadata, versioning, dual scoring (SYS-Ready + EARS-Ready >=90%)
  2. Executive Summary: Business value and timeline overview (2-3 sentences)
  3. Problem Statement: Current state, business impact, opportunity assessment
  4. Target Audience & User Personas: Primary users, secondary users, business stakeholders
  5. Success Metrics (KPIs): Primary KPIs, secondary KPIs, success criteria by phase
  6. Goals & Objectives: Primary business goals, secondary objectives, stretch goals
  7. Scope & Requirements: In scope features, out of scope items, dependencies, assumptions
  8. User Stories & User Roles: Role definitions, story summaries (PRD-level only, no EARS/BDD detail)
  9. Functional Requirements: User journey mapping, capability requirements
  10. Customer-Facing Content & Messaging (MANDATORY): Product positioning, messaging, user-facing content
  11. Acceptance Criteria: Business acceptance, technical acceptance, quality assurance
  12. Constraints & Assumptions: Business/technical/external constraints, key assumptions
  13. Risk Assessment: High-risk items, risk mitigation plan
  14. Success Definition: Go-live criteria, post-launch validation, measurement timeline
  15. Stakeholders & Communication: Core team, stakeholders, communication plan
  16. Implementation Approach: Development phases, testing strategy
  17. Budget & Resources: Development/operational budget, resource requirements
  18. Traceability: Upstream sources, downstream artifacts, traceability tags, validation evidence
  19. References: Internal documentation, external standards, domain references, technology references
  20. EARS Enhancement Appendix: EARS pattern templates and requirement syntax guidance
  21. Quality Assurance & Testing Strategy: QA standards, testing strategy
Critical Notes:
  • All 21 sections are MANDATORY with explicit numbering (
    ## N. Title
    format)
  • Section 10 (Customer-Facing Content) is blocking - must contain substantive content
  • Section 8 (User Stories) must include layer separation scope note
  • Section 21 (QA & Testing Strategy) moved from BRD as technical QA belongs at product level
PRD文档遵循MVP模板结构（17个章节）。完整结构请见
ai_dev_flow/02_PRD/PRD-MVP-TEMPLATE.md
。
注意：MVP模板是框架默认模板，采用≥85%的分数阈值（完整版模板为≥90%）。针对企业/合规项目，提供包含21个章节的完整模板。
第1章 文档控制（必填——首章）：
  • 状态、版本、创建日期、最后更新日期
  • 作者、审核人、批准人
  • BRD引用（格式：
    @brd: BRD.NN.EE.SS
    ）
  • SYS就绪分数：要求≥90%（格式：
    XX% (目标: ≥90%)
    ）
  • EARS就绪分数：要求≥90%（格式：
    XX% (目标: ≥90%)
    ）
  • 模板变体（标准型/基于Agent型/自动化聚焦型）
  • 文档修订历史表格
所有21个章节（按顺序）：
  1. 文档控制：元数据、版本管理、双重评分（SYS就绪+EARS就绪≥90%）
  2. 执行摘要：业务价值和时间线概述（2-3句话）
  3. 问题陈述：当前状态、业务影响、机会评估
  4. 目标受众与用户画像：主要用户、次要用户、业务利益相关者
  5. 成功指标（KPI）：核心KPI、次要KPI、分阶段成功标准
  6. 目标与目的：核心业务目标、次要目标、延伸目标
  7. 范围与需求：范围内功能、范围外事项、依赖关系、假设条件
  8. 用户故事与用户角色：角色定义、故事摘要（仅PRD层面，不含EARS/BDD细节）
  9. 功能需求：用户旅程映射、能力需求
  10. 客户面向内容与话术（必填）：产品定位、核心话术、用户面向内容
  11. 验收标准：业务验收、技术验收、质量保证
  12. 约束与假设：业务/技术/外部约束、关键假设
  13. 风险评估：高风险项、风险缓解计划
  14. 成功定义：上线标准、上线后验证、测量时间线
  15. 利益相关者与沟通：核心团队、利益相关者、沟通计划
  16. 实施方法：开发阶段、测试策略
  17. 预算与资源：开发/运营预算、资源需求
  18. 可追溯性：上游来源、下游工件、可追溯性标签、验证证据
  19. 参考资料：内部文档、外部标准、领域参考、技术参考
  20. EARS增强附录：EARS模式模板和需求语法指导
  21. 质量保证与测试策略：QA标准、测试策略
关键注意事项：
  • 所有21个章节必须按顺序明确编号（格式：
    ## N. 标题
    ）
  • 第10章（客户面向内容）为阻塞项——必须包含实质性内容
  • 第8章（用户故事）必须包含层级分离范围说明
  • 第21章（QA与测试策略）从BRD中迁移至此，因为技术QA属于产品层面

2. Dual Scoring Requirements

2. 双重评分要求

PRD documents require two quality scores in Document Control:
ScorePurposeThreshold
SYS-Ready ScoreReadiness for SYS creation>=90%
EARS-Ready ScoreReadiness for EARS creation>=90%
Format: 
XX% (Target: >=90%)
SYS-Ready Scoring Criteria (100%):
  • Product Requirements Completeness (40%): All 21 sections, measurable KPIs, acceptance criteria, stakeholder analysis
  • Technical Readiness (30%): System boundaries, quality attributes quantified, Architecture Decision Requirements
  • Business Alignment (20%): ROI validated, market analysis, success metrics, risk mitigation
  • Traceability (10%): Upstream BRD references, downstream links
EARS-Ready Scoring Criteria (100%):
  • Business Requirements Clarity (40%): SMART objectives, functional requirements, acceptance criteria
  • Requirements Maturity (35%): System boundaries, stakeholder requirements, problem statement
  • EARS Translation Readiness (20%): User journeys, quality attributes quantified
  • Strategic Alignment (5%): Domain-specific business logic references
PRD文档在文档控制章节中需要包含两个质量分数：
分数用途阈值
SYS就绪分数评估创建SYS的就绪度≥90%
EARS就绪分数评估创建EARS的就绪度≥90%
格式：
XX% (目标: ≥90%)
SYS就绪评分标准（100%）：
  • 产品需求完整性（40%）：所有21个章节、可衡量的KPI、验收标准、利益相关者分析
  • 技术就绪度（30%）：系统边界、量化的质量属性、架构决策需求
  • 业务对齐度（20%）：ROI验证、市场分析、成功指标、风险缓解
  • 可追溯性（10%）：上游BRD引用、下游链接
EARS就绪评分标准（100%）：
  • 业务需求清晰度（40%）：SMART目标、功能需求、验收标准
  • 需求成熟度（35%）：系统边界、利益相关者需求、问题陈述
  • EARS转换就绪度（20%）：用户旅程、量化的质量属性
  • 战略对齐度（5%）：领域特定业务逻辑引用

3. Template Variant Selection

3. 模板变体选择

VariantSectionsUse Case
Standard1-21 (21)Business features, core platform (DEFAULT)
Agent-Based1-15 (15)ML/AI agents, intelligent systems
Automation-Focused1-12 (12)n8n workflows, event processing
Selection Criteria:
  1. ML/AI agent? -> Agent-Based
  2. n8n workflow/automation? -> Automation-Focused
  3. Otherwise -> Standard (default)
变体章节数量使用场景
标准型1-21（共21个）业务功能、核心平台（默认）
基于Agent型1-15（共15个）ML/AI Agent、智能系统
自动化聚焦型1-12（共12个）n8n工作流、事件处理
选择标准：
  1. 是ML/AI Agent相关？→ 选择基于Agent型
  2. 是n8n工作流/自动化相关？→ 选择自动化聚焦型
  3. 其他情况→ 选择标准型（默认）

4. User Stories Scope (Section 8)

4. 用户故事范围（第8章）

Layer Separation Principle:
  • PRD (Layer 2): User role definitions, story summaries, product-level acceptance criteria
  • EARS (Layer 3): Detailed behavioral scenarios (WHEN-THE-SHALL-WITHIN format)
  • BDD (Layer 4): Executable test scenarios (Given-When-Then format)
MANDATORY Scope Note (include in Section 8):
This section provides role definitions and story summaries. Detailed behavioral requirements are captured in EARS; executable test specifications are in BDD feature files.
User Story Format: "As a [role], I want [capability] so that [benefit]"
PRD-Level Content (INCLUDE):
  • User role definitions (personas)
  • Story titles and summaries (2-3 sentences max)
  • Product-level acceptance criteria
  • Business value justification
NOT PRD-Level (EXCLUDE):
  • EARS-level specifications -> Layer 3
  • BDD-level test scenarios -> Layer 4
  • Technical implementation details -> Layer 6/7
  • System architecture decisions -> ADR (Layer 5)
层级分离原则：
  • PRD（第2层）：用户角色定义、故事摘要、产品层面的验收标准
  • EARS（第3层）：详细的行为场景（WHEN-THE-SHALL-WITHIN格式）
  • BDD（第4层）：可执行的测试场景（Given-When-Then格式）
必填范围说明（需包含在第8章中）：
本章提供角色定义和故事摘要。详细的行为需求记录在EARS中；可执行的测试规格记录在BDD功能文件中。
用户故事格式："作为[角色]，我希望[能力]，以便[收益]"
PRD层面需包含的内容：
  • 用户角色定义（用户画像）
  • 故事标题和摘要（最多2-3句话）
  • 产品层面的验收标准
  • 业务价值论证
PRD层面不应包含的内容：
  • EARS层面的规格→ 第3层
  • BDD层面的测试场景→ 第4层
  • 技术实现细节→ 第6/7层
  • 系统架构决策→ ADR（第5层）

5. Customer-Facing Content (Section 10) - MANDATORY

5. 客户面向内容（第10章）——必填

Status: BLOCKING - error if missing or placeholder-only
Required Content Categories (minimum 3):
  1. Product positioning statements
  2. Key messaging themes
  3. Feature descriptions for marketing
  4. User-facing documentation requirements
  5. Help text and tooltips
  6. Error messages (user-visible)
  7. Success confirmations
  8. Onboarding content
  9. Release notes template
状态：阻塞项——如果缺失或仅含占位符则视为错误
必填内容类别（至少3个）：
  1. 产品定位声明
  2. 核心话术主题
  3. 面向营销的功能描述
  4. 用户面向文档需求
  5. 帮助文本和提示框
  6. 用户可见的错误信息
  7. 成功确认信息
  8. 入门引导内容
  9. 版本说明模板

6. Architecture Decision Requirements (Section 18)

6. 架构决策需求（第18章）

Purpose: Elaborate BRD Section 7.2 topics with technical content (options, criteria).
Layer Separation:
BRD Section 7.2          ->    PRD Section 18         ->    ADR
(WHAT & WHY)                   (HOW to evaluate)           (Final decision)
-------------------------------------------------------------------
Business drivers               Technical options           Selected option
Business constraints           Evaluation criteria         Trade-off analysis
PRD Section 18 Format:
markdown
undefined
目的：用技术内容（选项、标准）细化BRD第7.2节的主题。
层级分离：
BRD第7.2节          →    PRD第18章         →    ADR
(内容与原因)                   (评估方法)           (最终决策)
-------------------------------------------------------------------
业务驱动因素               技术选项           选定选项
业务约束条件               评估标准           权衡分析
PRD第18章格式：
markdown
undefined
BRD.NN.32.SS: [Topic Name]
BRD.NN.32.SS: [主题名称]
Upstream: BRD-NN section 7.2.X
Technical Options:
  1. [Option A]: [Description]
  2. [Option B]: [Description]
Evaluation Criteria:
  • [Criterion 1]: [Measurable target]
  • [Criterion 2]: [Measurable target]
Product Constraints:
  • [Constraint 1]
Decision Timeline: [Milestone reference]
ADR Requirements: [What ADR must decide]

**CRITICAL**: Do NOT reference specific ADR numbers (ADR-01, ADR-033, etc.) - ADRs don't exist yet!
上游来源：BRD-NN第7.2.X节
技术选项:
  1. [选项A]: [描述]
  2. [选项B]: [描述]
评估标准:
  • [标准1]: [可衡量的目标]
  • [标准2]: [可衡量的目标]
产品约束:
  • [约束1]
决策时间线: [里程碑参考]
ADR需求: [ADR必须做出的决策]

**关键**：不要引用具体的ADR编号（如ADR-01、ADR-033等）——ADR此时尚未存在！

7. EARS Enhancement Appendix (Section 20)

7. EARS增强附录（第20章）

Purpose: Provides structured requirements for EARS transformation.
Required Subsections:
20.1 Timing Profile Matrix:
Operationp50p95p99UnitTrigger EventNotes
[operation][value][value][value]ms[event][constraints]
20.2 Boundary Value Matrix:
ThresholdOperatorValueAt BoundaryAboveBelow
[name]>= or > or <= or <[value][behavior][behavior][behavior]
20.3 State Transition Diagram: Mermaid stateDiagram-v2 with error states
20.4 Fallback Path Documentation:
DependencyFailure ModeDetectionFallback BehaviorTimeoutRecovery
20.5 EARS-Ready Checklist: All timing, boundary, state, fallback items verified
目的：为EARS转换提供结构化需求。
必填子章节：
20.1 时间分布矩阵:
操作p50p95p99单位触发事件说明
[操作][数值][数值][数值]ms[事件][约束条件]
20.2 边界值矩阵:
阈值运算符数值边界处行为超过边界行为低于边界行为
[名称]>= 或 > 或 <= 或 <[数值][行为][行为][行为]
20.3 状态转换图：包含错误状态的Mermaid stateDiagram-v2图
20.4 回退路径文档:
依赖项故障模式检测方式回退行为超时时间恢复方式
20.5 EARS就绪检查表：所有时间、边界、状态、回退项均已验证

Tag Format Convention

标签格式约定

NotationFormatArtifactsPurpose
DashTYPE-NNADR, SPEC, CTRTechnical artifacts - file references
DotTYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKSHierarchical - element references
Key Distinction:
  • @adr: ADR-033
    -> Points to document 
    ADR-033_slug.md
  • @brd: BRD.17.01.01
    -> Points to element 01.01 inside 
    BRD-017.md
符号格式适用工件用途
短横线TYPE-NNADR, SPEC, CTR技术工件——文件引用
点TYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS层级化——元素引用
关键区别:
  • @adr: ADR-033
    -> 指向文档
    ADR-033_slug.md
  • @brd: BRD.17.01.01
    -> 指向
    BRD-017.md
    内的元素01.01

Unified Element ID Format (MANDATORY)

统一元素ID格式（必填）

Pattern: 
PRD.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
(4 segments, dot-separated)
Element TypeCodeExample
Functional Requirement01PRD.02.01.01
Quality Attribute02PRD.02.02.01
Constraint03PRD.02.03.01
Assumption04PRD.02.04.01
Dependency05PRD.02.05.01
Acceptance Criteria06PRD.02.06.01
Risk07PRD.02.07.01
Metric08PRD.02.08.01
User Story09PRD.02.09.01
Use Case11PRD.02.11.01
Feature Item22PRD.02.22.01
Stakeholder Need24PRD.02.24.01
REMOVED Patterns (Do NOT use):
  • AC-XXX
    -> Use 
    PRD.NN.06.SS
  • FR-XXX
    -> Use 
    PRD.NN.01.SS
  • F-XXX
    -> Use 
    PRD.NN.09.SS
  • US-XXX
    -> Use 
    PRD.NN.09.SS
格式：
PRD.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
（4个分段，点分隔）
元素类型代码示例
功能需求01PRD.02.01.01
质量属性02PRD.02.02.01
约束条件03PRD.02.03.01
假设条件04PRD.02.04.01
依赖关系05PRD.02.05.01
验收标准06PRD.02.06.01
风险07PRD.02.07.01
指标08PRD.02.08.01
用户故事09PRD.02.09.01
用例11PRD.02.11.01
功能项22PRD.02.22.01
利益相关者需求24PRD.02.24.01
已废弃格式（禁止使用）:
  • AC-XXX
    -> 改用
    PRD.NN.06.SS
  • FR-XXX
    -> 改用
    PRD.NN.01.SS
  • F-XXX
    -> 改用
    PRD.NN.09.SS
  • US-XXX
    -> 改用
    PRD.NN.09.SS

Cumulative Tagging Requirements

累积标签要求

Layer 2 (PRD): Must include tags from Layer 1 (BRD)
Tag Count: 1 tag (@brd)
Format:
markdown
undefined
第2层（PRD）：必须包含第1层（BRD）的标签
标签数量：1个标签（@brd）
格式:
markdown
undefined

18. Traceability

18. 可追溯性

Traceability Tags

可追溯性标签

Required Tags (Cumulative Tagging Hierarchy - Layer 2):
markdown
@brd: BRD.01.01.03, BRD.01.01.10
  • BRD.01.01.03 - Business requirements driving this product
  • BRD.01.01.10 - Success criteria from business case
Upstream Sources:
  • BRD-01 - Parent business requirements
Downstream Artifacts:
  • EARS-NN (to be created) - Formal requirements
  • BDD-NN (to be created) - Test scenarios
undefined
必填标签（累积标签层级——第2层）:
markdown
@brd: BRD.01.01.03, BRD.01.01.10
  • BRD.01.01.03 - 驱动本产品的业务需求
  • BRD.01.01.10 - 业务案例中的成功标准
上游来源:
  • BRD-01 - 父业务需求
下游工件:
  • EARS-NN（待创建）- 正式需求
  • BDD-NN（待创建）- 测试场景
undefined

Creation Process

创建流程

Step 1: Read Parent BRD

步骤1：阅读父BRD

Read and understand the BRD that drives this PRD.
Sectioned BRD Handling: If BRD is split into multiple section files (folder structure 
docs/BRD/BRD-NN_{slug}/
):
  1. Read ALL section files (BRD-NN.0 through BRD-NN.18)
  2. Treat as ONE logical document
  3. Extract information holistically (no section-to-section mapping)
阅读并理解驱动本PRD的BRD文档。
分段BRD处理: 如果BRD被拆分为多个分段文件（文件夹结构
docs/BRD/BRD-NN_{slug}/
）:
  1. 阅读所有分段文件（BRD-NN.0至BRD-NN.18）
  2. 将其视为一个逻辑文档
  3. 整体提取信息（无需逐段映射）

Step 2: Reserve ID Number

步骤2：预留ID编号

Check 
docs/PRD/
for next available ID number (e.g., PRD-01, PRD-02).
ID Numbering Convention: Start with 2 digits and expand only as needed.
  • ✅ Correct: PRD-01, PRD-99, PRD-102
  • ❌ Incorrect: PRD-001, PRD-009 (extra leading zero not required)
ID Matching: PRD ID does NOT need to match BRD ID (PRD-09 may implement BRD-16).
查看
docs/PRD/
获取下一个可用的ID编号（例如：PRD-01、PRD-02）。
ID编号约定：从2位数字开始，仅在需要时扩展。
  • ✅ 正确格式：PRD-01, PRD-99, PRD-102
  • ❌ 错误格式：PRD-001, PRD-009（无需多余前导零）
ID匹配：PRD ID无需与BRD ID匹配（PRD-09可实现BRD-16的需求）

Step 3: Create PRD Folder and Files

步骤3：创建PRD文件夹和文件

Folder structure (DEFAULT - nested folder per document):
  1. Create folder: 
    docs/PRD/PRD-NN_{slug}/
  2. Create index file: 
    docs/PRD/PRD-NN_{slug}/PRD-NN.0_index.md
  3. Create section files: 
    docs/PRD/PRD-NN_{slug}/PRD-NN.S_{section_type}.md
Example:
docs/PRD/PRD-01_user_authentication/
  PRD-01.0_index.md
  PRD-01.1_executive_summary.md
  PRD-01.2_problem_statement.md
  ...
OPTIONAL (for small documents <25KB): 
docs/PRD/PRD-NN_{slug}.md
(monolithic)
文件夹结构（默认——每个文档对应嵌套文件夹）:
  1. 创建文件夹：
    docs/PRD/PRD-NN_{slug}/
  2. 创建索引文件：
    docs/PRD/PRD-NN_{slug}/PRD-NN.0_index.md
  3. 创建分段文件：
    docs/PRD/PRD-NN_{slug}/PRD-NN.S_{section_type}.md
示例:
docs/PRD/PRD-01_user_authentication/
  PRD-01.0_index.md
  PRD-01.1_executive_summary.md
  PRD-01.2_problem_statement.md
  ...
可选格式（适用于小于25KB的小型文档）：
docs/PRD/PRD-NN_{slug}.md
（单文件）

Step 4: Complete Document Control

步骤4：完成文档控制

Fill all required metadata fields:
  • Status, Version, Dates, Author/Reviewer/Approver
  • BRD Reference with 
    @brd
    tag
  • SYS-Ready Score and EARS-Ready Score (both >=90%)
  • Template Variant
  • Document Revision History table
填写所有必填元数据字段:
  • 状态、版本、日期、作者/审核人/批准人
  • 带
    @brd
    标签的BRD引用
  • SYS就绪分数和EARS就绪分数（均≥90%）
  • 模板变体
  • 文档修订历史表格

Step 5: Complete Core Sections (2-17)

步骤5：完成核心章节（第2-17章）

Section 2-3: Problem context and business impact Section 4-6: Users, KPIs, goals Section 7-9: Scope, user stories, functional requirements Section 10: Customer-facing content (MANDATORY) Section 11-14: Acceptance criteria, constraints, risks, success Section 15-17: Stakeholders, implementation, budget
第2-3章：问题背景和业务影响 第4-6章：用户、KPI、目标 第7-9章：范围、用户故事、功能需求 第10章：客户面向内容（必填） 第11-14章：验收标准、约束条件、风险、成功定义 第15-17章：利益相关者、实施方法、预算

Step 6: Complete Traceability (Section 18)

步骤6：完成可追溯性（第18章）

  • Add upstream BRD references
  • Document downstream artifact placeholders
  • Include Architecture Decision Requirements elaboration
  • Add bidirectional reference table if cross-PRD dependencies exist
  • 添加上游BRD引用
  • 记录下游工件占位符
  • 包含架构决策需求的细化内容
  • 如果存在跨PRD依赖，添加双向引用表格

Step 7: Complete References (Section 19)

步骤7：完成参考资料（第19章）

Internal documentation, external standards, domain and technology references.
内部文档、外部标准、领域和技术参考资料。

Step 8: Complete EARS Enhancement Appendix (Section 20)

步骤8：完成EARS增强附录（第20章）

  • Timing Profile Matrix (p50/p95/p99)
  • Boundary Value Matrix (explicit operators)
  • State Transition Diagram (with error states)
  • Fallback Path Documentation
  • EARS-Ready Checklist
  • 时间分布矩阵（p50/p95/p99）
  • 边界值矩阵（明确运算符）
  • 状态转换图（包含错误状态）
  • 回退路径文档
  • EARS就绪检查表

Step 9: Complete QA Strategy (Section 21)

步骤9：完成QA策略（第21章）

Quality standards and testing strategy (moved from BRD).
质量标准和测试策略（从BRD迁移至此）。

Step 10: Create/Update Traceability Matrix

步骤10：创建/更新可追溯性矩阵

MANDATORY: Create or update 
docs/PRD/PRD-00_TRACEABILITY_MATRIX.md
必填：创建或更新
docs/PRD/PRD-00_TRACEABILITY_MATRIX.md

Step 11: Update Upstream BRD Traceability (MANDATORY)

步骤11：更新上游BRD的可追溯性（必填）

CRITICAL - Often Missed: When creating a PRD, you MUST update the parent BRD's traceability section.
Process:
  1. Open the upstream BRD (e.g., 
    docs/BRD/BRD-01_platform.md
    )
  2. Locate the 
    ## Traceability
    section
  3. Add this PRD to 
    Downstream Artifacts
    :
    markdown
    - Downstream Artifacts: [PRD-01](../PRD/PRD-01_user_authentication/PRD-01.0_index.md#PRD-01)
  4. Commit BRD update with PRD creation (single commit)
Why This Matters:
  • Enables bidirectional navigation between BRD and PRD
  • Impact analysis: BRD changes show affected PRDs
  • Audit compliance: Regulators require bidirectional traceability
Reference: See 
.claude/skills/doc-flow/SHARED_CONTENT.md
Section 4.3 "Bidirectional Traceability Update Workflow" for complete guidance.
关键——常被遗漏：创建PRD时，必须更新父BRD的可追溯性章节。
流程:
  1. 打开上游BRD（例如：
    docs/BRD/BRD-01_platform.md
    ）
  2. 定位
    ## 可追溯性
    章节
  3. 将本PRD添加到
    下游工件
    中:
    markdown
    - 下游工件: [PRD-01](../PRD/PRD-01_user_authentication/PRD-01.0_index.md#PRD-01)
  4. 将BRD更新与PRD创建提交到同一个版本提交中
重要性:
  • 实现BRD与PRD之间的双向导航
  • 影响分析：BRD变更可显示受影响的PRD
  • 合规审计：监管机构要求双向可追溯性
参考：完整指导请见
.claude/skills/doc-flow/SHARED_CONTENT.md
第4.3节“双向可追溯性更新工作流”

Step 12: Validate PRD

步骤12：验证PRD

bash
undefined
bash
undefined

PRD validation

PRD验证

python ai_dev_flow/scripts/validate_prd.py docs/PRD/PRD-NN_{slug}/
python ai_dev_flow/scripts/validate_prd.py docs/PRD/PRD-NN_{slug}/

Link integrity

链接完整性检查

python ai_dev_flow/scripts/validate_links.py --path docs/PRD/
python ai_dev_flow/scripts/validate_links.py --path docs/PRD/

Cumulative tagging validation

累积标签验证

python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact PRD-NN --expected-layers brd --strict
undefined
python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact PRD-NN --expected-layers brd --strict
undefined

Validation Checklist

验证检查表

Structure (21 Sections):
  • All 21 numbered sections present (1-21)
  • Document Control (Section 1) at top with all required fields
  • Customer-Facing Content (Section 10) has substantive content
  • User Stories (Section 8) includes layer separation scope note
  • EARS Enhancement Appendix (Section 20) completed
  • Quality Assurance & Testing Strategy (Section 21) completed
Document Control Required Fields:
  • Status, Version, Date Created, Last Updated
  • Author, Reviewer, Approver
  • BRD Reference with @brd tag
  • SYS-Ready Score >=90%
  • EARS-Ready Score >=90%
  • Template Variant specified
  • Document Revision History table initialized
Content Quality:
  • Parent BRD identified and referenced
  • Problem-Goals framework completed
  • User personas and user stories defined (PRD-level only)
  • Product features specified with priority levels
  • KPIs quantified (measurable metrics with targets)
  • Quality attributes quantified (performance, reliability)
  • Risk assessment with mitigation strategies
  • Architecture Decision Requirements listed (NO ADR numbers)
  • EARS Enhancement Appendix complete (timing, boundary, state, fallback)
Traceability:
  • Cumulative tags: @brd included
  • Traceability matrix created/updated
  • Upstream BRD traceability section updated with this PRD
  • No ADR forward references
  • No broken links
Size Limits:
  • File size <50,000 tokens (standard) or <100,000 tokens (maximum)
结构（21个章节）:
  • 所有21个编号章节均存在（1-21）
  • 文档控制（第1章）位于顶部，包含所有必填字段
  • 客户面向内容（第10章）包含实质性内容
  • 用户故事（第8章）包含层级分离范围说明
  • EARS增强附录（第20章）已完成
  • 质量保证与测试策略（第21章）已完成
文档控制必填字段:
  • 状态、版本、创建日期、最后更新日期
  • 作者、审核人、批准人
  • 带@brd标签的BRD引用
  • SYS就绪分数≥90%
  • EARS就绪分数≥90%
  • 指定模板变体
  • 初始化文档修订历史表格
内容质量:
  • 已识别并引用父BRD
  • 完成问题-目标框架
  • 定义了用户画像和用户故事（仅PRD层面）
  • 指定了带优先级的产品功能
  • 量化了KPI（带目标的可衡量指标）
  • 量化了质量属性（性能、可靠性）
  • 包含风险评估和缓解策略
  • 列出了架构决策需求（无ADR编号）
  • 完成EARS增强附录（时间、边界、状态、回退）
可追溯性:
  • 累积标签：包含@brd
  • 创建/更新了可追溯性矩阵
  • 更新了上游BRD的可追溯性章节，添加了本PRD
  • 无ADR前置引用
  • 无损坏链接
大小限制:
  • 文件大小<50,000 tokens（标准）或<100,000 tokens（最大值）

Post-Creation Validation (MANDATORY - NO CONFIRMATION)

创建后验证（必填——无需确认）

CRITICAL: Execute this validation loop IMMEDIATELY after document creation.
LOOP:
  1. Run: python ai_dev_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed
关键：文档创建后立即执行此验证循环。
循环:
  1. 执行: python ai_dev_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. 如果错误已修复: 回到循环（重新验证）
  3. 如果警告已修复: 回到循环（重新验证）
  4. 如果存在无法修复的问题: 记录以便人工审核，继续后续操作
  5. 如果验证通过: 标记为已验证，继续后续操作

Validation Command

验证命令

bash
undefined
bash
undefined

Per-document validation (Phase 1)

单文档验证（第1阶段）

python ai_dev_flow/scripts/validate_cross_document.py --document docs/PRD/PRD-NN_slug.md --auto-fix
python ai_dev_flow/scripts/validate_cross_document.py --document docs/PRD/PRD-NN_slug.md --auto-fix

Layer validation (Phase 2) - run when all PRD documents complete

层级验证（第2阶段）——所有PRD文档完成后执行

python ai_dev_flow/scripts/validate_cross_document.py --layer PRD --auto-fix
undefined
python ai_dev_flow/scripts/validate_cross_document.py --layer PRD --auto-fix
undefined

Validation Codes Reference

验证代码参考

CodeDescriptionSeverity
XDOC-001Referenced requirement ID not foundERROR
XDOC-002Missing cumulative tag (@brd)ERROR
XDOC-003Upstream document not foundERROR
XDOC-006Tag format invalidERROR
XDOC-009Missing traceability sectionERROR
FWDREF-E001Forward reference to non-existent ADRERROR
代码描述严重程度
XDOC-001引用的需求ID不存在错误
XDOC-002缺失累积标签(@brd)错误
XDOC-003上游文档不存在错误
XDOC-006标签格式无效错误
XDOC-009缺失可追溯性章节错误
FWDREF-E001前置引用不存在的ADR错误

Quality Gate

质量门

Blocking: YES - Cannot proceed to EARS/SYS creation until validation passes with 0 errors.
阻塞性：是——必须验证通过且无错误，才能继续创建EARS/SYS

Common Pitfalls

常见陷阱

  1. Missing dual scores: Both SYS-Ready and EARS-Ready scores required
  2. Incorrect section structure: Must be exactly 21 sections (1-21) in order
  3. Missing Section 10 content: Customer-Facing Content is MANDATORY
  4. User Stories scope violation: Section 8 must stay at PRD-level (no EARS/BDD detail)
  5. ADR forward references: Don't write "See ADR-033" (ADRs don't exist yet)
  6. Missing @brd tags: Layer 2 must include Layer 1 tags
  7. ID format errors: Use unified format PRD.NN.TT.SS (not F-XXX, US-XXX, etc.)
  8. Missing EARS Enhancement Appendix: Section 20 required for EARS-Ready score
  9. Missing upstream BRD update: Must add PRD reference to parent BRD's Downstream Artifacts
  1. 缺失双重分数：必须同时包含SYS就绪分数和EARS就绪分数
  2. 章节结构错误：必须严格包含21个章节（1-21）且顺序正确
  3. 缺失第10章内容：客户面向内容为必填项
  4. 用户故事范围违规：第8章必须仅保留PRD层面内容（不含EARS/BDD细节）
  5. ADR前置引用：不要写“参见ADR-033”（ADR此时尚未存在）
  6. 缺失@brd标签：第2层必须包含第1层的标签
  7. ID格式错误：使用统一格式PRD.NN.TT.SS（不要使用F-XXX、US-XXX等）
  8. 缺失EARS增强附录：第20章是获取EARS就绪分数的必填项
  9. 未更新上游BRD：必须将PRD引用添加到父BRD的下游工件中

Template Binding (MANDATORY)

模板绑定（必填）

When creating PRD documents, use EXACTLY these metadata values:
yaml
tags:
  - prd                 # REQUIRED - Use 'prd' NOT 'product-prd', 'feature-prd'
  - layer-2-artifact    # REQUIRED - Layer identifier

custom_fields:
  document_type: prd    # REQUIRED - Use 'prd' NOT 'product-requirements'
  artifact_type: PRD    # REQUIRED - Uppercase
  layer: 2              # REQUIRED - PRD is Layer 2
  architecture_approaches: [ai-agent-based]  # REQUIRED - Array format
FORBIDDEN Values:
  • Tags: 
    product-prd
    , 
    feature-prd
    , 
    product-requirements
  • document_type: 
    product-requirements
    , 
    product_requirements
  • architecture_approach: value
    (singular form)
创建PRD文档时，必须使用以下精确元数据值:
yaml
tags:
  - prd                 # 必填——使用'prd'，不要使用'product-prd'、'feature-prd'
  - layer-2-artifact    # 必填——层级标识符

custom_fields:
  document_type: prd    # 必填——使用'prd'，不要使用'product-requirements'
  artifact_type: PRD    # 必填——大写
  layer: 2              # 必填——PRD是第2层
  architecture_approaches: [ai-agent-based]  # 必填——数组格式
禁止使用的值:
  • 标签: 
    product-prd
    , 
    feature-prd
    , 
    product-requirements
  • document_type: 
    product-requirements
    , 
    product_requirements
  • architecture_approach: value
    （单数形式）

Diagram Standards

图表标准

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited. See: 
ai_dev_flow/DIAGRAM_STANDARDS.md
and 
mermaid-gen
skill.
所有图表必须使用Mermaid语法。禁止使用基于文本的图表（ASCII艺术、框线图）。 参考：
ai_dev_flow/DIAGRAM_STANDARDS.md
和
mermaid-gen
技能。

Next Skill

下一个技能

After creating PRD, use:
doc-ears
 - Create formal EARS requirements (Layer 3)
The EARS will:
  • Reference this PRD as upstream source
  • Include 
    @brd
    and 
    @prd
    tags (cumulative)
  • Use WHEN-THE-SHALL-WITHIN format
  • Formalize PRD features into requirements
创建PRD后，使用:
doc-ears
 - 创建正式的EARS需求（第3层）
EARS将:
  • 引用本PRD作为上游来源
  • 包含
    @brd
    和
    @prd
    标签（累积）
  • 使用WHEN-THE-SHALL-WITHIN格式
  • 将PRD功能正式化为需求

Related Resources

相关资源

  • Main Guide: 
    ai_dev_flow/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md
  • PRD Schema: 
    ai_dev_flow/02_PRD/PRD_MVP_SCHEMA.yaml
  • PRD Template: 
    ai_dev_flow/02_PRD/PRD-MVP-TEMPLATE.md
  • PRD Creation Rules: 
    ai_dev_flow/02_PRD/PRD_CREATION_RULES.md
  • PRD Validation Rules: 
    ai_dev_flow/02_PRD/PRD_VALIDATION_RULES.md
  • PRD README: 
    ai_dev_flow/02_PRD/README.md
  • Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
Section Templates (DEFAULT for all PRD documents):
  • Structure: 
    docs/PRD/PRD-NN_{slug}/PRD-NN.S_{slug}.md
  • Index template: 
    ai_dev_flow/02_PRD/PRD-SECTION-0-TEMPLATE.md
  • Content template: 
    ai_dev_flow/02_PRD/PRD-SECTION-TEMPLATE.md
  • Reference: 
    ai_dev_flow/ID_NAMING_STANDARDS.md
  • 主指南: 
    ai_dev_flow/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md
  • PRD Schema: 
    ai_dev_flow/02_PRD/PRD_MVP_SCHEMA.yaml
  • PRD模板: 
    ai_dev_flow/02_PRD/PRD-MVP-TEMPLATE.md
  • PRD创建规则: 
    ai_dev_flow/02_PRD/PRD_CREATION_RULES.md
  • PRD验证规则: 
    ai_dev_flow/02_PRD/PRD_VALIDATION_RULES.md
  • PRD README: 
    ai_dev_flow/02_PRD/README.md
  • 共享标准: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
章节模板（所有PRD文档默认使用）:
  • 结构: 
    docs/PRD/PRD-NN_{slug}/PRD-NN.S_{slug}.md
  • 索引模板: 
    ai_dev_flow/02_PRD/PRD-SECTION-0-TEMPLATE.md
  • 内容模板: 
    ai_dev_flow/02_PRD/PRD-SECTION-TEMPLATE.md
  • 参考: 
    ai_dev_flow/ID_NAMING_STANDARDS.md

Quick Reference

快速参考

PRD Purpose: Define product features and user needs
Layer: 2
Tags Required: @brd (1 tag)
Key Sections:
  • Section 1: Document Control with dual scoring (SYS-Ready + EARS-Ready >=90%)
  • Section 8: User Stories (PRD-level only)
  • Section 10: Customer-Facing Content (MANDATORY)
  • Section 18: Traceability with Architecture Decision Requirements
  • Section 20: EARS Enhancement Appendix
Next: doc-ears
PRD目的: 定义产品功能和用户需求
层级: 2
必填标签: @brd（1个）
关键章节:
  • 第1章: 带双重评分的文档控制（SYS就绪+EARS就绪≥90%）
  • 第8章: 用户故事（仅PRD层面）
  • 第10章: 客户面向内容（必填）
  • 第18章: 带架构决策需求的可追溯性
  • 第20章: EARS增强附录
下一步: doc-ears

Version History

版本历史

VersionDateChangesAuthor
1.02026-02-08Initial skill definition with YAML frontmatter standardizationSystem
版本日期变更内容作者
1.02026-02-08初始技能定义，标准化YAML前置元数据系统