规范驱动开发 (SDD) — 引导模式
用户无需了解 SDD 流程。您来推动：在每一步中，您要弄清楚项目当前所处阶段，独立完成所有能做的事情，只询问您无法推断的内容，并在最后明确告知用户下一步会发生什么。
每个功能都按照 spec.md → design.md → tasks.md → 实现 → review.md 的流程推进。模板位于 ${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates/。每个复制模板的 shell 命令都以 T="${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates"; 开头（下面的代码片段使用 $T）。
循环（每次使用该技能时运行）
- 检测状态（参见 状态检测）。悄无声息地执行此操作 — 读取文件，不要询问用户当前处于哪个阶段。
- 吸收输入。 无论用户发送什么 — 一个
task.md路径、粘贴的文档、一句话、“继续”、“ok” — 都将其映射到当前步骤（参见 处理输入）。 - 自行完成该步骤的工作。 根据您已知的信息草拟文档：输入、
docs/PRODUCT.md、docs/PRINCIPLES.md、docs/ARCHITECTURE.md、docs/GLOSSARY.md以及代码本身。检查代码库，而不是询问代码能回答的问题（技术栈、命令、文件路径、现有模式）。按照写作风格编写每份文档，并在展示文档之前运行其自检。 - 仅询问差距（参见 提问）。永远不要询问您已经以合理信心草拟的内容 — 展示出来，让用户纠正。
- 以引导块结束（参见 引导块）。每条回复都必须以引导块结束，无一例外。
使用用户使用的语言与用户交谈。使用项目现有文档使用的语言编写文档（如果没有现有文档则使用英语，除非用户另有要求）。
状态检测
按以下顺序检查，停在第一个匹配项：
| # | 条件 | 当前步骤 |
|---|---|---|
| 1 | 不存在 docs/PRODUCT.md 或 docs/PRINCIPLES.md | Setup — 项目文档 |
| 2 | PRODUCT.md/PRINCIPLES.md 仍包含 [placeholder] 文本 | Setup — 完成填写 |
| 3 | 用户发送了新工作（文件、文本、想法），不是当前活跃功能 | Triage 新工作 |
| 4 | 活跃功能的 spec.md 包含 status: draft | Spec |
| 5 | spec.md 已批准，design.md 缺失或状态为 status: draft | Design |
| 6 | design.md 已批准，tasks.md 仍包含模板占位符 | Tasks（规划） |
| 7 | tasks.md 中有任何 T 不是 done | 实现 — 下一个 T |
| 8 | 所有 T 完成，review.md 状态为 status: pending | Review |
| 9 | review.md 已批准 / 批准附注 | Close — 写入 memory + 状态，然后提供下一个功能 |
活跃功能 = 在 docs/MEMORY.md → Current State → In progress 中命名的功能；如果该项为空，则是编号最高的 docs/specs/NNN-*/ 且其 review.md 尚未批准。如果多个功能处于开放状态且用户未指定，询问用户是哪一个（一个问题，列出它们）。
快速读取状态的方法：
ls docs/ docs/specs/ 2>/dev/null
grep -H '^status:' docs/specs/*/*.md 2>/dev/null
grep -H -- '- \*\*Status:\*\*' docs/specs/*/tasks.md 2>/dev/null
处理输入
- 一个
task.md（或任何 .md/.txt）的路径 — 完整读取。将其视为原始需求，而不是已经完成的tasks.md：提取问题、行为、示例、边界情况、约束、文件提示。然后进行分类。 - 粘贴的文本或一行想法 — 同上。
- "continue" / "próximo" / "ok" / "aprovado" / "pode seguir" — 如果当前文档正在等待批准，这表示批准：设置其
status并在同一条回复中移至下一步。否则，直接运行当前步骤。 - 纠正或回答 — 将其应用于当前文档，更新它所解决的任何
Q，重新检查差距，继续。 - 关于流程的问题 — 简要回答，然后以引导块恢复。
分类（新工作）
决定工作的大小并用一句话说明您的决定：
- 小 — 明显的、可逆的、涉及 ~1–3 个文件、没有设计选择（拼写错误、小错误、配置更改）。仅创建
tasks.md（在docs/specs/NNN-name/中），填写它，然后直接进入实现。除非用户要求，否则跳过 spec/design/review。 - 功能 — 任何需要定义行为或做出设计选择的工作。运行完整流程。
- 需要调研 — 一个关键选择确实未知（库、方法、供应商）。完整流程加上 design 之前的
research.md。
当在小和功能之间犹豫时，选择功能，并说明用户可以要求快捷方式。
然后创建文件夹：
- 下一个编号 =
docs/specs/中最高的NNN-+ 1（从001开始）。名称 = 根据输入生成的短横线命名；不要询问。 - 复制模板：
D=docs/specs/NNN-feature-name; mkdir -p "$D"
cp $T/specs/spec.md $T/specs/design.md $T/specs/tasks.md $T/specs/review.md "$D"/
# 仅在需要调研时：
cp $T/specs/research.md "$D"/
- 将从输入中提取的所有内容立即放入正确的文档：问题/验收条件/约束/非范围 →
spec.md；实现提示和文件路径 → 保留作为design.md/tasks.md的注释（不要丢失它们；一旦到达相关部分就添加到其中）。 - 更新
docs/MEMORY.md→ Current State → In progress，包含功能 ID 和步骤。 - 在同一条回复中直接继续进入 Spec 步骤。
步骤
Setup
mkdir -p docs/decisions docs/specs
for f in PRODUCT PRINCIPLES ARCHITECTURE GLOSSARY MEMORY; do [ -f docs/$f.md ] || cp $T/$f.md docs/$f.md; done
[ -f docs/decisions/0000-template.md ] || cp $T/decisions/0000-template.md docs/decisions/
[ -f CLAUDE.md ] || cp $T/CLAUDE.md CLAUDE.md
永远不要覆盖现有文件。然后在询问任何问题之前从仓库预填信息：读取 package.json / pyproject.toml / go.mod / Cargo.toml / Makefile / CI 文件 / README，以填充技术栈、命令、目录映射和组件。仅询问代码无法告知的内容：产品是什么以及为谁而建、目标、非目标、业务规则、团队规则。如果用户带着功能来，保持 setup 简短（PRODUCT + PRINCIPLES 要点），然后继续处理功能；ARCHITECTURE 和 GLOSSARY 可以在之后逐步完善。
Spec
根据输入填写 spec.md。每个验收条件（AC）必须是 Given/When/Then 格式，并且可以独立测试 — 自己将模糊的需求重写为验收条件并展示给用户。每个阻碍设计位置的未知项成为 Q [blocking]；次要未知项成为 Q [non-blocking]，附上您建议的答案。呈现一个简短摘要（问题、验收条件、非范围、未决问题）并请求批准。门控： 仅当没有未解决的 blocking 问题且用户已批准（或告知您可以继续而无需询问）时，design 才能开始 → 设置 status: approved。
Design
读取 docs/PRINCIPLES.md 和 docs/ARCHITECTURE.md，并检查相关的代码路径。自行草拟完整的 design.md；覆盖每个验收条件（说明哪个部分覆盖哪个）。将局部决策以 D 条目的形式做出并附上理由；仅将那些代价高昂难以撤销或属于偏好问题的决策提交给用户，每个决策都附上您的建议。影响整个项目的决策 → 在 docs/decisions/ 中提议一个 ADR。展示一个简短摘要并请求批准。门控： 与 spec 相同。
Tasks
根据 spec + design 填写 tasks.md：小的 T 按依赖顺序排列，每个 T 包含 Covers、Files 以及来自 PRINCIPLES.md → 命令的真实验证命令。每个验收条件至少由一个 T 覆盖；每个边界情况 E 都有一个测试。除非用户要求，否则没有批准门控 — 展示任务列表并移至实现。
实现
一次一个 T：设置为 in-progress，实现，运行其验证，设置为 done（或 blocked 并说明原因）。在每个 T 之后，用 2-3 行报告并继续下一个，除非某些内容失败、某个 T 与 PRINCIPLES.md 冲突、或者完成时需要非范围中的内容 — 然后停止并询问。保持 docs/MEMORY.md → In progress 指向当前 T。
Review
填写 review.md：实现报告、每个验收条件的结果和证据、运行完整的测试/lint/构建命令、应用 PRINCIPLES 审查清单、列出发现。对照写作风格检查功能文档。将每个违规记录为 minor 发现。呈现结论。如果用户同意，修复 blocker/major 发现，然后重新审查。
Close
将持久化的经验教训移至 docs/MEMORY.md，更新 Current State（Done += 此功能，In progress 清除），将能力添加到 PRODUCT.md → Capabilities，根据后续行动创建任何 ADR。然后提供下一个项目（来自 Next、来自审查的后续行动、或“发送下一个任务”）。
提问
- 每次最多问 3-5 个问题，最重要的优先。编号、简短。
- 每个问题都附有您建议的答案，这样用户可以回复“ok”/“1 ok, 2 não”而不是打字：
1. 过期链接是否应显示错误页面？→ 建议：是的，附带“重新发送”按钮。 - 当
AskUserQuestion工具可用且答案在少数几个选项之间选择时，使用该工具，将推荐选项放在首位。 - 永远不要询问代码、文档或输入已经回答的问题。永远不要询问用户下一步该做哪个 SDD 步骤 — 那是您的工作。
- 如果用户说“decide you”/“tanto faz”/“pode seguir”，采纳您的建议，记录下来（作为
Q → answer或D），然后继续。
引导块
每条回复都以这个块结束（使用用户的语言），这样用户永远无需考虑接下来要做什么：
---
📍 功能：NNN-feature-name · 步骤：Spec (2/6) [Setup · Spec · Design · Tasks · 实现 · Review]
✅ 已完成：<一行>
❓ 我需要您提供：<编号问题，或“无”>
➡️ 下一步：<用户回复后将发生什么 — 例如“回复 'ok' 批准 spec，我将编写 design”>
如果不需要用户提供任何东西，请说明并告诉用户“继续”后您将做什么。
引导块和聊天消息不需要完整的写作风格自检。保持简短直接。
文档规则
- 替换每个
[placeholder]、NNN和YYYY-MM-DD。空章节变为None.— 永远不要删除标题。 - 使用 ID（
AC、Q、D、T、E、F）在文档之间交叉引用，而不是复制文本。 - 在
design.md之前和实现任何任务之前读取docs/PRINCIPLES.md。 - 如果需求不明确，添加
Q并询问，而不是猜测。如果任务与PRINCIPLES.md冲突，停止并询问。 - 每个事实存在于一个文档中；其他文档指向它。
写作风格（每份文档）
下一个模型会读取这些文档并据此执行。编写时确保每个句子只有一个含义。这些规则适用于每种语言。
清晰与精确（受 ASD-STE100 启发）
- 每句一个想法。 指令最多使用 20 个词。描述最多使用 25 个词。
- 每句一个指令。 动作使用祈使句。写“返回
404。”不要写“系统应该可能返回 404。” - 主动语态，现在时。 指明行为者：用户、系统或其组件名称。
- 一个术语 = 一个含义。 使用来自
docs/GLOSSARY.md的精确术语。不要为同一概念使用同义词。当您使用新的领域术语时，将该术语添加到GLOSSARY.md。 - 需求关键词： 仅使用 必须 / 绝不 / 可以。不要使用“应该”、“理想情况下”、“尝试”、“如果可能”。
- 量化。 用数字、单位或可观察的结果替换每个模糊的词。不要在没有数字的情况下使用这些词：快速、缓慢、很多、很少、大、小、健壮、容易、简单、适当、用户友好、一些、“等”、“等等”。
- 错误：“页面加载很快。”正确：“页面在 2 秒（p95）内加载。”
- 没有习语、隐喻、笑话、填充词或营销语气。
- 没有不明确的代词。 如果“它”、“这”或“那”可以指代两个名词，重复该名词。
- 结构优于散文。 优先使用列表和表格。段落最多 3 个句子。
- 精确名称使用
code。 将标识符、路径、命令、字段和值写在反引号中。不要转述它们。
第一性原理
- 从事实开始。 习惯和类比不是理由。“其他项目做 X”不是理由。
- 为每个重要的声明打上标签：
- 事实 — 已验证。给出来源：文件路径、命令输出、数据或文档。
- 假设 — 未验证。说明如何验证。
- 决策 — 一个选择。给出理由，源于事实或约束。
- 追溯每个决策 到问题、
AC或约束。如果决策没有追溯，则移除它。 - 需求先于解决方案。 按以下顺序编写：问题 → 约束 → 满足它们的最简单解决方案。
- 首先选择最简单的选项。 选择满足所有验收条件的最简单选项。每个添加的组件、依赖项或步骤都需要有明确的理由。
自检（在展示文档之前运行）
- 没有
[placeholder]、NNN或YYYY-MM-DD残留。 - 没有规则 5 和 6 中的禁用词残留。
- 每个句子都在规则 1 的词数限制内。
- 每个领域术语都在
docs/GLOSSARY.md中。 - 每个
D和每个决策都有理由。 - 每个未经验证的声明都标记为假设并有验证方法。
参考
模板位于 $T = ${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates/：
PRODUCT.md、PRINCIPLES.md、ARCHITECTURE.md、GLOSSARY.md、MEMORY.md、CLAUDE.md— 项目级别，创建一次。decisions/0000-template.md— 每个项目级决策一个 ADR。specs/spec.md、design.md、tasks.md、review.md、research.md— 每个功能一套。