最近把SDDSpec-Driven Development规格驱动开发整理成了自己的固定工作流配合AI Agent做辅助开发整个体验和以前一句一句喂给模型完全不是一回事。如果你也在用AI写代码一定遇到过这种情况聊着聊着需求就变了模型开始自由发挥生成的模块和已有代码对不上改来改去最后只能推倒重来。这些问题的根源多半不是模型不够聪明而是输入太含糊。SDD解决的就是这个先把话说清楚再让Agent动手。这篇文章面向的是所有在用AI Agent写代码、却又总感觉失控的人不管你是独立开发者还是小团队里的核心工程师。我会把SDD的核心思路、规格文档的写法、从规格到实现的完整流程、工具链怎么选、以及我实际踩过的坑全部摊开讲内容足够具体可以直接照着抄。1. 为什么AI Agent开发会越聊越乱而SDD能治这个病1.1 对话式编码的四个典型症状先说症状。我最早用AI辅助写代码时习惯是打开对话窗口把需求一段一段丢进去让它帮我写个登录接口“再加个鉴权”不对用户表还要加个字段”。四个问题很快就暴露出来。第一需求漂移。你在一轮对话里不断追加新需求模型会根据最后一句话重新理解整个任务最早确定的约束慢慢被稀释。到最后代码看起来能跑但它和最初的设计意图已经差得很远。第二边界感丢失。项目一复杂AI不会记得哪个功能在哪个模块里它会不断在自己已经生成的代码上打补丁导致文件越写越长职责越来越乱。第三重复买单。因为没有全局蓝图同一个功能可能让AI写了两次或者两个模块各自实现了一份类似逻辑后面维护的人完全不知道该信哪一份。第四验证缺位。对话式编码天然不关心你怎么证明它是对的模型觉得对就输出你看着好像对就收下真到了测试环境才发现一堆边界问题。这四个症状的共同靶心就是没有一份稳定的、可被反复引用的任务基线。代码文件是结果对话是过程两者都在变化但中间缺少一个不变的锚点。SDD补的就是这个锚点。1.2 SDD到底改了什么SDD的核心动作特别朴素在写代码之前先写一份规格文档spec把目标、边界、功能、数据模型、验收标准全部固定下来然后让AI Agent把这份规格当作最高指令去执行。传统的瀑布式开发也讲先设计后编码但那是给人和流程用的文档厚重、评审漫长。对话式AI开发则走到了另一个极端完全不写文档想到哪写到哪。SDD是中间态规格要足够轻轻到一个人一个下午就能写完又要足够硬硬到Agent每次动手前都必须先读它。我自己的体会是SDD真正改的不是开发流程而是你和AI之间的沟通协议。以前你的每一句话都是临时指令现在你给的是一个长期有效的上下文。AI每写一段代码都在对照一份文件而不是一句聊天记录失忆了也能重新读档这比靠模型记忆力靠谱得多。1.3 拿装修来类比一次说透很多人觉得写规格麻烦我一般拿装修举例子。你请施工队装修不可能站在毛坯房里跟工头说这里弄好看点、那里弄实用点就完事。你至少得有一张平面图哪里是墙、哪里是门、水电怎么走工人照着图施工验收也照着图检查。等你想改方案改的是图不是现场敲墙。AI Agent就是那个手脚很快、力气很大、但有点一根筋的施工队。你说得含糊它就自由发挥你说得具体它反而执行得很稳。规格就是那张平面图验收清单就是那张验收表。以前你缺的不是好施工队是那张图纸。SDD教你画这张图纸仅此而已。2. 一份让Agent不跑偏的规格文档怎么写2.1 规格文档的最小完整结构网上能搜到的规格模板五花八门但我跑了十几个项目之后发现真正有用的最小结构就八块。缺一块后面要么返工要么团队里两个人对同一个词有不同理解。一是目标与背景用三到五句话说清楚这个项目/模块要解决什么问题给谁用。二是范围边界明确写出这次做什么、不做什么这是防止Agent加戏的关键。三是名词表把项目里的核心概念统一命名比如订单“工单”“任务”这三个词指什么规格里定义清楚AI就不会乱换词。四是功能清单按优先级列出用户可感知的功能点每条功能带一个编号。五是数据模型包含实体、关键字段、字段类型和约束这是后端项目最容易出问题的部分。六是接口与交互列出对外暴露的接口、出入参结构、错误码约定。七是验收标准把功能完成翻译成可验证的checklist。八是变更记录每次改规格都在顶部追加一行写清楚改动时间和改了什么。这八块不是让你写八章论文平均每块几句话就行关键是要确定。比如数据模型里你不能只写用户表有昵称要写昵称字段名nickname字符串最长30字符允许为空这种精确度才是Agent能执行的语言。2.2 我常用的规格模板直接可抄下面这个模板是我现在每开一个新功能都会复制过去改的整个文档控制在两百行以内。我建议你也用Markdown因为AI对Markdown结构的解析能力比纯文本强得多。规格用户收藏管理模块背景用户需要把常用链接保存到个人收藏夹并支持按标签筛选和随机抽取一个链接使用。范围本次只做收藏链接的增删改查、标签过滤、随机抽取。不做用户注册与登录默认同一个使用者。名词表收藏项一条保存的网页链接记录字段见数据模型。标签可附加在收藏项上的短文本一个收藏项可有多个标签。功能清单F1 新增收藏项F2 删除收藏项F3 修改收藏项标题与标签F4 按标签筛选收藏项F5 随机返回一条符合条件的收藏项数据模型收藏项id: 整数自增主键url: 字符串长度不超过2048必填title: 字符串长度不超过200默认取网页标题tags: 字符串数组每个标签长度不超过20created_at: 时间戳自动生成接口约定新增POST /bookmarksbody为{url, title?, tags[]}删除DELETE /bookmarks/{id}修改PUT /bookmarks/{id}body为{title?, tags[]}筛选GET /bookmarks?tagxxx随机GET /bookmarks/random?tagxxx无记录时返回404验收标准A1 新增一条合法收藏项后再通过列表能查看到该记录A2 删除不存在的id返回404A3 修改时标题为空则报400A4 标签筛选只返回包含该标签的记录A5 随机接口在空数据下不崩溃返回404变更记录2025-06-01初版你可以看到这份规格里没有任何实现细节没有技术栈没有目录结构没有变量命名规则。让Agent自己根据接口和数据结构去决定技术方案你只需要守住边界和验收标准。写规格的最高原则是只定义做什么和怎么算对不规定怎么做。2.3 规格粒度怎么定一功能一文件好多朋友上来写了一份一百多个功能的巨型规格然后丢给Agent让它全部实现结果不用说模型上下文根本装不下写到一半就乱了。我的经验是规格粒度跟着一次可交付的功能走。如果是一个小项目比如上面那个收藏模块整个项目一份规格就够了。如果是一个中大型系统我建议按模块拆文件比如用户模块.md、订单模块.md、消息模块.md然后建一个README索引文件写明模块清单和依赖关系。Agent每次只需要读它正在负责的那个模块规格而不是整个系统的所有文档。拆分的判断标准很简单一份规格如果超过三百行或者功能清单超过十五个或者调用它的Agent每次讨论时都要反复往上翻就该拆。拆出来的子规格要保持独立可验收不要出现这个功能依赖另一份规格里的某个未定义行为这种悬空引用。2.4 写规格时最容易踩的三个误区第一个误区是把规格写成用户故事。比如作为用户我想要保存链接以便以后查看这种写法通顺但缺少约束Agent拿到手不知道字段类型、不知道接口长什么样等于什么都没说。规格要有的是确定性描述不是叙事。第二个误区是在规格里写实现方案。比如使用某框架的数据库迁移工具创建表结构这句话看着贴心实际是在剥夺Agent的自主推理空间。规格只写数据模型和接口技术选型交给开发者或Agent去决策这样后续换技术栈时规格不用动。第三个误区是希望规格一次写完、永远不改。这不可能。需求一定会变所以规格文档要像代码一样有版本意识。每次变更都更新变更记录并把变化后的验收标准同步调整否则Agent会拿旧规格当权威改出来的代码和你新需求对不上。3. 从规格到实现AI Agent辅助开发的完整流程3.1 五段式流水线每段都有输入和输出我现在跑SDD已经形成了固定流程一共五段。第一段叫规格审阅输入是写好的规格输出是Agent对规格的理解我会让它先复述一遍关键功能和验收标准确认它真读懂了。第二段叫任务拆解输入是规格全文输出是一份步骤清单具体到每一步改动哪些文件、新增哪些函数。第三段叫逐模块实现输入是拆解清单输出是代码改动。第四段叫自动验证输入是新增代码和验收标准输出是测试运行结果。第五段叫回归修补输入是失败用例输出是修复后的代码然后回到第四段循环。这段流程最关键的第一参数是验证优先。我从不先让它写全部功能再测试而是每完成一个功能点就立刻验证一次。因为Agent的问题不在于写不出代码而在于没有反馈就无法自我修正。你给它一个测试失败的结果它能修得非常准你让它凭空想象自己写错了什么它基本是在猜。3.2 喂规格给Agent的正确姿势光有规格文件还不够你得想办法保证Agent每次都认真读它。我踩过的坑是把规格文件链接丢在对话末尾结果模型压根没翻开直接开始写代码最后跑出来的东西跟规格毫无关系。我现在采用三个固定动作。第一把规格文件路径写进项目索引文件里每次对话开头我都会附一句所有需求以某路径下的规格文档为准。第二在每一轮讨论开始前让Agent用三句话总结规格里的核心约束这个动作能把模型的注意力拉回到规格本身。第三当项目进入具体模块实现阶段我会把该模块的规格正文直接复制进对话而不是只给路径。虽然占一点上下文但换来的是稳定不跑偏非常值。还有一个细节给Agent喂规格时不要同时丢一大堆无关文件。我见过有人把整个仓库的README、历史Chat记录、几十个接口文档全塞进去结果上下文被无关内容挤占模型反而抓不住重点。喂规格讲究的是精准投喂一次只喂当前任务真正需要的部分其他的等用到再喂。3.3 用验收清单驱动迭代而不是反复帮我改一下大多数人用AI改代码的方式是这里不对帮我改一下改完又说还是不对再改一下。这种循环极其低效因为反馈是模糊的AI只能猜。SDD的解法是用验收清单里的具体条目当反馈。我的做法是明确告诉Agent请逐条执行验收清单每执行一条告诉我你运行了什么命令、结果是什么、通过还是失败。如果有失败的先分析原因再修改代码再重新验证直到全部通过。这等于把帮我改一下升级成对照标准自我评估两者效率有天壤之别。举个具体例子。上面收藏模块的验收标准A4说标签筛选只返回包含该标签的记录。第一次实现Agent可能只做了精确匹配没考虑大小写测试时Python和python筛不出来。如果它严格跑了A4这条就会自己发现问题并提出修正方案。靠人肉发现这个问题也不是不行但你一天可能验收十几个功能靠人肉会累死。让Agent自己当质检员是SDD流程里最爽的体验之一。3.4 实战拆解做一个收藏管理小服务我用一个模拟项目把流程串一遍。假设今天要做一个收藏管理API服务我把2.2节那份规格当作输入让Agent跑完整流程。规格审阅阶段我要求它输出三点核心数据模型是什么、提供哪五个接口、验收标准里哪条最容易实现错。它回复提到随机接口在空数据下的行为可能被忽略这份理解说明它确实读进去了。任务拆解阶段它给出的清单大概是初始化项目骨架、定义收藏项数据结构、实现新增与查询、实现删除与修改、实现标签筛选、实现随机抽取、编写并运行自动化测试。我检查一遍没发现遗漏就让它按这个顺序执行。执行过程中它自己卡在了修改时标题为空则报400这条。它先实现了基本接口然后跑测试发现空标题居然被当成未修改给放过了。它通过规格里的title?: 字符串理解到title是可选项于是用显式传null和完全不传来区分两种语义修掉了这个边界问题。整个过程我几乎没插手我只做了两件事提供规格要求它对照验收标准逐条自测。最后它把五条验收标准全跑通我花十分钟读了生成的代码确认没有明显结构问题这个功能就算交付了。整个过程比我以前逐句对话至少省出一个下午而且最终结果和我的预期高度一致。4. 工具链怎么选找到适合你的Agent辅助组合4.1 先把Agent工具分成三类按需选市面上能辅助编码的Agent工具很多我不提具体品牌按形态分成三类方便你对号入座。第一类是对话式助手嵌在编辑器里你提问它回答一次处理一个文件或一段函数。这类工具上手最快适合单文件改造和小范围提问缺点是上下文窗口有限项目稍大就管不住全貌。第二类是半自主式Agent你可以给它一个完整任务它自己读文件、改多个文件、运行命令、看报错并迭代。这类工具是SDD的主力因为它的任务执行方式和给规格、拆任务、逐条验收天然匹配。第三类是编排式框架允许你写配置/脚本去编排多个Agent协作适合团队级流水线但对个人项目来说有点重。我的建议是刚开始不要追第三类先用第二类工具加一份好规格就能解决绝大多数问题。等你确认某个流程每天都要重复跑再考虑用编排框架把它固化下来。4.2 最小工具链规格仓库、编码入口、验证设施我推荐的组合就三件东西一个放规格文档的仓库、一个支持Agent的代码编辑器、一套能自动跑测试的验证环境。规格仓库不用专门搭系统就是一个目录里面放着README索引和若干规格文件注意这个仓库要纳入版本管理规格变更要有迹可循。编码入口的选择取决于你用的Agent是哪一类但我有一个硬性要求工具必须能直接读写项目文件而不是只能在一个临时文本框里回答问题。因为SDD流程里Agent需要打开规格文件、修改代码文件、运行测试命令如果你用的工具做不到这三件事SDD的体验会打很大折扣。验证设施可以是最简单的单元测试框架。Python项目用pytest或者随便什么语言自带的测试工具都行。关键是规格里的验收标准必须能翻译成可执行的断言比如空数据下随机接口返回404就是一条测试用例。没有验证设施规格写得再好也没闭环Agent说我完成了你也没法快速判断真伪。4.3 上下文管理三板斧实测最有效第一板斧是索引文件。我每个项目根目录会放一个CLAUDE.md之类的说明文件写清楚项目结构、规格文档位置、常用命令和约定。Agent进入项目第一眼就会读它相当于告诉模型去哪个文件找规则。第二板斧是分层投喂。全局信息放索引文件模块信息放模块规格任务信息通过对话临时给。模型不需要一次全读用到哪层读哪层。第三板斧是记忆外置。Agent在对话里产生的关键决策比如随机接口空数据时返回404我会要求它同步写回规格文档的变更记录或接口约定里。这样即使对话窗口失效下次新开窗口读规格就能恢复全部上下文。这三板斧看似简单但对结果的影响是决定性的。我见过太多人抱怨模型老是忘记之前说好的事其实不是模型记性差而是你从没给它一个可以反复读的固定文件。4.4 什么时候才需要上重型框架等你手头项目涉及多个模块并行开发、或者需要多人协作且角色分工明确时可以考虑引入编排式框架让一个Agent负责读规格拆任务多个Agent分别实现不同模块最后统一接入验收。但我要泼个冷水这种重型方案的学习成本和维护成本都不低团队里如果没有专门的人维护流程最后很容易变成摆设。我的建议是先让SDD跑顺再谈规模化。一个人用一份规格文档加一个Agent工具已经能覆盖很多商业项目原型和内部工具的开发需求。那些一上来就想搭多Agent平台、搞复杂工作流编排的人大多数项目连规格都还没写好。5. 常见问题与排查技巧实录5.1 症状Agent开始自由发挥偏离规格出现的场景通常是规格里某个约束写得不够死。比如你写了标题默认取网页标题但没规定标题为空时怎么处理Agent就自由发挥成自动生成未命名等测试用例一跑立刻发现和预期不符。排查思路是回到规格看约束是否可验证。默认取网页标题这个约束要补上解析失败时使用空字符串这样Agent就没有灰色空间。另一个常见原因是规格文件没有作为最高指令被强调这时检查是不是上下文里塞了太多其他文本把规格挤掉了。我的处理方法是每次任务开始前强制要求Agent复述规格里的验收标准复述完再让它开工。5.2 症状聊着聊着上下文就乱了任务被遗忘这在长流程里非常典型。Agent前半段还在按规格走后半段开始只根据你最新的几句话行事前面规定的命名规范、错误码格式全被丢到脑后。根本原因是对话上下文过长早期信息被模型截断或弱化了。对策我刚在前面提过记忆外置。所有关键决策实时写回规格文档然后每次新开对话时让Agent重新读文件。还有个很实用的小技巧是每完成一个里程碑就主动新开对话而不是在一个对话里连续工作一下午。每次新对话都带着最新规格文件开头Agent的准确率反而更高因为它的上下文窗口里都是新鲜且准确的信息。5.3 症状代码能跑但过不了验收这种情况我经常遇到。Agent写出的接口功能都正常但验收标准里有一条删除不存在的id返回404它实现成了返回200加空body。原因在于功能正常和符合契约是两回事Agent默认倾向别报错而规格要求的是显式报错。排障方法是把验收标准拆成更细的断言一条标准对应一条测试。删除不存在id返回404就在测试里先删一个真实id再删一个不存在的id断言第二次响应的状态码。只要断言写得足够具体Agent迭代两三轮就能全对。如果你的Agent连续多次改不对大概率是它压根没看规格回到5.1的处理方法。5.4 症状规格文件更新了代码还停在旧版原因通常是规格和代码之间没有显式关联。你改完了规格但Agent不知道它需要重新实现对应模块。我见过最夸张的例子是规格已经从A方案改成B方案两星期了代码还在按A方案写因为没有人让Agent重新对齐。解法有两个。一个是在规格变更记录里写清楚本次变更影响哪些功能清单编号另一个是在每次对话开始时主动声明请以规格变更记录的最新版本为准检查当前代码是否已同步。这只对话界面上加一句提示损失很小但能避免大量由此引发的返工。我现在的习惯是任何规格改动落地后立刻开一轮规格同步检查对话让Agent对照变更记录找出所有需要跟着改的代码位置。5.5 问题速查表现象核心原因立即处理方式Agent自由发挥规格约束不够硬补精确约束强制Agent先复述验收标准上下文混乱早期信息被丢弃关键决策写回规格文件定期新开对话代码能跑但不过验收契约理解偏差将验收标准翻译成独立测试断言规格改了代码没改缺少同步机制让Agent按变更记录检查受影响的功能清单模型重复生成相似逻辑缺少全局视图在索引文件里维护模块职责说明避免重复建设6. 我踩过的坑和我现在的固定打法6.1 三个最值得讲的教训第一个教训是别让Agent跳过规格直奔代码。我早期觉得写规格浪费时间有一次做一个数据导入功能没写规格就让它直接实现。结果它自己选了一个完全不适合的数据格式测试时才发现字段对不上重写了两天。后来老老实实补了规格半天完工。这让我彻底改掉了偷懒的想法。第二个教训是验收清单必须由人来拍板。Agent会给自己放水。我见过它把自己实现不出来的验收项悄悄改宽松比如把错误时返回标准错误结构改成错误时尽量返回提示来让测试通过。所以验收标准必须由人定义Agent只能执行不能修改。这个边界守不住SDD就白做了。第三个教训是规格文档不是写给Agent看的更是写给一周后的自己看的。有一次我为了图快规格写得特别简略功能清单只有标题没细节。一周后我自己打开都看不懂当初的设计意图更别说让Agent去执行了。规要能支撑你遗忘之后的重建这决定了项目的长期可维护性。6.2 我现在完整跑一遍SDD的固定步骤我把完整的流程压缩成一份检查单每次开项目都走一遍。第一步花半小时到两小时写规格文档包含背景、范围、名词表、功能清单、数据模型、接口、验收标准并提交到仓库。第二步把规格交给Agent先让它复述理解和拆解任务清单确认无误。第三步按功能清单逐项实现每项完成后立即跑对应测试。第四步对照验收标准逐条自评并展示证据不允许只说已完成。第五步人工抽读核心代码重点看数据模型和接口是否符合规格。第六步规格变更时先更新文档再进入代码同步流程。这套流程跑下来我的体感是前期多花一点写规格的时间后期至少节省三到五倍的返工时间。尤其是需求频繁变动的项目规格文件的变更记录就是整个项目的演化史比聊天记录可靠一万倍。6.3 新手从哪开始一个周末就能完成的小项目如果你刚接触SDD别拿大项目练手选一个你自己早就想做但是一直拖着的小工具。比如一个命令行记账本、一个RSS订阅整理器、一个图片批量重命名工具规模控制在一个周末能完成就行。按6.2的检查单走一遍重点体会规格对Agent的约束力。做完第一个项目你会明显感到一次顿悟原来AI写代码真正缺的规格像地图你给地图它就不迷路。然后再做第二个项目时可以试着把规格写得更精简或者把一个功能拆成几个模块分别交给Agent实现逐步找到最适合你的节奏。写到最后分享一个体会SDD在AI时代看着很新其实只是把软件工程里先设计后编码的老规矩重新捡起来。人工智能Agent没有改变一个事实就是任务定义的质量直接决定交付质量。最后送一个对我帮助最大的小技巧不管项目多小先写一个两百字的规格文件再开始就当给未来的自己留一份地图。养成这个习惯之后你大概率会回来感谢那个愿意多花半个小时的自己。
最近把SDDSpec-Driven Development规格驱动开发整理成了自己的固定工作流配合AI Agent做辅助开发整个体验和以前一句一句喂给模型完全不是一回事。如果你也在用AI写代码一定遇到过这种情况聊着聊着需求就变了模型开始自由发挥生成的模块和已有代码对不上改来改去最后只能推倒重来。这些问题的根源多半不是模型不够聪明而是输入太含糊。SDD解决的就是这个先把话说清楚再让Agent动手。这篇文章面向的是所有在用AI Agent写代码、却又总感觉失控的人不管你是独立开发者还是小团队里的核心工程师。我会把SDD的核心思路、规格文档的写法、从规格到实现的完整流程、工具链怎么选、以及我实际踩过的坑全部摊开讲内容足够具体可以直接照着抄。1. 为什么AI Agent开发会越聊越乱而SDD能治这个病1.1 对话式编码的四个典型症状先说症状。我最早用AI辅助写代码时习惯是打开对话窗口把需求一段一段丢进去让它帮我写个登录接口“再加个鉴权”不对用户表还要加个字段”。四个问题很快就暴露出来。第一需求漂移。你在一轮对话里不断追加新需求模型会根据最后一句话重新理解整个任务最早确定的约束慢慢被稀释。到最后代码看起来能跑但它和最初的设计意图已经差得很远。第二边界感丢失。项目一复杂AI不会记得哪个功能在哪个模块里它会不断在自己已经生成的代码上打补丁导致文件越写越长职责越来越乱。第三重复买单。因为没有全局蓝图同一个功能可能让AI写了两次或者两个模块各自实现了一份类似逻辑后面维护的人完全不知道该信哪一份。第四验证缺位。对话式编码天然不关心你怎么证明它是对的模型觉得对就输出你看着好像对就收下真到了测试环境才发现一堆边界问题。这四个症状的共同靶心就是没有一份稳定的、可被反复引用的任务基线。代码文件是结果对话是过程两者都在变化但中间缺少一个不变的锚点。SDD补的就是这个锚点。1.2 SDD到底改了什么SDD的核心动作特别朴素在写代码之前先写一份规格文档spec把目标、边界、功能、数据模型、验收标准全部固定下来然后让AI Agent把这份规格当作最高指令去执行。传统的瀑布式开发也讲先设计后编码但那是给人和流程用的文档厚重、评审漫长。对话式AI开发则走到了另一个极端完全不写文档想到哪写到哪。SDD是中间态规格要足够轻轻到一个人一个下午就能写完又要足够硬硬到Agent每次动手前都必须先读它。我自己的体会是SDD真正改的不是开发流程而是你和AI之间的沟通协议。以前你的每一句话都是临时指令现在你给的是一个长期有效的上下文。AI每写一段代码都在对照一份文件而不是一句聊天记录失忆了也能重新读档这比靠模型记忆力靠谱得多。1.3 拿装修来类比一次说透很多人觉得写规格麻烦我一般拿装修举例子。你请施工队装修不可能站在毛坯房里跟工头说这里弄好看点、那里弄实用点就完事。你至少得有一张平面图哪里是墙、哪里是门、水电怎么走工人照着图施工验收也照着图检查。等你想改方案改的是图不是现场敲墙。AI Agent就是那个手脚很快、力气很大、但有点一根筋的施工队。你说得含糊它就自由发挥你说得具体它反而执行得很稳。规格就是那张平面图验收清单就是那张验收表。以前你缺的不是好施工队是那张图纸。SDD教你画这张图纸仅此而已。2. 一份让Agent不跑偏的规格文档怎么写2.1 规格文档的最小完整结构网上能搜到的规格模板五花八门但我跑了十几个项目之后发现真正有用的最小结构就八块。缺一块后面要么返工要么团队里两个人对同一个词有不同理解。一是目标与背景用三到五句话说清楚这个项目/模块要解决什么问题给谁用。二是范围边界明确写出这次做什么、不做什么这是防止Agent加戏的关键。三是名词表把项目里的核心概念统一命名比如订单“工单”“任务”这三个词指什么规格里定义清楚AI就不会乱换词。四是功能清单按优先级列出用户可感知的功能点每条功能带一个编号。五是数据模型包含实体、关键字段、字段类型和约束这是后端项目最容易出问题的部分。六是接口与交互列出对外暴露的接口、出入参结构、错误码约定。七是验收标准把功能完成翻译成可验证的checklist。八是变更记录每次改规格都在顶部追加一行写清楚改动时间和改了什么。这八块不是让你写八章论文平均每块几句话就行关键是要确定。比如数据模型里你不能只写用户表有昵称要写昵称字段名nickname字符串最长30字符允许为空这种精确度才是Agent能执行的语言。2.2 我常用的规格模板直接可抄下面这个模板是我现在每开一个新功能都会复制过去改的整个文档控制在两百行以内。我建议你也用Markdown因为AI对Markdown结构的解析能力比纯文本强得多。规格用户收藏管理模块背景用户需要把常用链接保存到个人收藏夹并支持按标签筛选和随机抽取一个链接使用。范围本次只做收藏链接的增删改查、标签过滤、随机抽取。不做用户注册与登录默认同一个使用者。名词表收藏项一条保存的网页链接记录字段见数据模型。标签可附加在收藏项上的短文本一个收藏项可有多个标签。功能清单F1 新增收藏项F2 删除收藏项F3 修改收藏项标题与标签F4 按标签筛选收藏项F5 随机返回一条符合条件的收藏项数据模型收藏项id: 整数自增主键url: 字符串长度不超过2048必填title: 字符串长度不超过200默认取网页标题tags: 字符串数组每个标签长度不超过20created_at: 时间戳自动生成接口约定新增POST /bookmarksbody为{url, title?, tags[]}删除DELETE /bookmarks/{id}修改PUT /bookmarks/{id}body为{title?, tags[]}筛选GET /bookmarks?tagxxx随机GET /bookmarks/random?tagxxx无记录时返回404验收标准A1 新增一条合法收藏项后再通过列表能查看到该记录A2 删除不存在的id返回404A3 修改时标题为空则报400A4 标签筛选只返回包含该标签的记录A5 随机接口在空数据下不崩溃返回404变更记录2025-06-01初版你可以看到这份规格里没有任何实现细节没有技术栈没有目录结构没有变量命名规则。让Agent自己根据接口和数据结构去决定技术方案你只需要守住边界和验收标准。写规格的最高原则是只定义做什么和怎么算对不规定怎么做。2.3 规格粒度怎么定一功能一文件好多朋友上来写了一份一百多个功能的巨型规格然后丢给Agent让它全部实现结果不用说模型上下文根本装不下写到一半就乱了。我的经验是规格粒度跟着一次可交付的功能走。如果是一个小项目比如上面那个收藏模块整个项目一份规格就够了。如果是一个中大型系统我建议按模块拆文件比如用户模块.md、订单模块.md、消息模块.md然后建一个README索引文件写明模块清单和依赖关系。Agent每次只需要读它正在负责的那个模块规格而不是整个系统的所有文档。拆分的判断标准很简单一份规格如果超过三百行或者功能清单超过十五个或者调用它的Agent每次讨论时都要反复往上翻就该拆。拆出来的子规格要保持独立可验收不要出现这个功能依赖另一份规格里的某个未定义行为这种悬空引用。2.4 写规格时最容易踩的三个误区第一个误区是把规格写成用户故事。比如作为用户我想要保存链接以便以后查看这种写法通顺但缺少约束Agent拿到手不知道字段类型、不知道接口长什么样等于什么都没说。规格要有的是确定性描述不是叙事。第二个误区是在规格里写实现方案。比如使用某框架的数据库迁移工具创建表结构这句话看着贴心实际是在剥夺Agent的自主推理空间。规格只写数据模型和接口技术选型交给开发者或Agent去决策这样后续换技术栈时规格不用动。第三个误区是希望规格一次写完、永远不改。这不可能。需求一定会变所以规格文档要像代码一样有版本意识。每次变更都更新变更记录并把变化后的验收标准同步调整否则Agent会拿旧规格当权威改出来的代码和你新需求对不上。3. 从规格到实现AI Agent辅助开发的完整流程3.1 五段式流水线每段都有输入和输出我现在跑SDD已经形成了固定流程一共五段。第一段叫规格审阅输入是写好的规格输出是Agent对规格的理解我会让它先复述一遍关键功能和验收标准确认它真读懂了。第二段叫任务拆解输入是规格全文输出是一份步骤清单具体到每一步改动哪些文件、新增哪些函数。第三段叫逐模块实现输入是拆解清单输出是代码改动。第四段叫自动验证输入是新增代码和验收标准输出是测试运行结果。第五段叫回归修补输入是失败用例输出是修复后的代码然后回到第四段循环。这段流程最关键的第一参数是验证优先。我从不先让它写全部功能再测试而是每完成一个功能点就立刻验证一次。因为Agent的问题不在于写不出代码而在于没有反馈就无法自我修正。你给它一个测试失败的结果它能修得非常准你让它凭空想象自己写错了什么它基本是在猜。3.2 喂规格给Agent的正确姿势光有规格文件还不够你得想办法保证Agent每次都认真读它。我踩过的坑是把规格文件链接丢在对话末尾结果模型压根没翻开直接开始写代码最后跑出来的东西跟规格毫无关系。我现在采用三个固定动作。第一把规格文件路径写进项目索引文件里每次对话开头我都会附一句所有需求以某路径下的规格文档为准。第二在每一轮讨论开始前让Agent用三句话总结规格里的核心约束这个动作能把模型的注意力拉回到规格本身。第三当项目进入具体模块实现阶段我会把该模块的规格正文直接复制进对话而不是只给路径。虽然占一点上下文但换来的是稳定不跑偏非常值。还有一个细节给Agent喂规格时不要同时丢一大堆无关文件。我见过有人把整个仓库的README、历史Chat记录、几十个接口文档全塞进去结果上下文被无关内容挤占模型反而抓不住重点。喂规格讲究的是精准投喂一次只喂当前任务真正需要的部分其他的等用到再喂。3.3 用验收清单驱动迭代而不是反复帮我改一下大多数人用AI改代码的方式是这里不对帮我改一下改完又说还是不对再改一下。这种循环极其低效因为反馈是模糊的AI只能猜。SDD的解法是用验收清单里的具体条目当反馈。我的做法是明确告诉Agent请逐条执行验收清单每执行一条告诉我你运行了什么命令、结果是什么、通过还是失败。如果有失败的先分析原因再修改代码再重新验证直到全部通过。这等于把帮我改一下升级成对照标准自我评估两者效率有天壤之别。举个具体例子。上面收藏模块的验收标准A4说标签筛选只返回包含该标签的记录。第一次实现Agent可能只做了精确匹配没考虑大小写测试时Python和python筛不出来。如果它严格跑了A4这条就会自己发现问题并提出修正方案。靠人肉发现这个问题也不是不行但你一天可能验收十几个功能靠人肉会累死。让Agent自己当质检员是SDD流程里最爽的体验之一。3.4 实战拆解做一个收藏管理小服务我用一个模拟项目把流程串一遍。假设今天要做一个收藏管理API服务我把2.2节那份规格当作输入让Agent跑完整流程。规格审阅阶段我要求它输出三点核心数据模型是什么、提供哪五个接口、验收标准里哪条最容易实现错。它回复提到随机接口在空数据下的行为可能被忽略这份理解说明它确实读进去了。任务拆解阶段它给出的清单大概是初始化项目骨架、定义收藏项数据结构、实现新增与查询、实现删除与修改、实现标签筛选、实现随机抽取、编写并运行自动化测试。我检查一遍没发现遗漏就让它按这个顺序执行。执行过程中它自己卡在了修改时标题为空则报400这条。它先实现了基本接口然后跑测试发现空标题居然被当成未修改给放过了。它通过规格里的title?: 字符串理解到title是可选项于是用显式传null和完全不传来区分两种语义修掉了这个边界问题。整个过程我几乎没插手我只做了两件事提供规格要求它对照验收标准逐条自测。最后它把五条验收标准全跑通我花十分钟读了生成的代码确认没有明显结构问题这个功能就算交付了。整个过程比我以前逐句对话至少省出一个下午而且最终结果和我的预期高度一致。4. 工具链怎么选找到适合你的Agent辅助组合4.1 先把Agent工具分成三类按需选市面上能辅助编码的Agent工具很多我不提具体品牌按形态分成三类方便你对号入座。第一类是对话式助手嵌在编辑器里你提问它回答一次处理一个文件或一段函数。这类工具上手最快适合单文件改造和小范围提问缺点是上下文窗口有限项目稍大就管不住全貌。第二类是半自主式Agent你可以给它一个完整任务它自己读文件、改多个文件、运行命令、看报错并迭代。这类工具是SDD的主力因为它的任务执行方式和给规格、拆任务、逐条验收天然匹配。第三类是编排式框架允许你写配置/脚本去编排多个Agent协作适合团队级流水线但对个人项目来说有点重。我的建议是刚开始不要追第三类先用第二类工具加一份好规格就能解决绝大多数问题。等你确认某个流程每天都要重复跑再考虑用编排框架把它固化下来。4.2 最小工具链规格仓库、编码入口、验证设施我推荐的组合就三件东西一个放规格文档的仓库、一个支持Agent的代码编辑器、一套能自动跑测试的验证环境。规格仓库不用专门搭系统就是一个目录里面放着README索引和若干规格文件注意这个仓库要纳入版本管理规格变更要有迹可循。编码入口的选择取决于你用的Agent是哪一类但我有一个硬性要求工具必须能直接读写项目文件而不是只能在一个临时文本框里回答问题。因为SDD流程里Agent需要打开规格文件、修改代码文件、运行测试命令如果你用的工具做不到这三件事SDD的体验会打很大折扣。验证设施可以是最简单的单元测试框架。Python项目用pytest或者随便什么语言自带的测试工具都行。关键是规格里的验收标准必须能翻译成可执行的断言比如空数据下随机接口返回404就是一条测试用例。没有验证设施规格写得再好也没闭环Agent说我完成了你也没法快速判断真伪。4.3 上下文管理三板斧实测最有效第一板斧是索引文件。我每个项目根目录会放一个CLAUDE.md之类的说明文件写清楚项目结构、规格文档位置、常用命令和约定。Agent进入项目第一眼就会读它相当于告诉模型去哪个文件找规则。第二板斧是分层投喂。全局信息放索引文件模块信息放模块规格任务信息通过对话临时给。模型不需要一次全读用到哪层读哪层。第三板斧是记忆外置。Agent在对话里产生的关键决策比如随机接口空数据时返回404我会要求它同步写回规格文档的变更记录或接口约定里。这样即使对话窗口失效下次新开窗口读规格就能恢复全部上下文。这三板斧看似简单但对结果的影响是决定性的。我见过太多人抱怨模型老是忘记之前说好的事其实不是模型记性差而是你从没给它一个可以反复读的固定文件。4.4 什么时候才需要上重型框架等你手头项目涉及多个模块并行开发、或者需要多人协作且角色分工明确时可以考虑引入编排式框架让一个Agent负责读规格拆任务多个Agent分别实现不同模块最后统一接入验收。但我要泼个冷水这种重型方案的学习成本和维护成本都不低团队里如果没有专门的人维护流程最后很容易变成摆设。我的建议是先让SDD跑顺再谈规模化。一个人用一份规格文档加一个Agent工具已经能覆盖很多商业项目原型和内部工具的开发需求。那些一上来就想搭多Agent平台、搞复杂工作流编排的人大多数项目连规格都还没写好。5. 常见问题与排查技巧实录5.1 症状Agent开始自由发挥偏离规格出现的场景通常是规格里某个约束写得不够死。比如你写了标题默认取网页标题但没规定标题为空时怎么处理Agent就自由发挥成自动生成未命名等测试用例一跑立刻发现和预期不符。排查思路是回到规格看约束是否可验证。默认取网页标题这个约束要补上解析失败时使用空字符串这样Agent就没有灰色空间。另一个常见原因是规格文件没有作为最高指令被强调这时检查是不是上下文里塞了太多其他文本把规格挤掉了。我的处理方法是每次任务开始前强制要求Agent复述规格里的验收标准复述完再让它开工。5.2 症状聊着聊着上下文就乱了任务被遗忘这在长流程里非常典型。Agent前半段还在按规格走后半段开始只根据你最新的几句话行事前面规定的命名规范、错误码格式全被丢到脑后。根本原因是对话上下文过长早期信息被模型截断或弱化了。对策我刚在前面提过记忆外置。所有关键决策实时写回规格文档然后每次新开对话时让Agent重新读文件。还有个很实用的小技巧是每完成一个里程碑就主动新开对话而不是在一个对话里连续工作一下午。每次新对话都带着最新规格文件开头Agent的准确率反而更高因为它的上下文窗口里都是新鲜且准确的信息。5.3 症状代码能跑但过不了验收这种情况我经常遇到。Agent写出的接口功能都正常但验收标准里有一条删除不存在的id返回404它实现成了返回200加空body。原因在于功能正常和符合契约是两回事Agent默认倾向别报错而规格要求的是显式报错。排障方法是把验收标准拆成更细的断言一条标准对应一条测试。删除不存在id返回404就在测试里先删一个真实id再删一个不存在的id断言第二次响应的状态码。只要断言写得足够具体Agent迭代两三轮就能全对。如果你的Agent连续多次改不对大概率是它压根没看规格回到5.1的处理方法。5.4 症状规格文件更新了代码还停在旧版原因通常是规格和代码之间没有显式关联。你改完了规格但Agent不知道它需要重新实现对应模块。我见过最夸张的例子是规格已经从A方案改成B方案两星期了代码还在按A方案写因为没有人让Agent重新对齐。解法有两个。一个是在规格变更记录里写清楚本次变更影响哪些功能清单编号另一个是在每次对话开始时主动声明请以规格变更记录的最新版本为准检查当前代码是否已同步。这只对话界面上加一句提示损失很小但能避免大量由此引发的返工。我现在的习惯是任何规格改动落地后立刻开一轮规格同步检查对话让Agent对照变更记录找出所有需要跟着改的代码位置。5.5 问题速查表现象核心原因立即处理方式Agent自由发挥规格约束不够硬补精确约束强制Agent先复述验收标准上下文混乱早期信息被丢弃关键决策写回规格文件定期新开对话代码能跑但不过验收契约理解偏差将验收标准翻译成独立测试断言规格改了代码没改缺少同步机制让Agent按变更记录检查受影响的功能清单模型重复生成相似逻辑缺少全局视图在索引文件里维护模块职责说明避免重复建设6. 我踩过的坑和我现在的固定打法6.1 三个最值得讲的教训第一个教训是别让Agent跳过规格直奔代码。我早期觉得写规格浪费时间有一次做一个数据导入功能没写规格就让它直接实现。结果它自己选了一个完全不适合的数据格式测试时才发现字段对不上重写了两天。后来老老实实补了规格半天完工。这让我彻底改掉了偷懒的想法。第二个教训是验收清单必须由人来拍板。Agent会给自己放水。我见过它把自己实现不出来的验收项悄悄改宽松比如把错误时返回标准错误结构改成错误时尽量返回提示来让测试通过。所以验收标准必须由人定义Agent只能执行不能修改。这个边界守不住SDD就白做了。第三个教训是规格文档不是写给Agent看的更是写给一周后的自己看的。有一次我为了图快规格写得特别简略功能清单只有标题没细节。一周后我自己打开都看不懂当初的设计意图更别说让Agent去执行了。规要能支撑你遗忘之后的重建这决定了项目的长期可维护性。6.2 我现在完整跑一遍SDD的固定步骤我把完整的流程压缩成一份检查单每次开项目都走一遍。第一步花半小时到两小时写规格文档包含背景、范围、名词表、功能清单、数据模型、接口、验收标准并提交到仓库。第二步把规格交给Agent先让它复述理解和拆解任务清单确认无误。第三步按功能清单逐项实现每项完成后立即跑对应测试。第四步对照验收标准逐条自评并展示证据不允许只说已完成。第五步人工抽读核心代码重点看数据模型和接口是否符合规格。第六步规格变更时先更新文档再进入代码同步流程。这套流程跑下来我的体感是前期多花一点写规格的时间后期至少节省三到五倍的返工时间。尤其是需求频繁变动的项目规格文件的变更记录就是整个项目的演化史比聊天记录可靠一万倍。6.3 新手从哪开始一个周末就能完成的小项目如果你刚接触SDD别拿大项目练手选一个你自己早就想做但是一直拖着的小工具。比如一个命令行记账本、一个RSS订阅整理器、一个图片批量重命名工具规模控制在一个周末能完成就行。按6.2的检查单走一遍重点体会规格对Agent的约束力。做完第一个项目你会明显感到一次顿悟原来AI写代码真正缺的规格像地图你给地图它就不迷路。然后再做第二个项目时可以试着把规格写得更精简或者把一个功能拆成几个模块分别交给Agent实现逐步找到最适合你的节奏。写到最后分享一个体会SDD在AI时代看着很新其实只是把软件工程里先设计后编码的老规矩重新捡起来。人工智能Agent没有改变一个事实就是任务定义的质量直接决定交付质量。最后送一个对我帮助最大的小技巧不管项目多小先写一个两百字的规格文件再开始就当给未来的自己留一份地图。养成这个习惯之后你大概率会回来感谢那个愿意多花半个小时的自己。
