SDD和Harness：AI编程的两大支柱
Hi，我是阿昌，今天学习记录：SDD 和 Harness：AI 编程的两大支柱。
现在 AI 编程相关概念很多，比如：
- SDD
- Harness Engineering
- Vibe Coding
- Context Engineering
- ReAct
- Test-Driven AI
- Plan-then-Execute
- AI-First Architecture
看起来都挺有道理，但真正成熟、可教、能在项目里稳定落地的，主要就两个：SDD 和 Harness。
简单说就是：
1 | SDD 解决“想什么”的问题 |
一个负责把需求想清楚，一个负责把 AI 管起来。两个合起来，才是一套完整的 AI 编程工作流。
一、结论
最核心的一句话是：
SDD 告诉 AI 做什么，Harness 保证 AI 做对。
以前我们写代码，很多事情都在工程师脑子里：需求边界、技术方案、风险点、验收标准、项目规范。
但是到了 AI 编程时代，如果这些东西还只藏在脑子里，AI 是不知道的。你只说一句“帮我加个功能”，AI 就只能靠概率猜。
猜对了，是运气。
猜错了，你再纠正。
来回几轮以后，看起来是在和 AI 协作，其实是在反复补需求、补上下文、补规则。
AI 编程拆成两个问题：
1 | 想：到底要做什么？边界是什么？验收标准是什么？ |
SDD 解决前一个问题，Harness 解决后一个问题。
二、SDD：把“想清楚”工程化
SDD 可以理解为 Spec-Driven Development，也就是规格驱动开发。
它不是单纯写一份需求文档，而是把需求变成 AI 能执行的结构化规格。
一份好的 spec 至少要讲清楚：
- 背景是什么
- 目标是什么
- 用户故事是什么
- 验收标准是什么
- 哪些事情不做
- 有哪些边界条件
- 做完怎么验证
也就是说，SDD 的重点不是“写文档”，而是逼着你先想清楚。
很多 AI 编程失败，不是因为 AI 写代码能力差，而是因为人给的信息太模糊。
比如你说：
1 | 帮我优化一下订单查询。 |
这个需求就很危险。
AI 不知道你要优化什么：
- 是优化 SQL？
- 是加缓存？
- 是改索引？
- 是减少接口字段？
- 是解决超时？
- 是提升代码可读性？
如果没有 spec，AI 就会自己猜。
但如果你写成：
1 | 目标：优化订单列表接口在大数据量下的查询性能。 |
这时候 AI 就清楚很多。
所以 SDD 的本质是：把脑子里的隐性判断，变成可以被 AI 读取、可以被人 review、可以被团队共享的显性规格。
三、SDD 的三种落地方式
SDD 的落地方式分成了三种。
1. Spec-Kit：自动化模式
Spec-Kit 是 GitHub 推出的 SDD 工具，它的流程比较完整，核心是四个命令：
1 | /specify 定义需求 |
大概流程是：
- 你先给一个粗略需求。
- Spec-Kit 帮你生成
spec.md。 - 再基于 spec 生成
plan.md。 - 再拆成
tasks.md。 - 最后 AI 按任务清单执行。
这个模式的好处是流程完整，适合新手练 SDD，也适合中等复杂度、探索性开发、团队对齐。
但它也有问题：
AI 会先拆任务，再执行任务，中间有两轮推断。
1 | 需求 -> AI 拆任务 -> AI 执行任务 |
每一轮都可能有误差。
如果拆任务时就错了，后面执行得再努力，也是在错误方向上努力。最后你 review 一大堆代码时，才发现最前面的任务拆错了，返工成本就很高。
所以 Spec-Kit 适合“先把流程跑起来”，但不适合所有高风险场景。
2. OpenSpec：手动控制 + delta spec
OpenSpec 更强调人工控制。
它的思路是：
1 | 人写 spec / plan |
也就是说，全局判断始终在人手里，AI 只做局部执行。
这点很重要。
因为 AI 最擅长的是“给清晰任务写代码”，不擅长替你做产品判断、架构取舍、业务边界决策。
OpenSpec 还有一个很实用的点：delta spec。
所谓 delta spec，就是增量规格。
它不要求你为整个项目写一份完整 spec，而是只写这次变更：
1 | 这次要改什么？ |
这个非常适合 老项目改造。
因为老项目已经在那里了，你不是从 0 到 1 设计一个新系统，而是在已有系统上做增量改动。
比如修一个历史遗留问题，就没必要写完整项目规格，只要把这次变更边界写清楚就行。
delta spec 也很适合写 PR 描述。一个好的 PR，本质上就是一份 delta spec：告诉 reviewer 这次改了什么、为什么改、影响范围是什么、怎么验证。
3. 轻量手工模式
第三种模式更像很多资深工程师真实使用 AI 的方式。
它不一定写正式 spec，也不一定上 SDD 专用工具。
流程是：
1 | 人在脑子里想清楚方案 |
比如一个需求，先在脑子里想清楚：
- 要改哪些类
- 方法怎么拆
- 接口怎么设计
- 边界条件怎么处理
- 先写哪一段，后写哪一段
然后把任务拆得很小，小到 AI 一次能写完，你一次能看完。
可能只是一个函数、一个类、几十行逻辑。
这种模式看起来不够“工具化”，但很稳。
因为 AI 不做创造性决策，只负责执行。
你让它写这一段，它就写这一段；写完你马上看，有问题马上改，不让错误累积。
这也是里很重要的观点：
SDD 的核心是思考方法，不是工具本身。
当你足够熟悉项目，任务规模也可控时，SDD 可以内化成你的工作习惯，不一定非要外化成正式文档。
四、三种 SDD 模式怎么选？
可以简单按场景选：
| 场景 | 推荐方式 |
|---|---|
| 新手练习、中等复杂度新项目 | Spec-Kit 自动化模式 |
| 资深工程师做系统级新项目 | OpenSpec 手动控制模式 |
| 老项目改造、PR、增量功能 | OpenSpec delta spec |
| 熟悉项目、关键路径、小步开发 | 轻量手工模式 |
| 团队协作，需要统一任务清单 | Spec-Kit + 手动控制混用 |
自己的理解是：
- 不熟的时候，让工具帮你搭流程。
- 高风险的时候，人必须抓住全局判断。
- 很熟的时候，轻量手工反而最快。
工具不是越多越高级，关键是场景合适。
五、Harness：把 AI 的执行管起来
如果说 SDD 是告诉 AI “目标在哪”，那 Harness 就是告诉 AI “路该怎么走，哪里不能碰，做完怎么检查”。
翻译 Harness 解释成“挽具”。
AI 能力很强，但是缺少边界感。
它可能会：
- 偏离当前任务
- 改了不该改的文件
- 读了太多无关上下文后判断跑偏
- 执行危险命令
- 写完代码不验证
Harness 就是通过一套配置和约束，让 AI 在合理边界内工作。
几个核心工具：
1. CLAUDE.md / AGENTS.md：项目说明书
这个很好理解，就是放在项目根目录的 AI 项目说明。
Claude Code 读 CLAUDE.md，Codex 读 AGENTS.md，Cursor 读 .cursorrules。
名字不一样，本质一样：让 AI 一进项目就知道规则。
一个最小可用版本可以包含：
1 | 项目概况：这个项目是做什么的，技术栈是什么 |
这个投入很小，但收益很大。
不写的话，每次都要重新告诉 AI：项目怎么跑、测试怎么跑、哪些地方不能动。
写了以后，AI 起码不会一上来就用错命令、乱猜项目结构。
2. Skills / Slash Commands：沉淀重复流程
很多事情是反复做的：
- 代码 review
- PR 描述
- bug 排查
- 新模块脚手架
- 接入某个中间件的标准流程
每次都重新告诉 AI 一遍，很浪费。
所以可以把它们封装成 Skill 或 Slash Command。
简单理解：
1 | Skill：AI 在合适场景下自动调用的能力 |
这其实就是把个人经验、团队规范沉淀到 AI 里。
3. Subagents：隔离上下文
AI 的上下文窗口是有限的。
如果主对话一次性读太多代码，很容易污染上下文，后面就忘了最开始的重要约束。
Subagents 的价值是把大任务拆出去：
1 | 主对话：负责决策和汇总 |
适合这些场景：
- 需要读大量代码
- 几件事可以并行做
- 不想让主对话被无关信息污染
注意点：轻量手工模式下，不一定要用 Subagents。
如果任务本来就很小，主对话能装得下，引入子代理反而会打散节奏。
4. Plan Mode：先规划再执行
Plan Mode 的作用是防止 AI 一上来就乱改。
开启以后，AI 在写代码前先说清楚：
1 | 我要做什么 |
你确认后，它再动手。
这个模式特别适合：
- 改核心模块
- 改生产配置
- 做大规模重构
- 改数据库 schema
- 进入不熟悉代码区域
小任务可以不开，重要任务建议开。
因为看几百字 plan，比 review 几百行错误代码便宜太多。
5. Permission：事前权限控制
Permission 是告诉 AI：
1 | 哪些操作可以直接做 |
一般分三类：
| 类型 | 说明 |
|---|---|
| allow | 可以直接执行，比如读文件、跑测试、跑 lint |
| ask | 需要确认，比如安装依赖、改 package.json、改配置 |
| deny | 绝对禁止，比如删文件、改 .env、跑生产部署 |
这个机制能解决一个很现实的问题：
没有权限控制时，你要么每个操作都手动确认，很累；要么完全放开，又不放心。
Permission 给了一个中间状态：安全的事情让 AI 自己做，危险的事情拦住。
6. Hooks：事后自动检查
Hooks 是让 AI 做完以后自动跑检查。
比如：
- 写完代码自动跑 lint
- 改完文件自动跑相关测试
- 执行命令前检查是否危险
- 写完后自动 format
- 改接口后自动检查文档是否同步
它的核心价值是把反馈循环自动化。
以前是：
1 | AI 写完代码 -> 人发现错 -> 人提醒 AI 改 |
有 Hooks 后变成：
1 | AI 写完代码 -> 自动跑测试/lint -> 失败结果反馈给 AI -> AI 修复 |
这才更像工程化流程。
六、SDD 和 Harness 为什么必须合起来用？
只用 SDD，不用 Harness，会出现这个问题：
spec 写得很清楚，但 AI 执行时还是可能乱改、漏边界、凑合实现、改错文件。
也就是说：目标清楚，但过程不可控。
只用 Harness，不用 SDD，也会有问题：
权限、Hooks、Plan Mode 都配得很好，但 AI 不知道真正要做什么。
也就是说：过程可控，但目标不清楚。
所以两个要一起用：
1 | SDD 给清晰目标 |
这样 AI 才能在明确目标里前进，在明确边界内行动，出错有检查，危险操作有拦截，关键决策有人确认。
七、落地建议
如果今天就要开始实践，可以按这个顺序来。
第一步：先写项目说明
先在常用项目里写一份 CLAUDE.md 或 AGENTS.md。
不用追求完美，先写最小版：
1 | 项目是什么 |
后面和 AI 协作时，发现有规则没写进去，就补一条。
这个文件是用出来的，不是一次性设计出来的。
第二步：选一种 SDD 模式
如果你还不熟，先用 Spec-Kit，把完整流程跑一遍。
如果是老项目改造，用 delta spec。
如果项目你很熟，就用轻量手工模式：自己想方案，拆小任务，让 AI 一段段写。
第三步：逐步加 Harness 工具
可以按这个顺序来：
1 | CLAUDE.md / AGENTS.md |
不是所有工具都要一次上齐。
轻量手工模式下，可能 CLAUDE.md + Skill 就能覆盖大部分场景。
大型项目改造时，Subagents + Permission + Hooks 会更重要。
批量自动化任务里，Hooks + Permission 又会变成核心。
八、总结
不要把 AI 当成“完全懂你的同事”，而要把它当成：
能力很强，但缺少边界判断的执行者。
所以我们需要做两件事：
1 | 第一，把需求想清楚，也就是 SDD。 |
SDD 让 AI 不再靠猜。
Harness 让 AI 不再乱跑。
真正稳定的 AI 编程，不是多写 prompt，也不是盲目堆工具，而是把“想”和“做”都工程化。
AI 编程越往后走，拼的不是谁更会喊 AI 写代码，而是谁更会定义目标、拆任务、设边界、做验证。
把 SDD 和 Harness 这两件事练熟，才算真正进入了 AI 编程的工程化阶段。