第21部分。结论与工作系统

SDD 不是为了文件而存在的文件集合。它是一个工作系统，帮助人类在代理能够在几分钟内改变过去需要数小时完成的事情时保持控制。关键技能不是编写尽可能长的提示，而是在意图、规划、实现和验证之间建立正确的边界。

如果只留下一个公式，它是这样的：

规范保存长期意图。
事实决定是否可以合并分支。
代理快速执行。
人类负责判断。

或者更简短：

规范引导。
事实允许合并。

仓库的最终结构

agentclinic/
  AGENTS.md
  QWEN.md
  README.md
  CHANGELOG.md
  package.json
  tsconfig.json
  .qwen/
    settings.json
    hooks/
      pre_tool_guard.py
      log_tool_result.py
      inject_sdd_context.py
    memory/
      agent-memory.db
    skills/
      feature-spec/
        SKILL.md
      changelog/
        SKILL.md
  specs/
    mission.md
    tech-stack.md
    roadmap.md
    2026-05-01-hello-hono/
      requirements.md
      plan.md
      validation.md
    2026-05-02-agents-ailments/
      requirements.md

plan.md
      validation.md
  src/
  tests/
.github/
  pull_request_template.md

操作循环

每个功能之前：

git checkout main
git pull --ff-only
git status --short
npm test
npm run typecheck

在 Qwen Code 中：

/clear
使用 feature-spec 技能来开始路线图中的下一个功能。
不要实现代码。

规范之后：

git add specs/YYYY-MM-DD-feature-name
git commit -m "Add <feature> spec"

实现：

/clear
阅读 @QWEN.md、@specs/mission.md、@specs/tech-stack.md
和 @specs/YYYY-MM-DD-feature-name/plan.md。
只实现任务组 1。
在报告更改的文件和验证命令后停止。

验证：

/clear
将实现与 @specs/YYYY-MM-DD-feature-name/validation.md 进行比较。
列出已确认的事实、失败的事实、缺失的事实
和模糊的验证项。
不要更改文件。

合并：

使用 changelog 技能为此分支更新 @CHANGELOG.md。

npm test
npm run typecheck
git checkout main
git merge <feature-branch>
git branch -d <feature-branch>

重新规划：

/clear

检查 @specs/mission.md、@specs/tech-stack.md、@specs/roadmap.md、
最近的功能规范和 @CHANGELOG.md。
在下一个功能之前需要更新什么？
在我批准之前不要更改文件。

决策边界

记录在 mission.md 中：

• 受众；
• 产品意义；
• 语气；
• 成功定义。

记录在 tech-stack.md 中：

• 语言；
• 运行时环境；
• 框架；
• 数据库；
• 测试；
• 部署限制；
• 禁止或推迟的技术。

记录在 roadmap.md 中：

• 阶段顺序；
• 阶段状态；
• 小的可交付成果；
• 什么被认为是下一步。

记录在功能规范中：

• 边界以及边界之外的内容；
• 此功能的具体决策；
• 任务组；
• validation.md 中的事实集；
• 带有预期结果的验证命令；
• 事实状态：草稿、必需、已实现、推迟；
• 手动检查。

记录在 QWEN.md 或 AGENTS.md 中：

• 代理行为规则；
• 验证命令；
• 禁止投机性重构；
• 要求先写规范，再写代码。

最常见的错误

1. 第一个功能太大。从基础设施模板开始，而不是从 MVP 开始。

1. 规范已写，但未在实现请求中使用。
2. 验证仅限于"看起来正常"，而不是事实。
3. 跳过重新规划，规范变得过时。
4. 给代理旧的聊天上下文，而不是文件。
5. 技能创建得太早，在理解流程之前。
6. 在 QWEN.md 中放入所有内容，代理不再遵循主要规则。
7. 在没有明确任务的情况下连接 MCP。

如何在真实团队中实施

不要从 20 页的流程开始，而是从一条规则开始：

没有 requirements.md、plan.md 和 validation.md，就没有多文件功能。

然后添加：

• 简短的 AGENTS.md；
• specs/mission.md；
• specs/tech-stack.md；
• 最近 3-5 个阶段的路线图；
• 一个用于功能规范的项目技能；
• 一个用于变更日志的技能；
• 合并请求中的强制检查清单。

经过 2-3 个功能后进行回顾：

• 代理在哪里猜测；
• 哪些规范是无用的；
• 哪些检查捕获了真实错误；
• 哪些检查项是愿望，而不是事实；
• 什么应该自动化。

最小 SDD 模板

specs/
  mission.md
  tech-stack.md
  roadmap.md
  YYYY-MM-DD-feature/

requirements.md
    plan.md
    validation.md

这足以开始。不需要等待完美的框架。

SDD 成熟度等级

为了了解您所在的位置以及前进的方向，方便将团队中的 SDD 流程描述为从 0 到 4 的简短等级。这个等级不声称是标准；它有助于注意到哪个步骤现在会带来最大的收益。

• 等级 0 — 氛围编码。 与代理的一个长聊天。决策留在会话历史中。没有规范，验证是"看看它如何工作"。
• 等级 1 — 规范出现，但是可选的。 在大型功能中，团队编写 requirements.md，在小型功能中则不编写。validation.md 更像是愿望清单。/clear 在角色之间被忘记。
• 等级 2 — SDD 作为默认标准。 任何多文件功能都从规范开始。validation.md 包含可执行的事实。/clear 在角色之间成为习惯。在功能之间进行重新规划。
• 等级 3 — 成文化流程。 重复请求提取到技能中。保护性钩子自动检查危险操作。审查按四个层次进行（第16部分）。反模式（第20部分）被识别并快速修复。

• 等级 4 — 可学习的流程。 团队定期将观察转化为新规则（第10部分，编码步骤）。代理内存在真正有用的地方连接，在冗余的地方删除。代理的可替换性（第15部分）已通过实践验证：团队更换了工具，没有丢失流程。

大多数学习团队位于等级 0 和 2 之间。本教程的目标是将您的团队在教学项目 AgentClinic 上带到等级 2。等级 3 和 4 已经是关于特定团队、特定产品和特定年份的。它们不应该是目标本身。

从等级 1 过渡到 2 的标志：团队中的新功能默认从规范开始，而不是从"写代码"的请求开始。

从等级 2 过渡到 3 的标志：当代理出现重复错误时，有人平静地说"让我们在 QWEN.md 中添加一条规则"，这条规则确实出现了。

最终实践

拿您的真实项目，只添加：

1. AGENTS.md 或 QWEN.md；
2. specs/mission.md；
3. specs/tech-stack.md；
4. specs/roadmap.md；
5. 一个小功能的规范。

请求 Qwen Code：

作为没有先前上下文的新代理行动。

阅读项目 SDD 工件。
告诉我，您是否可以安全地实现下一个功能。
在编写代码之前，列出缺失的信息。

如果代理提出好问题，您就在正确的道路上。

复习问题

1. 哪些文件应该让新代理理解项目？
2. 如果实现通过了测试，但不符合规范，该怎么办？
3. 明天您可以实施的最小 SDD 流程是什么？