Back to Details

doc-brd

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-brd

文档-BRD

Purpose

目的

Create Business Requirements Documents (BRD) - Layer 1 artifact in the SDD workflow that defines high-level business needs, strategic objectives, and success criteria.
Layer: 1 (Entry point - no upstream dependencies)
Downstream Artifacts: PRD (Layer 2), EARS (Layer 3), BDD (Layer 4), ADR (Layer 5)
创建业务需求文档（BRD）——SDD工作流中的第1层工件，用于定义高层业务需求、战略目标和成功标准。
层级: 1（入口点 - 无上游依赖）
下游工件: PRD（第2层）、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/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/REQ/ 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 BRD, read:
  1. Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. Template: 
    ai_dev_flow/01_BRD/BRD-MVP-TEMPLATE.md
  3. Creation Rules: 
    ai_dev_flow/01_BRD/BRD_CREATION_RULES.md
  4. Validation Rules: 
    ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md
  5. Platform vs Feature Guide: 
    ai_dev_flow/PLATFORM_VS_FEATURE_BRD.md
For New Projects: Use 
project-init
skill first to initialize project structure.
在创建本文档前，你必须：
  1. 列出已有的上游工件:
    bash
    ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/REQ/ 2>/dev/null
  2. 在可追溯性标签中仅引用已存在的文档
  3. 仅当上游工件类型确实不存在时，使用
    null
  4. 绝不使用
    BRD-XXX
    或
    TBD
    这类占位符
  5. 不要创建缺失的上游工件——跳过相关功能即可
在创建BRD前，请阅读：
  1. 共享标准: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. 模板: 
    ai_dev_flow/01_BRD/BRD-MVP-TEMPLATE.md
  3. 创建规则: 
    ai_dev_flow/01_BRD/BRD_CREATION_RULES.md
  4. 验证规则: 
    ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md
  5. 平台与功能指南: 
    ai_dev_flow/PLATFORM_VS_FEATURE_BRD.md
针对新项目: 请先使用
project-init
技能初始化项目结构。

Pre-Flight Check (MANDATORY)

预检查（强制）

Before creating ANY BRD section, confirm:
  1. ✅ Read 
    ai_dev_flow/ID_NAMING_STANDARDS.md
    - Element Type Codes table
  2. ✅ Element ID format: 
    BRD.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
    (4 segments, dots)
Common Element Types:
CodeTypeExample
01Functional RequirementBRD.02.01.01
06Acceptance CriteriaBRD.02.06.01
23Business ObjectiveBRD.02.23.01
32Architecture TopicBRD.02.32.01
⚠️ Removed Patterns: Do NOT use 
AC-XXX
, 
FR-XXX
, 
BC-XXX
, 
BO-XXX
formats.
在创建BRD的任何章节前，请确认：
  1. ✅ 已阅读
    ai_dev_flow/ID_NAMING_STANDARDS.md
    中的元素类型代码表
  2. ✅ 元素ID格式为
    BRD.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
    （4段式，点分隔）
常见元素类型:
代码类型示例
01功能需求BRD.02.01.01
06验收标准BRD.02.06.01
23业务目标BRD.02.23.01
32架构主题BRD.02.32.01
⚠️ 已废弃格式: 请勿使用
AC-XXX
、
FR-XXX
、
BC-XXX
、
BO-XXX
这类格式。

When to Use This Skill

何时使用本技能

Use 
doc-brd
when:
  • Starting a new project or feature
  • Defining business requirements and objectives
  • Documenting strategic alignment and market context
  • Establishing success criteria and stakeholder needs
  • You are at Layer 1 of the SDD workflow
在以下场景使用
doc-brd
:
  • 启动新项目或新功能
  • 定义业务需求与目标
  • 记录战略对齐情况和市场背景
  • 确立成功标准与干系人需求
  • 处于SDD工作流的第1层

BRD Categorization: Platform vs Feature

BRD分类：平台型 vs 功能型

CRITICAL DECISION: Before creating a BRD, determine if it's a Platform BRD or Feature BRD.
关键决策: 在创建BRD前，需确定它是平台型BRD还是功能型BRD。

Questionnaire

调查问卷

  1. Does this BRD define infrastructure, technology stack, or cross-cutting concerns?
    • Yes → Likely Platform BRD
    • No → Continue
  2. Does this BRD describe a specific user-facing workflow or feature?
    • Yes → Likely Feature BRD
    • No → Continue
  3. Will other BRDs depend on or reference this BRD's architectural decisions?
    • Yes → Likely Platform BRD
    • No → Likely Feature BRD
  4. Does this BRD establish patterns, standards, or capabilities used across multiple features?
    • Yes → Platform BRD
    • No → Feature BRD
  5. Does this BRD implement functionality on top of existing platform capabilities?
    • Yes → Feature BRD
    • No → Platform BRD
  1. 此BRD是否定义基础设施、技术栈或横切关注点？
    • 是 → 大概率为平台型BRD
    • 否 → 继续
  2. 此BRD是否描述特定的用户端工作流或功能？
    • 是 → 大概率为功能型BRD
    • 否 → 继续
  3. 其他BRD是否会依赖或引用此BRD的架构决策？
    • 是 → 大概率为平台型BRD
    • 否 → 大概率为功能型BRD
  4. 此BRD是否确立跨多个功能使用的模式、标准或能力？
    • 是 → 平台型BRD
    • 否 → 功能型BRD
  5. 此BRD是否在现有平台能力之上实现功能？
    • 是 → 功能型BRD
    • 否 → 平台型BRD

Auto-Detection Logic

自动检测逻辑

  • Title contains "Platform", "Architecture", "Infrastructure", "Integration" → Platform BRD
  • Title contains specific workflow names, user types (B2C, B2B), or feature names → Feature BRD
  • References/depends on BRD-01 or foundation ADRs → Feature BRD
  • Establishes technology choices or system-wide patterns → Platform BRD
  • 标题包含"Platform"、"Architecture"、"Infrastructure"、"Integration" → 平台型BRD
  • 标题包含特定工作流名称、用户类型（B2C、B2B）或功能名称 → 功能型BRD
  • 引用/依赖BRD-01或基础ADR → 功能型BRD
  • 确立技术选型或全系统范围的模式 → 平台型BRD

Workflow Differences

工作流差异

Platform BRD Path:
1. Create Platform BRD (populate sections 3.6 and 3.7)
2. Create ADRs for critical technology decisions (identified in BRD sections 3.6/3.7)
3. Create PRD referencing Platform BRD and ADRs
4. Create additional ADRs for implementation details
5. Continue to SPEC
Feature BRD Path:
1. Create Feature BRD (reference Platform BRD in sections 3.6 and 3.7)
2. Create PRD for feature
3. Create ADRs for implementation decisions (if needed)
4. Continue to SPEC
平台型BRD路径:
1. 创建平台型BRD（填充第3.6和3.7章节）
2. 为关键技术决策创建ADR（在BRD的3.6/3.7章节中识别）
3. 创建引用平台型BRD和ADR的PRD
4. 为实现细节创建额外的ADR
5. 进入SPEC阶段
功能型BRD路径:
1. 创建功能型BRD（在第3.6和3.7章节中引用平台型BRD）
2. 为功能创建PRD
3. 为实现决策创建ADR（如有需要）
4. 进入SPEC阶段

Section 3.6 & 3.7 Rules

第3.6和3.7章节规则

Platform BRD:
  • MUST populate Section 3.6 (Technology Stack Prerequisites) with detailed technology choices
  • MUST populate Section 3.7 (Mandatory Technology Conditions) with non-negotiable constraints
Feature BRD:
  • MUST mark Section 3.6 as "N/A - See Platform BRD-NN Section 3.6" and reference specific items
  • MUST mark Section 3.7 as "N/A - See Platform BRD-NN Section 3.7" and reference specific conditions
Reference: 
ai_dev_flow/PLATFORM_VS_FEATURE_BRD.md
for detailed guidance
平台型BRD:
  • 必须填充第3.6章节（技术栈前置条件），包含详细的技术选型
  • 必须填充第3.7章节（强制技术条件），包含不可协商的约束
功能型BRD:
  • 必须标记第3.6章节为"不适用 - 参见平台型BRD-NN第3.6章节"并引用具体内容
  • 必须标记第3.7章节为"不适用 - 参见平台型BRD-NN第3.7章节"并引用具体条件
参考: 详细指南请见
ai_dev_flow/PLATFORM_VS_FEATURE_BRD.md

BRD-Specific Guidance

BRD专属指导

1. Template Selection

1. 模板选择

Primary Template:
BRD-TEMPLATE.md - Comprehensive business requirements (general purpose)
  • Use for: All business requirements documents
  • Sections: Complete 18-section structure
  • Best for: Complex projects, regulatory compliance needs
  • Location: 
    ai_dev_flow/01_BRD/BRD-TEMPLATE.md
Note: Use the comprehensive template for all BRD documents. For simpler requirements, complete only the essential sections and mark others as "N/A - Not applicable for this scope".
Note: Technical QA standards, testing strategy, and defect management are documented in PRD-TEMPLATE.md Section 21 (product level).
Two Structure Options:
StructureFormatUse When
Monolithic (Flat)
docs/BRD/BRD-NN_{slug}.md
Single-file documents <25KB, MVP templates
Section-Based (Nested)
docs/BRD/BRD-NN_{slug}/BRD-NN.S_{section}.md
Documents >25KB, complex multi-section
Monolithic Structure (Flat) - for MVP/small documents:
  • Location: 
    docs/BRD/BRD-NN_{slug}.md
    (directly in BRD directory, no nested folder)
  • H1 Title: 
    # BRD-NN: Document Title
    (no 
    .S
    suffix)
  • Template: 
    ai_dev_flow/01_BRD/BRD-MVP-TEMPLATE.md
    or simplified 
    BRD-TEMPLATE.md
  • Rule: Do NOT create a folder for monolithic files
Section-Based Structure (Nested) - for large/complex documents:
  • Location: 
    docs/BRD/BRD-NN_{slug}/BRD-NN.S_{section}.md
  • Folder Naming: 
    BRD-NN_{slug}/
    where slug MUST match the index file slug
  • H1 Title: 
    # BRD-NN.S: Section Title
    (includes 
    .S
    suffix)
  • Index template: 
    ai_dev_flow/01_BRD/BRD-SECTION-0-TEMPLATE.md
  • Content template: 
    ai_dev_flow/01_BRD/BRD-SECTION-TEMPLATE.md
  • Reference: 
    ai_dev_flow/ID_NAMING_STANDARDS.md
    (Section-Based File Splitting)
主模板:
BRD-TEMPLATE.md - 全面的业务需求模板（通用型）
  • 适用场景: 所有业务需求文档
  • 章节: 完整的18章节结构
  • 最佳适用: 复杂项目、合规需求项目
  • 位置: 
    ai_dev_flow/01_BRD/BRD-TEMPLATE.md
注意: 所有BRD文档均使用全面模板。对于简单需求，仅需完成必要章节，其他章节标记为"不适用 - 超出本次范围"即可。
注意: 技术QA标准、测试策略和缺陷管理记录在PRD-TEMPLATE.md的第21章节（产品层面）。
两种结构选项:
结构格式适用场景
单体式（扁平）
docs/BRD/BRD-NN_{slug}.md
单文件文档<25KB，MVP模板
章节式（嵌套）
docs/BRD/BRD-NN_{slug}/BRD-NN.S_{section}.md
文档>25KB，复杂多章节
单体式结构（扁平） - 适用于MVP/小型文档:
  • 位置: 
    docs/BRD/BRD-NN_{slug}.md
    （直接放在BRD目录，无嵌套文件夹）
  • H1标题: 
    # BRD-NN: 文档标题
    （无
    .S
    后缀）
  • 模板: 
    ai_dev_flow/01_BRD/BRD-MVP-TEMPLATE.md
    或简化版
    BRD-TEMPLATE.md
  • 规则: 请勿为单体式文件创建文件夹
章节式结构（嵌套） - 适用于大型/复杂文档:
  • 位置: 
    docs/BRD/BRD-NN_{slug}/BRD-NN.S_{section}.md
  • 文件夹命名: 
    BRD-NN_{slug}/
    ，其中slug必须与索引文件的slug匹配
  • H1标题: 
    # BRD-NN.S: 章节标题
    （包含
    .S
    后缀）
  • 索引模板: 
    ai_dev_flow/01_BRD/BRD-SECTION-0-TEMPLATE.md
  • 内容模板: 
    ai_dev_flow/01_BRD/BRD-SECTION-TEMPLATE.md
  • 参考: 
    ai_dev_flow/ID_NAMING_STANDARDS.md
    （章节式文件拆分规则）

2. Required Sections (18 Total)

2. 必填章节（共18个）

Document Control (MANDATORY - First section before all numbered sections):
  • Project Name
  • Document Version
  • Date (YYYY-MM-DD)
  • Document Owner
  • Prepared By
  • Status (Draft, In Review, Approved, Superseded)
  • Document Revision History table
Core Sections:
  1. Executive Summary
  2. Business Context
  3. Stakeholder Analysis
  4. Business Requirements
  5. Success Criteria
  6. Constraints and Assumptions
  7. Architecture Decision Requirements (topics needing ADRs, NOT specific ADR numbers)
  8. Risk Assessment
  9. Traceability (Section 7 format from SHARED_CONTENT.md) 10-16. Additional content sections (see BRD-TEMPLATE.md for full structure)
  10. Glossary - Domain terms and definitions
  11. Appendices - Supporting materials and references
Platform BRD Additional Sections:
  • 3.6 Technology Stack Prerequisites (MUST populate for Platform BRD)
  • 3.7 Mandatory Technology Conditions (MUST populate for Platform BRD)
文档控制（强制 - 所有编号章节之前的第一个章节）:
  • 项目名称
  • 文档版本
  • 日期（YYYY-MM-DD）
  • 文档所有者
  • 编制人
  • 状态（草稿、评审中、已批准、已作废）
  • 文档修订历史表
核心章节:
  1. 执行摘要
  2. 业务背景
  3. 干系人分析
  4. 业务需求
  5. 成功标准
  6. 约束与假设
  7. 架构决策需求（需要ADR的主题，而非具体ADR编号）
  8. 风险评估
  9. 可追溯性（遵循SHARED_CONTENT.md中的第7章节格式） 10-16. 附加内容章节（完整结构请见BRD-TEMPLATE.md）
  10. 术语表 - 领域术语与定义
  11. 附录 - 支持材料与参考资料
平台型BRD附加章节:
  • 3.6 技术栈前置条件（平台型BRD必须填充）
  • 3.7 强制技术条件（平台型BRD必须填充）

3. Strategy References (MANDATORY)

3. 战略参考（强制）

ALWAYS START WITH STRATEGY: Read relevant 
{project_root}/strategy/
documents FIRST
Reading Order:
  1. {project_root}/strategy/README.md
    - Performance targets, strategy goals
  2. {project_root}/strategy/strategy_overview.md
    - Strategic framework
  3. {project_root}/strategy/core_algorithm.md
    - Primary algorithm specifications
  4. {project_root}/strategy/risk_management.md
    - Risk management policies
  5. {project_root}/strategy/selection_criteria/
    - Entry criteria
Every BRD MUST cite specific strategy document sections in Traceability section.
始终从战略开始: 请先阅读相关的
{project_root}/strategy/
文档
阅读顺序:
  1. {project_root}/strategy/README.md
    - 性能指标、战略目标
  2. {project_root}/strategy/strategy_overview.md
    - 战略框架
  3. {project_root}/strategy/core_algorithm.md
    - 核心算法规范
  4. {project_root}/strategy/risk_management.md
    - 风险管理政策
  5. {project_root}/strategy/selection_criteria/
    - 准入标准
每个BRD必须在可追溯性章节中引用具体的战略文档章节。

4. Architecture Decision Requirements Section (7.2) - MANDATORY

4. 架构决策需求章节（7.2） - 强制

Purpose: Identify architectural topics requiring decisions with cost-focused, alternatives-based analysis.
Every BRD MUST include Section 7.2: "Architecture Decision Requirements" addressing all 7 mandatory ADR topic categories.
目的: 识别需要基于成本、多方案分析进行决策的架构主题。
每个BRD必须包含第7.2章节："架构决策需求"，涵盖全部7个强制ADR主题类别。

7 Mandatory ADR Topic Categories

7个强制ADR主题类别

#CategoryElement IDDescriptionWhen N/A
1InfrastructureBRD.NN.32.01Compute, deployment, scalingPure data/analytics project
2Data ArchitectureBRD.NN.32.02Database, storage, cachingNo persistent data needed
3IntegrationBRD.NN.32.03APIs, messaging, external systemsStandalone system
4SecurityBRD.NN.32.04Auth, encryption, access controlInternal tool, no sensitive data
5ObservabilityBRD.NN.32.05Monitoring, logging, alertingMVP/prototype only
6AI/MLBRD.NN.32.06Model serving, training, MLOpsNo AI/ML components
7Technology SelectionBRD.NN.32.07Languages, frameworks, platformsUsing existing stack
Element Type Code: 
32
= Architecture Topic
序号类别元素ID描述不适用场景
1基础设施BRD.NN.32.01计算、部署、扩容纯数据/分析项目
2数据架构BRD.NN.32.02数据库、存储、缓存无需持久化数据
3集成BRD.NN.32.03API、消息传递、外部系统独立系统
4安全BRD.NN.32.04认证、加密、访问控制内部工具，无敏感数据
5可观测性BRD.NN.32.05监控、日志、告警仅MVP/原型
6AI/MLBRD.NN.32.06模型服务、训练、MLOps无AI/ML组件
7技术选型BRD.NN.32.07语言、框架、平台使用现有技术栈
元素类型代码: 
32
= 架构主题

Required Fields Per Topic

每个主题必填字段

FieldDescriptionRequired For
Status
Selected
, 
Pending
, or 
N/A
All topics
Business DriverWHY this decision matters to businessSelected/Pending
Business ConstraintsNon-negotiable business rulesSelected/Pending
Alternatives OverviewMANDATORY table with cost estimatesSelected
Cloud Provider ComparisonMANDATORY GCP/Azure/AWS comparisonSelected
Recommended SelectionSelected option with rationaleSelected
PRD RequirementsWhat PRD must elaborateAll topics
字段描述适用场景
状态
Selected
（已选定）、
Pending
（待确定）或
N/A
（不适用）		所有主题
业务驱动因素该决策对业务的重要性原因已选定/待确定
业务约束不可协商的业务规则已选定/待确定
方案概述带成本估算的强制表格已选定
云服务商对比强制GCP/Azure/AWS对比表格已选定
推荐选型选定方案及理由已选定
PRD需求PRD需要细化的内容所有主题

Alternatives Overview Table (MANDATORY for Selected status)

方案概述表格（已选定状态必填）

markdown
**Alternatives Overview**:

| Option | Function | Est. Monthly Cost | Selection Rationale |
|--------|----------|-------------------|---------------------|
| Serverless | Event-driven compute | $200-$800 | Selected - cost-effective |
| Kubernetes | Container orchestration | $500-$2,000 | Rejected - over-engineered |
| VM-based | Traditional VMs | $400-$1,500 | Rejected - manual scaling |
markdown
**方案概述**:

| 选项 | 功能 | 预估月度成本 | 选型理由 |
|--------|----------|-------------------|---------------------|
| Serverless | 事件驱动计算 | $200-$800 | 选定 - 成本效益高 |
| Kubernetes | 容器编排 | $500-$2,000 | 否决 - 过度设计 |
| VM-based | 传统虚拟机 | $400-$1,500 | 否决 - 手动扩容 |

Cloud Provider Comparison Table (MANDATORY for Selected status)

云服务商对比表格（已选定状态必填）

markdown
**Cloud Provider Comparison**:

| Criterion | GCP | Azure | AWS |
|-----------|-----|-------|-----|
| **Service Name** | Cloud Run | Container Apps | Fargate |
| **Est. Monthly Cost** | $300 | $350 | $400 |
| **Key Strength** | Auto-scaling | AD integration | Ecosystem |
| **Key Limitation** | Fewer features | Higher cost | Complex pricing |
| **Fit for This Project** | High | Medium | Medium |
markdown
**云服务商对比**:

| 评估项 | GCP | Azure | AWS |
|-----------|-----|-------|-----|
| **服务名称** | Cloud Run | Container Apps | Fargate |
| **预估月度成本** | $300 | $350 | $400 |
| **核心优势** | 自动扩容 | AD集成 | 生态系统完善 |
| **核心局限** | 功能较少 | 成本较高 | 定价复杂 |
| **项目适配度** | 高 | 中 | 中 |

Complete Topic Example

完整主题示例

markdown
undefined
markdown
undefined

BRD.01.32.01: Infrastructure

BRD.01.32.01: 基础设施

Status: Selected
Business Driver: Customer onboarding workflow requires scalable compute for variable registration volumes.
Business Constraints:
  • Must support auto-scaling for peak periods (10x baseline)
  • Maximum infrastructure cost: $5,000/month
  • 99.9% availability during business hours
Alternatives Overview:
OptionFunctionEst. Monthly CostSelection Rationale
Serverless (Cloud Functions)Event-driven compute$200-$800Selected - cost-effective for variable load
Kubernetes (GKE/EKS)Container orchestration$500-$2,000Rejected - over-engineered for this scale
VM-based (Compute Engine)Traditional VMs$400-$1,500Rejected - manual scaling overhead
Cloud Provider Comparison:
CriterionGCPAzureAWS
Service NameCloud RunContainer AppsLambda + Fargate
Est. Monthly Cost$300$350$400
Key StrengthSimple container deploymentAzure AD integrationLargest ecosystem
Key LimitationFewer enterprise featuresHigher baseline costComplex pricing
Fit for This ProjectHighMediumMedium
Recommended Selection: GCP Cloud Run - serverless containers with optimal cost-to-scale ratio.
PRD Requirements: Evaluate cold start impact on latency. Specify concurrency limits and scaling policies.
undefined
状态: 已选定
业务驱动因素: 客户注册工作流需要可扩容的计算资源以应对波动的注册量。
业务约束:
  • 必须支持峰值时段的自动扩容（基线的10倍）
  • 基础设施月成本上限：$5,000
  • 工作时间内可用性达99.9%
方案概述:
选项功能预估月度成本选型理由
Serverless（云函数）事件驱动计算$200-$800选定 - 应对可变负载的成本效益最优
Kubernetes（GKE/EKS）容器编排$500-$2,000否决 - 该规模下过度设计
VM-based（计算引擎）传统虚拟机$400-$1,500否决 - 手动扩容开销大
云服务商对比:
评估项GCPAzureAWS
服务名称Cloud RunContainer AppsLambda + Fargate
预估月度成本$300$350$400
核心优势简单容器部署Azure AD集成生态系统最庞大
核心局限企业级功能较少基线成本较高定价复杂
项目适配度高中中
推荐选型: GCP Cloud Run - 无服务器容器，成本与扩容比最优。
PRD需求: 评估冷启动对延迟的影响。指定并发限制和扩容策略。
undefined

Handling N/A and Pending Status

不适用与待确定状态处理

N/A Example:
markdown
undefined
不适用示例:
markdown
undefined

BRD.01.32.06: AI/ML Architecture

BRD.01.32.06: AI/ML架构

Status: N/A - No AI/ML components in project scope
Reason: This feature uses standard rule-based validation. No machine learning, AI agents, or predictive analytics required.
PRD Requirements: None for current scope. Flag for Phase 2 evaluation if ML-based fraud detection needed.

**Pending Example**:
```markdown
状态: 不适用 - 项目范围内无AI/ML组件
原因: 本功能使用标准规则引擎验证。无需机器学习、AI Agent或预测分析能力。
PRD需求: 当前范围无需求。若后续需要基于ML的欺诈检测，可在Phase 2评估。

**待确定示例**:
```markdown

BRD.01.32.05: Observability

BRD.01.32.05: 可观测性

Status: Pending - Awaiting infrastructure finalization
Business Driver: System monitoring required for SLA compliance.
Business Constraints:
  • Real-time alerting for system failures
  • Minimum 30-day log retention
Alternatives Overview: [Placeholder - To be completed after infrastructure selection]
PRD Requirements: Complete observability analysis after infrastructure finalization.
undefined
状态: 待确定 - 等待基础设施最终确定
业务驱动因素: 系统监控是SLA合规的要求。
业务约束:
  • 系统故障实时告警
  • 日志保留至少30天
方案概述: [占位符 - 基础设施选定后补充]
PRD需求: 基础设施确定后完成可观测性分析。
undefined

Layer Separation Principle

层级分离原则

BRD Section 7.2          →    PRD Section 18         →    ADR
(WHAT & WHY & HOW MUCH)       (HOW to evaluate)          (Final decision)
─────────────────────────────────────────────────────────────────────────
Business drivers              Technical details          Implementation decision
Business constraints          Deep-dive analysis         Trade-off analysis
Cost estimates                Evaluation criteria        Selected approach
Do NOT write: "See ADR-033" or "Reference ADR-045" (ADRs don't exist yet)
Reference: See 
ai_dev_flow/01_BRD/BRD_CREATION_RULES.md
Section 9 for complete guidelines
BRD第7.2章节          →    PRD第18章节         →    ADR
(做什么 & 为什么 & 成本多少)       (如何评估)          (最终决策)
─────────────────────────────────────────────────────────────────────────
业务驱动因素              技术细节          实现决策
业务约束              深度分析          权衡分析
成本估算              评估标准          选定方案
请勿编写: "参见ADR-033"或"引用ADR-045"（ADR此时尚未存在）
参考: 完整指南请见
ai_dev_flow/01_BRD/BRD_CREATION_RULES.md
第9章节

5. Document Control Section Positioning

5. 文档控制章节位置

CRITICAL: Document Control MUST be the first section at the very top of the BRD (before all numbered sections).
Correct Structure:
markdown
undefined
关键: 文档控制章节必须是BRD的第一个章节，位于所有编号章节之前。
正确结构:
markdown
undefined

BRD-01: Project Name

BRD-01: 项目名称

Document Control

文档控制

[All metadata fields here]
[所有元数据字段]

1. Executive Summary

1. 执行摘要

[Content here]
undefined
[内容]
undefined

Cumulative Tagging Requirements

累计标签要求

Layer 1 (BRD): No upstream tags required (entry point)
Tag Count: 0 tags
Format: BRD has no 
@
tags since it's Layer 1 (top of hierarchy)
Downstream artifacts will tag BRD (using unified format):
  • PRD will include: 
    @brd: BRD.01.01.30
    (TYPE.NN.TT.SS format)
  • EARS will include: 
    @brd: BRD.01.01.30
  • All downstream artifacts inherit BRD tags
第1层（BRD）: 无需上游标签（入口点）
标签数量: 0个
格式: BRD作为第1层（层级顶端），没有
@
标签
下游工件将标记BRD（使用统一格式）:
  • PRD将包含: 
    @brd: BRD.01.01.30
    （TYPE.NN.TT.SS格式）
  • EARS将包含: 
    @brd: BRD.01.01.30
  • 所有下游工件继承BRD标签

Tag Format Convention (By Design)

标签格式约定（设计如此）

The SDD framework uses two distinct notation systems for cross-references:
NotationFormatArtifactsPurpose
DashTYPE-NNADR, SPEC, CTRTechnical artifacts - references to files/documents
DotTYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKSHierarchical artifacts - references to elements inside documents
Key Distinction:
  • @adr: ADR-033
    → Points to the document 
    ADR-033_risk_limit_enforcement.md
  • @brd: BRD.17.01.01
    → Points to element 01.01 inside document 
    BRD-017.md
SDD框架使用两种不同的标记系统进行交叉引用:
标记方式格式适用工件用途
短横线TYPE-NNADR, SPEC, CTR技术工件 - 引用文件/文档
点TYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS层级化工件 - 引用文档内的元素
核心区别:
  • @adr: ADR-033
    → 指向文档
    ADR-033_risk_limit_enforcement.md
  • @brd: BRD.17.01.01
    → 指向文档
    BRD-017.md
    内的元素01.01

Unified Element ID Format (MANDATORY)

统一元素ID格式（强制）

For hierarchical requirements (BRD, PRD, EARS, BDD, SYS, REQ):
  • Always use: 
    TYPE.NN.TT.SS
    (dot separator, 4-segment unified format)
  • Never use: 
    TYPE-NN:NNN
    (colon separator - DEPRECATED)
  • Never use: 
    TYPE.NN.TT
    (3-segment format - DEPRECATED)
Examples:
  • @brd: BRD.17.01.01
    ✅
  • @brd: BRD.017.001
    ❌ (old 3-segment format)
针对层级化需求（BRD, PRD, EARS, BDD, SYS, REQ）:
  • 必须使用: 
    TYPE.NN.TT.SS
    （点分隔，4段式统一格式）
  • 禁止使用: 
    TYPE-NN:NNN
    （冒号分隔 - 已废弃）
  • 禁止使用: 
    TYPE.NN.TT
    （3段式格式 - 已废弃）
示例:
  • @brd: BRD.17.01.01
    ✅
  • @brd: BRD.017.001
    ❌（旧3段式格式）

Upstream/Downstream Artifacts

上游/下游工件

Upstream Sources (what drives BRD creation):
  • Strategy documents (
    {project_root}/strategy/
    )
  • Business owner requirements
  • Market analysis
  • Stakeholder inputs
Downstream Artifacts (what BRD drives):
  • PRD (Layer 2) - Product requirements derived from BRD
  • EARS (Layer 3) - Formal requirements from BRD business needs
  • BDD (Layer 4) - Test scenarios validating BRD objectives
  • ADR (Layer 5) - Architecture decisions for topics identified in BRD Section "Architecture Decision Requirements"
Same-Type Document Relationships (conditional):
  • @related-brd: BRD-NN
    - BRDs sharing business domain context
  • @depends-brd: BRD-NN
    - BRD that must be implemented first (e.g., platform BRD before feature BRD)
上游来源（驱动BRD创建的因素）:
  • 战略文档 (
    {project_root}/strategy/
    )
  • 业务所有者需求
  • 市场分析
  • 干系人输入
下游工件（由BRD驱动）:
  • PRD（第2层） - 基于BRD衍生的产品需求
  • EARS（第3层） - 基于BRD业务需求的正式需求
  • BDD（第4层） - 验证BRD目标的测试场景
  • ADR（第5层） - 针对BRD"架构决策需求"章节中识别的主题制定的架构决策
同类型文档关系（可选）:
  • @related-brd: BRD-NN
    - 共享业务领域背景的BRD
  • @depends-brd: BRD-NN
    - 必须先实现的BRD（例如，平台型BRD先于功能型BRD）

Creation Process

创建流程

Step 1: Determine BRD Type

步骤1: 确定BRD类型

Use questionnaire above to determine Platform vs Feature BRD.
使用上述调查问卷确定是平台型还是功能型BRD。

Step 2: Read Strategy Documents

步骤2: 阅读战略文档

Read relevant 
{project_root}/strategy/
sections to understand business logic.
阅读相关的
{project_root}/strategy/
章节，理解业务逻辑。

Step 3: Select Template

步骤3: 选择模板

Choose appropriate template (comprehensive, simplified, or domain-specific).
选择合适的模板（全面版、简化版或领域专属版）。

Step 4: Reserve ID Number

步骤4: 预留ID编号

Check 
docs/BRD/
for next available ID number (e.g., BRD-01, BRD-02).
ID Numbering Convention: Start with 2 digits and expand only as needed.
  • ✅ Correct: BRD-01, BRD-99, BRD-102
  • ❌ Incorrect: BRD-001, BRD-009 (extra leading zero not required)
检查
docs/BRD/
获取下一个可用的ID编号（例如，BRD-01, BRD-02）。
ID编号约定: 从2位数字开始，仅在需要时扩展。
  • ✅ 正确: BRD-01, BRD-99, BRD-102
  • ❌ 错误: BRD-001, BRD-009（无需前导零）

Step 5: Create BRD Folder and Files

步骤5: 创建BRD文件夹与文件

Folder structure (DEFAULT - nested folder per document with descriptive slug):
  1. Create folder: 
    docs/BRD/BRD-NN_{slug}/
    (folder slug MUST match index file slug)
  2. Create index file: 
    docs/BRD/BRD-NN_{slug}/BRD-NN.0_{section_type}.md
    (shortened, PREFERRED)
  3. Create section files: 
    docs/BRD/BRD-NN_{slug}/BRD-NN.S_{section_type}.md
    (shortened, PREFERRED)
Example (Shortened Pattern - PREFERRED):
docs/BRD/BRD-01_platform_architecture/
├── BRD-01.0_index.md
├── BRD-01.1_executive_summary.md
├── BRD-01.2_business_context.md
└── BRD-01.3_requirements.md
Note: Folder contains descriptive slug, so filenames can omit it. Full pattern (
BRD-01.0_platform_architecture_index.md
) also accepted for backward compatibility.
OPTIONAL (for small documents <25KB): 
docs/BRD/BRD-NN_{slug}.md
(monolithic)
文件夹结构（默认 - 每个文档对应嵌套文件夹，带描述性slug）:
  1. 创建文件夹: 
    docs/BRD/BRD-NN_{slug}/
    （文件夹slug必须与索引文件slug匹配）
  2. 创建索引文件: 
    docs/BRD/BRD-NN_{slug}/BRD-NN.0_{section_type}.md
    （简化版，推荐）
  3. 创建章节文件: 
    docs/BRD/BRD-NN_{slug}/BRD-NN.S_{section_type}.md
    （简化版，推荐）
示例（简化格式 - 推荐）:
docs/BRD/BRD-01_platform_architecture/
├── BRD-01.0_index.md
├── BRD-01.1_executive_summary.md
├── BRD-01.2_business_context.md
└── BRD-01.3_requirements.md
注意: 文件夹包含描述性slug，因此文件名可省略slug。完整版格式（
BRD-01.0_platform_architecture_index.md
）也兼容，用于向后兼容。
可选（适用于<25KB的小型文档）: 
docs/BRD/BRD-NN_{slug}.md
（单体式）

Step 6: Fill Document Control Section

步骤6: 填充文档控制章节

Complete all required metadata fields and initialize Document Revision History table.
完成所有必填元数据字段并初始化文档修订历史表。

Step 7: Complete Core Sections

步骤7: 完成核心章节

Fill all 18 required sections following template structure.
Platform BRD: Populate sections 3.6 and 3.7 with technology details Feature BRD: Mark sections 3.6 and 3.7 as "N/A - See Platform BRD-NN"
遵循模板结构填充全部18个必填章节。
平台型BRD: 填充第3.6和3.7章节的技术细节 功能型BRD: 将第3.6和3.7章节标记为"不适用 - 参见平台型BRD-NN"

Step 8: Document Architecture Decision Requirements

步骤8: 记录架构决策需求

List topics needing architectural decisions (do NOT reference specific ADR numbers).
列出需要架构决策的主题（请勿引用具体ADR编号）。

Step 9: Add Strategy References

步骤9: 添加战略引用

In Traceability section, link to specific 
{project_root}/strategy/
sections.
在可追溯性章节中，链接到具体的
{project_root}/strategy/
章节。

Step 10: Create/Update Traceability Matrix

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

MANDATORY: Create or update 
docs/BRD/BRD-00_TRACEABILITY_MATRIX.md
  • Use template: 
    ai_dev_flow/01_BRD/BRD-00_TRACEABILITY_MATRIX-TEMPLATE.md
  • Add BRD entry with upstream sources and downstream artifacts
  • Update traceability matrix in same commit after BRD validation passes (see SHARED_CONTENT.md Traceability Matrix Update Workflow)
强制: 创建或更新
docs/BRD/BRD-00_TRACEABILITY_MATRIX.md
  • 使用模板: 
    ai_dev_flow/01_BRD/BRD-00_TRACEABILITY_MATRIX-TEMPLATE.md
  • 添加BRD条目，包含上游来源和下游工件
  • BRD验证通过后，在同一提交中更新可追溯性矩阵（参见SHARED_CONTENT.md中的可追溯性矩阵更新工作流）

Step 11: Validate BRD

步骤11: 验证BRD

Run validation scripts:
bash
undefined
运行验证脚本:
bash
undefined

BRD structure validation

BRD结构验证

./ai_dev_flow/scripts/validate_brd_template.sh docs/BRD/BRD-01_*.md
./ai_dev_flow/scripts/validate_brd_template.sh docs/BRD/BRD-01_*.md

Link integrity

链接完整性

./ai_dev_flow/scripts/validate_links.py --path docs/BRD/
undefined
./ai_dev_flow/scripts/validate_links.py --path docs/BRD/
undefined

Step 12: Commit Changes

步骤12: 提交变更

Commit BRD file and traceability matrix together.
将BRD文件和可追溯性矩阵一起提交。

Validation

验证

Automated Validation

自动化验证

BRD-Specific Validation:
bash
./ai_dev_flow/scripts/validate_brd_template.sh docs/BRD/BRD-01_platform.md
Quality Gates Validation:
bash
./scripts/validate_quality_gates.sh docs/BRD/BRD-01_platform.md
BRD专属验证:
bash
./ai_dev_flow/scripts/validate_brd_template.sh docs/BRD/BRD-01_platform.md
质量门验证:
bash
./scripts/validate_quality_gates.sh docs/BRD/BRD-01_platform.md

Manual Checklist

手动检查清单

  • Document Control section at top (before all numbered sections)
  • All required metadata fields completed
  • Document Revision History table initialized
  • BRD type determined (Platform vs Feature)
  • Sections 3.6 & 3.7 handled correctly for BRD type
  • Architecture Decision Requirements listed (no ADR numbers referenced)
  • Strategy references in Traceability section
  • All 18 sections completed
  • Traceability matrix created/updated
  • No broken links
  • File size <50,000 tokens (standard) or <100,000 tokens (maximum)
  • 文档控制章节位于顶部（所有编号章节之前）
  • 所有必填元数据字段已完成
  • 文档修订历史表已初始化
  • 已确定BRD类型（平台型vs功能型）
  • 第3.6和3.7章节已根据BRD类型正确处理
  • 已列出架构决策需求（未引用ADR编号）
  • 可追溯性章节包含战略引用
  • 所有18个章节已完成
  • 已创建/更新可追溯性矩阵
  • 无失效链接
  • 文件大小<50,000 tokens（标准）或<100,000 tokens（最大值）

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
技能。

Common Pitfalls

常见误区

  1. Referencing ADR numbers: Don't write "See ADR-033" in Architecture Decision Requirements section (ADRs don't exist yet)
  2. Wrong sections 3.6/3.7 treatment: Platform BRD must populate, Feature BRD must reference Platform BRD
  3. Missing strategy references: Every BRD must cite 
    {project_root}/strategy/
    sections
  4. Document Control not first: Must be at very top before all numbered sections
  5. Skipping traceability matrix: MANDATORY to create/update matrix
  1. 引用ADR编号: 请勿在架构决策需求章节中编写"参见ADR-033"（ADR此时尚未存在）
  2. 第3.6/3.7章节处理错误: 平台型BRD必须填充，功能型BRD必须引用平台型BRD
  3. 缺失战略引用: 每个BRD必须引用
    {project_root}/strategy/
    章节
  4. 文档控制章节位置错误: 必须位于所有编号章节之前
  5. 跳过可追溯性矩阵: 强制要求创建/更新矩阵

Post-Creation Validation (MANDATORY - NO CONFIRMATION)

创建后验证（强制 - 无需确认）

CRITICAL: Execute this validation loop IMMEDIATELY after document creation. Do NOT proceed to next document until validation passes.
关键: 文档创建后立即执行此验证循环。验证通过前请勿进行下一个文档的创建。

Automatic Validation Loop

自动验证循环

LOOP:
  1. Run BRD template validation script
  2. IF errors found: Fix issues
  3. IF warnings found: Review and address
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed
循环:
  1. 运行BRD模板验证脚本
  2. 若发现错误: 修复问题
  3. 若发现警告: 检查并处理
  4. 若存在无法修复的问题: 记录以便手动检查，继续
  5. 若验证通过: 标记为已验证，继续

Validation Command

验证命令

bash
undefined
bash
undefined

BRD structure validation (primary)

BRD结构验证（主要）

./ai_dev_flow/scripts/validate_brd_template.sh docs/BRD/BRD-NN_slug.md
./ai_dev_flow/scripts/validate_brd_template.sh docs/BRD/BRD-NN_slug.md

Link integrity validation

链接完整性验证

./ai_dev_flow/scripts/validate_links.py --path docs/BRD/
./ai_dev_flow/scripts/validate_links.py --path docs/BRD/

Quality gates validation

质量门验证

./scripts/validate_quality_gates.sh docs/BRD/BRD-NN_slug.md
undefined
./scripts/validate_quality_gates.sh docs/BRD/BRD-NN_slug.md
undefined

Layer-Specific Upstream Requirements

层级专属上游要求

This LayerRequired Upstream TagsCount
BRD (Layer 1)None (entry point)0 tags
当前层级必填上游标签数量
BRD（第1层）无（入口点）0个

Auto-Fix Actions (No Confirmation Required)

自动修复操作（无需确认）

IssueFix Action
Invalid tag formatCorrect to TYPE.NN.TT.SS (4-segment) or TYPE-NN format
Broken linkRecalculate path from current location
Missing traceability sectionInsert from template
问题修复操作
无效标签格式修正为TYPE.NN.TT.SS（4段式）或TYPE-NN格式
失效链接从当前位置重新计算路径
缺失可追溯性章节从模板插入

Validation Codes Reference

验证代码参考

CodeDescriptionSeverity
XDOC-006Tag format invalidERROR
XDOC-008Broken internal linkERROR
XDOC-009Missing traceability sectionERROR
代码描述严重程度
XDOC-006标签格式无效错误
XDOC-008内部链接失效错误
XDOC-009缺失可追溯性章节错误

Quality Gate

质量门

Blocking: YES - Cannot proceed to next document until Phase 1 validation passes with 0 errors.
阻塞: 是 - 第1阶段验证必须零错误通过，否则无法进入下一个文档的创建。

Next Skill

下一个技能

After creating BRD, use:
doc-prd
 - Create Product Requirements Document (Layer 2)
The PRD will:
  • Reference this BRD as upstream source
  • Include 
    @brd: BRD.NN.01.SS
    tags (unified 4-segment format)
  • Define product features and KPIs
  • Inherit Architecture Decision Requirements topics
创建BRD后，请使用:
doc-prd
 - 创建产品需求文档（第2层）
PRD将:
  • 引用此BRD作为上游来源
  • 包含
    @brd: BRD.NN.01.SS
    标签（统一4段式格式）
  • 定义产品功能与KPI
  • 继承架构决策需求主题

Reference Documents

参考文档

For supplementary documentation related to BRD artifacts:
  • Format: 
    BRD-REF-NNN_{slug}.md
  • Skill: Use 
    doc-ref
    skill
  • Validation: Reduced (4 checks only)
  • Examples: Project overviews, executive summaries, stakeholder guides
关于BRD工件的补充文档:
  • 格式: 
    BRD-REF-NNN_{slug}.md
  • 技能: 使用
    doc-ref
    技能
  • 验证: 简化（仅4项检查）
  • 示例: 项目概述、执行摘要、干系人指南

BRD-REF Ready-Score Exemption

BRD-REF就绪分数豁免

BRD-REF documents are EXEMPT from ready-scores and quality gates:
Standard BRDBRD-REF
PRD-Ready Score: ✅ Required (≥90%)PRD-Ready Score: NOT APPLICABLE
Cumulative tags: RequiredCumulative tags: NOT REQUIRED
Quality gates: Full validationQuality gates: EXEMPT
Format: Structured 18 sectionsFormat: Free format, business-oriented
Purpose: BRD-REF documents are reference targets that other documents link to. They provide supporting information, context, or external references but do not define formal business requirements.
Reference: See 
ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md
for validation details.
BRD-REF文档豁免就绪分数和质量门检查:
标准BRDBRD-REF
PRD就绪分数: ✅ 必填（≥90%）PRD就绪分数: 不适用
累计标签: 必填累计标签: 无需
质量门: 完整验证质量门: 豁免
格式: 结构化18章节格式: 自由格式，面向业务
目的: BRD-REF文档是引用目标，供其他文档链接。它们提供支持信息、背景或外部参考，但不定义正式业务需求。
参考: 验证细节请见
ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md
。

Related Resources

相关资源

  • Main Guide: 
    ai_dev_flow/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md
  • Platform vs Feature Guide: 
    ai_dev_flow/PLATFORM_VS_FEATURE_BRD.md
  • BRD Creation Rules: 
    ai_dev_flow/01_BRD/BRD_CREATION_RULES.md
  • BRD Validation Rules: 
    ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md
  • BRD README: 
    ai_dev_flow/01_BRD/README.md
  • Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  • 主指南: 
    ai_dev_flow/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md
  • 平台与功能指南: 
    ai_dev_flow/PLATFORM_VS_FEATURE_BRD.md
  • BRD创建规则: 
    ai_dev_flow/01_BRD/BRD_CREATION_RULES.md
  • BRD验证规则: 
    ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md
  • BRD说明文档: 
    ai_dev_flow/01_BRD/README.md
  • 共享标准: 
    .claude/skills/doc-flow/SHARED_CONTENT.md

Quick Reference

快速参考

BRD Purpose: Define business needs and objectives
Layer: 1 (Entry point)
Tags Required: None (0 tags)
Key Decision: Platform vs Feature BRD
Critical Sections:
  • 3.6 Technology Stack Prerequisites (Platform BRD populates, Feature BRD references)
  • 3.7 Mandatory Technology Conditions (Platform BRD populates, Feature BRD references)
  • Architecture Decision Requirements (list topics, NOT ADR numbers)
Next: doc-prd
BRD目的: 定义业务需求与目标
层级: 1（入口点）
必填标签: 无（0个）
关键决策: 平台型vs功能型BRD
核心章节:
  • 3.6 技术栈前置条件（平台型BRD填充，功能型BRD引用）
  • 3.7 强制技术条件（平台型BRD填充，功能型BRD引用）
  • 架构决策需求（列出主题，而非ADR编号）
下一步: doc-prd