主题：第1部分. 基于规范的软件开发（SDD）简介
难度级别：中级
预计学习时间：8-10小时
前置条件： 具备JavaScript或TypeScript的基础编程技能
理解终端和命令行的操作原理
具备版本控制系统（git）的初步使用经验
了解Web开发的基本原理（HTML、CSS、数据库）
愿意学习使用AI智能体的新方法论
学习目标： 阐述SDD的定义，并解释其与传统的AI智能体"氛围编码"方法的根本区别
识别规范作为主要开发工件的角色，并描述项目章程的创建过程
应用SDD方法初始化学习项目AgentClinic，并遵守所有结构要求
分析"不良"自由提示与SDD风格提示之间的差异，创建自己的示例
根据成功标准清单评估项目与工具型智能体协作的准备程度
概述：第1部分"简介"介绍了基于规范的软件开发（SDD）方法论的基础概念。学习材料展示了开发控制点的根本性转变：从与AI智能体的混乱"氛围编码"交互模式，转向结构化流程，其中规范成为唯一真相来源。引入了工具型智能体的概念（以Qwen Code CLI为例），解释了人与机器之间的责任分配，并概述了学习项目AgentClinic——一个讽刺性的Web应用程序，将在整个教程中逐步发展。特别关注术语约定、按强度分类的断言（标准、建议、前沿）以及SDD关键概念的最小词汇表。该材料为实际创建项目章程、功能规范和与智能体协作的组织工作做准备。
核心概念： SDD（基于规范的软件开发）：一种开发方法论，其中规范是主要的管理工件。代码由智能体基于规范生成，而非基于自由提示。人类负责意图、约束和验收标准；智能体负责速度、代码搜索和常规实现。该方法允许在会话和智能体之间保留项目记忆。
氛围编码（vibe coding）：与AI智能体交互的非正式方法，开发者编写简短的自由提示（例如"给我做个反馈表单"）并凭感觉接受结果。特点是快速生成代码后进行一系列修正。适用于原型，但难以扩展到大型系统：决策留在聊天中，架构蔓延。
功能规范：包含单一功能的实现要求和验证标准的文档。包括requirements.md、plan.md和validation.md文件。作为智能体的输入文件，决定结果质量。在编写代码之前创建，在阶段完成后更新。
项目章程：确定项目身份的文件集合：使命（mission.md）、技术栈（tech-stack.md）、路线图（roadmap.md）和关键约定。在每个会话开始时加载，确保对项目理解的延续性。
Qwen.md：Qwen Code CLI的永久上下文文件，包含项目的协作规则。在智能体会话启动时自动加载。可位于用户级别或项目级别。
工具型智能体：读取规范并生成代码的程序工具（Qwen Code CLI、Claude Code、Codex CLI、Cursor等）。在教程语境中，术语"智能体"特指此类工具，而非AgentClinic诊所的角色。
责任分离：SDD的基本原则：人类负责阐述意图、定义约束、验证结果和更新规范。智能体负责执行速度、代码搜索、常规实现和机械性修改。双方各尽其能。
技能（skill.md）：以标准化格式为智能体提供的可重复指令。存储在.qwen/skills/目录中。示例：功能规范技能，智能体可在无需额外指示的情况下多次应用。
验收标准：实现必须满足的具体、可验证的条件。在编写代码前确定，并包含在validation.md中。允许客观评估任务是否正确完成。
重新规划：在功能之间更新章程和路线图的过程。当对项目的理解在工作中发生变化时进行。确保文档的时效性。
验证：确认实现符合规范的过程。由人类基于validation.md中的标准进行。独立于开发过程，是质量的正式确认。
重要日期： 标准（standard）：工具或SDD通用实践的固定行为。不容讨论。
建议（recommendation）：在大多数情况下有效的经验实践，但允许合理的例外。
前沿（frontier）：已被采用但尚未成熟的方法；结果高度依赖具体团队。
练习题目： 标题：分析方法之间的差异
问题：阅读两种向智能体发送提示的方式："不良"提示"添加一个评价页面"和SDD风格的"良好"提示。制作一个表格，比较：(1) 每个提示中的不确定性数量，(2) 对项目的风险，(3) 每种情况下智能体需要自行决定什么，(4) 执行提示后什么会留在聊天中。
解答：1. 不良提示：产生大量不确定性——数据存储在哪里、是否需要评分、表单、验证、导航、测试。智能体自行做出所有决定，可能与项目架构冲突。决定留在聊天中，会话切换时丢失。
- SDD风格的良好提示：包含明确的指示，要求阅读章程、提问、在仓库中创建工件。智能体不编写代码，而是准备规范。所有决定都被记录并保存。
- 比较表格：
| 标准 | 不良提示 | SDD风格提示 |
|---|---|---|
| 不确定性 | >10 | 0 |
| 智能体的决定 | 架构性 | 程序性 |
| 保存性 | 在聊天中 | 在仓库中 |
| 可重复性 | 否 | 是 |
难度：中级
标题：初始化AgentClinic项目
问题：为学习项目AgentClinic创建一个空目录。初始化git仓库。创建一个包含以下内容的README.md草稿：(1) 项目名称，(2) 其用途，(3) 三组参与者（工程团队、产品团队、营销）及其需求。暂时不要编写代码，也不要请求Qwen Code的帮助。
解答：1. 创建目录并初始化git： mkdir agentclinic cd agentclinic git init
- 创建README.md草稿：
# AgentClinic
AgentClinic是一家虚构的诊所，AI智能体在与人类工作后在此康复。
## 项目参与者的需求
### 工程团队
- 清晰的TypeScript学习代码
- 责任分离的整洁架构
- 具备测试和文档
### 产品团队
- 功能：智能体患者、疾病、治疗、预约
- 评价和反馈
- 排队管理系统
### 营销
- 难忘的浏览器体验
- 吸引人的用户界面
- 诊所品牌美学
难度：初级
标题：断言分类
问题：以下是教程中的断言。确定哪些是标准、建议或前沿：(a) QWEN.md在Qwen Code会话启动时加载；(b) 超过两天的阶段应拆分为两个；(c) 通过多智能体流水线完全自动化审查；(d) 规范是机器的输入文件；(e) 智能体可以在不丢失项目记忆的情况下被替换。
解答：a) 标准——工具的固定行为，可由文档确认。
b) 建议——基于经验的实践。两天的阶段期限是最佳的，但可能有例外（例如非常小的功能）。
c) 前沿——方法处于实验阶段，结果高度依赖具体团队和上下文。
d) 标准——SDD中的基本定义。
e) 建议——在规范组织得当的情况下可实现的目标，但不能自动保证。
难度：中级
标题：创建成功标准清单
问题：基于"什么将被视为成功"部分，创建一个包含10个要点的清单，用于检查仓库与工具型智能体协作的准备程度。每个要点必须包含动作动词（有、已创建、已编写等）并且可验证。
解答：仓库准备清单：
- 有包含Qwen Code协作规则的QWEN.md文件
- 已创建specs/目录
- 有包含项目使命描述的specs/mission.md
- 有包含技术列表的specs/tech-stack.md
- 有包含发展计划的specs/roadmap.md
- 每个主要功能都从requirements.md开始
- 每个功能都包含实现计划的plan.md
- 每个功能都包含验证标准的validation.md
- 实现在独立分支中进行（不在main/master中）
- 验证标准在代码之前编写
- 阶段后更新路线图和规范
- 有.qwen/skills/feature-spec/SKILL.md文件
- 变更日志被维护并保持最新
难度：高级
标题：重构自由提示
问题：将以下自由提示转换为SDD风格的提示："在AgentClinic诊所为我做一个新患者注册表单"。提示必须：(1) 包含阅读相关文档的指示，(2) 包含工作前提问的指示，(3) 确定要创建哪些工件，(4) 包含禁止在第一阶段编写代码的要求。
解答：SDD风格的提示：
"为路线图的下一个阶段开始新功能规范：诊所患者注册。
首先阅读specs/mission.md、specs/tech-stack.md和specs/roadmap.md。确保理解项目的使命和当前技术栈。
然后就以下主题向我提问：
- 需要收集哪些患者数据（姓名、联系方式、病史）？
- 是否需要字段验证（邮箱格式、姓名长度）？
- 表单是否应支持自动保存？
- 需要考虑哪些数据安全限制？
收到答案后，在新目录specs/YYYY-MM-DD-patient-registration/中创建以下工件：
- requirements.md — 功能需求
- plan.md — 带阶段评估的实现计划
- validation.md — 验证标准
暂时不要编写代码。等待我批准规范。"
难度：中级
案例研究： 标题：初创公司从"氛围编码"迁移到SDD：CloudFlow团队的经验
场景：CloudFlow初创公司的4人开发团队正在开发云端项目管理平台。早期与Claude Code的交互建立在"氛围编码"之上：简短提示、快速修正、最少文档。当代码量达到10,000行时，团队面临严重问题：代码库变得不可控，智能体在不同会话中给出矛盾的建议，新开发者融入需要数周时间。
挑战：主要问题：(1) 架构决策由智能体做出且未记录，(2) 会话切换时智能体不记得先前决策的上下文，(3) 重构一个功能会影响15+个相关位置，因为缺乏协调，(4) 两名开发者从不同智能体会话中获得了同一功能的矛盾实现。
解决方案：团队进行了为期三周的迁移：(1) 创建了包含mission.md、tech-stack.md、roadmap.md的项目章程；(2) 编写了包含明确规则的QWEN.md；(3) 将待办事项重构为功能规范；(4) 实施规则：每个功能经历需求→计划→验证→代码阶段；(5) 创建了标准化流程的SPEC.md技能；(6) 配置了包含validation.md强制标准的CI。
结果：迁移两个月后：新开发者融入时间从3周缩短到3天；每个版本的缺陷数量减少60%；新功能添加速度提高30%（尽管有额外交付阶段，这是反直觉的）；从Claude Code切换到Qwen Code时，确认了可在不丢失上下文的情况下替换智能体。
经验教训： 规范不是官僚程序，而是对项目可控性的投资；编写规范的成本在规模扩大时多倍回报
相关概念： SDD（基于规范的软件开发）
项目章程
功能规范
人-智能体责任分离
验收标准
学习建议： 从理解"为什么"开始——在了解SDD的机制之前，先认识到"氛围编码"在大型项目中的局限性
动手操作学习项目：创建目录和文件远比理论理解重要
注意断言的标记（标准、建议、前沿）——这有助于理解哪里可以实验，哪里不可以
练习将自由提示转换为SDD风格提示——这是需要实践的关键技能
记住最小词汇表：章程、功能规范、验证、重新规划、技能——没有这些术语，SDD中的有效沟通是不可能的
在实践练习之前先了解Qwen Code CLI工具——理解智能体的能力有助于更好地构建提示
不要试图立即将SDD应用于现有项目——从学习项目AgentClinic开始，以获得纯净的体验
与同事讨论材料：断言分类和提示分析是结对讨论的好主题
记录自己的理解——用自己的话写摘要有助于发现理解上的空白
在规范阶段不要担心显得"慢"——加速发生在实现阶段，当规范消除了不确定性时
额外资源： Qwen code cli documentation: Qwen Code CLI官方文档，包括QWEN.md描述、工作模式和可用命令
Agentclinic repository: GitHub上的学习项目，展示从规范到实现的SDD完整周期
Sdd methodology overview: 基于规范的软件开发方法论概述，包含团队应用示例
技能示例（.qwen/skills/）：用于标准化智能体可重复操作的SKILL.md文件集合
文章《从聊天到工件》：关于AI智能体角色从代码生成器到规范执行者的转变的思考
总结：第1部分"简介"为SDD方法论的工作奠定基础。关键结论：规范不是官僚文件，而是决定结果质量的机器输入文件。SDD与"氛围编码"的根本区别在于控制点的转移：不是"提示—修正"的迭代系列，而是创建包含项目章程、功能规范和明确责任分离的结构化流程。人类负责意图、约束和验收标准；智能体负责常规实现。学习项目AgentClinic作为稳定的实践模型；掌握方法论后，可以将其替换为任何自己的项目。最终目标是：一个可以替换智能体而不丢失项目记忆的仓库，规范确保可重复的质量。