1. 为什么要用SDD Harness做AI全栈开发1.1 盲目让AI写代码等于给自己挖坑先说结论让大模型直接“给我写一个某某系统”大概率只能得到一个能跑通最小主流程、但离交付还有十万八千里的半成品。在我过去做AI辅助开发的经验里第一版生成的质量往往取决于提示词写的详细程度但哪怕提示词写得很细模型还是会频繁出现这几个问题——数据库字段前后不一致、一个接口在三个地方定义了三套DTO、前端拿到的数据结构和后端的真实返回对不上、边界条件没人处理。这些问题单独看都不致命攒到一起就是灾难。真正的问题不在大模型的能力而在需求进入编码之前的那一段路。传统的开发流程是人类需求分析师把业务变成PRDPRD再被工程师翻译成技术方案中间每一道翻译都会丢失信息。换成AI开发之后这段翻译变得更野蛮提示词输入进去模型按它的概率理解输出一个“自认为合理”的系统没人真正较真需求是否说清楚了也没有人在动手前定义“什么叫做完”。SDDSpecification-Driven Development规范驱动开发解决的就是这一段问题。它把“模糊想法”强制变成“结构化规范”让AI在动手之前就拿到一套明确的行为约束。你可以把规范的编写者理解成需求方的翻译官把AI理解成一个动手能力极强、但不太喜欢追问的新人工程师。给新人说清楚验收标准他交出来的东西才有谱一句话“做个系统”打发出去他给你的就是一锅乱炖。1.2 规范驱动不是流程负担而是给AI看的“需求说明书”很多人一听“写规范文档”就觉得重觉得敏捷开发不搞这些。但SDD在AI开发语境里其实相当轻量它和传统的重量级需求文档有个核心区别传统文档是给人看的重点是讲故事而SDD规范是给AI看的重点是条目化、可验证、无歧义。我自己的实践里一份合格的SDD文档不需要长篇大论但必须包含四个部分功能清单、数据规范、验收标准、变更记录。功能清单不要写“用户可以登录”这种话要写“用户使用邮箱密码登录密码经加密存储登录失败连续5次则锁定账号30分钟”。数据规范要定义实体有哪些字段、类型、约束和关联关系这部分直接决定数据库表结构也要决定前后端通信的数据协议。验收标准更关键每一条都要能转成测试用例能写成自动化断言而不是“体验流畅”这种无法验证的形容词。这套规范的价值在AI编程时体现得很明显它不是把项目需求“翻译”给模型而是在需求还没变成代码之前先把需求本身锁死了。AI后续跑偏了你不用从头跟它解释业务逻辑直接指到规范第几条就行。调试和回溯的成本从“重新写一遍完整上下文”降到了“指出偏差条目”。1.3 Harness把AI从一个写代码工具变成项目交付引擎SDD解决了“做什么、做到什么程度”的问题Harness解决的是“怎么稳稳当当地把这件事做完”的问题。我在项目里使用的Harness本质上是一个AI工程化工作流编排层它通过插件体系和工作流配置把大模型能力组织得像一条自动化生产流水线。你可以给不同的任务定义不同的角色模型、上下文策略、工具调用权限和检查节点。打个比方裸用AI编程就像直接操作一台没有安全罩的数控机床功能没问题但误操作代价很高。而Harness之于AI开发相当于给这台机床装上了PLC控制器和安全联锁需求进来走什么流程、哪个节点需要人工确认、每个步骤的输出怎么校验、出错之后怎么回滚这些都是可配置、可记录、可复现的。热词里经常看到“deepseek harness”、“harness工程”这些说法我理解它们指的就是同一种用法把国产大模型接入Harness工作流让AI Agent沿着既定的工程轨道去执行任务而不是每次都在聊天窗口里重新“自由发挥”。项目做到后期我最大的感受是提示词、模型选型、上下文窗口这些东西都不再是瓶颈瓶颈变成了“流程有没有被固化下来”而这个恰恰就是Harness的强项。2. 我的SDD规范模板一份能指挥AI的需求文档怎么写2.1 需求条目化每条需求都必须能单独验收在实际项目里我用的SDD文档分五个区块每个区块都有固定的填写格式。功能需求这块每一条都用“当XX场景发生时系统需要做什么并且必须满足XX约束”的句式。例如“当用户提交重置密码请求时系统需要在30秒内向绑定邮箱发送含唯一链接的邮件链接12小时内有效且只能使用一次”。这种写法有三个好处模型可以直接据此生成对应接口和逻辑测试人员能直接写用例业务方也能看懂需求是否满足了。数据规范这块我会直接列出实体关系、字段名、类型、默认值、空值策略、索引要求。还是那句话数据库是AI最容易出错的地方两个模块各建一张表、字段名大小写不一致、把用户ID存成字符串还是整数这类问题几乎每个AI项目都会出现。所以数据规范必须先行而且越细越好。2.2 验收标准从需求描述变成可自动化验证的断言验收标准是我的SDD里最关键的板块。我的原则是AI生成的代码能不能合入主干不完全靠Code Review而是靠自动化验收用例是否跑通。每一条验收标准都要有可执行的验证动作例如“用正确的邮箱密码调用登录接口必须返回200和token用错误密码连续调用5次第6次必须返回账号锁定提示”。这些标准我会直接写成Gherkin风格或断言列表顺手就能转成测试代码。这样做还有一个隐藏好处验收标准写清楚之后AI规划技术方案时会主动贴近标准去实现因为这比让它按照自己的“默认偏好”写更容易获得后续过程的肯定信号。这其实符合大模型对齐的基本逻辑——你用一个明确信号体系给它做对齐它产出结果的质量就会围绕这个信号体系稳定。2.3 变更记录与边界约束让AI不碰它不该碰的东西除了正向需求我还会在SDD里明确写“非目标”和“边界约束”。比如“本期不做社交关系链、不做消息推送、不使用外部存储服务”“所有文件只允许上传至本项目后端、大小不超过10MB”。这些内容看起来多余实际上非常重要。AI最擅长“自由发挥”你告诉它做任务管理它能顺手给你生成一个公告板、一个评论系统、一个站内信模块。边界约束写清楚之后模型跑偏的概率大幅下降。变更记录的设计则是为了应对迭代式对话。我会在文档最下面保留一个变更表记录每次需求调整内容、日期、原因。每一轮跟AI对话前把更新后的规范文件作为上下文给到工作流让模型在旧内容基础上只做增量修改而不是整体推倒重来。这一点配合Harness的会话管理特别好用上下文不会越聊越乱。3. Harness工程化实操从安装到跑通全栈流水线3.1 环境准备与安装细节我目前常用的Harness环境是基于本地运行的工作流插件方案。安装过程不算复杂但有几个坑值得拿出来说。首先是环境依赖。Harness运行时依赖Node.js和Python双环境两边的版本要求都不低我建议Node用18以上、Python用3.10以上。装的时候直接按官方文档走的基本顺利但如果你用的是Windows以外的系统注意部分编译型插件需要额外安装构建工具链没有的话在安装插件阶段就会报错。其次是模型接入配置。Harness本身不自带大模型推理能力它通过配置密钥和模型端点来接入各类模型服务。我在项目里同时接入了DeepSeek和Claude的API给不同的工作流节点配不同的模型。写SQL、造测试数据这类结构化任务用DeepSeek因为速度快且便宜需求拆解、架构设计这类长链思考任务用Claude原因是长程推理指令跟随更强。3.2 工作流编排让AI Agent沿着工程轨道走安装好之后重点就是配置工作流。我把一个典型全栈需求拆成了六个阶段需求解析、架构设计、后端实现、前端实现、联调验证、迭代返工。每个阶段都是一个独立节点节点之间传递结构化数据。需求解析节点做的工作是把SDD规范文档喂给模型让模型输出技术方案包括表结构设计、接口清单、页面清单。这个输出我会人工过一遍确认没问题后再让工作流继续。架构设计节点根据技术方案生成更细的模块划分和代码实现计划。后端实现节点只负责生成后端代码前端实现节点只负责前端代码联调节点则负责起服务、跑接口测试。这里有一个关键配置不要让AI同时改前后端否则接口对不上时你不知道是前端错了还是后端错了。把边界切清楚错误定位的效率会高很多。每个节点完成后Harness会把产出物归集到指定目录并打上标签方便回溯。3.3 自动化测试与持续回归的接入全栈项目的联调阶段是最折磨人的模型生成的前后端即便单独看都“合理”合在一起也可能出现字段名不匹配、路由参数不对、跨域配置缺失这类问题。我的做法是把自动化测试作为工作流的强制卡点。具体是三步。第一步在需求解析节点输出接口定义文件以OpenAPI规范为标准。第二步用这个接口文件同时约束后端代码生成和前端Mock数据的生成前后端都按同一份契约来字段不一致的概率会被压到最低。第三步每次代码生成后自动执行一轮接口级测试用真实HTTP请求验证关键路径。我最常跑的是一份70多个断言的全栈主流程测试覆盖注册登录、创建任务、修改状态、分页查询、权限校验这几条核心链路。Harness任务卡点设置为“测试通过才能交付”实测下来一次迭代的返工次数从裸用AI时的平均四轮到五轮降到了一到两轮。4. 实战案例一个带用户体系的轻量任务管理系统4.1 需求背景与SDD文档拆解这个项目是一个带JWT鉴权、支持多用户任务的轻量任务管理系统前端用Vue3 Element Plus后端用FastAPI。项目本身不复杂但刚好覆盖全栈开发的完整链路我用SDD Harness跑完整套流程。规范文档的功能清单部分我写了15条需求其中有几条值得展示一下。比如“任务创建时用户可以选择截止时间但截止时间必须晚于当前时间创建成功后系统返回任务对象和待办提示”。又比如“非任务创建者或非管理员访问任务详情时接口必须返回403且操作记录中要保留这次越权访问的日志信息”。数据规范部分我定义了用户表、任务表和操作日志表。用户表包含ID、邮箱、密码哈希、昵称、角色、创建时间任务表包含ID、标题、描述、状态、优先级、截止时间、创建人ID、分配人ID操作日志表包含ID、用户ID、动作类型、目标对象、时间戳。为了让AI不发挥我甚至规定了每个字段的长度范围和精度。验收标准部分写了22条全部转换成自动化断言之后编码阶段的工作就变得非常机械AI只需要照着规范写实现然后让测试跑一遍看哪里红了。4.2 Harness工作流中的实际执行记录工作流跑起来之后真实情况比预想的顺但也有意外。前端生成阶段出现过一次组件层级混乱的问题模型生成的页面目录里有一半组件是重复的一个弹窗组件被定义了四次每次的内容还略有差异。这个问题的根因是需求描述里写了“任务弹窗”而规范里没定义“哪些信息通过弹窗展示、哪些直接展示在页面主区”上下文里缺乏约束条件模型就自行发挥起来了。发现这个问题后我做的第一件事不是让AI重写而是往SDD文档补充了一条边界“任务的新建和编辑功能统一在右侧抽屉中实现不在页面中引入额外弹窗组件”。然后把文档更新到Harness工作流的上下文中重新触发前端生成第二次出来的页面结构就干净了。后端部分的执行比较顺利因为数据规范和接口契约定义得早模型生成的CRUD代码基本是“一次过”。联调阶段有个小坑任务列表的分页参数前端传的是page和pageSize后端定义的是skip和limit两者在联调时对不上接口返回504的数据结构完全正确但前端把skip当page用第二页数据永远为空。这种问题在传统开发中靠人眼排查也不难但放在AI协作里如果契约文件不统一AI会各写各的而且都觉得自己没错。这也是为什么我在第三节反复强调OpenAPI契约文件的重要性。后来我在SDD规范里把分页参数统一成page和pageSize并把契约文件同时注入前后端节点问题再没出现过。4.3 交付效果与时间成本整个项目从需求整理到最终交付大约用了一个专项工作日的时间产出包括7张数据表、22个API接口、18个前端页面、70多个自动化测试断言以及一份完整的接口文档。如果按传统开发方式排期这个体量的项目通常需要一周到十天。效率提升是实打实的但我也必须强调前提是SDD规范文档本身花了半天时间打磨Harness工作流也花了小半天配置这些准备成本不会凭空消失它们只是换来了后面开发阶段的高效率。5. 常见问题排查与避坑实录5.1 harness failed to load plugins 的经典排查路径“harness failed to load plugins”是我在群里看到大家问得最多的一个报错自己也遇到过。这个报错绝大多数情况下不是插件本身坏了而是插件加载路径或者依赖环境出了问题。先检查插件安装路径是否包含中文或空格。我遇到过一次插件放在带空格的目录里运行时加载机制解析路径出错报错信息没有任何可疑之处最后是逐条环保路径才发现的。再检查Node和Python版本是否匹配插件是编译型的话版本不匹配几乎必挂。最后看日志里有没有“did not activate”这个关键字如果有说明插件加载成功了但插件注册时依赖的某些扩展点没有初始化常见原因是启动顺序问题可以先启动主程序再手动触发插件激活。5.2 插件激活失败的常见原因热词里有“web boot: 2 entries did not activate”这个提醒这描述的情况是插件加载时有多个条目没有自我激活。我被这个坑坑过两次。第一次是我在配置文件中启用了插件A但忘记安装它的依赖插件B导致A在初始化时找不到B的服务直接放弃激活。第二次是我把同一份配置文件拷贝到了两个不同环境其中一个环境缺少某个系统库插件加载到一半就静默失败了日志里只留下一行“did not activate”。建议的做法是每次换环境后先用最小配置跑一遍确认核心插件能激活再逐步加插件不要一次性把一个完整项目配置搬到新环境里。还有一个排查技巧看Harness工作目录下的运行时日志时把等级调到DEBUG插件注册过程中发生了什么一目了然。5.3 AI全栈协作中的三个常见逻辑坑除开工具本身的报错AI编程阶段我踩过的三个逻辑坑也很值得分享。第一是时间相关字段的默认值。模型生成后端时创建时间的默认值有时候给了“当前时间戳”有时候给了“NULL”而这直接导致前端展示时间时出现NaN或1970年。我后来在数据规范里明确写上“所有时间字段不允许为空由服务端生成”这类问题就消失了。第二是状态机的隐含约束。任务状态从“待办”到“进行中”再到“已完成”这个流转是单向的但AI在实现时不一定会有状态合法性校验直接就能把“已完成”改回“待办”。这就需要SDD里明确写出“任务状态不允许回退”“已完成的任务不允许修改标题和描述”否则测试阶段总会有漏网之鱼。第三是权限边界。很多AI项目在没做权限校验时功能完全正常一旦给普通用户发一个管理员的请求系统直接放行。这倒不是AI故意留后门而是因为“权限”本身是所有业务系统的横切关注点模型生成每个接口时只关心它自己的输入输出很少主动往一个中间件里塞鉴权逻辑。我在Harness工作流里专门加了一个“安全攻防测试”节点自动生成越权请求去怼接口这些问题就变成了自动化就能发现的常规问题。6. 后续扩展方向与我的几点体会6.1 从AI写代码到AI维护代码SDD Harness这套组合目前帮我把“从零开发”的效率提上去了但更让我在意的是在“后续维护”里的扩展可能。以前项目上线后改一个小需求要重新梳理上下文现在规范文档本身就是项目的一部分新需求来了直接在文档里增量追加一条Harness工作流会自动识别变化范围只重跑受影响的功能模块测试。这个工作方式的下一步是引入变更影响分析能力让AI对比新旧规范标记出可能受影响的接口和页面。虽然现在大模型做精确影响分析还有误差但已经能帮人省掉大量重复比对工作。6.2 拆解提示词与规范文档的关系不少人问我SDD规范文档和写提示词有什么区别。我的体会是提示词是“任务指令”解决的是“这一步让AI干什么”SDD规范文档是“项目宪法”解决的是“这个系统到底长什么样”。提示词每次对话都可能被遗忘、被修改而规范文档作为工作流上下文被反复注入会持续约束AI的行为。所以我不再过度追求一次性把提示词写得惊艳而是专心把SDD文档的生命周期管理好让它在迭代中被持续维护、被验证。提示词反而可以保持稳定、简洁每次都是那句“严格按照规范文档执行输出可合并的代码变更”。6.3 对个人开发者团队的一点建议如果你是一个个人开发者或者两三个人的小团队我强烈建议不要跳过分层直接裸用AI写全栈。你可能会觉得前期写规范文档浪费时间但不写的代价在后期会翻倍还回去——需求大改时模型全部重来、前后端数据衔接一团乱、测试靠人肉一遍遍点页面。SDD Harness本质上是用一种工程纪律来对冲大模型的不确定性纪律要花时间建立但它是唯一能让AI产出价值从“玩具级”稳定提升到“产品级”的路径。我的最终建议是从一个小项目开始先习惯写SDD式的需求文档然后在Harness工作流里只规划三个节点需求解析、代码生成、联调测试。跑通一个最小闭环之后再去扩展节点、加插件、做自动化回归。不要一上来就搭一个复杂的多渠道协作集群工程化是循序渐进的过程不是一次到位的魔法。这套方法我现在已经固化成了自己的默认开发流程每接到一个新需求先写规范再跑流水线最后收测试报告AI写代码的效率和质量能兑现到什么程度取决于你为它铺了多结实的轨道。