用途:doc-ears 属于 SDD 流程第 3 层,将 BRD/PRD 需求形式化为精确、原子、可测试的 EARS(Easy Approach to Requirements Syntax)语句,使用 WHEN-THE-SHALL-WITHIN 语法,为 BDD 翻译做准备。上游为 PRD(第 2 层),下游依次为 BDD、ADR、SPEC、TDD、IPLAN、Code。每条语句须可测试(可推导 Given-When-Then)、可度量、可追溯(@prd)、原子(一个概念)。
主要能力:支持五种 EARS 模式——事件驱动(WHEN…THE…SHALL…WITHIN)、状态驱动(WHILE…)、可选(WHERE…)、异常(IF…)、全局(THE…SHALL…for…);多条件需求由这些模式组合而成。文档结构为 5 个编号章节加术语表:Document Control(状态、版本、日期、优先级、单一 @prd、BDD-Ready 评分、修订历史)、Purpose & Context、Requirements、Quality Attributes(表格)、Traceability。元素 ID 形如 EARS.{doc_id}.{section_id}.{hash},如 EARS.01.03.c4d8。量化语言要求用 SHALL/SHALL NOT/SHOULD/MAY,延迟用 p50/p95/p99 表示,非延迟边界用具体值加单位,可变值用 @threshold 标签。
使用方式:先阅读模板 EARS-TEMPLATE.yaml、层 README、ID 与标签标准、写作风格及上游 PRD;确认无 ID 冲突(ls docs/03_EARS/);预留下一个空闲 EARS-NN;在 docs/03_EARS/EARS-NN_{slug}/ 下创建嵌套文件夹,超过 25 KB 时按章节拆分;先写 Document Control,再完成其余章节与术语表;更新索引 docs/03_EARS/EARS-00_index.md 并一起提交。校验由本技能自身完成,无运行时代码,错误码包括 XDOC-006、XDOC-008、XDOC-009;质量门为 BDD-Ready 评分 ≥ 90/100。
适用场景:已有 PRD 且需要形式化需求、把产品功能转为精确行为语句、建立事件/状态/可选/异常/全局规则时使用。端到端生成可改用 doc-ears-autopilot。
限制:不计算 SHA-256,哈希由确定性工具生成;不得使用已移除的模式(Event-XXX、State-XXX、UB-XXX、REQ-XXX 等);EARS 元素不输出 @brd 标签;不得引用不存在的下游产物;仅遵循 .aidoc/profile.yaml 中本技能的配置项。具体收费、价格、平台等信息暂未提供。