mcpField
D
doc-ears

doc-ears

github.com/vladm3105开发1763 次安装1 天前更新
代码仓库

关于 doc-ears

用于 SDD 第 3 层的 EARS 需求编写技能，将 PRD 内容整理为原子化、可测试且可追溯的规范陈述。它规定五种需求模式、量化约束、文档结构和 BDD 就绪质量门槛。

主要功能

  1. 01编写五类 EARS 需求
  2. 02要求陈述原子化且可测试
  3. 03使用量化质量属性约束
  4. 04维护需求 ID 与 PRD 追溯
  5. 05验证文档结构和就绪评分

适用场景

  1. 01将 PRD 功能转成行为需求
  2. 02明确事件、状态和错误处理规则
  3. 03为需求设置可测量的性能目标
  4. 04为后续 BDD 场景准备需求

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-ears

安装后在 Claude Code 中输入/doc-ears确认已加载。

详细介绍

doc-ears

用途

创建 EARS（需求语法简易方法） 文档，即 SDD 流程的第 3 层。EARS 使用 WHEN-THE-SHALL-WITHIN 语法，将 BRD/PRD 需求形式化为精确、原子、可测试的陈述，为转换为 BDD 做好准备。

层级：第 3 层——形式化 Context（BRD）→ Container（PRD）过渡的细化步骤；自身不属于任何 C4 层级。 上游：PRD（第 2 层）。（根据必要上游契约，可通过 @ 标签链传递追溯到上游 BRD。） 下游：BDD → ADR → SPEC → TDD → IPLAN → Code。

每条 EARS 陈述都必须可测试（可推导出 Given-When-Then）、可衡量（约束可量化）、可追溯（@prd）且原子化（每条陈述只包含一个概念）。

使用时机

在以下情况下使用 doc-ears：

  • PRD（第 2 层）已存在，且你需要正式需求（上游 BRD 可通过 PRD 自身的 @brd 标签传递追溯到）。
  • 将产品功能转换为精确的行为陈述。
  • 确立事件驱动、状态驱动、可选/功能门控、错误处理或系统级规则。

若要从 PRD、提示词或 IPLAN 端到端生成文档，请使用 ../doc-ears-autopilot/SKILL.md。

前置条件

编写前，请阅读：

  1. 模板（事实依据）： ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-TEMPLATE.yaml
  2. 层级 README： ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/README.md
  3. ID 和标签规范： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  4. 编写风格： ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md
  5. 驱动此 EARS 的上游 PRD（以及通过 PRD 自身的 @brd 标签追溯到的源 BRD）。

确认没有 ID 冲突：ls docs/03_EARS/ 2>/dev/null。只引用确实存在的上游文档；绝不要编造 PRD-XXX 或 TBD 之类的占位符。

层级指南

必需结构（5 个编号章节 + 术语表附录）

document_control 是第 1 节（状态、版本、日期 YYYY-MM-DD、优先级、单个 @prd: 来源、BDD 就绪度评分、修订历史表）。 然后依次为：

  1. 目的与上下文 · 3. 需求（五种模式）· 4. 质量属性（表格）· 5. 可追溯性。

另需包含术语表附录章节（glossary: 模板键——必需，不编号）。章节编号和标识符以 EARS-TEMPLATE.yaml 自带的 # Section N: 编号为准——模板是事实依据。

各章节的内容和内嵌编写指南参见 EARS-TEMPLATE.yaml。

五种 EARS 模式（第 3 节）
模式语法用途
事件驱动WHEN [trigger], THE [component] SHALL [action] WITHIN [timing].用户/API/计时器事件
状态驱动WHILE [state], THE [component] SHALL [behavior] WITHIN [context].持续性/依赖模式的行为
可选WHERE [feature enabled], THE [component] SHALL [behavior].功能标志控制/配置门控的行为
非预期情况IF [error], THE [component] SHALL [recovery] WITHIN [timing].故障、边缘情况、回退方案
普遍性THE [component] SHALL [behavior] for [scope].全局不变量、日志记录、审计

真正包含多条件的需求会组合这些模式（例如 WHILE [state], WHEN [event], THE … SHALL …）——这是组合，而非第六种模式。 EARS 使用 THE … SHALL … 作为响应子句，绝不使用 THEN 连接词。

每项需求都必须是原子化的（只包含一个可测试的概念），并带有元素 ID 和逐项的 @prd: … 可追溯性行。适用时，使用模板中的边界值矩阵、状态转换（包含错误状态）和回退路径模式。

可量化语言（第 3 / 4 节）

正确使用 SHALL / SHALL NOT / SHOULD / MAY。将含糊的 延迟替换为百分位数：real-time → p50<100ms/p95<300ms/p99<1000ms；immediately → <500ms；fast/quickly → 精确延迟。第 4 节（质量属性： 性能、安全性、可靠性）采用表格形式，并设定可测量的目标： 延迟/响应时间使用 p50/p95/p99 表示法，而非延迟 边界（周期/迭代次数、事件窗口、批次大小、*.count）则 以具体值 + 单位量化（不适用百分位数）。将可变值作为 @threshold: PRD.NN.category.key 标签传递（标签中不使用 PRD 章节编号）。

元素 ID 和标签
  • 分层元素 ID：EARS.{doc_id}.{section_id}.{hash}（例如 EARS.01.03.c4d8；需求 = 第 03 节，质量属性 = 第 04 节）。为每个元素生成一个稳定的 4 位十六进制标识符，且在其所属章节内不重复（HASH01）；发生冲突时扩展为 8 位。不要在此提示词中计算 SHA-256——哈希形式是由确定性工具流程生成的规范化目标，字节精确字段提取仅针对 BRD §7 定义（EARS 将在第 2 阶段及后续阶段处理）。权威来源：framework/governance/ID_NAMING_STANDARDS.md。
  • EARS 属于第 3 层，因此必须带有必需的上游 @prd 标签（遵循必要上游契约）。文档控制中只能有一个 @prd:（额外标签放在各需求的标签中）；不使用范围。上游 BRD 的沿袭关系可通过 PRD 自身的 @brd 标签传递追溯——不要在 EARS 元素上输出 @brd:。
  • 已移除的模式（请勿使用）：Event-XXX、State-XXX、UB-XXX、 REQ-XXX；旧式三段式 EARS.NN.xxxx；数字类型代码 EARS.NN.25.SS； 短横线形式 EARS-NN-XXX。

创建流程

  1. 阅读上游文档——驱动这些需求的 PRD（以及通过其 @brd 标签关联的源 BRD）。
  2. 预留 ID——下一个可用的 EARS-NN（两位数字：EARS-01、EARS-99、 EARS-102）。 按层独立（CLEANUP-PR-F 第 18 项）： 在你所属层的索引中选择下一个可用编号——上游编号不是你的编号 （文档编号按层顺序递增且彼此独立；参见 framework/governance/ID_NAMING_STANDARDS.md §Cross-layer cardinality）。
  3. 创建嵌套文件夹——每份 EARS 文档都必须放在 docs/03_EARS/EARS-NN_{slug}/ 中，不受文档大小影响。单文件形式： 在其中创建 EARS-NN_{slug}.md；按章节拆分（>25 KB）：创建 EARS-NN.S_{section}.md
    • 索引模板：${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-00_index.TEMPLATE.md。
  4. 先完成文档控制（第 1 节），然后根据模板完成 §2–§5 及末尾的术语表。
  5. 按五种模式对需求进行分类；编写原子化的 THE … SHALL … 陈述（适用时注明 WITHIN 时限），并添加 @threshold: 约束。
  6. 填写质量属性（表格形式；延迟 → 百分位数，非延迟边界 → 值 + 单位）和可追溯性 （遵循必要上游契约添加 @prd）。
  7. 在同一次变更中更新 EARS 索引 docs/03_EARS/EARS-00_index.md。
  8. 验证（见下文），并一并提交 EARS 文档和索引。

验证

此技能就是验证器（不含运行时代码）。请针对 ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/README.md 和 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md 执行验证。

  • Document Control 是第一个部分。
  • 5 个部分均存在且内容非空。
  • 每条陈述均使用 WHEN-THE-SHALL-WITHIN 语法；SHALL/SHOULD/MAY 使用正确。
  • 需求已分类（Event、State、Optional、Unwanted、Ubiquitous）且为原子项。
  • 元素 ID 符合 EARS.NN.SS.xxxx；不含已移除的模式。
  • 存在必需的上游标签：@prd（根据必要上游契约）；不含范围。
  • Document Control 中只有一个 @prd:；约束可量化（不含“快”等模糊表述）。
  • 不含对尚不存在的工件的数字下游引用。
  • 已创建或更新可追溯性矩阵 / 索引；没有失效链接。

错误代码（严重级别均为 error）：XDOC-006 标签格式无效 · XDOC-008 内部链接失效 · XDOC-009 缺少可追溯性部分。

**质量门禁（阻断性）：**继续之前，BDD-Ready 评分必须 ≥ 90/100。如果发现问题，请修复并重新检查；如果无法修复，请记录下来以供人工审核。

下一项技能

../doc-bdd/SKILL.md — BDD 会引用此 EARS（@ears: EARS.NN.SS.xxxx），并将每条陈述转换为可执行的 Given-When-Then 场景。（BDD 所需的上游仅为 @ears；更上游的溯源信息可通过 @-标签链传递获取。）

适配

读取 .aidoc/profile.yaml；仅遵循此技能的可调项 （section_toggles、glossary）。忽略未知键；如果没有配置文件，则使用 框架默认值。权威来源： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

相关资源

  • 模板 / 编写规则：${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-TEMPLATE.yaml
  • 层级 README：${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/README.md
  • 索引模板：${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-00_index.TEMPLATE.md
  • ID 与标签标准：${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  • 质量门禁：../doc-ears-audit/SKILL.md · 修复：../doc-ears-fixer/SKILL.md
  • 生成流水线：../doc-ears-autopilot/SKILL.md
  • 图表（状态 / 时序）：../charts-flow/SKILL.md

快速参考

目的使用 WHEN-THE-SHALL-WITHIN 语法将需求形式化
层级3（细化；无 C4 层级）
上游标签@prd（根据必要上游契约）
关键规则每条陈述均应原子化、可测试且可量化
必须包含Document Control（置于首位）、五种模式、5 个部分
质量门禁BDD-Ready ≥ 90/100
下一步doc-bdd

评论

支持 Markdown