这两年用AI写代码已经从一个“能不能用”的问题变成了“怎么管得住”的问题。我自己从最早让大语言模型一口气生成几百行业务代码到后来发现线上出事故有一半的锅要算在“AI悄悄改坏了某个边界条件”上中间踩的坑足够写一本小册子。今天想跟你聊的是我目前觉得最靠谱的一条路SDDSpecification-Driven Development规范驱动开发配上一套叫Harness的工程化驾驭层把 AI 辅助开发从“碰运气”变成“走流程”。这套组合解决的痛点很直接AI 写代码的能力已经够强了但它不懂你的业务约束、不认你的代码规范、也不记得上次改到哪一行。没有规矩、没有围栏再强的模型也是“熊孩子”。SDD 负责把“需求意图”变成结构化的规格Harness 负责把“AI 生成过程”管起来包括权限、回退、审计、插件编排。适合谁用正在用 AI 编码工具但觉得不受控的个人开发者想把 AI 稳定落地到项目里的技术负责人以及需要在企业内网环境里搭建 AI 辅助开发体系的工程师都可以参考这套思路。以下内容是我在实际搭建和日常使用中的经验总结不是官方文档的搬运很多坑是真实踩过之后才摸清楚的。1. 为什么“SDD 规范驱动 Harness 工程AI”是最稳的组合1.1 让 AI 写代码的第一步不是写代码而是写规格很多人用 AI 写代码的方式是打开对话框粘一段需求回车然后等结果。需求如果是“帮我写一个订单导出功能”模型确实能给你输出一个能跑的脚本但它大概率不满足你的真实约束——比如导出上限是多少、走哪个数据服务、要不要拆分文件、字段精度怎么处理。这些约束你没说模型就自由发挥这是绝大多数“AI 生成的代码落地即翻车”的根本原因。SDD 的核心思想其实很简单先想清楚“要什么”和“怎么算对”再让 AI 去写“怎么做”。它和 TDD测试驱动开发有点像但更靠前一步——TDD 是先写测试再写实现SDD 是先写规格再让 AI 完成任务。规格文件里写清楚背景、目标、约束、验收标准、边界情况AI 拿到这份规格去做代码生成、测试生成、变更解释每一步都有据可依。我拿装修打个比方。你直接跟工头说“把厨房搞得好看点”他可能全屋贴满大理石但如果你给一份图纸标清楚插座位置、台面高度、水管走向他做出来的东西才可能是你要的东西。SDD 就是给 AI 的那张图纸而且这张图纸本身是可执行、可校验的。1.2 裸奔式 AI 开发的四个失控现场不搞规范驱动的直接后果我在项目里见过太多次。第一个失控现场是需求语义漂移运营提的原始需求被模型“发挥”成了另一个功能比如要“导出订单”结果它顺手把“删除订单”的代码也写出来了代码里还藏着个危险接口。第二个失控现场是连锁破坏AI 为了完成你这个功能改了上游定义或公共函数下游模块的测试全崩但它在自己的会话里根本看不到提交完之后 CI 才炸。第三个失控现场是乱碰权限AI 读代码库的时候把.env里的敏感配置读出来写进了日志或者试图去访问它不该碰的系统目录。第四个失控现场是无法回退AI 改完一版你看着觉得不行想退回上一版结果发现没有快照只能靠 git 翻历史甚至手动找补。这四个问题单靠“换更强的模型”解决不了因为它们的根因都不在模型能力而在工程治理。你需要一个“驾驭层”在模型和代码库之间做约束、监督、记录和回退这正好是 Harness 这类工程AI工具出场的理由。1.3 Harness 到底是什么从“工具”到“驾驭”的定位转变Harness 不是一个具体的 IDE 插件它是一类“AI 编码代理编排与管控层”的总称。不同模型生态里有不同叫法比如 DeepSeek Harness、Claude Code Harness本质都是把 Agent 包上一层工程围栏让它按规矩干活。我习惯用一个比喻Agent 是骑手Harness 是缰绳、马鞍和护栏。骑手负责跑、负责写代码但往哪个方向跑、能不能抄近道、跑错了怎么拉回来由 Harness 控制。所以在 Harness 的体系里你会看到几个关键模块插件系统、规则引擎、技能Skill管理、权限模型、代码快照与回退、上下文窗口管理。这些模块盯着 Agent 的产出和行为确保 AI 辅助开发是可控的。这个定位非常关键。很多人还在争论“哪个 Agent 写代码最强”那是把问题放在了“生成能力”的层面。可一旦你进入真实项目尤其是多人协作、有代码规范、有合规要求的场景你会发现“写代码”只是整个流程里最后一小段。前置的规格拆解、过程中的行为约束、产出的质量校验、事后的审计回退才是真正决定这套体系能不能长期跑下去的胜负手。2. SDD 规范驱动到底怎么落地2.1 一份能“喂”给 AI 的规格文件长什么样规格文件不能写成大段散文AI 读起来费劲人也难维护。我建议用半结构化的 YAML 或 Markdown 组织成固定字段核心包括背景、目标、用户故事、技术约束、验收标准、接口定义、数据模型、边界情况。下面是我常用的一份“订单导出”规格片段spec: id: order-export title: 订单导出功能 background: 运营需要按条件导出订单数据到 Excel供线下分析 goals: - 支持按时间范围、订单状态、支付渠道三个维度筛选 - 导出文件为 xlsx列包含订单号、用户ID、金额、状态、下单时间 constraints: - 不得直接读取生产库必须走下游数据服务 - 单次导出数据量上限为 10 万行超过则拆分文件 acceptance_criteria: - GIVEN 用户选择最近 7 天且状态为“已支付” WHEN 点击导出 THEN 生成包含对应数据的 xlsx文件名带时间戳控制台无报错 boundary_cases: - 数据为空时导出空模板并给出提示 - 金额精度保留两位小数注意几个要点目标要写可观测的效果约束要写“禁止做什么”验收标准要写成 Given/When/Then 结构。AI 对“能做什么”很在行但对“不能做什么”经常选择性忽略所以约束和边界情况才是规格文件里最值钱的部分。2.2 从自然语言需求到结构化规格的三步拆解法拿到一句原始需求时我习惯按三步处理。第一步是“提取核心意图”把描述里的修饰词、口头禅剥掉找到真正要交付的东西。运营说“给我一个能导订单的按钮最好还能按渠道看看”核心意图其实是“按多条件筛选并导出订单”按钮只是交互形式不是核心。第二步是“补全边界与约束”这一步是把自己代入到线上环境问几个问题——数据源在哪里、量级多大、失败怎么办、并发怎么处理、有没有合规红线。模型不会替你问这些问题但你不问它就会替你随便答。第三步是“转成可验证的验收项”把每条需求变成机器可判断的检查点这一步直接决定了后面 AI 生成的代码能不能自动校验。这个转换过程有一个隐藏收益你在写规格文件的时候其实就是在做一次完整的需求评审。很多业务上模糊不清的地方在写“边界情况”的时候就会暴露出来比直接在代码里发现要便宜得多。2.3 规格文件在 AI 辅助开发体系里的两种用法规格文件写完之后不是躺在文档仓库里当摆设的。我目前用到的两种方式效果都很稳定。第一种是把规格文件当作系统提示词的注入源。在 Harness 的会话配置里指定“先读取spec/xxx.yaml再开始任务”这样 AI 生成代码前就带着完整约束而不是只凭你临时敲的那几句话。第二种是把规格文件当作自动校验的基准。AI 生成完代码后Harness 的工作流插件会对照规格文件里的验收标准自动生成测试用例或运行已有契约测试检查产出是否满足规格。这一步很像“契约测试”只不过契约的对象从接口变成了业务规格。规格文件应该跟代码一起走 git每次修改都留痕这样你能追踪“需求变了”和“代码坏了”之间的因果关系。3. Harness 工程化实践把 AI 关进“可控”的围栏3.1 Harness 与 Agent 到底有什么区别很多人在搜索“harness 和 agent 区别”说明这个概念确实容易混淆。我把它俩的关系总结成一句话Agent 是干活的人Harness 是管理流程的工长。Agent 负责理解任务、生成代码、执行命令Harness 负责在它动手之前、动手过程中、动手之后做约束和审计。这里的一个对比表格方便你快速理解。维度AgentHarness核心职责理解任务、生成代码/操作约束 Agent 行为、编排任务、审计结果运行方式单次会话内自主执行跨任务、跨会话的管控与编排输入输出Prompt → 代码/命令规格 规则 → 可复现的开发流程出错处理依赖自身有限重试快照回退、隔离异常、降级人工处理权限边界相对宽松能接触什么取决于工具细粒度控制文件、命令、网络访问所以当你听到“AI 数字员工”“AI 编程助手”这类概念时它们大多属于 Agent 的范畴而 Harness 是那个“看着它们别乱来”的体系。没有 Harness 的 Agent就像没有刹车系统的跑车动力很强但你不一定敢天天开。3.2 插件与技能机制按需给 AI“装腿”Harness 的插件生态是我觉得它最有工程味的地方。插件可以给 AI 增加不同的“行为约束能力”或“交互能力”。比如提示词优化插件负责在任务开始前把用户的自然语言请求改写得更精准代码回退插件负责在每次 AI 修改前自动打快照工作流插件负责编排“读规格 → 生成代码 → 跑测试 → 生成变更说明”的完整流程还有面向 RPA 落地的插件能把 AI 生成的指令对接到底层自动化脚本里。技能Skill则更像一组预置的“行为准则包”它不是一个独立程序而是把规则、脚本和指令组合成一个语义化的单元。比如你可以定义一个frontend-review技能里面包含“必须检查响应式布局”“禁止在组件里直接调用 API”等若干条规则AI 在相关任务里会自动遵守。我的建议是不要装太多插件。插件之间指令冲突会让 AI 行为变得奇怪比如一个插件要求它“总是先写测试”另一个插件要求它“尽快产出原型”AI 就会在任务规划里摇摆不定。我实际跑下来的体感核心 5 个以内的插件就够日常使用了多了反而把上下文窗口挤爆。3.3 权限控制模型AI 能碰什么、不能碰什么Harness 最关键的一个能力是细粒度权限控制。没有权限边界AI 可能会读取.env文件、修改基础配置、甚至执行危险命令。我在实际项目里会做三层限制。第一层是文件系统访问限制指定 AI 只能读取或写入某些目录比如只能访问src、tests、docs/specs禁止访问.env、node_modules、deploy等目录。第二层是命令执行限制允许 AI 运行哪些命令、禁止哪些命令。比如允许pnpm test、git diff禁止rm -rf、chmod -R、curl到未知地址等。第三层是网络访问限制如果在 Harness 里给 AI 接了外部工具或 Web 能力必须明确它能请求哪些域名或服务防止数据外带或者被恶意调用。这里顺便提一个我在 Windows 开发机上真实踩过的坑AI 通过技能去读取项目文件时报setnamedsecurityinfow failed (win32)。这个错误本质是程序在尝试给文件设置 Windows 安全描述符时没有足够权限常见原因包括当前用户缺少相应系统权限、工作目录放在系统保护目录下、或者磁盘文件系统不支持这类 ACL 操作。我的解决办法很朴素把项目从C:\Program Files挪到普通用户目录下用普通权限账号跑开发环境不要以管理员身份运行。这个坑在 Windows 上很典型Linux 服务器上反而少见。3.4 内网与局域网部署的实践经验企业里落地 AI 辅助开发大概率不能把所有代码都送到云端模型厂商那边去尤其是涉及核心业务代码和客户数据的项目。我给出的建议是把 Harness 做“内网化”部署Harness 客户端跑在开发机上模型服务跑在公司的内网服务器或私有化部署的推理服务上代码仓库、规格库、插件包都放在内网环境里。部署结构其实很清晰Harness 客户端只负责转发请求和做工程编排模型推理服务内网提供 APIHarness 只要配置好模型服务的base_url指到内网地址就能对接。插件和技能的离线安装也不需要额外折腾直接把插件目录拷贝到对应位置重启加载就行。很多人一听到“内网部署”就头大实际上最难的不是技术而是把“模型服务地址、密钥管理、插件版本控制”这三件事从个人电脑里的“随手配置”变成团队里的“统一标准”。4. 实操过程从零搭一套“SDD Harness”开发闭环4.1 环境准备与安装配置先说环境。我自己目前的生产组合是一台 Linux 服务器跑模型推理服务开发机用 Windows 或 macOS安装 Harness 命令行工具加上配套桌面端。安装过程不复杂下载对应平台的安装包配置好模型接入信息就能跑起来。关键点在于模型接入的配置。无论你用的是本地私有化部署的模型还是团队内网统一接入的模型服务都只需要在 Harness 配置里填一个base_url和认证信息。我自己在 Linux 内网服务器上部署后开发机的配置长这样harness config set model.base_url http://model.internal:8000/v1 harness config set model.api_key 从密钥管理服务里获取 harness config set workspace /data/projects/order-center配置完先别急着干活跑一个健康检查命令确认模型服务和 Harness 之间的链路是通的。这一步省不了否则后面 AI 动不动就“失联”你都不知道是哪一环出了问题。4.2 规则库与系统提示词配置环境就绪后第一件正事是把规则库配好。规则库是 Harness 控制 AI 行为的核心我建议至少包含几类规则工作区快照规则、危险操作拦截规则、测试前置规则、文件路径禁用规则。下面是一份我常用的规则文件片段你可以根据自己的项目调整rules: - id: git-checkpoint-before-edit action: snapshot scope: workspace when: before_task - id: no-prod-write action: block match: - INSERT INTO prod_ - UPDATE prod_ - DELETE FROM prod_ - id: test-before-commit action: require before: commit command: pnpm test --run - id: file-access-restrict action: restrict paths: allowed: [./src, ./tests, ./docs/specs] denied: [./.env, ./node_modules, ./deploy]规则配置完之后AI 每次操作前都会先过一遍规则引擎。比如它想生成一段包含DELETE FROM prod_的代码no-prod-write这条规则会直接拦截并提示违规。这个过程相当于给 AI 装了一个“红绿灯系统”越线就刹停。4.3 代码回退与版本保护策略AI 写代码最大的问题是“改坏了你怎么拉回来”。我建议的配置是让 Harness 在每次任务开始前自动给工作区打一个快照快照和 git 提交配合使用形成双保险。实际操作中我会在开启一个任务之前手动打一个带标签的快照harness snapshot create --tag before-order-export然后让 AI 去改代码。如果改出来不对直接回退harness rollback --tag before-order-export这里要特别注意一个细节回退之后AI 在任务期间生成的临时文件也要清理干净。有几次我回退代码后遗留的日志文件、临时配置文件还留在工作区里导致后续任务误读了旧的状态。后来我把“回退后执行git status确认工作区干净”写进了自己的检查清单才彻底治了这个问题。4.4 工作流插件编排实战有了规则和回退机制最后一步是把整个流程串成自动化工作流。我目前用得最多的一个流程是“规格驱动开发闭环”用工作流插件把它编排成固定步骤。pipeline: - step: read-spec plugin: spec-reader input: docs/specs/order-export.yaml - step: plan plugin: task-planner prompt: 基于规格生成开发计划和文件改动清单 - step: generate plugin: code-generator output: src/export/order_export.ts - step: verify plugin: test-runner command: pnpm test export - step: review-diff plugin: diff-highlight require_confirm: true - step: commit-message plugin: commit-generator这个流程跑起来之后AI 不再是“你说一句我写一段”的随机状态而是先读规格、再列计划、再写代码、再跑测试、再让人类确认 diff最后自动生成提交信息。每一步都在 Harness 的日志里有记录出了任何问题都可以回溯到具体的输入和输出。这就是我理解里“可控化 AI 辅助开发体系”的完整形态不是限制 AI而是让 AI 的每一步都有前因后果。5. 常见问题与排查技巧实录5.1 插件加载失败怎么处理我遇到过 Harness 启动时报failed to load plugins类似 “web boot: 1 entry did not activate” 的错误。这种情况多半是某个插件的入口注册失败或者插件版本和当前 Harness 版本不兼容。我的排查顺序是先看启动日志里是哪个插件报错再尝试禁用该插件单独启动最后用“安全模式”启动 Harness只加载内置插件。提示插件加载问题的重灾区是“插件之间互相依赖”比如你装了一个工作流插件它又依赖另一个上报插件被依赖插件没启动工作流插件就整体挂掉。解决办法是把插件依赖关系理清楚尽量只保留有明确用途的插件不搞插件全家桶。5.2 skill 读取文件报权限问题前面提到的setnamedsecurityinfow failed (win32)我再补充几个排查思路。第一确认当前账号是否对工作目录有“修改”权限而不仅是“读取”权限。第二确认路径所在磁盘是 NTFSFAT32 和部分网络映射盘对 ACL 的支持很有限。第三检查是否有安全软件拦截了 ACL 写入操作。很多人的第一反应是“给 AI 更高权限”但我实测下来反而应该“给 AI 更低权限”用普通账号、干净的用户目录、最小授权问题基本能解决。5.3 模型响应不稳定与上下文超窗AI 在长任务里经常出现“前面记得规格后面开始自由发挥”的问题。这跟上下文窗口被撑爆有关。我的做法是把规格文件做“双份”——完整版用于起始注入精简版用于任务中途刷新。在 Harness 的工作流里加一个“context-refresh”步骤当任务超过一定轮次时重新注入精简版的规格摘要把 AI 拉回正轨。另外尽量把大任务拆成小任务每个任务只围绕一个规格文件展开不要在同一个会话里连续处理多个功能否则上下文混乱几乎必然发生。5.4 回退后工作区不一致回退之后有一种情况容易忽略AI 生成的配置文件或缓存文件没有被快照覆盖。比如它写了.harness/cache/xxx.json你回退代码时这个文件还在后续任务读到的还是旧缓存。我的经验是除了代码文件把cache、tmp、logs等目录也加入快照清理范围保证回退后工作区跟快照时刻完全一致。宁可在回退时多清一点也不要在排查“哪里不对”时多花两个小时。写在最后的个人体会这套体系我跑了几个月最大的感受不是“AI 变聪明了”而是“团队对开发的确定性变高了”。以前代码评审要反复追问 AI 怎么得出这个实现现在规格文件、规则日志、工作流记录都在那里评审变成了核对流程效率反而上去了。我最后再分享一个小技巧规格文件和规则配置写完之后一定记得在团队内部沉淀一份操作手册把你们自己踩过的坑、定过的规则、常用的插件组合都记录下来。我见过太多团队只在个人电脑里配好了 Harness换个人、换台机器就全乱套。这套东西的价值不在于某个人的奇技淫巧而在于它能不能成为团队可以复制的基础设施。AI 辅助开发这条路还很长但“先立规矩再驭工具”这个方向我实测下来很稳。