第一部分：简介
规范驱动开发（SDD）将开发中的控制点从代理转移到规范。在熟悉的"氛围编码"模式下——开发者输入简短的自由请求如"给我做个反馈表单"，凭感觉接受结果——代理快速生成代码，然后进入一系列修复。这对原型有效，但难以扩展到大型系统：决策留在聊天中，架构蔓延，下一个代理或下一次会话已不知道代码为何如此设计。
在 SDD 中，核心工件变为规范。代码仍然重要，但作为执行规范的结果出现。人类负责意图、约束、验收标准和质量控制。代理负责速度、代码搜索、常规实现和机械性修改。
在本教程中，我们将使用 Qwen Code CLI。SDD 方法本身不绑定特定代理：可在 Qwen Code、Claude Code、Codex CLI、Cursor、JetBrains AI Assistant 中实现。Qwen Code 适合此类工作，因为它从终端启动、读取项目文件、支持 QWEN.md、@file 命令、通过 ! 执行 shell 命令、无界面模式、项目技能和 MCP。
术语约定。 文中"代理"一词指 Qwen Code CLI（或其等效工具）——读取规范并编写代码的工具。教学项目 AgentClinic 有其领域内的"代理"——虚构的诊所 AI 患者角色。若上下文不明确，将注明"工具代理"或"诊所角色"。
如何理解教程中的陈述
教程包含不同强度的陈述。为避免混淆"Qwen Code 的确切工作方式"、"团队惯例做法"和"仅处于尝试阶段的做法"，有争议处将标注：
- 标准。 工具的固定行为或 SDD 的通用实践。示例："
QWEN.md在 Qwen Code 会话启动时加载"——标准。
- 建议。 在多数情况下有效的经验实践，但允许合理例外。示例："将超过两天的阶段拆分为两个"——建议。
- 前沿。 已有应用但尚未成熟的方法；结果高度依赖团队。示例："通过多代理流水线完全自动化评审"——前沿。
若无标注，则将该陈述视为标准或建议。前沿将明确标注。
你将构建什么
教学项目名为 AgentClinic。这是一个讽刺性 Web 应用：AI 代理来到诊所，从与人类的工作中恢复。内容幽默，但技术严肃：TypeScript、Hono、服务端 JSX、SQLite、Vitest、CSS、功能规范和变更日志。
你不必逐字复制此项目。它的作用是提供稳定的学习模型。完成后，可将 AgentClinic 替换为自己的服务、内部工具、分析应用或遗留项目。
什么算成功
到教程结束时，你应拥有一个满足以下条件的仓库：
- 包含规定 Qwen Code 工作规则的
QWEN.md；
- 包含
specs/mission.md、specs/tech-stack.md、specs/roadmap.md； - 每个大功能始于
requirements.md、plan.md、validation.md； - 实现在独立分支中进行；
- 验证标准在代码之前编写；
- 阶段结束后更新路线图、规范和变更日志；
- 可重复的功能规范流程整理为
.qwen/skills/feature-spec/SKILL.md； - 可替换代理而不丢失项目记忆。
人类的基本角色
在 SDD 中，开发者不会消失。其工作变得更像架构师和意图层的编辑：
- 阐明需要构建什么；
- 决定哪些约束不可讨论；
- 指明代理可自主决策的范围；
- 不仅检查代码，还检查代码是否符合规范；
- 当项目理解变化时更新规范。
最常见的错误是将规范视为官僚主义。在代理辅助开发中，规范不是给经理的文书。它是决定结果质量的机器输入文件。
最小词汇表
宪章——项目宪章：使命、技术栈、路线图、关键约定。
功能规范——单个功能的需求、计划和验证标准。
验证——确认实现与规范一致。
重规划——功能间更新宪章和路线图。
技能——代理的可重复指令，格式为 SKILL.md。
QWEN.md——Qwen Code 针对项目或用户的持久上下文。
第一个示例：差请求与好请求
差请求：
添加一个评价页面。问题：代理将自行决定评价存储位置、是否需要评分、是否需要表单、如何验证字段、如何更新导航、是否需要测试。
SDD 风格的请求：
为路线图下一阶段启动新功能规范：评价展示。
先阅读 specs/mission.md、specs/tech-stack.md 和 specs/roadmap.md。
然后向我询问关于边界、决策和上下文的问题。
得到答复后，创建 specs/YYYY-MM-DD-reviews-display/requirements.md、
plan.md 和 validation.md。暂时不写代码。差异不在请求长度，而在控制。第二种情况下，代理不会直接跳入代码；它帮助创建将存于仓库的工件。
实践
为教学项目创建空目录：
mkdir agentclinic
cd agentclinic
git init创建草稿文件 README.md：
# AgentClinic
AgentClinic 是一家虚构的诊所，AI 代理在这里从与人类的工作中恢复。
项目参与者期望：
- 工程团队想要清晰的教学型 TypeScript 代码；
- 产品团队想要代理、病症、疗法、预约、评价和反馈；
- 市场部门需要令人难忘的浏览器体验。暂时不要求 Qwen Code 编写代码。此阶段的任务是固定项目想法，为宪章做准备。
自测问题
- 在 SDD 中，主要真相来源在哪里：代码、聊天还是规范？
- 为什么同一变更通过规范可能比"请求—修复"的迭代序列成本更低？
- 如果代理提出了技术上可行但产品方向错误的方案，人类应该做什么？