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:

List existing upstream artifacts:

bash

ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/REQ/ 2>/dev/null

Reference only existing documents in traceability tags
Use
null
only when upstream artifact type genuinely doesn't exist
NEVER use placeholders like
```
BRD-XXX
```
or
```
TBD
```
Do NOT create missing upstream artifacts - skip functionality instead

Before creating a BRD, read:

Shared Standards:

.claude/skills/doc-flow/SHARED_CONTENT.md

Template:
```
ai_dev_flow/01_BRD/BRD-MVP-TEMPLATE.md
```

Creation Rules:

ai_dev_flow/01_BRD/BRD_CREATION_RULES.md

Validation Rules:

ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md

Platform vs Feature Guide:
```
ai_dev_flow/PLATFORM_VS_FEATURE_BRD.md
```

For New Projects: Use

project-init

skill first to initialize project structure.

在创建本文档前，你必须：

列出已有的上游工件:

bash

ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/REQ/ 2>/dev/null

在可追溯性标签中仅引用已存在的文档
仅当上游工件类型确实不存在时，使用
null
绝不使用
```
BRD-XXX
```
或
```
TBD
```
这类占位符
不要创建缺失的上游工件——跳过相关功能即可

在创建BRD前，请阅读：

共享标准:

.claude/skills/doc-flow/SHARED_CONTENT.md

模板:
```
ai_dev_flow/01_BRD/BRD-MVP-TEMPLATE.md
```

创建规则:

ai_dev_flow/01_BRD/BRD_CREATION_RULES.md

验证规则:

ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md

平台与功能指南:
```
ai_dev_flow/PLATFORM_VS_FEATURE_BRD.md
```

针对新项目: 请先使用

project-init

技能初始化项目结构。

Pre-Flight Check (MANDATORY)

预检查（强制）

Before creating ANY BRD section, confirm:

✅ Read
```
ai_dev_flow/ID_NAMING_STANDARDS.md
```
- Element Type Codes table
✅ Element ID format:
```
BRD.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
```
(4 segments, dots)

Common Element Types:

Code	Type	Example
01	Functional Requirement	BRD.02.01.01
06	Acceptance Criteria	BRD.02.06.01
23	Business Objective	BRD.02.23.01
32	Architecture Topic	BRD.02.32.01

⚠️ Removed Patterns: Do NOT use
AC-XXX
,
FR-XXX
,
BC-XXX
,
BO-XXX
formats.

在创建BRD的任何章节前，请确认：

✅ 已阅读
```
ai_dev_flow/ID_NAMING_STANDARDS.md
```
中的元素类型代码表
✅ 元素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

调查问卷

Does this BRD define infrastructure, technology stack, or cross-cutting concerns?
- Yes → Likely Platform BRD
- No → Continue
Does this BRD describe a specific user-facing workflow or feature?
- Yes → Likely Feature BRD
- No → Continue
Will other BRDs depend on or reference this BRD's architectural decisions?
- Yes → Likely Platform BRD
- No → Likely Feature BRD
Does this BRD establish patterns, standards, or capabilities used across multiple features?
- Yes → Platform BRD
- No → Feature BRD
Does this BRD implement functionality on top of existing platform capabilities?
- Yes → Feature BRD
- No → Platform BRD

此BRD是否定义基础设施、技术栈或横切关注点？
- 是 → 大概率为平台型BRD
- 否 → 继续
此BRD是否描述特定的用户端工作流或功能？
- 是 → 大概率为功能型BRD
- 否 → 继续
其他BRD是否会依赖或引用此BRD的架构决策？
- 是 → 大概率为平台型BRD
- 否 → 大概率为功能型BRD
此BRD是否确立跨多个功能使用的模式、标准或能力？
- 是 → 平台型BRD
- 否 → 功能型BRD
此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:

Structure	Format	Use 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:

Executive Summary
Business Context
Stakeholder Analysis
Business Requirements
Success Criteria
Constraints and Assumptions
Architecture Decision Requirements (topics needing ADRs, NOT specific ADR numbers)
Risk Assessment
Traceability (Section 7 format from SHARED_CONTENT.md) 10-16. Additional content sections (see BRD-TEMPLATE.md for full structure)
Glossary - Domain terms and definitions
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）
文档所有者
编制人
状态（草稿、评审中、已批准、已作废）
文档修订历史表

核心章节:

执行摘要
业务背景
干系人分析
业务需求
成功标准
约束与假设
架构决策需求（需要ADR的主题，而非具体ADR编号）
风险评估
可追溯性（遵循SHARED_CONTENT.md中的第7章节格式） 10-16. 附加内容章节（完整结构请见BRD-TEMPLATE.md）
术语表 - 领域术语与定义
附录 - 支持材料与参考资料

平台型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:

```
{project_root}/strategy/README.md
```
- Performance targets, strategy goals

{project_root}/strategy/strategy_overview.md

- Strategic framework

{project_root}/strategy/core_algorithm.md

- Primary algorithm specifications

{project_root}/strategy/risk_management.md

- Risk management policies

{project_root}/strategy/selection_criteria/

- Entry criteria

Every BRD MUST cite specific strategy document sections in Traceability section.

始终从战略开始: 请先阅读相关的

{project_root}/strategy/

文档

阅读顺序:

```
{project_root}/strategy/README.md
```
- 性能指标、战略目标

{project_root}/strategy/strategy_overview.md

- 战略框架

{project_root}/strategy/core_algorithm.md

- 核心算法规范

{project_root}/strategy/risk_management.md

- 风险管理政策

{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主题类别

#	Category	Element ID	Description	When N/A
1	Infrastructure	BRD.NN.32.01	Compute, deployment, scaling	Pure data/analytics project
2	Data Architecture	BRD.NN.32.02	Database, storage, caching	No persistent data needed
3	Integration	BRD.NN.32.03	APIs, messaging, external systems	Standalone system
4	Security	BRD.NN.32.04	Auth, encryption, access control	Internal tool, no sensitive data
5	Observability	BRD.NN.32.05	Monitoring, logging, alerting	MVP/prototype only
6	AI/ML	BRD.NN.32.06	Model serving, training, MLOps	No AI/ML components
7	Technology Selection	BRD.NN.32.07	Languages, frameworks, platforms	Using existing stack

Element Type Code:

= Architecture Topic

序号	类别	元素ID	描述	不适用场景
1	基础设施	BRD.NN.32.01	计算、部署、扩容	纯数据/分析项目
2	数据架构	BRD.NN.32.02	数据库、存储、缓存	无需持久化数据
3	集成	BRD.NN.32.03	API、消息传递、外部系统	独立系统
4	安全	BRD.NN.32.04	认证、加密、访问控制	内部工具，无敏感数据
5	可观测性	BRD.NN.32.05	监控、日志、告警	仅MVP/原型
6	AI/ML	BRD.NN.32.06	模型服务、训练、MLOps	无AI/ML组件
7	技术选型	BRD.NN.32.07	语言、框架、平台	使用现有技术栈

元素类型代码:

= 架构主题

Required Fields Per Topic

每个主题必填字段

Field	Description	Required For
Status	`Selected` , `Pending` , or `N/A`	All topics
Business Driver	WHY this decision matters to business	Selected/Pending
Business Constraints	Non-negotiable business rules	Selected/Pending
Alternatives Overview	MANDATORY table with cost estimates	Selected
Cloud Provider Comparison	MANDATORY GCP/Azure/AWS comparison	Selected
Recommended Selection	Selected option with rationale	Selected
PRD Requirements	What PRD must elaborate	All 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:

Option	Function	Est. Monthly Cost	Selection Rationale
Serverless (Cloud Functions)	Event-driven compute	$200-$800	Selected - cost-effective for variable load
Kubernetes (GKE/EKS)	Container orchestration	$500-$2,000	Rejected - over-engineered for this scale
VM-based (Compute Engine)	Traditional VMs	$400-$1,500	Rejected - manual scaling overhead

Cloud Provider Comparison:

Criterion	GCP	Azure	AWS
Service Name	Cloud Run	Container Apps	Lambda + Fargate
Est. Monthly Cost	$300	$350	$400
Key Strength	Simple container deployment	Azure AD integration	Largest ecosystem
Key Limitation	Fewer enterprise features	Higher baseline cost	Complex pricing
Fit for This Project	High	Medium	Medium

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	否决 - 手动扩容开销大

云服务商对比:

评估项	GCP	Azure	AWS
服务名称	Cloud Run	Container Apps	Lambda + 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:

Notation	Format	Artifacts	Purpose
Dash	TYPE-NN	ADR, SPEC, CTR	Technical artifacts - references to files/documents
Dot	TYPE.NN.TT.SS	BRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS	Hierarchical 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-NN	ADR, SPEC, CTR	技术工件 - 引用文件/文档
点	TYPE.NN.TT.SS	BRD, 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):

Create folder:
```
docs/BRD/BRD-NN_{slug}/
```
(folder slug MUST match index file slug)

Create index file:

docs/BRD/BRD-NN_{slug}/BRD-NN.0_{section_type}.md

(shortened, PREFERRED)

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）:

创建文件夹:
```
docs/BRD/BRD-NN_{slug}/
```
（文件夹slug必须与索引文件slug匹配）

创建索引文件:

docs/BRD/BRD-NN_{slug}/BRD-NN.0_{section_type}.md

（简化版，推荐）

创建章节文件:

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

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

手动检查清单

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

常见误区

Referencing ADR numbers: Don't write "See ADR-033" in Architecture Decision Requirements section (ADRs don't exist yet)
Wrong sections 3.6/3.7 treatment: Platform BRD must populate, Feature BRD must reference Platform BRD
Missing strategy references: Every BRD must cite
```
{project_root}/strategy/
```
sections
Document Control not first: Must be at very top before all numbered sections
Skipping traceability matrix: MANDATORY to create/update matrix

引用ADR编号: 请勿在架构决策需求章节中编写"参见ADR-033"（ADR此时尚未存在）
第3.6/3.7章节处理错误: 平台型BRD必须填充，功能型BRD必须引用平台型BRD
缺失战略引用: 每个BRD必须引用
```
{project_root}/strategy/
```
章节
文档控制章节位置错误: 必须位于所有编号章节之前
跳过可追溯性矩阵: 强制要求创建/更新矩阵

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

Link integrity validation

链接完整性验证

./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 Layer	Required Upstream Tags	Count
BRD (Layer 1)	None (entry point)	0 tags

当前层级	必填上游标签	数量
BRD（第1层）	无（入口点）	0个

Auto-Fix Actions (No Confirmation Required)

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

Issue	Fix Action
Invalid tag format	Correct to TYPE.NN.TT.SS (4-segment) or TYPE-NN format
Broken link	Recalculate path from current location
Missing traceability section	Insert from template

问题	修复操作
无效标签格式	修正为TYPE.NN.TT.SS（4段式）或TYPE-NN格式
失效链接	从当前位置重新计算路径
缺失可追溯性章节	从模板插入

Validation Codes Reference

验证代码参考

Code	Description	Severity
XDOC-006	Tag format invalid	ERROR
XDOC-008	Broken internal link	ERROR
XDOC-009	Missing traceability section	ERROR

代码	描述	严重程度
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 BRD	BRD-REF
PRD-Ready Score: ✅ Required (≥90%)	PRD-Ready Score: NOT APPLICABLE
Cumulative tags: Required	Cumulative tags: NOT REQUIRED
Quality gates: Full validation	Quality gates: EXEMPT
Format: Structured 18 sections	Format: 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文档豁免就绪分数和质量门检查:

标准BRD	BRD-REF
PRD就绪分数: ✅ 必填（≥90%）	PRD就绪分数: 不适用
累计标签: 必填	累计标签: 无需
质量门: 完整验证	质量门: 豁免
格式: 结构化18章节	格式: 自由格式，面向业务

目的: BRD-REF文档是引用目标，供其他文档链接。它们提供支持信息、背景或外部参考，但不定义正式业务需求。

参考: 验证细节请见

ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md

。

Related Resources

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