SDD与Harness：从氛围编码到可控AI原生软件工程实践

1. 从“氛围编码”到可控工程：SDD 与 Harness 到底在解决什么

“氛围编码”这个词，最早在开发者圈子里流行起来的时候，带着一种半调侃半惊艳的味道。你打开一个 AI 编程助手，用自然语言描述一下想要什么，它噼里啪啦吐出一大段代码，跑起来居然还能用。那种感觉就像你对着空气说了句“给我做个登录页”，然后屏幕上真的出现了一个登录页。爽是真爽，但用过一阵子的人都知道，这种爽感消退得特别快。

原因不复杂。氛围编码的本质是“意图直接映射到代码”，中间缺少了工程上最关键的几层约束：需求有没有被精确定义？边界条件有没有被覆盖？生成出来的代码和现有系统怎么衔接？后续谁来维护？当项目从“一个周末的玩具”变成“要上线、要迭代、要多人协作”的真实系统时，氛围编码的那套玩法立刻就会露馅。你会发现自己陷入一种循环：让 AI 改一个 bug，它改好了，但引入了两个新问题；再让它修那两个新问题，它又把最初那个 bug 带回来了。

这就是 SDD（Specification-Driven Development，规范驱动开发）和 Harness（驾驭工程）这两个概念被提出来的背景。它们不是要否定 AI 编程，恰恰相反，它们是要把 AI 编程从“碰运气”升级成“可复现、可审计、可回退”的工程实践。SDD 管的是“做什么”和“做成什么样”——把模糊的意图固化成机器可读、人可审查的规范；Harness 管的是“怎么做”和“做完怎么验证”——给 AI Agent 套上一套可控的执行框架，让它的每一步操作都在预设的轨道上跑。

关键词里提到的“AI 原生软件工程”，说的就是这个转变。不是把 AI 当成一个外挂的代码补全工具，而是把 AI Agent 当作工程流程中的一等公民，围绕它的能力边界和失效模式来重新设计开发流程。SDD 和 Harness 就是这套新流程的两根支柱。

这篇文章适合谁看？如果你只是偶尔用 AI 写个脚本、做个 demo，那氛围编码够用了，不必折腾。但如果你正在尝试把 AI 编程引入真实项目——尤其是多人协作、有质量要求、需要长期维护的项目——那 SDD 和 Harness 这套思路值得你花时间搞清楚。下面我会从核心原理、实操步骤、工具选型、踩坑经验几个维度，把这件事拆开讲透。

2. SDD 规范驱动开发：把“我想要”翻译成“必须满足”

2.1 规范不是文档，是 AI 可执行的约束条件

很多人第一次听到“规范驱动开发”，第一反应是“哦，就是先写需求文档再写代码”。这个理解不能说错，但太浅了。传统需求文档是给人看的，人可以容忍模糊、容忍歧义、容忍“这里你看着办”。但 AI Agent 不行，它不会“看着办”，它只会按照字面意思去执行，或者更糟——按照它训练数据里最常见的模式去“脑补”。

SDD 的核心洞察是：给 AI 的规范必须是可执行的。什么叫可执行？就是规范本身要足够精确，精确到可以被转化成测试用例、可以被转化成类型定义、可以被转化成接口契约。举个例子，你说“用户登录后返回用户信息”，这是给人看的。但 SDD 要求你写成：“POST /api/login 接收 {email: string, password: string}，成功返回 200 和 {userId: number, token: string, expiresAt: ISO8601}，失败返回 401 和 {error: string}，密码错误和用户不存在返回相同的错误信息以防止枚举攻击。”这才是 AI 能准确执行的规范。

我自己的做法是，在写任何 AI 生成代码的提示词之前，先花 20 分钟把规范写成三个东西：接口契约（输入输出是什么）、状态转换图（系统在什么条件下从什么状态变到什么状态）、验收标准（怎么判断做完了）。这三样东西不需要多正式，用 Markdown 写就行，但必须精确到没有歧义。

2.2 规范的分层：从业务意图到代码级约束

SDD 的规范不是铁板一块，它应该分层。我在实践中把它分成三层：

关键点在于：AI Agent 主要消费的是行为规范和实现规范，业务规范是给人看的上下文。很多团队犯的错误是把业务规范直接丢给 AI，然后抱怨 AI 生成的东西“方向不对”。方向不对是因为你给的是意图，不是约束。

行为规范怎么写？我通常用“Given-When-Then”的变体：给定什么前置条件，当发生什么操作，系统应该表现出什么行为。这个格式的好处是它天然接近测试用例，写完规范之后稍微转换一下就是自动化测试。而测试用例正是 Harness 验证 AI 输出的依据。

2.3 规范先行的实操流程：从空白到可执行

具体怎么操作？我拿一个真实场景举例：给一个已有的 REST API 添加“批量导出”功能。

第一步，写业务规范。一句话：管理员可以选中多条记录，导出为 CSV 文件，导出操作记录在审计日志中。

第二步，写行为规范。这里要穷举边界：选中 0 条怎么办？选中 10000 条怎么办？导出过程中某条记录被删了怎么办？CSV 的编码格式是什么？字段顺序是什么？空值怎么表示？这些全部写清楚。

第三步，写实现规范。接口是 POST /api/export，请求体是 {ids: number[], format: 'csv'}，响应是文件流或者一个下载链接。依赖现有的权限中间件和审计日志服务。性能要求是 1000 条记录在 2 秒内完成。

第四步，把这三层规范整理成一个结构化的 Markdown 文件，作为 AI Agent 的输入。注意，不是把整个文件丢给 AI 就完事了，而是要根据任务拆解，把相关的规范片段喂给对应的 Agent。比如负责写接口的 Agent 只需要行为规范和实现规范，负责写测试的 Agent 需要行为规范和验收标准。

提示：规范写完之后，先自己读一遍，问自己“如果我是 AI，我能不能仅凭这些信息就写出正确的代码”。如果答案是否定的，说明规范还不够精确。

2.4 规范与代码的双向同步：避免规范腐化

SDD 最大的坑不是写规范，而是规范写完就没人管了。代码改了，规范没改，下次 AI 基于过时的规范生成代码，直接跑偏。这个问题在传统开发里叫“文档腐化”，在 SDD 里更致命，因为 AI 是真的会严格按照规范执行的。

我的做法是：把规范文件纳入版本控制，和代码放在同一个仓库里。每次代码变更的 PR 里，必须包含规范文件的对应更新。更进一步，可以用脚本检查规范和代码的一致性——比如从规范里的接口定义自动生成 TypeScript 类型，如果代码里的类型和生成的不一致，CI 直接报错。

这个机制听起来麻烦，但它是 SDD 能持续运转的前提。没有双向同步，SDD 就退化成“写了一次就扔”的文档，还不如不写。

3. Harness 驾驭工程：给 AI Agent 套上缰绳

3.1 Harness 不是 Agent，是 Agent 的运行环境

关键词里有个高频问题：“harness 和 agent 区别”。这个问题问得很好，因为很多人把两者混为一谈。简单说：Agent 是干活的，Harness 是管着 Agent 干活的。

Agent 是一个能自主决策、调用工具、执行任务的 AI 程序。Harness 是包裹在 Agent 外面的那一层框架，它负责：给 Agent 提供工具接口、限制 Agent 的操作范围、记录 Agent 的每一步动作、在 Agent 跑偏时介入、在 Agent 完成后验证结果。

打个比方：Agent 是一个新来的实习生，能力很强但不太靠谱；Harness 是公司的管理制度、代码审查流程、CI/CD 流水线。没有 Harness，实习生可能写出能跑但一塌糊涂的代码；有了 Harness，实习生的产出会被自动检查、测试、格式化，不合格的打回去重做。

“Harness 驾驭工程”这个说法里的“驾驭”二字很准确。它不是“控制”，不是把 AI 锁死，而是像骑马一样——你给它方向，它出力，但缰绳始终在你手里。

3.2 Harness 的四个核心组件

一个完整的 Harness 通常包含四个部分：

工具层：Agent 能调用哪些工具？读写文件、执行命令、调用 API、查询数据库。每个工具都要有明确的输入输出定义和权限边界。比如“写文件”这个工具，应该限制在项目目录内，不能写到系统目录。

记忆层：Agent 在多轮对话中需要记住什么？当前任务的目标、已经尝试过的方案、失败的教训、用户的反馈。记忆层要区分短期记忆（当前会话）和长期记忆（跨会话的项目知识）。

验证层：Agent 完成一步操作后，怎么判断它做对了？跑测试、跑 linter、跑类型检查、对比预期输出。验证层是 Harness 最核心的部分，没有验证的 Harness 就是个空壳。

回退层：Agent 搞砸了怎么办？能回退到上一个已知good状态吗？关键词里有人问“deepseek harness 代码回退”，说明这是实际使用中的高频需求。回退层通常依赖版本控制（git）和快照机制。

3.3 验证闭环：Harness 工程的核心价值

验证闭环是 Harness 区别于普通“AI 编程助手”的关键。普通的 AI 编程助手是你问它答，它不关心答案对不对。Harness 是：Agent 生成代码 → 自动跑测试 → 测试失败 → 把失败信息喂回给 Agent → Agent 修正 → 再跑测试 → 直到通过或达到重试上限。

这个闭环听起来简单，但实操中有很多细节。比如：测试跑多久算超时？重试几次算失败？失败之后是让 Agent 自己修还是通知人类？测试环境怎么隔离？这些问题没有标准答案，要根据项目特点来定。

我的经验是：重试上限设 3 次。第一次失败通常是 Agent 理解偏差，第二次失败是修正方向不对，第三次还失败说明要么规范有问题，要么任务超出了 Agent 的能力边界，这时候应该通知人类介入，而不是让 Agent 无限循环下去。

另一个经验是：验证要分层。先跑最快的检查（语法、类型），再跑中等速度的检查（单元测试），最后跑慢速检查（集成测试、端到端测试）。这样 Agent 能快速得到反馈，不用等几分钟才知道语法错了。

3.4 从单 Agent 到多 AI 协作：Harness 的扩展形态

关键词里“多 AI 协作”也是高频词。当任务复杂到单个 Agent 搞不定时，就需要多个 Agent 分工协作。这时候 Harness 的角色从“管一个 Agent”变成“管一群 Agent”。

多 Agent 协作的典型模式是：一个 Orchestrator Agent 负责拆解任务、分配工作、汇总结果；多个 Worker Agent 各自负责一个子任务。Harness 要确保：Worker 之间的接口一致、Orchestrator 能正确判断 Worker 的产出质量、冲突能被检测和解决。

这里有个容易踩的坑：Agent 之间的通信开销。如果 Orchestrator 和 Worker 之间来回确认太多次，整体效率可能还不如单个 Agent。我的做法是：给每个 Worker 的任务描述尽可能自包含，减少来回沟通；Orchestrator 只在关键节点做决策，不微管理。

4. 把 SDD 和 Harness 串起来：一套可落地的 AI 原生工作流

4.1 工作流的五个阶段

把 SDD 和 Harness 结合起来，我实际使用的工作流是这样的：

阶段一：规范编写。人类（或者人类+AI 辅助）写出业务规范、行为规范、实现规范，存入版本控制。

阶段二：任务拆解。把规范拆成一个个可独立验证的任务单元。每个任务单元有明确的输入（相关规范片段）和输出（代码+测试）。

阶段三：Agent 执行。Harness 启动 Agent，喂入任务和规范，Agent 生成代码和测试。Harness 在每一步之后跑验证。

阶段四：验证与回退。验证通过则进入下一任务；验证失败则触发回退，把失败信息喂回 Agent 重试；重试超限则通知人类。

阶段五：规范同步。任务完成后，检查代码和规范是否一致，不一致则更新规范。

这个流程的关键在于：每个阶段都有明确的输入输出和退出条件。不是“让 AI 随便写”，而是“让 AI 在约束下写，写完必须过检查”。

4.2 工具选型：Harness 框架怎么挑

关键词里出现了不少工具名，我不具体推荐某一个，而是给一套选型标准。挑 Harness 框架时看这几点：

工具接口是否可扩展：你能不能自己加工具？比如你的项目需要调用内部 API，框架支不支持自定义工具？

验证机制是否灵活：能不能配置不同的验证步骤？能不能针对不同任务用不同的验证策略？

回退能力是否可靠：回退是基于 git 还是快照？回退粒度是文件级还是操作级？

日志是否完整：Agent 的每一步操作有没有记录？出问题了能不能追溯？

是否支持多 Agent：如果未来需要多 Agent 协作，框架能不能平滑扩展？

注意：不要一上来就追求功能最全的框架。先用最简单的 Harness 跑通一个任务，确认工作流可行，再逐步增加复杂度。我见过太多团队在选型上花了两周，结果发现核心问题是规范没写好，换什么框架都没用。

4.3 提示词工程在 SDD+Harness 中的位置

关键词里“ai 编程提示词”和“deepseek harness 提示词优化插件”出现频率很高。提示词当然重要，但在 SDD+Harness 的框架下，提示词的角色变了。

传统 AI 编程里，提示词是核心——你花大量时间琢磨怎么把需求描述清楚。但在 SDD 框架下，规范才是核心，提示词只是把规范喂给 Agent 的载体。你不需要在提示词里重复规范的内容，只需要告诉 Agent：“你的任务是实现规范文件 spec/export.md 中定义的功能，相关测试在 test/export.test.ts，请生成代码使测试通过。”

提示词的作用变成了：设定 Agent 的角色、指定它要读哪些规范文件、告诉它验证标准是什么、约束它的操作范围。这些内容相对固定，可以模板化。真正需要花心思的是规范本身，而不是提示词的措辞。

4.4 内网部署与离线场景的注意事项

关键词里有人问“deepseek harness 附带 skill 怎么部署到内网服务器”，这是个很实际的问题。很多企业的开发环境是隔离的，不能直接访问外部服务。这种情况下，Harness 的部署要注意：

模型本地化：如果用的是云端模型，内网环境需要本地部署的模型。模型的选择要权衡能力和资源消耗，不是越大越好。

依赖离线化：Harness 依赖的各种工具、插件、运行时，都要提前打包好，不能运行时才去下载。

验证环境隔离：内网的验证环境要和开发环境一致，否则会出现“本地测试通过、内网跑不起来”的问题。

日志与审计：内网环境下，Agent 的操作日志要本地存储，方便审计和问题追溯。

这些准备工作看起来繁琐，但一次配好之后，后续的 AI 编程效率提升是值得的。

5. 实操中的坑与经验：那些文档不会告诉你的事

5.1 规范写太细反而限制 AI 发挥

这是我最开始踩的坑。我以为规范越细越好，把每个函数的实现逻辑都写清楚了。结果 AI 生成的代码确实符合规范，但极其死板，完全没有利用它自己的优化能力。后来我调整了粒度：规范定义“做什么”和“不能做什么”，不定义“怎么做”。比如规范说“导出 1000 条记录要在 2 秒内完成”，但不规定用流式处理还是批量查询，让 AI 自己选。

5.2 Agent 的“自信错误”最难处理

AI Agent 有时候会生成看起来完全正确、实际上有微妙错误的代码。比如一个边界条件写反了，但测试用例恰好没覆盖到。这种错误比明显的语法错误更难发现，因为 Agent 自己也很“自信”。

我的应对方法是：在验证层加入变异测试。简单说，就是故意在代码里注入一些小错误，看测试能不能抓到。如果抓不到，说明测试覆盖不够，需要补充测试用例。这个做法增加了前期工作量，但大幅降低了漏 bug 的概率。

5.3 回退不是万能的

关键词里“deepseek harness 代码回退”被频繁搜索，说明大家很关心回退。但回退有个前提：你得知道回退到哪个状态。如果 Agent 连续做了 10 步操作，第 7 步出了问题，你是回退到第 6 步还是第 1 步？回退到第 6 步可能保留了前 6 步的正确工作，但也可能前 6 步里已经有隐患。

我的做法是：每个任务单元完成后打一个快照。回退的最小粒度是一个任务单元，不是单步操作。这样既不会丢失太多工作，也不会保留隐患。

5.4 多 Agent 协作时的“责任推诿”

多 Agent 协作时，如果最终结果不对，很难判断是哪个 Agent 的问题。Orchestrator 说 Worker 给的输入不对，Worker 说 Orchestrator 的任务描述不清楚。这种扯皮在 AI 之间也会发生。

解决办法是：给每个 Agent 的输入输出做完整记录。Orchestrator 给 Worker 的任务描述、Worker 返回的结果、验证层的检查结果，全部存档。出问题时，回溯记录就能定位到具体环节。这也是 Harness 日志功能的价值所在。

5.5 不要指望 AI 理解“潜规则”

每个项目都有一些不成文的规矩：命名习惯、代码风格、目录结构、错误处理惯例。这些潜规则人类新人要花几周才能摸清，AI 更不可能自己悟出来。解决办法是：把潜规则显式化。在规范文件里专门开一节“项目约定”，把命名规范、目录结构、常用工具函数都写清楚。这看起来是额外工作，但能大幅减少 AI 生成的代码“风格不对”的问题。

6. 这套方法适合什么样的团队和项目

SDD + Harness 不是银弹，它有明确的适用边界。根据我的经验，这套方法在以下场景收益最大：

多人协作的中大型项目：规范是团队沟通的媒介，Harness 是质量保障的底线。人越多，这套方法的价值越大。

有长期维护需求的项目：规范作为活文档，能帮助新成员快速理解系统；Harness 的验证闭环能防止回归。

对质量要求高的项目：金融、医疗、基础设施等领域，代码错误的代价很高，值得投入时间建规范、搭 Harness。

反过来，以下场景可能不适合：一次性脚本、探索性原型、个人小工具。这些场景下，氛围编码的快速迭代优势更明显，上 SDD+Harness 反而是过度工程。

最后分享一个我自己的体会：SDD 和 Harness 的投入产出比不是线性的。前期投入很大，可能前两周效率反而下降。但一旦规范体系和 Harness 配置稳定下来，后续的 AI 编程效率会有质的提升——不是快 10%，而是快几倍，而且质量更可控。关键是熬过前期的“阵痛期”，不要因为一开始不顺手就放弃。