1. 从“氛围编码”到可控工程为什么我们需要 SDD 与 Harness“氛围编码”这个词最早在开发者圈子里流行起来的时候带着一种半调侃半惊艳的味道。你打开一个 AI 编程助手用自然语言描述一下想要的功能它噼里啪啦吐出一大段代码跑起来居然还能用。那种感觉就像在跟一个懂你的搭档聊天氛围到了代码就出来了。但真正把这种模式用到生产项目里的人很快就会发现氛围这东西来得快去得也快。今天生成的代码能跑明天换个提示词同样的需求给你整出一套完全不同的架构变量命名风格飘忽不定边界条件处理时有时无测试覆盖率更是随缘。项目稍微大一点多人协作一介入整个代码库就开始散发出一种“能跑但不敢碰”的危险气息。这就是SDDSpecification-Driven Development规范驱动开发重新回到台前的背景。它并不是什么新概念早年在航空、汽车电子、金融系统这些对可靠性要求极高的领域规范驱动一直是标准做法。但在 AI 编程时代SDD 被赋予了新的意义它不再只是给人看的文档而是给 AI 看的“施工图纸”。你先把要做什么、不做什么、输入输出是什么、边界在哪里用结构化的方式写清楚然后再让 AI 去生成代码。这样一来AI 的创造力被约束在一个可控的框架里既保留了生成效率又避免了“自由发挥”带来的混乱。而Harness这个词在 AI 原生软件工程的语境下指的是一套“驾驭”AI 代理的工程化基础设施。你可以把它想象成马具马跑得快是好事但如果没有缰绳、鞍座和方向控制快马反而会把你甩下来。Harness 就是给 AI 代理套上缰绳的那套东西——它负责管理上下文、注入规范、控制工具调用、记录决策轨迹、执行代码回退、校验输出结果。没有 Harness 的 AI 编程就像让一个实习生在没有代码规范、没有 Code Review、没有 CI 的环境里直接往主分支提交代码短期看效率很高长期看是在给自己挖坑。这篇文章适合三类人看第一类是被 AI 生成代码的“不可预测性”折磨过的开发者你想知道怎么让 AI 输出更稳定第二类是在团队里推动 AI 编程工具落地的技术负责人你需要一套可复制、可审计、可回退的工程方案第三类是对 AI 原生软件工程感兴趣的学生或转行者你想理解“规范驱动”和“驾驭工程”到底在解决什么问题。我会从设计思路、核心细节、实操过程、常见问题四个层面把 SDD 加 Harness 这套组合拳拆开讲清楚尽量让你看完就能在自己的项目里试起来。2. 整体设计与思路拆解SDD 和 Harness 到底怎么配合2.1 为什么单纯靠提示词工程不够用很多人一开始接触 AI 编程第一反应是去搜“AI 编程提示词模板”然后收藏一堆“你是一个资深 Python 工程师请帮我写一个……”之类的句式。这些提示词在单次对话里确实有用但它们解决不了三个根本问题。第一个问题是上下文漂移。AI 模型在长对话中会逐渐“忘记”早期的约束。你在一开始说了“所有函数必须写类型注解”聊到第三十轮的时候它可能就开始写没有类型注解的函数了。这不是模型故意不听话而是注意力机制在长上下文中的自然衰减。提示词工程只能在一轮或几轮内起作用没法跨会话、跨文件地维持一致性。第二个问题是规范缺失。提示词里写的“帮我写一个用户登录接口”和真正的软件规范之间差了十万八千里。登录接口的密码加密方式是什么失败几次锁定Token 有效期多久并发登录怎么处理这些细节如果不在规范里写清楚AI 就会按自己的“常识”去猜而它的常识和你的业务需求往往对不上。第三个问题是不可审计。你让 AI 生成了五百行代码跑是跑通了但三个月后出了 bug你想知道当初为什么这么设计AI 不会给你留决策记录。你只能对着代码反推效率极低。在团队协作场景下这个问题会被放大张三让 AI 生成的代码李四根本不敢改因为不知道背后的约束条件是什么。SDD 解决的是“做什么”的问题Harness 解决的是“怎么做”和“做完怎么管”的问题。两者配合才能把 AI 编程从“氛围”拉到“工程”。2.2 SDD 的核心思路先写规范再写代码SDD 的核心理念可以用一句话概括规范是唯一的事实来源代码是规范的实现产物。在传统开发里规范往往是写完代码之后补的文档或者干脆不写。但在 SDD 里规范必须先行而且必须是机器可读、结构化的。一个典型的 SDD 规范包含以下几个部分功能描述用自然语言描述这个模块要做什么面向什么用户解决什么问题。接口定义输入参数、输出格式、错误码、数据类型最好用类似 OpenAPI 或 JSON Schema 的形式写清楚。行为约束边界条件、异常处理、性能要求、安全要求。验收标准什么样的测试通过才算完成包括单元测试、集成测试、端到端测试的预期结果。非目标明确写出“这个模块不做什么”防止 AI 过度设计。我自己的习惯是用 Markdown 加 YAML 的混合格式来写规范。Markdown 部分给人看YAML 部分给 AI 和工具链看。比如一个用户注册模块的规范我会先写清楚“注册时需要邮箱验证密码强度至少八位且包含大小写字母和数字同一邮箱二十四小时内最多发送三次验证邮件”然后在 YAML 里定义接口的请求体和响应体结构。这样 AI 在生成代码时既有自然语言的理解上下文又有结构化的约束条件。2.3 Harness 的定位AI 代理的“操作系统”如果说 SDD 是图纸那 Harness 就是施工现场的管理系统。它要管的事情包括上下文注入在每次调用 AI 之前自动把相关的规范片段、代码文件、历史决策记录拼接到提示词里确保 AI 看到的是最新、最相关的信息。工具调用管理AI 代理需要读文件、写文件、跑测试、查文档Harness 负责提供这些工具接口并记录每次调用的输入输出。输出校验AI 生成的代码不能直接落盘要先经过语法检查、类型检查、规范符合度检查通过了才写入。版本控制与回退每次 AI 修改代码都生成一个独立的变更集出问题可以一键回退到上一个稳定状态。决策日志记录 AI 在每一步的推理过程和选择理由方便事后审计。市面上已经有一些工具在做类似的事情比如一些 AI 编程插件提供了“代码回退”功能一些代理框架提供了“工具调用”能力。但 Harness 工程的关键在于把这些能力整合成一套可配置、可扩展的流水线而不是零散地堆在一起。2.4 方案选型为什么是 SDD 加 Harness而不是其他组合有人可能会问我直接用一个大模型配上好的提示词再加一个代码审查工具不就行了吗为什么非要搞 SDD 和 Harness 这么重的架构这个问题我在项目初期也纠结过。实测下来轻量方案在个人项目、原型验证、一次性脚本这些场景下确实够用。但一旦进入团队协作、长期维护、多模块联调的场景轻量方案就会暴露出三个致命短板。第一规范无法复用。你这次写了一个很好的提示词生成了一个不错的模块。下次换个需求提示词要重写之前的经验沉淀不下来。SDD 的规范是可以版本化、可以继承、可以组合的今天写的用户模块规范明天做订单模块时可以引用其中的权限校验部分。第二AI 行为无法约束。没有 Harness 的校验层AI 生成的代码直接进代码库出了问题只能靠人工 Review 兜底。而人工 Review 在 AI 生成代码量大的时候根本看不过来。Harness 的自动校验可以在代码落盘前就拦截掉大部分低级错误。第三协作成本高。团队里每个人用 AI 的方式不一样有人喜欢让 AI 写整个文件有人喜欢让 AI 补全函数有人喜欢让 AI 解释代码。没有统一的 Harness 层这些操作产生的变更无法统一管理代码库会变得混乱。Harness 提供了一套标准化的交互协议不管你怎么用 AI最终都走同一套校验和记录流程。所以我的结论是个人项目可以轻量团队项目必须上 SDD 加 Harness。这不是为了追求架构的“高级感”而是因为协作场景下规范缺失和校验缺失带来的返工成本远高于搭建这套基础设施的成本。3. 核心细节解析与实操要点3.1 规范怎么写才能让 AI 真正看懂写规范这件事最怕的是写成“给人看的文档”。人看文档可以脑补可以结合经验理解模糊表述但 AI 不行。AI 会把你的模糊表述当成“自由发挥空间”然后给你一个惊喜或者惊吓。我总结了一个“三写三不写”原则写具体不写抽象。不要写“系统要保证高性能”要写“单次查询响应时间在 P99 场景下不超过 200 毫秒并发量支持每秒 1000 次请求”。不要写“密码要安全”要写“密码使用 bcrypt 算法加密cost 因子为 12禁止使用 MD5 或 SHA1”。写边界不写愿景。不要写“支持多种登录方式”要写“支持邮箱密码登录和手机验证码登录不支持第三方 OAuth 登录本期非目标”。边界写清楚了AI 就不会自作主张给你加一堆用不上的功能。写验收不写感觉。不要写“代码质量要高”要写“所有公开函数必须有类型注解单元测试覆盖率不低于 80%lint 检查零错误”。验收标准要可量化、可自动检查。具体到格式我推荐用“规范卡片”的方式组织。每个功能模块一张卡片卡片包含以下字段字段说明示例模块名唯一标识user-registration功能描述一段话说明新用户通过邮箱注册账号输入参数列表email, password, captcha输出成功和失败响应201 Created / 400 Bad Request约束业务规则邮箱唯一密码强度校验验收测试要求单元测试覆盖所有分支非目标明确不做不做第三方登录这张卡片写完之后直接作为 Harness 的输入配置。每次 AI 生成或修改这个模块的代码Harness 都会把这张卡片注入上下文。3.2 Harness 的上下文管理怎么让 AI 每次都看到“对的”信息Harness 最核心的能力之一是上下文管理。AI 模型的上下文窗口是有限的你不可能把整个代码库都塞进去。所以 Harness 需要做“相关性筛选”根据当前任务从规范库、代码库、历史记录中挑出最相关的片段拼成一个精简的上下文包。我的做法是给每个文件和每个规范卡片打标签比如module:user、layer:api、type:spec。当 AI 要修改用户模块的 API 层代码时Harness 会自动检索带有module:user和layer:api标签的规范卡片和代码文件再加上最近三次相关的决策日志拼成上下文。这里有个细节要注意上下文不是越多越好。我试过把整个模块的所有文件都塞进去结果 AI 反而抓不住重点生成的代码开始“缝合”不同文件的风格。后来我把上下文控制在 3000 到 5000 token 之间只放最相关的三到五个文件片段效果明显更好。另外Harness 要维护一个“决策日志”。每次 AI 做出一个非显而易见的选择比如“选择用 Redis 而不是内存缓存”Harness 要把这个决策和理由记下来。下次 AI 再遇到类似场景日志会作为上下文注入避免它反复推翻之前的决策。3.3 工具调用的安全边界AI 能做什么不能做什么Harness 给 AI 代理提供工具接口但必须设置安全边界。我的原则是读操作放开写操作收紧危险操作禁止。读操作包括读文件、查规范、搜代码、看日志这些可以放开让 AI 自由调用最多做个频率限制。写操作包括创建文件、修改文件、删除文件这些必须经过校验层。AI 不能直接写磁盘它只能提交一个“变更提案”由 Harness 校验通过后才落盘。危险操作包括执行系统命令、访问网络、修改数据库这些默认禁止。如果确实需要比如跑测试那也要在沙箱环境里执行并且限制可执行的命令白名单。我踩过的一个坑是早期为了让 AI 能自动跑测试我给它开了执行 shell 命令的权限。结果有一次 AI 生成的测试代码里包含了一个死循环直接把开发机跑挂了。后来我改成在 Docker 容器里跑测试并且设置了超时时间才解决了这个问题。3.4 代码回退机制怎么做到“随时可以重来”AI 编程最让人不放心的就是“改坏了怎么办”。Harness 的代码回退机制就是解决这个问题的。每次 AI 提交变更Harness 都会做三件事第一生成变更快照。把修改前的文件内容、修改后的文件内容、变更理由、关联的规范卡片 ID 全部打包成一个变更集存到版本库里。第二运行校验流水线。语法检查、类型检查、lint、单元测试全部通过才允许合并。任何一步失败变更集标记为“未通过”不写入主代码库。第三保留回退入口。每个变更集都有一个唯一 ID开发者可以随时通过命令回退到任意一个历史变更集。回退操作本身也会生成一个新的变更集保证操作可追溯。这套机制听起来简单但实操中有个关键点校验流水线要快。如果每次 AI 改一行代码都要跑五分钟的测试那没人愿意用。我的做法是分层校验快速校验语法、类型、lint在十秒内完成慢速校验单元测试、集成测试异步执行不阻塞 AI 的下一步操作。如果慢速校验失败再触发回退。4. 实操过程与核心环节实现4.1 环境准备搭建 Harness 的最小可行配置在开始之前你需要准备以下环境一个支持函数调用的 AI 模型接口本地部署或云端 API 均可Python 3.10 以上版本Harness 脚本用 Python 写最方便Git用于版本控制和变更集管理Docker用于沙箱执行测试可选但强烈推荐我自己的 Harness 是用 Python 写的核心依赖只有三个pyyaml用于解析规范卡片gitpython用于操作 Gitjsonschema用于校验 AI 输出的结构化数据。不需要什么重型框架两百行代码就能跑起来。目录结构建议这样组织project/ specs/ # 规范卡片 user-registration.yaml order-creation.yaml src/ # 源代码 user/ order/ harness/ # Harness 脚本 context_builder.py validator.py change_manager.py changes/ # 变更集存储 logs/ # 决策日志4.2 编写第一张规范卡片我们以用户注册模块为例写一张完整的规范卡片。文件放在specs/user-registration.yamlmodule: user-registration description: | 新用户通过邮箱注册账号。注册时需要提供邮箱、密码和图形验证码。 邮箱必须唯一密码需要满足强度要求验证码五分钟内有效。 inputs: - name: email type: string required: true constraint: 符合 RFC 5322 邮箱格式长度不超过 254 字符 - name: password type: string required: true constraint: 长度 8-64至少包含一个大写字母、一个小写字母和一个数字 - name: captcha type: string required: true constraint: 6 位数字与服务器端存储的验证码一致且在有效期内 outputs: success: code: 201 body: { user_id: string, email: string, created_at: string } errors: - code: 400 reason: 参数格式错误 - code: 409 reason: 邮箱已被注册 - code: 429 reason: 验证码错误次数过多 constraints: - 同一邮箱 24 小时内最多发送 3 次验证码 - 密码使用 bcrypt 加密cost 因子 12 - 注册成功后自动发送欢迎邮件异步 acceptance: - 单元测试覆盖所有错误分支 - 集成测试验证邮箱唯一性约束 - 性能测试单次注册请求 P99 小于 300ms non_goals: - 不支持第三方 OAuth 登录 - 不支持手机号注册 - 不做邮箱真实性验证仅格式校验这张卡片写完之后Harness 会在 AI 生成代码时自动注入。注意non_goals字段很重要它明确告诉 AI“不要做什么”防止过度设计。4.3 构建上下文注入脚本接下来写harness/context_builder.py它的职责是根据当前任务从规范库和代码库中检索相关片段拼成提示词import yaml from pathlib import Path def load_spec(module_name): spec_path Path(specs) / f{module_name}.yaml with open(spec_path, r, encodingutf-8) as f: return yaml.safe_load(f) def load_recent_changes(module_name, limit3): changes_dir Path(changes) / module_name if not changes_dir.exists(): return [] files sorted(changes_dir.glob(*.yaml), reverseTrue)[:limit] changes [] for f in files: with open(f, r, encodingutf-8) as fh: changes.append(yaml.safe_load(fh)) return changes def build_context(module_name, task_description): spec load_spec(module_name) recent load_recent_changes(module_name) context { spec: spec, recent_decisions: recent, task: task_description, } return context这个脚本很简陋但已经够用了。核心逻辑就是“按模块名找规范按时间倒序找最近变更”。如果你有多个模块可以再加一层标签匹配根据任务描述里的关键词去检索相关模块。4.4 校验流水线的实现校验流水线是 Harness 的守门员。我把它分成三层第一层语法与格式校验。AI 输出的代码先过一遍ast.parsePython或对应的解析器确保语法正确。同时检查是否符合规范卡片里定义的接口签名。第二层静态检查。跑mypy做类型检查跑ruff做 lint跑bandit做安全扫描。这些工具都有现成的命令行接口Harness 只需要调用并解析输出。第三层测试校验。在 Docker 容器里跑单元测试和集成测试设置超时时间。测试通过的标准是“全部用例通过且覆盖率不低于规范卡片里定义的阈值”。import subprocess import json def run_validation(change_dir): results {} # 第一层语法检查 syntax_result subprocess.run( [python, -m, py_compile, f{change_dir}/main.py], capture_outputTrue, textTrue ) results[syntax] syntax_result.returncode 0 # 第二层类型检查 mypy_result subprocess.run( [mypy, change_dir, --ignore-missing-imports], capture_outputTrue, textTrue ) results[type_check] mypy_result.returncode 0 # 第三层测试 test_result subprocess.run( [pytest, change_dir, --cov, --cov-fail-under80], capture_outputTrue, textTrue, timeout300 ) results[tests] test_result.returncode 0 return results实测下来这套流水线在中小型项目上跑一次大概三十秒到两分钟。如果项目更大可以把测试拆成“快速测试”和“完整测试”快速测试每次变更都跑完整测试每天跑一次。4.5 变更管理与回退操作每次 AI 提交变更Harness 生成一个变更集文件命名格式是{timestamp}-{module}-{short_hash}.yaml内容包含change_id: 20250115-143022-user-registration-a3f2 module: user-registration timestamp: 2025-01-15T14:30:22 spec_version: v1.2 files_changed: - path: src/user/registration.py before_hash: abc123 after_hash: def456 validation: syntax: pass type_check: pass tests: pass decision_log: | 选择使用 bcrypt 而不是 argon2因为规范卡片指定了 bcrypt。 验证码校验放在密码强度校验之前避免无效计算。回退操作就是找到目标变更集把files_changed里的文件恢复到before_hash对应的版本。Git 本身就能做这件事Harness 只是包了一层更方便的接口。我自己的习惯是每天下班前把当天的变更集整理一遍把验证通过的合并到主分支验证失败的标记出来第二天排查。这样既保留了 AI 的生成效率又保证了代码库的整洁。5. 常见问题与排查技巧实录5.1 AI 生成的代码不符合规范怎么办这是最常见的问题。你明明在规范里写了“密码使用 bcrypt 加密”AI 却给你用了 SHA256。排查思路分三步第一步检查规范是否真的注入了上下文。有时候 Harness 的检索逻辑有 bug规范卡片没被加载进去。你可以在 Harness 的日志里打印每次注入的上下文内容确认规范片段在里面。第二步检查规范表述是否足够具体。如果你写的是“密码要安全加密”AI 可能理解成 SHA256 也够安全。改成“必须使用 bcrypt 算法cost 因子 12禁止使用 MD5/SHA1/SHA256”AI 就不会跑偏。第三步检查模型是否支持结构化输出。有些模型对 YAML 格式的规范理解能力较弱你可以把规范转成 JSON 再注入或者用更直白的自然语言重写一遍。如果以上三步都做了还是不行那就加一道“规范符合度检查”。写一个脚本用正则或 AST 分析 AI 生成的代码检查关键约束是否满足。不满足就打回重生成。5.2 Harness 执行速度太慢怎么优化Harness 的瓶颈通常在两个地方上下文构建和校验流水线。上下文构建慢往往是因为检索逻辑太复杂或者文件读取没有缓存。我的优化方法是给规范卡片和代码文件建一个内存索引启动时加载一次后续检索直接查内存。文件变更时更新索引而不是每次重新扫描磁盘。校验流水线慢通常是因为测试用例太多或者依赖太重。优化方法是分层执行快速校验语法、类型、lint同步跑慢速校验单元测试、集成测试异步跑。另外Docker 容器可以预热不要每次校验都重新创建容器。还有一个容易被忽略的点AI 调用本身的延迟。如果你用的是云端 API网络延迟可能占了大头。可以考虑在本地部署一个小模型做初步生成云端大模型做复杂推理这样能省不少时间。5.3 多人协作时规范冲突怎么处理团队里每个人对同一个模块的理解可能不一样写出来的规范卡片会有冲突。比如张三写“密码最小长度 8”李四写“密码最小长度 12”。Harness 需要一套冲突检测机制。我的做法是在规范卡片里加一个priority字段数值越大优先级越高。冲突时取优先级高的。同时Harness 在加载规范时会做一次一致性检查发现同一模块有多个规范卡片且关键字段冲突时直接报错让人来裁决。另外规范卡片要纳入 Git 管理每次修改都要走 Pull Request 流程。这样规范的变化有记录、有 Review、有回退不会出现“谁偷偷改了规范导致 AI 生成代码跑偏”的情况。5.4 常见问题速查表问题现象可能原因排查方法解决方案AI 生成的代码风格不一致上下文注入不稳定检查每次注入的上下文是否一致固定上下文模板减少随机性校验流水线频繁失败测试用例依赖外部服务查看失败日志中的错误类型用 Mock 替换外部依赖变更集无法回退Git 仓库状态不干净检查git status回退前先提交或暂存当前修改AI 反复推翻之前的决策决策日志未注入检查日志文件是否被加载把决策日志加入上下文构建逻辑规范卡片解析失败YAML 格式错误用yamllint检查修正缩进和特殊字符转义测试超时死循环或性能问题查看超时前的输出设置超时时间优化算法5.5 几个我踩过的坑和独家技巧第一个坑是过度依赖 AI 的“常识”。有一次我让 AI 生成一个日期处理函数规范里只写了“处理日期格式”没写具体格式。AI 用了MM/DD/YYYY但我们的系统用的是YYYY-MM-DD。后来我在规范里强制要求“所有日期格式必须为 ISO 8601”问题就解决了。教训是凡是涉及格式、单位、编码的地方规范里必须写死。第二个坑是校验流水线太严格导致 AI 无法迭代。早期我把测试覆盖率阈值设到 95%结果 AI 每次生成的代码都因为覆盖率不够被打回陷入死循环。后来我把阈值降到 80%并且允许“新增代码覆盖率不低于 80%整体覆盖率不下降”AI 的迭代就顺畅多了。教训是校验标准要留出迭代空间不要一步到位。第三个技巧是给 AI 留“注释锚点”。在代码里用特定格式的注释标记出关键位置比如# HARNESS:SPEC user-registrationHarness 在注入上下文时会优先检索这些锚点附近的代码。这样 AI 修改代码时能更精准地定位到相关片段减少误改。第四个技巧是定期清理决策日志。决策日志太多会占用上下文窗口我一般只保留最近三十天的日志更早的归档到冷存储。如果某个决策特别重要就把它提升为“永久规范”写进规范卡片里。6. 从工具到习惯把 SDD 和 Harness 融入日常开发6.1 个人开发者的轻量实践如果你是一个人在做项目不需要搞太复杂的 Harness。我的建议是先从规范卡片开始用 Markdown 写清楚每个模块的输入输出和约束放在项目根目录的specs/文件夹里。然后写一个简单的脚本在调用 AI 之前把相关规范拼到提示词里。校验部分可以先用现成的 lint 和测试工具不需要自己写流水线。关键是养成“先写规范再让 AI 写代码”的习惯。这个习惯一旦养成你会发现 AI 生成的代码质量明显提升返工次数大幅减少。我自己的项目从“氛围编码”切换到“规范驱动”之后AI 生成代码的一次通过率从大概四成提升到了七成以上。6.2 团队落地的推进节奏团队落地 SDD 和 Harness最怕的是一上来就搞大而全的架构。我的建议是分三步走第一步统一规范格式。先让团队里所有人用同一种格式写规范卡片哪怕一开始只是简单的 Markdown 模板。这一步的目标是“有规范”而不是“规范完美”。第二步搭建最小 Harness。先实现上下文注入和基础校验让 AI 生成的代码必须经过校验才能合并。这一步的目标是“有管控”而不是“管控全面”。第三步迭代优化。根据实际使用中的痛点逐步增加决策日志、代码回退、冲突检测等功能。这一步的目标是“好用”而不是“功能多”。整个推进过程大概需要两到三个月取决于团队规模和项目复杂度。关键是不要跳过第一步直接上 Harness没有规范Harness 就是空转。6.3 后续可以扩展的方向这套框架搭起来之后还有很多可以扩展的地方。比如把规范卡片和 API 文档生成工具打通规范一改文档自动更新。比如把 Harness 的决策日志接入项目管理工具每个变更集自动关联到对应的需求单。比如用多个 AI 代理协作一个负责生成代码一个负责写测试一个负责 ReviewHarness 负责协调它们的工作流。我个人在实际操作中的体会是SDD 和 Harness 的价值不在于让 AI 写出更聪明的代码而在于让 AI 写出的代码更可控、更可维护、更可协作。氛围编码适合探索和原型但真正要交付给用户、要长期维护的软件还是得回到工程化的路子上来。这套方法不是限制 AI 的创造力而是把创造力引导到正确的方向上。最后分享一个小技巧每次 AI 生成的代码合并之前花两分钟看一眼决策日志。如果日志里出现了“我选择用 X 而不是 Y因为……”这样的句子而你觉得这个选择有问题那就趁早改规范。规范改一次后面一百次生成都会受益。这个投入产出比比事后修 bug 高太多了。 
长河君 · 2026/10/26 19:18:16 · 阅读 1.2k SDD与Harness：从氛围编码到可控AI编程工程实践
1. 从“氛围编码”到可控工程为什么我们需要 SDD 与 Harness“氛围编码”这个词最早在开发者圈子里流行起来的时候带着一种半调侃半惊艳的味道。你打开一个 AI 编程助手用自然语言描述一下想要的功能它噼里啪啦吐出一大段代码跑起来居然还能用。那种感觉就像在跟一个懂你的搭档聊天氛围到了代码就出来了。但真正把这种模式用到生产项目里的人很快就会发现氛围这东西来得快去得也快。今天生成的代码能跑明天换个提示词同样的需求给你整出一套完全不同的架构变量命名风格飘忽不定边界条件处理时有时无测试覆盖率更是随缘。项目稍微大一点多人协作一介入整个代码库就开始散发出一种“能跑但不敢碰”的危险气息。这就是SDDSpecification-Driven Development规范驱动开发重新回到台前的背景。它并不是什么新概念早年在航空、汽车电子、金融系统这些对可靠性要求极高的领域规范驱动一直是标准做法。但在 AI 编程时代SDD 被赋予了新的意义它不再只是给人看的文档而是给 AI 看的“施工图纸”。你先把要做什么、不做什么、输入输出是什么、边界在哪里用结构化的方式写清楚然后再让 AI 去生成代码。这样一来AI 的创造力被约束在一个可控的框架里既保留了生成效率又避免了“自由发挥”带来的混乱。而Harness这个词在 AI 原生软件工程的语境下指的是一套“驾驭”AI 代理的工程化基础设施。你可以把它想象成马具马跑得快是好事但如果没有缰绳、鞍座和方向控制快马反而会把你甩下来。Harness 就是给 AI 代理套上缰绳的那套东西——它负责管理上下文、注入规范、控制工具调用、记录决策轨迹、执行代码回退、校验输出结果。没有 Harness 的 AI 编程就像让一个实习生在没有代码规范、没有 Code Review、没有 CI 的环境里直接往主分支提交代码短期看效率很高长期看是在给自己挖坑。这篇文章适合三类人看第一类是被 AI 生成代码的“不可预测性”折磨过的开发者你想知道怎么让 AI 输出更稳定第二类是在团队里推动 AI 编程工具落地的技术负责人你需要一套可复制、可审计、可回退的工程方案第三类是对 AI 原生软件工程感兴趣的学生或转行者你想理解“规范驱动”和“驾驭工程”到底在解决什么问题。我会从设计思路、核心细节、实操过程、常见问题四个层面把 SDD 加 Harness 这套组合拳拆开讲清楚尽量让你看完就能在自己的项目里试起来。2. 整体设计与思路拆解SDD 和 Harness 到底怎么配合2.1 为什么单纯靠提示词工程不够用很多人一开始接触 AI 编程第一反应是去搜“AI 编程提示词模板”然后收藏一堆“你是一个资深 Python 工程师请帮我写一个……”之类的句式。这些提示词在单次对话里确实有用但它们解决不了三个根本问题。第一个问题是上下文漂移。AI 模型在长对话中会逐渐“忘记”早期的约束。你在一开始说了“所有函数必须写类型注解”聊到第三十轮的时候它可能就开始写没有类型注解的函数了。这不是模型故意不听话而是注意力机制在长上下文中的自然衰减。提示词工程只能在一轮或几轮内起作用没法跨会话、跨文件地维持一致性。第二个问题是规范缺失。提示词里写的“帮我写一个用户登录接口”和真正的软件规范之间差了十万八千里。登录接口的密码加密方式是什么失败几次锁定Token 有效期多久并发登录怎么处理这些细节如果不在规范里写清楚AI 就会按自己的“常识”去猜而它的常识和你的业务需求往往对不上。第三个问题是不可审计。你让 AI 生成了五百行代码跑是跑通了但三个月后出了 bug你想知道当初为什么这么设计AI 不会给你留决策记录。你只能对着代码反推效率极低。在团队协作场景下这个问题会被放大张三让 AI 生成的代码李四根本不敢改因为不知道背后的约束条件是什么。SDD 解决的是“做什么”的问题Harness 解决的是“怎么做”和“做完怎么管”的问题。两者配合才能把 AI 编程从“氛围”拉到“工程”。2.2 SDD 的核心思路先写规范再写代码SDD 的核心理念可以用一句话概括规范是唯一的事实来源代码是规范的实现产物。在传统开发里规范往往是写完代码之后补的文档或者干脆不写。但在 SDD 里规范必须先行而且必须是机器可读、结构化的。一个典型的 SDD 规范包含以下几个部分功能描述用自然语言描述这个模块要做什么面向什么用户解决什么问题。接口定义输入参数、输出格式、错误码、数据类型最好用类似 OpenAPI 或 JSON Schema 的形式写清楚。行为约束边界条件、异常处理、性能要求、安全要求。验收标准什么样的测试通过才算完成包括单元测试、集成测试、端到端测试的预期结果。非目标明确写出“这个模块不做什么”防止 AI 过度设计。我自己的习惯是用 Markdown 加 YAML 的混合格式来写规范。Markdown 部分给人看YAML 部分给 AI 和工具链看。比如一个用户注册模块的规范我会先写清楚“注册时需要邮箱验证密码强度至少八位且包含大小写字母和数字同一邮箱二十四小时内最多发送三次验证邮件”然后在 YAML 里定义接口的请求体和响应体结构。这样 AI 在生成代码时既有自然语言的理解上下文又有结构化的约束条件。2.3 Harness 的定位AI 代理的“操作系统”如果说 SDD 是图纸那 Harness 就是施工现场的管理系统。它要管的事情包括上下文注入在每次调用 AI 之前自动把相关的规范片段、代码文件、历史决策记录拼接到提示词里确保 AI 看到的是最新、最相关的信息。工具调用管理AI 代理需要读文件、写文件、跑测试、查文档Harness 负责提供这些工具接口并记录每次调用的输入输出。输出校验AI 生成的代码不能直接落盘要先经过语法检查、类型检查、规范符合度检查通过了才写入。版本控制与回退每次 AI 修改代码都生成一个独立的变更集出问题可以一键回退到上一个稳定状态。决策日志记录 AI 在每一步的推理过程和选择理由方便事后审计。市面上已经有一些工具在做类似的事情比如一些 AI 编程插件提供了“代码回退”功能一些代理框架提供了“工具调用”能力。但 Harness 工程的关键在于把这些能力整合成一套可配置、可扩展的流水线而不是零散地堆在一起。2.4 方案选型为什么是 SDD 加 Harness而不是其他组合有人可能会问我直接用一个大模型配上好的提示词再加一个代码审查工具不就行了吗为什么非要搞 SDD 和 Harness 这么重的架构这个问题我在项目初期也纠结过。实测下来轻量方案在个人项目、原型验证、一次性脚本这些场景下确实够用。但一旦进入团队协作、长期维护、多模块联调的场景轻量方案就会暴露出三个致命短板。第一规范无法复用。你这次写了一个很好的提示词生成了一个不错的模块。下次换个需求提示词要重写之前的经验沉淀不下来。SDD 的规范是可以版本化、可以继承、可以组合的今天写的用户模块规范明天做订单模块时可以引用其中的权限校验部分。第二AI 行为无法约束。没有 Harness 的校验层AI 生成的代码直接进代码库出了问题只能靠人工 Review 兜底。而人工 Review 在 AI 生成代码量大的时候根本看不过来。Harness 的自动校验可以在代码落盘前就拦截掉大部分低级错误。第三协作成本高。团队里每个人用 AI 的方式不一样有人喜欢让 AI 写整个文件有人喜欢让 AI 补全函数有人喜欢让 AI 解释代码。没有统一的 Harness 层这些操作产生的变更无法统一管理代码库会变得混乱。Harness 提供了一套标准化的交互协议不管你怎么用 AI最终都走同一套校验和记录流程。所以我的结论是个人项目可以轻量团队项目必须上 SDD 加 Harness。这不是为了追求架构的“高级感”而是因为协作场景下规范缺失和校验缺失带来的返工成本远高于搭建这套基础设施的成本。3. 核心细节解析与实操要点3.1 规范怎么写才能让 AI 真正看懂写规范这件事最怕的是写成“给人看的文档”。人看文档可以脑补可以结合经验理解模糊表述但 AI 不行。AI 会把你的模糊表述当成“自由发挥空间”然后给你一个惊喜或者惊吓。我总结了一个“三写三不写”原则写具体不写抽象。不要写“系统要保证高性能”要写“单次查询响应时间在 P99 场景下不超过 200 毫秒并发量支持每秒 1000 次请求”。不要写“密码要安全”要写“密码使用 bcrypt 算法加密cost 因子为 12禁止使用 MD5 或 SHA1”。写边界不写愿景。不要写“支持多种登录方式”要写“支持邮箱密码登录和手机验证码登录不支持第三方 OAuth 登录本期非目标”。边界写清楚了AI 就不会自作主张给你加一堆用不上的功能。写验收不写感觉。不要写“代码质量要高”要写“所有公开函数必须有类型注解单元测试覆盖率不低于 80%lint 检查零错误”。验收标准要可量化、可自动检查。具体到格式我推荐用“规范卡片”的方式组织。每个功能模块一张卡片卡片包含以下字段字段说明示例模块名唯一标识user-registration功能描述一段话说明新用户通过邮箱注册账号输入参数列表email, password, captcha输出成功和失败响应201 Created / 400 Bad Request约束业务规则邮箱唯一密码强度校验验收测试要求单元测试覆盖所有分支非目标明确不做不做第三方登录这张卡片写完之后直接作为 Harness 的输入配置。每次 AI 生成或修改这个模块的代码Harness 都会把这张卡片注入上下文。3.2 Harness 的上下文管理怎么让 AI 每次都看到“对的”信息Harness 最核心的能力之一是上下文管理。AI 模型的上下文窗口是有限的你不可能把整个代码库都塞进去。所以 Harness 需要做“相关性筛选”根据当前任务从规范库、代码库、历史记录中挑出最相关的片段拼成一个精简的上下文包。我的做法是给每个文件和每个规范卡片打标签比如module:user、layer:api、type:spec。当 AI 要修改用户模块的 API 层代码时Harness 会自动检索带有module:user和layer:api标签的规范卡片和代码文件再加上最近三次相关的决策日志拼成上下文。这里有个细节要注意上下文不是越多越好。我试过把整个模块的所有文件都塞进去结果 AI 反而抓不住重点生成的代码开始“缝合”不同文件的风格。后来我把上下文控制在 3000 到 5000 token 之间只放最相关的三到五个文件片段效果明显更好。另外Harness 要维护一个“决策日志”。每次 AI 做出一个非显而易见的选择比如“选择用 Redis 而不是内存缓存”Harness 要把这个决策和理由记下来。下次 AI 再遇到类似场景日志会作为上下文注入避免它反复推翻之前的决策。3.3 工具调用的安全边界AI 能做什么不能做什么Harness 给 AI 代理提供工具接口但必须设置安全边界。我的原则是读操作放开写操作收紧危险操作禁止。读操作包括读文件、查规范、搜代码、看日志这些可以放开让 AI 自由调用最多做个频率限制。写操作包括创建文件、修改文件、删除文件这些必须经过校验层。AI 不能直接写磁盘它只能提交一个“变更提案”由 Harness 校验通过后才落盘。危险操作包括执行系统命令、访问网络、修改数据库这些默认禁止。如果确实需要比如跑测试那也要在沙箱环境里执行并且限制可执行的命令白名单。我踩过的一个坑是早期为了让 AI 能自动跑测试我给它开了执行 shell 命令的权限。结果有一次 AI 生成的测试代码里包含了一个死循环直接把开发机跑挂了。后来我改成在 Docker 容器里跑测试并且设置了超时时间才解决了这个问题。3.4 代码回退机制怎么做到“随时可以重来”AI 编程最让人不放心的就是“改坏了怎么办”。Harness 的代码回退机制就是解决这个问题的。每次 AI 提交变更Harness 都会做三件事第一生成变更快照。把修改前的文件内容、修改后的文件内容、变更理由、关联的规范卡片 ID 全部打包成一个变更集存到版本库里。第二运行校验流水线。语法检查、类型检查、lint、单元测试全部通过才允许合并。任何一步失败变更集标记为“未通过”不写入主代码库。第三保留回退入口。每个变更集都有一个唯一 ID开发者可以随时通过命令回退到任意一个历史变更集。回退操作本身也会生成一个新的变更集保证操作可追溯。这套机制听起来简单但实操中有个关键点校验流水线要快。如果每次 AI 改一行代码都要跑五分钟的测试那没人愿意用。我的做法是分层校验快速校验语法、类型、lint在十秒内完成慢速校验单元测试、集成测试异步执行不阻塞 AI 的下一步操作。如果慢速校验失败再触发回退。4. 实操过程与核心环节实现4.1 环境准备搭建 Harness 的最小可行配置在开始之前你需要准备以下环境一个支持函数调用的 AI 模型接口本地部署或云端 API 均可Python 3.10 以上版本Harness 脚本用 Python 写最方便Git用于版本控制和变更集管理Docker用于沙箱执行测试可选但强烈推荐我自己的 Harness 是用 Python 写的核心依赖只有三个pyyaml用于解析规范卡片gitpython用于操作 Gitjsonschema用于校验 AI 输出的结构化数据。不需要什么重型框架两百行代码就能跑起来。目录结构建议这样组织project/ specs/ # 规范卡片 user-registration.yaml order-creation.yaml src/ # 源代码 user/ order/ harness/ # Harness 脚本 context_builder.py validator.py change_manager.py changes/ # 变更集存储 logs/ # 决策日志4.2 编写第一张规范卡片我们以用户注册模块为例写一张完整的规范卡片。文件放在specs/user-registration.yamlmodule: user-registration description: | 新用户通过邮箱注册账号。注册时需要提供邮箱、密码和图形验证码。 邮箱必须唯一密码需要满足强度要求验证码五分钟内有效。 inputs: - name: email type: string required: true constraint: 符合 RFC 5322 邮箱格式长度不超过 254 字符 - name: password type: string required: true constraint: 长度 8-64至少包含一个大写字母、一个小写字母和一个数字 - name: captcha type: string required: true constraint: 6 位数字与服务器端存储的验证码一致且在有效期内 outputs: success: code: 201 body: { user_id: string, email: string, created_at: string } errors: - code: 400 reason: 参数格式错误 - code: 409 reason: 邮箱已被注册 - code: 429 reason: 验证码错误次数过多 constraints: - 同一邮箱 24 小时内最多发送 3 次验证码 - 密码使用 bcrypt 加密cost 因子 12 - 注册成功后自动发送欢迎邮件异步 acceptance: - 单元测试覆盖所有错误分支 - 集成测试验证邮箱唯一性约束 - 性能测试单次注册请求 P99 小于 300ms non_goals: - 不支持第三方 OAuth 登录 - 不支持手机号注册 - 不做邮箱真实性验证仅格式校验这张卡片写完之后Harness 会在 AI 生成代码时自动注入。注意non_goals字段很重要它明确告诉 AI“不要做什么”防止过度设计。4.3 构建上下文注入脚本接下来写harness/context_builder.py它的职责是根据当前任务从规范库和代码库中检索相关片段拼成提示词import yaml from pathlib import Path def load_spec(module_name): spec_path Path(specs) / f{module_name}.yaml with open(spec_path, r, encodingutf-8) as f: return yaml.safe_load(f) def load_recent_changes(module_name, limit3): changes_dir Path(changes) / module_name if not changes_dir.exists(): return [] files sorted(changes_dir.glob(*.yaml), reverseTrue)[:limit] changes [] for f in files: with open(f, r, encodingutf-8) as fh: changes.append(yaml.safe_load(fh)) return changes def build_context(module_name, task_description): spec load_spec(module_name) recent load_recent_changes(module_name) context { spec: spec, recent_decisions: recent, task: task_description, } return context这个脚本很简陋但已经够用了。核心逻辑就是“按模块名找规范按时间倒序找最近变更”。如果你有多个模块可以再加一层标签匹配根据任务描述里的关键词去检索相关模块。4.4 校验流水线的实现校验流水线是 Harness 的守门员。我把它分成三层第一层语法与格式校验。AI 输出的代码先过一遍ast.parsePython或对应的解析器确保语法正确。同时检查是否符合规范卡片里定义的接口签名。第二层静态检查。跑mypy做类型检查跑ruff做 lint跑bandit做安全扫描。这些工具都有现成的命令行接口Harness 只需要调用并解析输出。第三层测试校验。在 Docker 容器里跑单元测试和集成测试设置超时时间。测试通过的标准是“全部用例通过且覆盖率不低于规范卡片里定义的阈值”。import subprocess import json def run_validation(change_dir): results {} # 第一层语法检查 syntax_result subprocess.run( [python, -m, py_compile, f{change_dir}/main.py], capture_outputTrue, textTrue ) results[syntax] syntax_result.returncode 0 # 第二层类型检查 mypy_result subprocess.run( [mypy, change_dir, --ignore-missing-imports], capture_outputTrue, textTrue ) results[type_check] mypy_result.returncode 0 # 第三层测试 test_result subprocess.run( [pytest, change_dir, --cov, --cov-fail-under80], capture_outputTrue, textTrue, timeout300 ) results[tests] test_result.returncode 0 return results实测下来这套流水线在中小型项目上跑一次大概三十秒到两分钟。如果项目更大可以把测试拆成“快速测试”和“完整测试”快速测试每次变更都跑完整测试每天跑一次。4.5 变更管理与回退操作每次 AI 提交变更Harness 生成一个变更集文件命名格式是{timestamp}-{module}-{short_hash}.yaml内容包含change_id: 20250115-143022-user-registration-a3f2 module: user-registration timestamp: 2025-01-15T14:30:22 spec_version: v1.2 files_changed: - path: src/user/registration.py before_hash: abc123 after_hash: def456 validation: syntax: pass type_check: pass tests: pass decision_log: | 选择使用 bcrypt 而不是 argon2因为规范卡片指定了 bcrypt。 验证码校验放在密码强度校验之前避免无效计算。回退操作就是找到目标变更集把files_changed里的文件恢复到before_hash对应的版本。Git 本身就能做这件事Harness 只是包了一层更方便的接口。我自己的习惯是每天下班前把当天的变更集整理一遍把验证通过的合并到主分支验证失败的标记出来第二天排查。这样既保留了 AI 的生成效率又保证了代码库的整洁。5. 常见问题与排查技巧实录5.1 AI 生成的代码不符合规范怎么办这是最常见的问题。你明明在规范里写了“密码使用 bcrypt 加密”AI 却给你用了 SHA256。排查思路分三步第一步检查规范是否真的注入了上下文。有时候 Harness 的检索逻辑有 bug规范卡片没被加载进去。你可以在 Harness 的日志里打印每次注入的上下文内容确认规范片段在里面。第二步检查规范表述是否足够具体。如果你写的是“密码要安全加密”AI 可能理解成 SHA256 也够安全。改成“必须使用 bcrypt 算法cost 因子 12禁止使用 MD5/SHA1/SHA256”AI 就不会跑偏。第三步检查模型是否支持结构化输出。有些模型对 YAML 格式的规范理解能力较弱你可以把规范转成 JSON 再注入或者用更直白的自然语言重写一遍。如果以上三步都做了还是不行那就加一道“规范符合度检查”。写一个脚本用正则或 AST 分析 AI 生成的代码检查关键约束是否满足。不满足就打回重生成。5.2 Harness 执行速度太慢怎么优化Harness 的瓶颈通常在两个地方上下文构建和校验流水线。上下文构建慢往往是因为检索逻辑太复杂或者文件读取没有缓存。我的优化方法是给规范卡片和代码文件建一个内存索引启动时加载一次后续检索直接查内存。文件变更时更新索引而不是每次重新扫描磁盘。校验流水线慢通常是因为测试用例太多或者依赖太重。优化方法是分层执行快速校验语法、类型、lint同步跑慢速校验单元测试、集成测试异步跑。另外Docker 容器可以预热不要每次校验都重新创建容器。还有一个容易被忽略的点AI 调用本身的延迟。如果你用的是云端 API网络延迟可能占了大头。可以考虑在本地部署一个小模型做初步生成云端大模型做复杂推理这样能省不少时间。5.3 多人协作时规范冲突怎么处理团队里每个人对同一个模块的理解可能不一样写出来的规范卡片会有冲突。比如张三写“密码最小长度 8”李四写“密码最小长度 12”。Harness 需要一套冲突检测机制。我的做法是在规范卡片里加一个priority字段数值越大优先级越高。冲突时取优先级高的。同时Harness 在加载规范时会做一次一致性检查发现同一模块有多个规范卡片且关键字段冲突时直接报错让人来裁决。另外规范卡片要纳入 Git 管理每次修改都要走 Pull Request 流程。这样规范的变化有记录、有 Review、有回退不会出现“谁偷偷改了规范导致 AI 生成代码跑偏”的情况。5.4 常见问题速查表问题现象可能原因排查方法解决方案AI 生成的代码风格不一致上下文注入不稳定检查每次注入的上下文是否一致固定上下文模板减少随机性校验流水线频繁失败测试用例依赖外部服务查看失败日志中的错误类型用 Mock 替换外部依赖变更集无法回退Git 仓库状态不干净检查git status回退前先提交或暂存当前修改AI 反复推翻之前的决策决策日志未注入检查日志文件是否被加载把决策日志加入上下文构建逻辑规范卡片解析失败YAML 格式错误用yamllint检查修正缩进和特殊字符转义测试超时死循环或性能问题查看超时前的输出设置超时时间优化算法5.5 几个我踩过的坑和独家技巧第一个坑是过度依赖 AI 的“常识”。有一次我让 AI 生成一个日期处理函数规范里只写了“处理日期格式”没写具体格式。AI 用了MM/DD/YYYY但我们的系统用的是YYYY-MM-DD。后来我在规范里强制要求“所有日期格式必须为 ISO 8601”问题就解决了。教训是凡是涉及格式、单位、编码的地方规范里必须写死。第二个坑是校验流水线太严格导致 AI 无法迭代。早期我把测试覆盖率阈值设到 95%结果 AI 每次生成的代码都因为覆盖率不够被打回陷入死循环。后来我把阈值降到 80%并且允许“新增代码覆盖率不低于 80%整体覆盖率不下降”AI 的迭代就顺畅多了。教训是校验标准要留出迭代空间不要一步到位。第三个技巧是给 AI 留“注释锚点”。在代码里用特定格式的注释标记出关键位置比如# HARNESS:SPEC user-registrationHarness 在注入上下文时会优先检索这些锚点附近的代码。这样 AI 修改代码时能更精准地定位到相关片段减少误改。第四个技巧是定期清理决策日志。决策日志太多会占用上下文窗口我一般只保留最近三十天的日志更早的归档到冷存储。如果某个决策特别重要就把它提升为“永久规范”写进规范卡片里。6. 从工具到习惯把 SDD 和 Harness 融入日常开发6.1 个人开发者的轻量实践如果你是一个人在做项目不需要搞太复杂的 Harness。我的建议是先从规范卡片开始用 Markdown 写清楚每个模块的输入输出和约束放在项目根目录的specs/文件夹里。然后写一个简单的脚本在调用 AI 之前把相关规范拼到提示词里。校验部分可以先用现成的 lint 和测试工具不需要自己写流水线。关键是养成“先写规范再让 AI 写代码”的习惯。这个习惯一旦养成你会发现 AI 生成的代码质量明显提升返工次数大幅减少。我自己的项目从“氛围编码”切换到“规范驱动”之后AI 生成代码的一次通过率从大概四成提升到了七成以上。6.2 团队落地的推进节奏团队落地 SDD 和 Harness最怕的是一上来就搞大而全的架构。我的建议是分三步走第一步统一规范格式。先让团队里所有人用同一种格式写规范卡片哪怕一开始只是简单的 Markdown 模板。这一步的目标是“有规范”而不是“规范完美”。第二步搭建最小 Harness。先实现上下文注入和基础校验让 AI 生成的代码必须经过校验才能合并。这一步的目标是“有管控”而不是“管控全面”。第三步迭代优化。根据实际使用中的痛点逐步增加决策日志、代码回退、冲突检测等功能。这一步的目标是“好用”而不是“功能多”。整个推进过程大概需要两到三个月取决于团队规模和项目复杂度。关键是不要跳过第一步直接上 Harness没有规范Harness 就是空转。6.3 后续可以扩展的方向这套框架搭起来之后还有很多可以扩展的地方。比如把规范卡片和 API 文档生成工具打通规范一改文档自动更新。比如把 Harness 的决策日志接入项目管理工具每个变更集自动关联到对应的需求单。比如用多个 AI 代理协作一个负责生成代码一个负责写测试一个负责 ReviewHarness 负责协调它们的工作流。我个人在实际操作中的体会是SDD 和 Harness 的价值不在于让 AI 写出更聪明的代码而在于让 AI 写出的代码更可控、更可维护、更可协作。氛围编码适合探索和原型但真正要交付给用户、要长期维护的软件还是得回到工程化的路子上来。这套方法不是限制 AI 的创造力而是把创造力引导到正确的方向上。最后分享一个小技巧每次 AI 生成的代码合并之前花两分钟看一眼决策日志。如果日志里出现了“我选择用 X 而不是 Y因为……”这样的句子而你觉得这个选择有问题那就趁早改规范。规范改一次后面一百次生成都会受益。这个投入产出比比事后修 bug 高太多了。