Back to Details

doc-ears

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-ears

doc-ears

Purpose

目的

Create EARS (Easy Approach to Requirements Syntax) documents - Layer 3 artifact in the SDD workflow that formalizes requirements using the WHEN-THE-SHALL-WITHIN syntax.
Layer: 3
Upstream: BRD (Layer 1), PRD (Layer 2)
Downstream Artifacts: BDD (Layer 4), ADR (Layer 5), SYS (Layer 6)
创建**EARS（需求语法简易方法，Easy Approach to Requirements Syntax）**文档——SDD工作流中的第3层工件，使用WHEN-THE-SHALL-WITHIN语法将需求正式化。
层级：3
上游工件：BRD（第1层）、PRD（第2层）
下游工件：BDD（第4层）、ADR（第5层）、SYS（第6层）

Prerequisites

前置条件

Upstream Artifact Verification (CRITICAL)

上游工件验证（关键）

Before creating this document, you MUST:
  1. List existing upstream artifacts:
    bash
    ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ 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 EARS, read:
  1. Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. Upstream BRD and PRD: Read the BRD and PRD that drive this EARS
  3. Template: 
    ai_dev_flow/03_EARS/EARS-MVP-TEMPLATE.md
    (Template Version 3.0, primary authority)
  4. Schema: 
    ai_dev_flow/03_EARS/EARS_SCHEMA.yaml
    (machine-readable validation rules)
  5. Creation Rules: 
    ai_dev_flow/03_EARS/EARS_CREATION_RULES.md
  6. Validation Rules: 
    ai_dev_flow/03_EARS/EARS_VALIDATION_RULES.md
在创建本文档前，您必须：
  1. 列出已有的上游工件：
    bash
    ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ 2>/dev/null
  2. 在可追溯性标签中仅引用已存在的文档
  3. 仅当上游工件类型确实不存在时使用
    null
  4. 绝不使用
    BRD-XXX
    或
    TBD
    这类占位符
  5. 不要创建缺失的上游工件——而是跳过相关功能
在创建EARS文档前，请阅读：
  1. 共享标准：
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. 上游BRD和PRD：阅读驱动本次EARS文档创建的BRD和PRD
  3. 模板：
    ai_dev_flow/03_EARS/EARS-MVP-TEMPLATE.md
    （模板版本3.0，首要权威依据）
  4. Schema：
    ai_dev_flow/03_EARS/EARS_SCHEMA.yaml
    （机器可读的验证规则）
  5. 创建规则：
    ai_dev_flow/03_EARS/EARS_CREATION_RULES.md
  6. 验证规则：
    ai_dev_flow/03_EARS/EARS_VALIDATION_RULES.md

Template Binding (CRITICAL)

模板绑定（关键）

Always use these exact metadata values:
yaml
tags:
  - ears                 # NOT 'ears-requirements' or 'ears-formal-requirements'
  - layer-3-artifact
  - shared-architecture  # OR 'ai-agent-primary' for agent docs

custom_fields:
  document_type: ears    # NOT 'engineering-requirements'
  artifact_type: EARS
  layer: 3
  architecture_approaches: [ai-agent-based, traditional-8layer]  # ARRAY format required
  priority: shared
  development_status: active
请始终使用以下精确的元数据值：
yaml
tags:
  - ears                 # 不要使用'ears-requirements'或'ears-formal-requirements'
  - layer-3-artifact
  - shared-architecture  # 若为Agent相关文档则使用'ai-agent-primary'

custom_fields:
  document_type: ears    # 不要使用'engineering-requirements'
  artifact_type: EARS
  layer: 3
  architecture_approaches: [ai-agent-based, traditional-8layer]  # 必须为数组格式
  priority: shared
  development_status: active

When to Use This Skill

何时使用本技能

Use 
doc-ears
when:
  • Have completed BRD (Layer 1) and PRD (Layer 2)
  • Need to formalize requirements with precise behavioral statements
  • Translating product features into formal requirements
  • Establishing event-driven, state-driven, or conditional requirements
  • You are at Layer 3 of the SDD workflow
在以下场景使用
doc-ears
：
  • 已完成BRD（第1层）和PRD（第2层）
  • 需要用精确的行为语句正式化需求
  • 将产品特性转化为正式需求
  • 建立事件驱动、状态驱动或条件型需求
  • 处于SDD工作流的第3层

Document Structure (MANDATORY)

文档结构（强制要求）

Per EARS-TEMPLATE.md, EARS documents require these sections:
SectionContent
Document ControlStatus, Version, Date, BDD-Ready Score, Source Document
1. Purpose and ContextDocument Purpose, Scope, Intended Audience
2. EARS in Development WorkflowLayer positioning diagram
3. RequirementsEvent-Driven, State-Driven, Unwanted Behavior, Ubiquitous
4. Quality AttributesPerformance, Security, Reliability (tabular format)
5. TraceabilityUpstream Sources, Downstream Artifacts, Tags, Thresholds
6. ReferencesInternal Documentation, External Standards
根据EARS-TEMPLATE.md，EARS文档必须包含以下章节：
章节内容
文档控制状态、版本、日期、BDD就绪度得分、源文档
1. 目的与背景文档目的、范围、目标受众
2. EARS在开发工作流中的定位层级定位图
3. 需求事件驱动型、状态驱动型、异常行为型、通用型
4. 质量属性性能、安全、可靠性（表格格式）
5. 可追溯性上游来源、下游工件、标签、阈值
6. 参考资料内部文档、外部标准

Document Control Requirements

文档控制要求

Required Fields (6 mandatory):
  • Status: Draft/In Review/Approved/Implemented
  • Version: Semantic versioning (e.g., 1.0.0)
  • Date Created/Last Updated: YYYY-MM-DD
  • Priority: High/Medium/Low
  • Source Document: Single 
    @prd: PRD.NN.EE.SS
    value (NO ranges, NO multiple @prd values)
  • BDD-Ready Score: Format 
    XX% (Target: ≥90%)
Source Document Rule (E044):
markdown
undefined
必填字段（6项强制）：
  • 状态：草稿/评审中/已批准/已实现
  • 版本：语义化版本（例如：1.0.0）
  • 创建日期/最后更新日期：YYYY-MM-DD
  • 优先级：高/中/低
  • 源文档：单个
    @prd: PRD.NN.EE.SS
    值（不允许范围，不允许多个@prd值）
  • BDD就绪度得分：格式为
    XX% (目标: ≥90%)
源文档规则（E044）：
markdown
undefined

VALID - Single @prd reference

有效 - 单个@prd引用

| Source Document | @prd: PRD.01.07.01 |
| 源文档 | @prd: PRD.01.07.01 |

INVALID - Range or multiple values

无效 - 范围或多个值

| Source Document | @prd: PRD.12.19.01 - @prd: PRD.12.19.57 |
undefined
| 源文档 | @prd: PRD.12.19.01 - @prd: PRD.12.19.57 |
undefined

EARS Syntax Patterns

EARS语法模式

1. Event-Driven Requirements

1. 事件驱动型需求

WHEN [triggering condition] THE [system] SHALL [response] WITHIN [constraint]
WHEN [trigger condition],
THE [system component] SHALL [action 1],
[action 2],
and [action 3]
WITHIN [timing constraint].
Example:
WHEN trade order received,
THE order management system SHALL validate order parameters
WITHIN 50 milliseconds (@threshold: PRD.035.timeout.order.validation).
WHEN [触发条件] THE [系统] SHALL [响应动作] WITHIN [约束条件]
WHEN [触发条件],
THE [系统组件] SHALL [动作1],
[动作2],
and [动作3]
WITHIN [时间约束].
示例:
WHEN 交易订单被接收,
THE 订单管理系统 SHALL 验证订单参数
WITHIN 50毫秒 (@threshold: PRD.035.timeout.order.validation).

2. State-Driven Requirements

2. 状态驱动型需求

WHILE [system state] THE [system] SHALL [behavior] WITHIN [constraint]
WHILE [state condition],
THE [system component] SHALL [continuous behavior]
WITHIN [operational context].
WHILE [系统状态] THE [系统] SHALL [行为] WITHIN [约束条件]
WHILE [状态条件],
THE [系统组件] SHALL [持续行为]
WITHIN [操作上下文].

3. Unwanted Behavior Requirements

3. 异常行为型需求

IF [error/problem] THE [system] SHALL [prevention/workaround] WITHIN [constraint]
IF [error condition],
THE [system component] SHALL [prevention/recovery action]
WITHIN [timing constraint].
IF [错误/问题] THE [系统] SHALL [预防/解决措施] WITHIN [约束条件]
IF [错误条件],
THE [系统组件] SHALL [预防/恢复动作]
WITHIN [时间约束].

4. Ubiquitous Requirements

4. 通用型需求

THE [system] SHALL [system-wide requirement] WITHIN [architectural boundary]
THE [system component] SHALL [universal behavior]
for [scope/context].
THE [系统] SHALL [全系统需求] WITHIN [架构边界]
THE [系统组件] SHALL [通用行为]
for [范围/上下文].

Code Block Formatting (MANDATORY)

代码块格式（强制要求）

Always use triple backticks for EARS statements:
markdown
undefined
EARS语句必须始终使用三重反引号包裹：
markdown
undefined

EARS.01.25.01: Requirement Name

EARS.01.25.01: 需求名称

WHEN [condition],
THE [component] SHALL [action]
WITHIN [constraint].
Traceability: @brd: BRD.01.01.01 | @prd: PRD.01.07.01
undefined
WHEN [条件],
THE [组件] SHALL [动作]
WITHIN [约束].
可追溯性: @brd: BRD.01.01.01 | @prd: PRD.01.07.01
undefined

Unified Element ID Format (MANDATORY)

统一元素ID格式（强制要求）

Pattern: 
EARS.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
(4 segments, dot-separated)
Element TypeCodeExample
EARS Statement25EARS.02.25.01
Category ID Ranges:
CategoryID RangeExample
Event-Driven001-099EARS.01.25.001
State-Driven101-199EARS.01.25.101
Unwanted Behavior201-299EARS.01.25.201
Ubiquitous401-499EARS.01.25.401
REMOVED PATTERNS - Do NOT use:
  • Category prefixes: 
    E-XXX
    , 
    S-XXX
    , 
    Event-XXX
    , 
    State-XXX
  • 3-segment format: 
    EARS.NN.EE
  • Dash-based: 
    EARS-NN-XXX
模式: 
EARS.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
（4个段，点分隔）
元素类型代码示例
EARS语句25EARS.02.25.01
类别ID范围:
类别ID范围示例
事件驱动型001-099EARS.01.25.001
状态驱动型101-199EARS.01.25.101
异常行为型201-299EARS.01.25.201
通用型401-499EARS.01.25.401
已弃用模式 - 请勿使用:
  • 类别前缀: 
    E-XXX
    , 
    S-XXX
    , 
    Event-XXX
    , 
    State-XXX
  • 3段格式: 
    EARS.NN.EE
  • 短横线分隔: 
    EARS-NN-XXX

BDD-Ready Scoring System

BDD就绪度评分系统

Purpose: Measures EARS maturity and readiness for BDD progression.
Format in Document Control:
markdown
| **BDD-Ready Score** | 95% (Target: ≥90%) |
目的: 衡量EARS文档的成熟度以及向BDD推进的就绪程度。
文档控制中的格式:
markdown
| **BDD就绪度得分** | 95% (目标: ≥90%) |

Status and BDD-Ready Score Mapping

状态与BDD就绪度得分映射

BDD-Ready ScoreRequired Status
≥90%Approved
70-89%In Review
<70%Draft
BDD就绪度得分要求的状态
≥90%已批准
70-89%评审中
<70%草稿

Scoring Criteria

评分标准

Requirements Clarity (40%):
  • EARS statements follow WHEN-THE-SHALL-WITHIN syntax: 20%
  • Each statement defines one testable concept (atomicity): 15%
  • All timing/constraint clauses are quantifiable: 5%
Testability (35%):
  • BDD translation possible for each statement: 15%
  • Observable verification methods defined: 10%
  • Edge cases and error conditions specified: 10%
Quality Attribute Completeness (15%):
  • Performance targets with percentiles: 5%
  • Security/compliance requirements complete: 5%
  • Reliability/scalability targets measurable: 5%
Strategic Alignment (10%):
  • Links to business objectives traceable: 5%
  • Implementation paths documented: 5%
Quality Gate: Score <90% blocks BDD artifact creation.
需求清晰度 (40%):
  • EARS语句遵循WHEN-THE-SHALL-WITHIN语法: 20%
  • 每条语句定义一个可测试的概念（原子性）: 15%
  • 所有时间/约束条款均可量化: 5%
可测试性 (35%):
  • 每条语句均可转化为BDD: 15%
  • 定义了可观察的验证方法: 10%
  • 指定了边缘情况和错误条件: 10%
质量属性完整性 (15%):
  • 带有百分位数的性能目标: 5%
  • 安全/合规需求完整: 5%
  • 可靠性/可扩展性目标可衡量: 5%
战略对齐度 (10%):
  • 可追溯到业务目标的关联: 5%
  • 记录了实现路径: 5%
质量闸门: 得分<90%将阻止BDD工件的创建。

Quality Attributes Section

质量属性章节

Use tabular format for quality attribute requirements:
质量属性需求请使用表格格式:

Performance Requirements

性能需求

QA IDRequirement StatementMetricTargetPriorityMeasurement Method
EARS.NN.02.01THE [component] SHALL complete [operation]Latencyp95 < NNmsHigh[method]
EARS.NN.02.02THE [component] SHALL process [workload]ThroughputNN/sMedium[method]
QA ID需求语句指标目标优先级测量方法
EARS.NN.02.01THE [组件] SHALL 完成[操作]延迟p95 < NNms高[方法]
EARS.NN.02.02THE [组件] SHALL 处理[工作负载]吞吐量NN/s中[方法]

Quality Attribute Categories

质量属性类别

CategoryKeywords for Detection
Performancelatency, throughput, response time, p95, p99
Reliabilityavailability, MTBF, MTTR, fault tolerance, recovery
Scalabilityconcurrent users, data volumes, horizontal scaling
Securityauthentication, authorization, encryption, RBAC
Observabilitylogging, monitoring, tracing, alerting, metrics
Maintainabilitycode coverage, deployment, CI/CD, documentation
类别检测关键词
性能延迟、吞吐量、响应时间、p95、p99
可靠性可用性、MTBF、MTTR、容错、恢复
可扩展性并发用户、数据量、水平扩展
安全认证、授权、加密、RBAC
可观测性日志、监控、追踪、告警、指标
可维护性代码覆盖率、部署、CI/CD、文档

Formal Language Rules

正式语言规则

Mandatory Keywords:
  • SHALL: Mandatory requirement (do this)
  • SHALL NOT: Prohibited requirement (never do this)
  • SHOULD: Recommended requirement (preferred but not mandatory)
  • MAY: Optional requirement (allowed but not required)
Avoid ambiguous terms: "fast", "efficient", "user-friendly" Use quantifiable metrics: "within 100ms", "with 99.9% uptime"
强制关键词:
  • SHALL: 强制需求（必须执行）
  • SHALL NOT: 禁止需求（绝不能执行）
  • SHOULD: 推荐需求（首选但非强制）
  • MAY: 可选需求（允许但非必须）
避免模糊术语: "快速"、"高效"、"用户友好" 使用可量化指标: "100毫秒内"、"99.9%可用时间"

Threshold References (Section 5.4)

阈值引用（第5.4节）

Purpose: EARS documents REFERENCE thresholds defined in PRD threshold registry. All quantitative values must use 
@threshold:
tags.
Threshold Naming Convention: 
@threshold: PRD.NN.category.subcategory.key
Example Usage:
WHEN [trigger condition],
THE [system component] SHALL [action]
WITHIN @threshold: PRD.035.timeout.request.sync.
Common Threshold Categories:
yaml
timing:
  - "@threshold: PRD.NN.timeout.request.sync"
  - "@threshold: PRD.NN.timeout.connection.default"

performance:
  - "@threshold: PRD.NN.perf.api.p95_latency"
  - "@threshold: PRD.NN.perf.batch.max_duration"

limits:
  - "@threshold: PRD.NN.limit.api.requests_per_second"

error:
  - "@threshold: PRD.NN.sla.error_rate.target"
目的: EARS文档引用PRD阈值注册表中定义的阈值。所有定量值必须使用
@threshold:
标签。
阈值命名规范: 
@threshold: PRD.NN.category.subcategory.key
示例用法:
WHEN [触发条件],
THE [系统组件] SHALL [动作]
WITHIN @threshold: PRD.035.timeout.request.sync.
常见阈值类别:
yaml
timing:
  - "@threshold: PRD.NN.timeout.request.sync"
  - "@threshold: PRD.NN.timeout.connection.default"

performance:
  - "@threshold: PRD.NN.perf.api.p95_latency"
  - "@threshold: PRD.NN.perf.batch.max_duration"

limits:
  - "@threshold: PRD.NN.limit.api.requests_per_second"

error:
  - "@threshold: PRD.NN.sla.error_rate.target"

Tag Format Convention

标签格式规范

NotationFormatArtifactsPurpose
DashTYPE-NNADR, SPEC, CTRTechnical artifacts - document references
DotTYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKSHierarchical artifacts - element references
标记法格式工件目的
短横线TYPE-NNADR, SPEC, CTR技术工件——文档引用
点TYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS分层工件——元素引用

Cumulative Tagging Requirements

累积标签要求

Layer 3 (EARS): Must include tags from Layers 1-2 (BRD, PRD)
Tag Count: 2 tags (@brd, @prd)
Format:
markdown
undefined
第3层（EARS）: 必须包含第1-2层（BRD、PRD）的标签
标签数量: 2个标签（@brd, @prd）
格式:
markdown
undefined

Traceability

可追溯性

Required Tags (Cumulative Tagging Hierarchy - Layer 3):
markdown
@brd: BRD.01.01.03, BRD.01.01.10
@prd: PRD.01.07.02, PRD.01.07.15
undefined
必填标签（累积标签层级——第3层）:
markdown
@brd: BRD.01.01.03, BRD.01.01.10
@prd: PRD.01.07.02, PRD.01.07.15
undefined

Traceability Tag Separators (E041)

可追溯性标签分隔符（E041）

Inline format - Use pipes:
markdown
**Traceability**: @brd: BRD.02.01.10 | @prd: PRD.02.01.01 | @threshold: PRD.035.key
List format - Also valid:
markdown
**Traceability**:
- @brd: BRD.02.01.10
- @prd: PRD.02.01.01
- @threshold: PRD.035.category.key
内联格式 - 使用竖线:
markdown
**可追溯性**: @brd: BRD.02.01.10 | @prd: PRD.02.01.01 | @threshold: PRD.035.key
列表格式 - 同样有效:
markdown
**可追溯性**:
- @brd: BRD.02.01.10
- @prd: PRD.02.01.01
- @threshold: PRD.035.category.key

Downstream Artifact References (E045)

下游工件引用（E045）

CRITICAL: Do NOT use numeric downstream references until artifacts exist.
markdown
undefined
关键: 在工件存在前，请勿使用数字格式的下游引用。
markdown
undefined

INVALID - Numeric references to non-existent artifacts

无效 - 引用不存在的工件的数字ID

Downstream: BDD-01, ADR-02, REQ-03
下游: BDD-01, ADR-02, REQ-03

VALID - Generic downstream names

有效 - 通用下游名称

Downstream: BDD, ADR, SYS, REQ, SPEC
undefined
下游: BDD, ADR, SYS, REQ, SPEC
undefined

File Size Limits and Splitting

文件大小限制与拆分规则

Limits:
  • Target: 300-500 lines per file
  • Maximum: 600 lines per file (absolute)
When to Split:
  • Document approaches 600 lines
  • Sections cover distinct capability areas
Splitting Process:
  1. Create 
    EARS-{NN}.0_index.md
    using 
    EARS-SECTION-0-TEMPLATE.md
  2. Create section files 
    EARS-{NN}.{S}_{slug}.md
    using 
    EARS-SECTION-TEMPLATE.md
  3. Maintain Prev/Next links
  4. Update traceability
限制:
  • 目标: 每个文件300-500行
  • 最大值: 每个文件600行（绝对限制）
何时拆分:
  • 文档接近600行
  • 章节涵盖不同的能力领域
拆分流程:
  1. 使用
    EARS-SECTION-0-TEMPLATE.md
    创建
    EARS-{NN}.0_index.md
  2. 使用
    EARS-SECTION-TEMPLATE.md
    创建章节文件
    EARS-{NN}.{S}_{slug}.md
  3. 维护上一页/下一页链接
  4. 更新可追溯性信息

Reserved ID Exemption

保留ID豁免规则

Pattern: 
EARS-00_*.md
Scope: Documents with reserved ID 
000
are FULLY EXEMPT from validation.
Document Types:
  • Index documents (
    EARS-00_index.md
    )
  • Traceability matrix templates (
    EARS-00_TRACEABILITY_MATRIX-TEMPLATE.md
    )
  • Glossaries, registries, checklists
模式: 
EARS-00_*.md
范围: 保留ID为
000
的文档完全豁免验证。
文档类型:
  • 索引文档（
    EARS-00_index.md
    ）
  • 可追溯性矩阵模板（
    EARS-00_TRACEABILITY_MATRIX-TEMPLATE.md
    ）
  • 术语表、注册表、检查表

Creation Process

创建流程

Step 1: Read Upstream Artifacts

步骤1: 阅读上游工件

Read and understand BRD and PRD that drive these formal requirements.
阅读并理解驱动本次正式需求创建的BRD和PRD。

Step 2: Reserve ID Number

步骤2: 预留ID编号

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

Step 3: Create EARS Folder and File

步骤3: 创建EARS文件夹与文件

Nested Folder Rule (MANDATORY): ALL EARS documents MUST be in nested folders regardless of size.
Folder structure:
  1. Create folder: 
    docs/03_EARS/EARS-NN_{slug}/
  2. Create EARS file(s) inside the folder
Monolithic EARS (for smaller documents ≤25KB):
docs/03_EARS/EARS-01_risk_limits/
  EARS-01_risk_limits.md
Sectioned EARS (for larger documents >25KB):
docs/03_EARS/EARS-01_risk_limits/
  EARS-01.0_index.md
  EARS-01.1_event_driven.md
  ...
CRITICAL: Even monolithic EARS MUST be in a nested folder. Never create 
docs/03_EARS/EARS-NN_{slug}.md
directly in the 
03_EARS/
directory.
嵌套文件夹规则（强制要求）: 所有EARS文档必须放在嵌套文件夹中，无论大小。
文件夹结构:
  1. 创建文件夹: 
    docs/03_EARS/EARS-NN_{slug}/
  2. 在该文件夹内创建EARS文件
单文件EARS（适用于≤25KB的小型文档）:
docs/03_EARS/EARS-01_risk_limits/
  EARS-01_risk_limits.md
分章节EARS（适用于>25KB的大型文档）:
docs/03_EARS/EARS-01_risk_limits/
  EARS-01.0_index.md
  EARS-01.1_event_driven.md
  ...
关键: 即使是单文件EARS也必须放在嵌套文件夹中。绝不要直接在
03_EARS/
目录下创建
docs/03_EARS/EARS-NN_{slug}.md
。

Step 4: Fill Document Control Section

步骤4: 填写文档控制章节

Complete all required metadata fields:
  • Status
  • Version
  • Dates
  • Priority
  • Source Document (single @prd: PRD.NN.EE.SS)
  • BDD-Ready Score
完成所有必填元数据字段:
  • 状态
  • 版本
  • 日期
  • 优先级
  • 源文档（单个@prd: PRD.NN.EE.SS）
  • BDD就绪度得分

Step 5: Categorize Requirements

步骤5: 对需求进行分类

Group requirements into 4 categories:
  1. Event-Driven (triggered by events)
  2. State-Driven (triggered by system state)
  3. Unwanted Behavior (preventive)
  4. Ubiquitous (always active)
将需求分为4个类别:
  1. 事件驱动型（由事件触发）
  2. 状态驱动型（由系统状态触发）
  3. 异常行为型（预防性）
  4. 通用型（始终生效）

Step 6: Write WHEN-THE-SHALL-WITHIN Statements

步骤6: 编写WHEN-THE-SHALL-WITHIN语句

For each requirement:
  • Use formal EARS syntax
  • Specify quantifiable constraints with @threshold tags
  • Use SHALL/SHOULD/MAY keywords correctly
  • Reference upstream PRD features
针对每个需求:
  • 使用正式的EARS语法
  • 使用@threshold标签指定可量化的约束
  • 正确使用SHALL/SHOULD/MAY关键词
  • 引用上游PRD特性

Step 7: Create Quality Attributes Section

步骤7: 创建质量属性章节

Use tabular format for Performance, Security, Reliability requirements.
使用表格格式编写性能、安全、可靠性需求。

Step 8: Add Cumulative Tags

步骤8: 添加累积标签

Include @brd and @prd tags (Layers 1-2) in Traceability section.
在可追溯性章节中包含@brd和@prd标签（第1-2层）。

Step 9: Add Threshold References

步骤9: 添加阈值引用

Document all thresholds used in section 5.4.
在第5.4节中记录所有使用的阈值。

Step 10: Create/Update Traceability Matrix

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

MANDATORY: Create or update 
docs/03_EARS/EARS-00_TRACEABILITY_MATRIX.md
强制要求: 创建或更新
docs/03_EARS/EARS-00_TRACEABILITY_MATRIX.md

Step 11: Validate EARS

步骤11: 验证EARS文档

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

EARS validation (must be in nested folder)

EARS验证（必须在嵌套文件夹中）

python scripts/validate_ears.py --path docs/03_EARS/EARS-01_{slug}/EARS-01_{slug}.md
python scripts/validate_ears.py --path docs/03_EARS/EARS-01_{slug}/EARS-01_{slug}.md

Cumulative tagging validation

累积标签验证

python ai_dev_flow/scripts/validate_tags_against_docs.py
--artifact EARS-01
--expected-layers brd,prd
--strict
undefined
python ai_dev_flow/scripts/validate_tags_against_docs.py
--artifact EARS-01
--expected-layers brd,prd
--strict
undefined

Step 12: Commit Changes

步骤12: 提交变更

Commit EARS file and traceability matrix together.
同时提交EARS文件和可追溯性矩阵。

Batch Creation Checkpoint Rules

批量创建检查点规则

Pre-Batch Verification

批量创建前验证

Before starting batch creation:
  1. Read 
    EARS_SCHEMA.yaml
    for current metadata requirements
  2. Verify tag standards: 
    ears
    (not 
    ears-requirements
    )
  3. Verify document_type: 
    ears
  4. Verify architecture format: 
    architecture_approaches: [value]
    (array)
开始批量创建前:
  1. 阅读
    EARS_SCHEMA.yaml
    了解当前元数据要求
  2. 验证标签标准: 使用
    ears
    （而非
    ears-requirements
    ）
  3. 验证document_type: 
    ears
  4. 验证架构格式: 
    architecture_approaches: [value]
    （数组）

Every 5-Document Checkpoint

每5个文档检查点

After creating every 5 EARS documents:
  1. Run validation: 
    python scripts/validate_ears.py --path docs/03_EARS/
  2. Check for tag consistency, document_type, Source Document format
  3. Fix any errors before continuing
每创建5个EARS文档后:
  1. 运行验证: 
    python scripts/validate_ears.py --path docs/03_EARS/
  2. 检查标签一致性、document_type、源文档格式
  3. 修复所有错误后再继续

End-of-Session Validation

会话结束验证

Before ending session:
  1. Run full validation: 
    python scripts/validate_ears.py
  2. Verify 0 errors
  3. Update EARS-00_index.md if document counts changed
结束会话前:
  1. 运行完整验证: 
    python scripts/validate_ears.py
  2. 确认0错误
  3. 若文档数量有变化，更新EARS-00_index.md

Validation

验证

Validation Error Codes Reference

验证错误代码参考

CodeDescriptionSeverity
E001YAML frontmatter invalidERROR
E002Required tags missing (ears, layer-3-artifact)ERROR
E003Forbidden tag patterns (ears-requirements, etc.)ERROR
E004Missing custom_fieldsERROR
E005document_type not 'ears'ERROR
E006artifact_type not 'EARS'ERROR
E007layer not 3ERROR
E008architecture_approaches not arrayERROR
E010Required sections missingERROR
E011Section numbering starts with 0ERROR
E013Document Control not in table formatERROR
E020Malformed table syntaxERROR
E030Requirement ID format invalidERROR
E040Source Document missing @prd: prefixERROR
E041Traceability tags missing pipe separatorsERROR
E042Duplicate requirement IDsERROR
E044Source Document has multiple @prd valuesERROR
E045Numeric downstream referencesERROR
代码描述严重程度
E001YAML前置元数据无效错误
E002缺失必填标签（ears, layer-3-artifact）错误
E003使用了禁用的标签模式（如ears-requirements）错误
E004缺失custom_fields错误
E005document_type不是'ears'错误
E006artifact_type不是'EARS'错误
E007layer不是3错误
E008architecture_approaches不是数组错误
E010缺失必填章节错误
E011章节编号从0开始错误
E013文档控制未使用表格格式错误
E020表格语法格式错误错误
E030需求ID格式无效错误
E040源文档缺失@prd:前缀错误
E041可追溯性标签缺失竖线分隔符错误
E042需求ID重复错误
E044源文档包含多个@prd值错误
E045使用了数字格式的下游引用错误

Manual Checklist

手动检查表

  • Document Control section uses table format
  • All required metadata fields completed
  • Source Document has single @prd: PRD.NN.EE.SS value
  • All statements use WHEN-THE-SHALL-WITHIN format
  • Requirements categorized (Event, State, Unwanted, Ubiquitous)
  • Element IDs use EARS.NN.25.SS format
  • SHALL/SHOULD/MAY keywords used correctly
  • Quantifiable constraints with @threshold tags
  • No ambiguous terms ("fast", "efficient")
  • Cumulative tags: @brd, @prd included
  • Traceability tags use pipe separators
  • No numeric downstream references
  • Quality Attributes in tabular format
  • Thresholds documented in section 5.4
  • File size <600 lines
  • 文档控制章节使用表格格式
  • 所有必填元数据字段已完成
  • 源文档为单个@prd: PRD.NN.EE.SS值
  • 所有语句使用WHEN-THE-SHALL-WITHIN格式
  • 需求已分类（事件驱动、状态驱动、异常行为、通用）
  • 元素ID使用EARS.NN.25.SS格式
  • 正确使用SHALL/SHOULD/MAY关键词
  • 带有@threshold标签的可量化约束
  • 无模糊术语（如"快速"、"高效"）
  • 包含累积标签@brd、@prd
  • 可追溯性标签使用竖线分隔符
  • 未使用数字格式的下游引用
  • 质量属性使用表格格式
  • 阈值已记录在第5.4节
  • 文件行数<600

Common Pitfalls

常见误区

MistakeCorrection
ears-requirements
tag		Use 
ears
document_type: engineering-requirements
Use 
document_type: ears
architecture_approach: value
Use 
architecture_approaches: [value]
#### Event-001: Title
Use 
#### EARS.01.25.01: Title
Source Document: PRD-NN
Use 
Source Document: @prd: PRD.NN.EE.SS
Multiple @prd in Source DocumentUse single @prd, list others in Upstream Sources
@brd: X @prd: Y
(no separators)		Use 
@brd: X | @prd: Y
Downstream: BDD-01, ADR-02
Use 
Downstream: BDD, ADR
Status: Approved
(with 50% score)		Use 
Status: Draft
## 0. Document Control
Use 
## Document Control
(no numbering)
错误修正方法
使用
ears-requirements
标签		使用
ears
使用
document_type: engineering-requirements
使用
document_type: ears
使用
architecture_approach: value
使用
architecture_approaches: [value]
使用
#### Event-001: 标题
使用
#### EARS.01.25.01: 标题
使用
源文档: PRD-NN
使用
源文档: @prd: PRD.NN.EE.SS
源文档包含多个@prd使用单个@prd，其余在"上游来源"中列出
使用
@brd: X @prd: Y
（无分隔符）		使用`@brd: X
使用
下游: BDD-01, ADR-02
使用
下游: BDD, ADR
得分50%时使用
状态: 已批准
使用
状态: 草稿
使用
## 0. 文档控制
使用
## 文档控制
（不要编号）

Post-Creation Validation (MANDATORY)

创建后验证（强制要求）

CRITICAL: Execute validation loop IMMEDIATELY after document creation.
关键: 文档创建后立即执行验证循环。

Automatic Validation Loop

自动验证循环

LOOP:
  1. Run: python scripts/validate_ears.py --path {doc_path}
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review
  5. IF clean: Mark VALIDATED, proceed
循环:
  1. 运行: python scripts/validate_ears.py --path {doc_path}
  2. 若错误已修复: 回到循环（重新验证）
  3. 若警告已修复: 回到循环（重新验证）
  4. 若存在无法修复的问题: 记录以便人工评审
  5. 若验证通过: 标记为已验证，继续后续操作

Quality Gate

质量闸门

Blocking: YES - Cannot proceed to BDD creation until validation passes with 0 errors.
阻塞: 是 - 验证未通过（0错误）前，无法推进到BDD创建阶段。

Next Skill

下一个技能

After creating EARS, use:
doc-bdd
 - Create BDD test scenarios (Layer 4)
The BDD will:
  • Reference this EARS as upstream source
  • Include 
    @brd
    , 
    @prd
    , 
    @ears
    tags (cumulative)
  • Use Gherkin Given-When-Then format
  • Validate EARS formal requirements with executable tests
创建EARS文档后，请使用:
doc-bdd
 - 创建BDD测试场景（第4层）
BDD将:
  • 引用本EARS文档作为上游来源
  • 包含
    @brd
    、
    @prd
    、
    @ears
    标签（累积）
  • 使用Gherkin Given-When-Then格式
  • 用可执行测试验证EARS正式需求

Related Resources

相关资源

  • Template: 
    ai_dev_flow/03_EARS/EARS-MVP-TEMPLATE.md
    (Template Version 3.0, primary authority)
  • Schema: 
    ai_dev_flow/03_EARS/EARS_SCHEMA.yaml
    (machine-readable validation)
  • Creation Rules: 
    ai_dev_flow/03_EARS/EARS_CREATION_RULES.md
  • Validation Rules: 
    ai_dev_flow/03_EARS/EARS_VALIDATION_RULES.md
  • Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  • ID Standards: 
    ai_dev_flow/ID_NAMING_STANDARDS.md
  • Threshold Naming: 
    ai_dev_flow/THRESHOLD_NAMING_RULES.md
Section Templates (for documents >300 lines):
  • Index template: 
    ai_dev_flow/03_EARS/EARS-SECTION-0-TEMPLATE.md
  • Content template: 
    ai_dev_flow/03_EARS/EARS-SECTION-TEMPLATE.md
  • 模板: 
    ai_dev_flow/03_EARS/EARS-MVP-TEMPLATE.md
    （模板版本3.0，首要权威依据）
  • Schema: 
    ai_dev_flow/03_EARS/EARS_SCHEMA.yaml
    （机器可读的验证规则）
  • 创建规则: 
    ai_dev_flow/03_EARS/EARS_CREATION_RULES.md
  • 验证规则: 
    ai_dev_flow/03_EARS/EARS_VALIDATION_RULES.md
  • 共享标准: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  • ID标准: 
    ai_dev_flow/ID_NAMING_STANDARDS.md
  • 阈值命名: 
    ai_dev_flow/THRESHOLD_NAMING_RULES.md
章节模板（适用于超过300行的文档）:
  • 索引模板: 
    ai_dev_flow/03_EARS/EARS-SECTION-0-TEMPLATE.md
  • 内容模板: 
    ai_dev_flow/03_EARS/EARS-SECTION-TEMPLATE.md

Quick Reference

快速参考

ItemValue
PurposeFormalize requirements with WHEN-THE-SHALL-WITHIN syntax
Layer3
Tags Required@brd, @prd (2 tags)
BDD-Ready Score≥90% required for "Approved" status
Element ID Format
EARS.NN.25.SS
(4-segment unified format)
Source DocumentSingle @prd: PRD.NN.EE.SS value
Downstream ReferencesGeneric names only (no numeric IDs)
File Size Limit600 lines maximum
Next Skilldoc-bdd
项目值
目的使用WHEN-THE-SHALL-WITHIN语法正式化需求
层级3
必填标签@brd, @prd（2个标签）
BDD就绪度得分"已批准"状态要求≥90%
元素ID格式
EARS.NN.25.SS
（4段统一格式）
源文档单个@prd: PRD.NN.EE.SS值
下游引用仅使用通用名称（无数字ID）
文件大小限制最多600行
下一个技能doc-bdd

Version History

版本历史

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