五要素范围规范

先解决什么问题

开发者常遇到一种场景：拿到一个 GitHub issue 或模糊的需求描述后，直接开始写代码。结果可能是实现方向跑偏、验收标准不明确，或者 PR 反复修改——根源在于作用范围没有被显式定义。五要素规范要解决的正是这个问题：在编码前用结构化模板把「做什么」和「不做什么」钉死，避免凭直觉猜测导致的返工。

核心原则很直接：如果无法用两句话说清「完成」长什么样，就还没准备好开始。这个规范通过五个要素强制划定边界：明确作用范围（解决什么问题）、可测试的验收标准（如何验证）、二元完成信号（done/not-done）、显式不做什么（防止范围蔓延）、已知边界（排除哪些情况）。

五要素规范如何工作

该规范的核心是一套轻量级规划模板，适用于需要超过 30 分钟的任务或会产生 PR 的工作。关键步骤包括：

• 从 issue 到规范：先阅读 issue 中的描述、评论和隐含需求，提取抱怨点、期望值和缺失信息。如果无法填满五要素模板，应先补充信息而非猜测。
• 创建可执行任务：将规范记录为任务或工单，把 success_criterion 作为一等字段。二元完成信号让自主执行成为可能，无需中途重新规划。
• 强制范围确认：通过「显式不做什么」列表防止范围蔓延，通过「已知边界」预判潜在问题。

适用边界与注意点

应该使用的情况：

• 未拆解为具体任务的 GitHub issue
• 验收标准不明确的功能开发
• 预计耗时超过 30 分钟的工作
• 会产生 PR 的代码变更

可以跳过的情况：

• 有明确复现路径且范围清晰的 bug 修复
• 机械性任务（改配置、重命名、升版本）
• 任务中已包含 success_criterion 字段

需要注意的反模式：

• 边做边定范围（正确做法是开工前明确边界）
• 只在 PR 里补验收标准（验收标准应在编码前确定）
• 忽略 issue 评论（线程中可能已讨论过边界条件）
• 试图实现 issue 中的所有内容（应选择最小可行切片）

五要素规范的价值在于将模糊需求转化为可验证的承诺，而不是愿望清单。它通过结构化思考减少主观判断，让开发者、审查者和自动化代理都能基于同一套标准协作。