sdd-define

SDD Define

首次响应此技能时，仅在开头写下这一行： sdd-define v1.2.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

快速开始

将 BRAINSTORM_*.md 文件转换为清晰、可测试且满足下一道关卡要求的 DEFINE_{FEATURE_NAME}.md。

1. 接收并阅读 Brainstorm Markdown 文件。
2. 仅提取 Brainstorm 所支持的事实、决策、初步需求、限制和依赖。
3. 必须使用 assets/DEFINE_TEMPLATE.md 填写草稿。
4. 标记歧义，不要猜测。
5. 计算初始 Clarity Score。
6. 仅针对妨碍清晰度、可衡量性、测试或 Verify Gate 的信息缺口，向用户提出澄清问题。
7. 使用 references/EARS.md 以 EARS 格式编写 Acceptance Tests。
8. 执行 references/CLARIFY.md 中的歧义扫描。
9. 根据 references/VERIFY_GATE.md 推导 Verify Gate。
10. 只有满足此 Skill 的质量关卡后，才能将 DEFINE 视为已准备就绪。
11. 将最终文档保存或交付为 DEFINE_{FEATURE_NAME}.md。
12. 文档必须以且仅以一个下一步结束：执行 **SDD Design by RDD**。

完整流程和交互规则请参阅 references/define-protocol.md。

何时使用 / 何时不使用

适用于：

• 已有 SDD Brainstorm by RDD 生成的 Markdown 文件；
• 用户希望将 Brainstorm 转换为正式且可验证的需求；
• 在进入 Design 前仍需进行针对性的澄清；
• 需要正式定义成功标准、验收测试、范围和 Verify Gate。

应用是否处理资金、税务或个人数据？在此 DEFINE 之后、Design 之前，运行配套 Skill sdd-governanca：它会推荐尚缺少的治理要求，是否采纳各项建议由你决定。

不适用于：

• 用户仍在探索问题、目标受众或解决方案方向；此时应先运行 SDD Brainstorm by RDD；
• 目标是设计架构、组件或详细实现；
• 目标是编写代码、执行构建或发布；
• 没有 Brainstorm，也没有足够的信息来还原其用途，且不凭空编造需求。

所需数据

必需

• Brainstorm Markdown 文件。

优先接受符合以下命名模式的文件： BRAINSTORM_{FEATURE_NAME}.md

如果文件不存在或无法读取，请先要求用户提供文件，再编写 DEFINE。

可选

• 用户对澄清问题的回答；
• Brainstorm 中已提及的示例；
• 用户提供的文档或技术背景；
• 项目的实际测试、smoke、eval 或 typecheck 命令；
• 部署、基础设施或技术领域的约定。

不要要求联网。不要假定能够访问代码仓库、文件系统、CI、数据库、API 或项目命令。

如何与学员沟通

首次回复前，阅读 references/como-falar.md：其中包含此技能的术语表和一个完整示例。 使用此技能的人通常从未用过 git 或终端。

阶段	面向学员的名称	此技能中的步骤
1	阅读头脑风暴文档	1 和 2
2	需求	3 和 4
3	验收测试	5 和 6
4	问题	7 和 8（每次回复一个主要问题）
5	验证关卡	9
6	保存	10 到 13

每次回复都按以下顺序排列（没有内容的部分跳过）：状态（Define: ✅ 1 … · ▶️ 2 … · ⬜ 3 …； ✅ 表示已完成，不只是访问过；⏸️ 表示暂停；➖ 表示跳过；返回某个阶段时，在“现在”中说明原因）· 已完成的事项（简短句子，不包含命令输出；记录学员的选择）· 现在：阶段 N — 名称（2 到 4 句话；在运行耗时操作前，说明将运行什么，以及无需回复）· 你的决定（授权：用粗体提问 + 说明每个选项的影响； 开放式问题：用粗体提问 + 说明如何作答，并提供“不知道”这个选项；分组并编号）· 下一步（一行）。

• 每次回复只处理一个阶段；以待作出的决定结束，然后暂停。
• 技术术语首次出现时必须附带解释——包括状态中的术语（参见参考文档中的术语表）。
• 命令输出绝不能原样照搬：说明数量、内容和令人担忧之处；名称最多列出 10 个，之后写“以及另外 N 个”。只有学员需要运行命令时才提供命令；每个编号步骤只提供一条命令，并说明屏幕上预期显示什么。
• 不要提及或概括此技能的说明（例如“按照第 N 步”）；说明这样做对学员有什么帮助。
• 如果回复与选项不匹配 ⇒ 解答疑问并重复列出选项。
• 暂停时：状态标为 ⏸️，用一句话说明原因和操作发生的位置，列出带预期结果的编号步骤，说明尚未完成的事项；如果学员需要操作，写“完成后，请再次告诉我——我会从这里继续。”

分步流程

1. 阅读并分类头脑风暴文档

提问之前，先通读整份文档。

提取：

• 原始输入 / 初始想法；
• 问题；
• 用户和受益者；
• 选定的方法；
• 关键决策；
• 建议的需求；
• 成功标准；
• YAGNI / 已移除或推迟的事项；
• 限制；
• 依赖项；
• 样本和 ground truth；
• 已完成的验证；
• TBD、局限和待解决的问题。

将头脑风暴文档中已验证的决策视为预先验证过的上下文。没有具体理由时，不要重新提出探索阶段的问题。

2. 基于资源创建草稿

使用 assets/DEFINE_TEMPLATE.md 作为最终文档的唯一结构依据。

不要凭记忆重建其他模板。

只填写以下内容：

• 头脑风暴文档中明确包含的内容；
• 用户在此阶段给出的回答；
• 必要时不可避免且尚未验证的技术推断，并明确标注为假设。

如果无法确定某项必填信息，标记其含糊之处并提问；绝不能为了让文档看起来完整而编造值。

3. 组织需求

将内容整理为：

• 问题陈述；
• 目标用户；
• 按 MUST / SHOULD / COULD 优先级排列的目标；
• 可衡量的成功标准；
• 验收测试；
• 范围外事项；
• 限制；
• 技术背景；
• 假设。

避免重复。如果头脑风暴文档与之后的回答冲突，以用户较新的回答为准，并在 Clarifications 中记录变更。

4. 编写可衡量的成功标准

凡是代表质量、数量、时间、成本、可用性、准确度或比率的成功标准，都必须包含可观察的目标值。

不要使用以下含糊的形容词：

• 快；
• 可扩展；
• 可靠；
• 简单；
• 大量；
• 高精度。

只有当数字有头脑风暴文档作为依据，或已由用户确认时，才将其转化为指标。

如果缺少数字，就提问。不要编造。

5. 使用 EARS 编写验收测试

阅读 references/EARS.md。

每个验收测试：

• 必须描述可观察的行为；
• 必须采用公认的 EARS 模式；
• 必须保留 EARS 锚定词的英文形式：When、While、If、then、Where、shall；
• 必须只包含一个主要行为。

如果存在合理的非预期触发条件，至少添加一项 If ... then ... shall ... 测试。

对于 Bug 修复，至少添加一项使用 shall continue to 的防止回归要求。

只要存在含糊或不可测试的验收测试，就不要结束。

6. 计算清晰度评分

为以下各项打 0 到 3 分：

• 问题；
• 用户；
• 目标；
• 成功标准；
• 范围。

评分标准：

• 0 = 缺失；
• 1 = 含糊或不完整；
• 2 = 清楚，但缺少细节；
• 3 = 清晰明确且可执行。

总分最高为 15 分。

将 DEFINE 标记为就绪的最低分数为 12/15。

不得为了通过门槛而虚增分数。

7. 澄清，不要猜测

阅读 references/CLARIFY.md。

检查以下九个类别：

1. 范围；
2. 数据模型；
3. UX 流程；
4. NFR；
5. 集成；
6. 边界情况；
7. 约束；
8. 术语；
9. 完成信号。

将每个类别标记为 Clear、Partial 或 Missing。

对于影响 DEFINE 的 Partial 和 Missing 项，在内部拟定一个客观问题。

每次交互优先提出 一个主要问题。如果上下文需要合并提问，同一轮最多提出 5 个问题。

存在明确选项时：

• 使用多项选择；
• 提供 2–4 个选项；
• 将推荐选项放在首位；
• 必要时允许开放式回答。

收到每条答复后：

• 在 DEFINE 正文中消除歧义；
• 在 ## Clarifications 中记录决定；
• 重新计算受影响部分的清晰度评分。

8. 检测 LLM Prompts 的使用情况

将 LLM Prompts 设为 true 或 false。

出现运行时提示词的强烈信号或足够多的弱信号时，标记为 true，例如：

• 明确指定了 LLM 提供商或模型；
• system prompt、user prompt、RAG、embeddings、classifier、synthesizer；
• 使用 LLM 的 chatbot、agent、自动回复或报告生成器；
• 专门用于提示词的路径或组件。

没有相关信号时，标记为 false。

如果只有一个孤立的弱信号，且意图不明确，则询问用户。

在 Notes 中记录理由。

9. 定义 Verify Gate

阅读 references/VERIFY_GATE.md。

DEFINE 必须且只能包含一个 verify_gate 代码块，其中包含：

• kind；
• cmd；
• pass_when；
• threshold；
• manual_fallback。

可接受的 kind：

• test；
• smoke；
• eval；
• typecheck；
• manual-ux。

根据验收测试的性质推导类型。

学生首次使用时，只问一个问题——“是否有一个成功时会返回 0 的命令？”。有 → 使用该命令作为 test；没有 → 使用 manual-ux，并写 3 至 5 句“我打开了……并看到了……”（格式见 VERIFY_GATE.md；示例见 assets/DEFINE_EXEMPLO.md）。

不要编造项目命令。

如果无法根据所提供的材料可靠推断实际命令：

• 询问用于验证该行为的命令；或
• 请用户从合理的 gate 选项中选择；
• 当验收确实需要人工判断或视觉检查，或询问后学生表示没有命令时，使用 manual-ux——绝不能把它当作无需提问的捷径。

没有有效的 Verify Gate，DEFINE 就尚未就绪。

10. 解决开放问题

## Open Questions 不应掩盖阻塞性歧义。

结束前：

• 解决所有影响范围、行为、成功标准、验收测试或 Verify Gate 的问题；
• 仅保留真正不会阻碍 Design 的问题；
• 如果没有问题，写 None - ready for Design.

11. 验证文档

在有文件系统且可用 Python 时运行：

python scripts/validate_define.py <caminho-do-DEFINE.md>

将脚本输出作为结构性 lint 结果。该脚本不能替代语义判断。

在声明文档已准备就绪之前，修复所有问题。

12. 生成并保存 DEFINE

首选名称： DEFINE_{FEATURE_NAME}.md

保存位置。 将文件保存到项目根目录下的 sdd/ ——这是一个可见目录，在任何 Agent 中都相同。如果项目已有 .claude/sdd/，则继续使用该目录。五个阶段的文档放在同一目录下，不创建子目录。

如果文件系统可写，则保存为 sdd/DEFINE_{FEATURE_NAME}.md（如果该目录已存在，则保存为 .claude/sdd/DEFINE_{FEATURE_NAME}.md）。

如果没有文件系统，则在平台支持时，将完整的 Markdown 作为 .md 文件提供下载。

如果存在以下任一情况，不要声明 Ready for Design：

• Clarity Score < 12/15；
• 存在阻塞性歧义；
• Acceptance Tests 未通过 EARS 规则；
• 相关的 Success Criteria 不可衡量；
• Verify Gate 缺失或不完整。

13. 以标准交接内容结束

文档的最后一节必须完全如下：

## Next Step

Execute o **SDD Design by RDD**.

此文本之后不得添加斜杠命令、路径、上传说明、对 GPT/Skill 的引用或并行操作。

验证与质量检查清单

在认为 DEFINE 已完成之前：

• 已完整阅读 Brainstorm。
• 已保留 Brainstorm 中经过预先验证的决策。
• 文档使用 assets/DEFINE_TEMPLATE.md。
• Problem Statement 具体明确。
• 至少有一个 Target User，并描述其 pain point。
• Goals 已排序。
• 相关的 Success Criteria 可衡量。
• Acceptance Tests 使用 EARS。
• 对可能出现的不期望触发条件，存在 If/Then 测试。
• 如适用，Bugfix 包含 shall continue to。
• 已检查全部九类澄清事项。
• 不存在尚未解决的阻塞性歧义。
• Clarity Score >= 12/15。
• Out of Scope 已明确说明。
• Constraints 与 assumptions 分开列出。
• Technical Context 中包含 LLM Prompts: true 或 false，并说明理由。
• 存在且仅存在一个有效的 Verify Gate。
• Verify Gate 不包含虚构的命令。
• Open Questions 中不包含阻塞性问题。
• 如可执行，scripts/validate_define.py lint 检查通过。
• 最终文件名为 DEFINE_{FEATURE_NAME}.md。
• Next Step 仅包含 Execute o **SDD Design by RDD**.

异常处理

• 缺少 Brainstorm： 请求提供 Markdown 文件；不要悄悄重建 Brainstorm。
• Brainstorm 不完整： 提取已有内容，仅针对必要的差距进行澄清。
• Brainstorm 存在矛盾： 在正式确定需求之前，询问以哪项决策为准。
• 用户更改 Brainstorm 中的决策： 采用最新决策，更新依赖该决策的章节，并在 Clarifications 中记录。
• Clarity Score < 12： 继续澄清；不要标记为已准备就绪。
• 指标没有具体数值： 询问目标值；不要编造数值。
• Verify Gate 命令未知： 询问；不要编造项目命令。
• 无法访问代码/仓库： 不要声称已检查路径、测试或基础设施。
• 用户希望带着阻塞性待办结束： 仅生成状态为 Needs Clarification 的草稿，不提供最终交接内容。
• 功能没有界面： 如果范围支持，可将 UX flow 设为 N/A；不要人为创建 UI。
• 纯 UX 功能： 允许使用 manual-ux，并提供客观的人工作业清单。

示例

预期输入

文件： BRAINSTORM_CONCILIACAO_BANCARIA.md

该 Skill 必须：

1. 提取问题、用户、选定的方法、YAGNI 和建议的需求；
2. 编写 DEFINE 草稿；
3. 识别缺失信息，例如指标、差异处理方式、支持的格式和可验证的门槛；
4. 只询问必要的问题；
5. 生成 DEFINE_CONCILIACAO_BANCARIA.md。

澄清问题

如果 Brainstorm 只写了“处理必须快速”，不要擅自将其转换成某个数字。

例如，可以询问： 处理一对银行对账单和分类账的最长可接受时间是多少：（a）不超过 30s［推荐］，（b）不超过 60s，（c）不超过 2 min，（d）其他？

最终交接

## Next Step

Execute o **SDD Design by RDD**.

---

SDD Open by RDD 的一部分 — https://github.com/robertodiasduarte/sdd-open