很多做开发的朋友应该都有过这种体验AI 编程助手用起来很爽但项目稍微复杂一点就开始翻车AI 改一个 bug 引出三个新 bug代码越改越乱最后只能自己动手擦屁股。我自己的实践结论是问题往往不在 AI 本身而在我们喂给 AI 的“输入”太糊了。最近我一直在系统性地用 SDDSpecification-Driven Development规范驱动开发配合 AI 来做项目从设计到落地整个流程理顺之后AI 才真正从“玩具”变成了生产力工具。这篇笔记不是讲理论是我最近一段时间实战下来的真实记录里面有完整步骤、踩坑经历、还有可以直接抄的规范模板。适合正在用或准备用 AI 辅助开发、开发 AI 应用、研究本地部署模型的同学尤其推荐给被 AI 编码折腾到怀疑人生的人。1. SDD 加 AI 的开发思路先把“说清楚”这件事解决1.1 我踩过的 AI 编码坑先说段不太光彩的历史。有阵子我迷上了让 AI 帮我写代码一开始确实惊艳写个爬虫、写个脚本、调个接口又快又像样。但一到正经项目就原形毕露需求说了三句话AI 理解出去十万八千里写了 2000 行业务代码没跑通一次改完一个 bug报错从 A 变成 BB 改完又冒出 C。最崩溃的一次我给某个模块加了新功能AI 顺手把我另一个已经跑通的模块逻辑给重构了测试集挂了一半线性回归直接失守。后来我认真复盘了一下问题不是 AI 笨而是我太懒。我给它的是口语化的需求片段它猜我的意图猜错了当然正常。人在团队协作里都知道要把需求写清楚再动手为什么到了 AI 这里就默认它可以读心想明白这一点SDD 自然而然地就浮出来了。1.2 SDD 的核心写清楚再动手AI 才能认真干活SDD 全称 Specification-Driven Development核心思想就一句话在写代码之前先把“要做什么、为什么做、做成什么样、怎么验证”这些内容写成一份足够清晰的规范文档再让 AI或者人按规范去实现。有人一听就觉得这是加重负担平时敏捷、快速迭代哪来时间写那么长的文档但我实践下来的体验恰好相反写规范花的十几分钟能在后面节省几小时的无效沟通和错误重改。把需求梳理清楚这件事本身就是开发的一部分而且是最值钱的那部分。尤其在 AI 时代你输入“帮我做一个用户登录功能”和输入“实现一个基于 JWT 的用户登录模块包含注册接口、登录接口、Token 刷新逻辑、连续 5 次密码错误锁定 15 分钟”AI 写出来的东西完全是两个次元的产物。SDD 的本质就是把隐藏在开发者脑子里的隐性知识显性化地铺到桌面上让 AI 这个极其聪明但也极其“听话”的助手不需要猜太多就能一次做对。2. 一次完整 SDD 加 AI 的实战流程从需求到验收2.1 需求阶段先别打开 IDE打开记事本我现在的习惯是接到任何新功能的第一步打开纯文本编辑器先把下面几个问题弄清楚这个功能的服务对象是谁是用户、管理员还是其他系统核心要解决的问题是什么什么场景下会出现这个需求有哪些约束条件比如数据量、并发量、安全等级、兼容性要求。达成什么指标才算成功这些描述不需要用专业术语大白话就行但一定要具体。比如“做一个待办事项应用”这就是不合格的模糊需求“做一个待办事项命令行工具支持增删改查、状态标记、数据持久化到本地 JSON 文件并支持通过配置文件切换存储路径”这就是合格的输入。在这个阶段我会直接用 AI 辅助做需求澄清。方法很简单把初稿丢给大模型让它扮演一个经验丰富的产品经理反问我所有可能的场景和边界然后我把答案一个个补回去。这样来回两三轮需求文档会肉眼可见地充实起来。2.2 规范设计阶段把需求变成可执行的“施工图”需求是“要什么”规范是“怎么做”。到这一步我会把需求文字拆成清晰的功能模块、数据结构、接口定义、页面表单和核心逻辑流程。这里有个实操技巧为了让 AI 能准确输出规范我给 AI 的“规范生成提示词”长这样你是一名资深软件架构师。请根据以下需求为开发团队输出一份技术规范文档。 需求内容 [粘贴需求文档内容] 要求 1. 按功能模块拆分每个模块写明职责边界 2. 定义模块之间的接口和数据流接口需包含入参字段、类型、长度、是否必填、校验规则 3. 数据结构需要用表格形式说明字段名、类型、默认值、约束、备注 4. 补充质量要求如响应时间、错误处理、安全要求 5. 输出格式为 Markdown务必使用中文接口字段名和代码变量名保留英文这样生成的第一版规范我基本都会手动改一遍。AI 生成的规范经常有几个通病过于理想化不考虑现有代码兼容性字段设计不够务实喜欢把什么字段都塞进去异常处理说得太模糊导致后端的空指针前端的白屏一片。把规范当草稿用你的真实业务经验去校正它这个过程不可省略。规范质量直接决定最终代码质量。2.3 代码实现阶段让 AI 按规范一块一块地交付规范写好后就进入了最爽也最省心的阶段。我的习惯是不让 AI 一口气生成整个项目而是一个模块一个模块地来。比如刚才说的待办事项工具我会拆成模块 A配置加载与校验模块 BJSON 存储与读写模块 C命令行交互层模块 D测试用例然后每个模块单独向 AI 下达执行指令。指令模板我用得比较顺手的是你是该项目的一名开发工程师。现在要求你严格按技术规范完成以下模块的开发。 模块名称[模块 A] 规范文档路径[粘贴规范中该模块的完整描述] 技术要求 1. 代码必须严格实现规范中的所有字段和逻辑不得自行新增或删减字段 2. 文件输出到 [相对路径] 3. 包含必要的注释注释用于解释关键难点而非复述代码 4. 遵守项目的现有目录结构不得引入额外依赖 5. 代码完成后输出一份模块自检清单逐一说明规范中的每项要求是如何实现的“务必严格按规范实现不得自行发明”这句话我几乎每次都放在提示词里。因为 AI 在不被约束时有个习惯自由发挥。自由发挥在写邮件的时候是优点在写业务代码的时候就是灾难。当单个模块代码回来后我不会直接把它并入主工程。先自己读一遍对照规范逐条过。确认没问题后再进入集成阶段。所有模块都集成完毕再整体让 AI 跑一遍自查。2.4 测试验收阶段规范没写到的就等于默认不做以前不用 SDD 时我验收代码凭感觉——代码能跑就行。但“能跑”和“正确”是两码事。用了 SDD 后代码返回给我我的第一个动作是打开规范文档把每个条目拉出来核对。比如规范里写“接口校验规则用户名长度 3 至 20 个字符仅允许数字和字母否则返回 400”我就去代码里找对应的校验逻辑。写上去了通过没写退回去让 AI 补齐。这个核对过程枯燥但极其有效因为它把“质量”从玄学变成了清单。除此之外我还习惯让 AI 按规范里的质量要求生成一份测试计划再让它自己实现核心路径的单元测试。毕竟规范里写了“异常处理存储目录不存在时自动创建”那就应该有对应的测试用例来验证这一点。用规范来驱动测试设计是 SDD 最重要的长期价值之一。3. 实操示例用 SDD 加本地部署的 AI 模型开发一个 Python 简易工具3.1 选什么工具本地 AI 模型还是在线 API在实操之前先回答一个很多朋友关心的问题是不是必须用特定的 AI 工具才能跑 SDD 流程其实不是。用 ChatGPT、Claude、各类 AI 编程助手甚至本地部署的开源模型都可以跑这套流程。关键是“你的流程走不走得通”而不是“某个特定工具能不能做到”。我个人的选择习惯是这样涉及隐私数据或者经常断网的项目优先用本地部署的 AI 模型纯学习或验证原型的项目用在线 AI 编程工具提效很明显。当前本地部署的生态已经很成熟几年前还是个极客玩具现在一个 7B 参数量的量化模型用家用级显卡或者中端消费级硬件就能跑起来写代码的能力已经相当可用。3.2 完整示例一个本地待办事项管理脚本下面我以一个非常入门的小项目为例完整展示一次 SDD 加 AI 的开发流程。目的不是教大家做待办事项而是让大家感受每一个步骤的输入输出长什么样。你完全可以把这套流程套到任何你的实际项目里。第一步需求描述。我给 AI 的一句话原始需求是我要一个 Python 命令行待办事项工具支持添加任务、列出任务、标记完成、删除任务数据存在本地文件里重启电脑数据不丢。第二步让 AI 生成规范。我用上文提到的提示词得到规范文档的核心内容大致如下截取部分功能模块输入存储与处理返回add任务名称 text, 优先级 level(1-3)追加到 JSON 列表, 默认优先级为2新任务IDlist无读取全部任务表格化的任务展示done任务ID标记 statuscompleted, 记录完成时间更新后的任务delete任务ID删除对应条目删除确认config配置文件路径读取 YAML 配置, 键为 data_file, 默认 data/tasks.json当前生效配置数据结构字段类型默认值约束idint自增唯一不小于1titlestr无必填长度 1~100priorityint21, 2, 3statusstrpendingpending / completedcreated_atstr当前时间戳ISO 格式completed_atstr空仅 completed 时有值第三步让 AI 按规范分模块实现代码。粘贴规范里“存储模块”的完整描述让 AI 实现 JSON 读写类粘贴“命令行层”的描述让 AI 实现 argparse 解析逻辑。每个模块回来后都跑一遍小脚本或者直接读一遍代码。第四步先生成测试。根据规范里的每项约束让 AI 输出 pytest 测试文件比如测试长任务名称报错、测试非法优先级报错、测试数据持久化。代码如下部分展示import json import pytest from pathlib import Path from task_store import TaskStore def test_add_task_persists_to_file(tmp_path): store TaskStore(data_filetmp_path / tasks.json) store.add(写完SDD实践笔记, priority1) saved json.loads((tmp_path / tasks.json).read_text(encodingutf-8)) assert len(saved) 1 assert saved[0][title] 写完SDD实践笔记 assert saved[0][priority] 1 def test_add_long_title_rejected(): store TaskStore(data_filePath(/tmp/test_invalid.json)) with pytest.raises(ValueError): store.add(长 * 101, priority1)第五步集成。让 AI 把各个模块拼接成主入口然后手动执行几条命令验证。这套流程跑下来我的真实感受是工作日里没有出现“AI 写的代码从头错到尾还能交付”的灾难现场绝大多数问题都在模块自测阶段被拦住了。每一步都是小幅反馈错得再离谱也容易修正。3.3 本地部署 AI 时的配置参考如果你打算用本地部署的模型跑这套 SDD 流程我给你一个当前阶段比较稳妥的参考配置思路。先说结论代码生成和规范分析这两个任务的“性价比甜点”通常在中型模型上而不是盲目追求最大参数。因为参数量越大硬件门槛越高单次推理速度越慢迭代效率反而下降。硬件方面我的实践建议是纯 CPU 推理适合 3B 到 7B 的量化模型能跑但生成速度偏慢适合做规范整理不适合高频代码迭代中端显卡显存 8G 上下可以流畅跑 7B 到 14B 的 4bit 量化模型开发辅助的体验已经比较舒适高端显卡显存 24G 左右可以跑 32B 级别模型代码质量和推理速度都能兼顾内存和硬盘也有要求模型文件较大建议预留足够空间内存需要和显存有合理比例如果你完全没有本地部署经验我的建议是直接先用在线服务把 SDD 流程跑通等确认这套方法论对自己的项目确实有效再考虑本地部署去解决隐私、成本、稳定性问题。不要把工具选型和流程学习两件事搅在一起那样容易两头都没有突破。4. 常见问题与排查技巧实录4.1 AI 没有严格按规范实现怎么办这是最最常见的问题。规范里写清楚了字段校验AI 就是不做规范里说禁止引入额外依赖它就是偷偷加了一个库。我踩过很多次坑之后总结出三个层次的对策提示词层面把“严格按规范实现不得自行增删”写进系统提示或用户提示并且要求 AI 在交付时附上“规范自检清单”流程层面每个模块完成时手动核对关键点。不要等到整个项目完成再统一检查那时返工成本已经很高了工具层面在支持规则配置的 AI 编程工具中把项目规范文件例如 AGENTS.md、CLAUDE.md 这类约定文件放到项目根目录让 AI 每次读取上下文时都能看到约束第四个层次如果还是不行那就把大模块拆成更小的子任务。很多时候 AI 跑偏是因为任务太大上下文太长它在“实现”过程中逐渐遗忘了开头的约束。拆细一点上下文短一点出错率会明显下降。4.2 同一个功能让 AI 改了好几遍还是不对我遇到过最崩溃的场景是规范里明明写的是 AAI 死活写成了 B告诉它不对它道个歉然后继续写 B。排查下来往往有三个原因第一提示词中有相互矛盾的信息。比如规范里说“删除任务后立即释放ID”但另一段又说“ID全局唯一自增”AI 不知道该听哪个大概率会在两个约束之间反复横跳。解决方法是统一规范中的每个细节把冲突扼杀在源头。第二AI 的上下文太长了。项目工程代码越堆越多前面的规范内容被压缩丢失AI 只能凭感觉操作。这种情况我会新建一个对话把规范和要改的模块描述重新喂一遍而不是在一个超长会话里连续修改。第三你改了代码但没同步更新规范。AI 在生成一个方案时综合了旧的规范和新的需求两边不一致自然越改越乱。记住SDD 流程里规范才是唯一的权威任何需求变化都应该先改规范再改代码。当你发现 AI 开始“自由发挥”时先检查是不是规范已经过时了。4.3 规范本身写不好怎么办有些朋友问我本来需求就理不清楚你让我写规范臣妾做不到啊。这里我给你一个非常顺手的破局办法用 AI 来帮你写规范但是以“提问回答”的模式。具体做法就是你先用大白话描述大概要做什么然后让 AI 扮演一个事事追问的架构师针对以下方向连环提问数据从哪里来格式是什么哪些边界和异常情况需要处理性能上有没有特殊要求安全问题涉及哪些未来可能如何扩展你回答完第一轮让 AI 针对回答继续追问第二轮。通常三轮下来你脑子里的模糊想法就已经被整理成一个很专业的规范初稿了。每一次提问都是帮你补盲区。这个技巧在本地部署模型上同样好用因为提示词工程带来的提升往往比换更大的模型更明显。4.4 团队协作时AI 写的代码别人看不懂个人项目无所谓但团队项目就麻烦了。AI 写的代码风格可能跟团队现有风格不一致命名习惯不同注释风格不同甚至模块划分逻辑都不同。这会让 code review 变得非常痛苦。我的解决方案是在规范文档里增加一节“代码风格与工程约束”把所有团队已经达成共识的开发规范写进去包括命名规范、目录结构、错误处理风格、日志要求等。然后把这个小节整段放进每个模块的实现指令里。如果一款 AI 编程工具支持项目级规则文件直接配置好让 AI 在每次回复前自动加载这些约束。还有一个很推荐的折中方案让 AI 先按照规范生成一个模块的“示例实现”团队评审确认风格后再复制到提示词里作为风格范例。有了这个带上下文约束的风格参考后续 AI 生成的代码就会稳定很多。再补一句团队协作相关的经验用 SDD 之后需求评审会和 code review 的价值反而变高了因为有了规范这个“锚点”所有人对齐的是“做出来的东西是否符合预期”而不是“代码语法是否优雅”。规范先行让 AI 承接重复劳动团队成员就能把时间花在真正需要判断力的地方比如方案设计、异常边界和代码审查上。4.5 补充别神话 SDD它也不是万能药最后必须得说句公道话。SDD 加 AI 这套组合不是万能的。有些领域它就是不太适用比如极早期的探索性原型、一次性脚本、创意工具类项目、画风和审美占主导的设计类开发。这类项目需求天然模糊需要大量人类主观判断过度强调规范会适得其反。另外SDD 不一定非要写很长很正式的文档。几十行清楚的需求要点加数据结构表格也算有效的规范。关键是信息完整度而不是文档字数。我自己的习惯是小功能写半页纸中功能写一页到两页系统级项目才写完整的技术方案。别让方法论绑架生产力。5. 我的几点实战心得5.1 规范性是 AI 开发的搬运工但真正的快递员是“边界感”使用 AI 开发软件最核心的发现是AI 擅长在清晰的边界内做扩展性执行而人类的价值在于定义边界。SDD 正好提供了这样一个边界把这个边界画清楚AI 就在里面干活。不要让 AI 去猜边界猜出来的边界一定不是你要的。Sharing 一个细节当我把项目规范文档放在项目根目录并通过适当的方式让 AI 在每次生成前自动读取这些文件输出质量能向上跨一个台阶。AI 代码生成这件事其实并不是玄学它就是“输入的质量决定输出的质量”。5.2 写规范时把自己当成“新人的上司”有一个特别好用的心态转换技巧写规范的时候别把读者想象成那个“什么都知道的你”而是想象成一个特别聪明但完全不了解项目背景的新员工。这个新人记性好、理解力强、工作速度快但缺乏你的项目经验你不告诉它的东西它默认不做。每次写完规范我都会自问一遍如果我是个刚毕业的学生照着这份文档干活能顺利交付吗如果中间有犹豫说明规范有漏洞。我和 AI 协作最顺畅的那段时间就是我把 AI 完全当成“非常聪明但毫无常识的新同事”来对待的那段时间。5.3 用好“复盘”这一环SDD 不是线性的它有个隐形的闭环项目做完之后我会把“哪些地方 AI 做得又快又好”“哪些地方 AI 反复跑偏”“哪些规范条目形同虚设”“哪些约束字段帮助巨大”这些记录在一个专门的笔记里。下次接新项目时先翻一翻这些笔记规范和提示词模板就能持续迭代起来。对我个人来说这个持续迭代的过程比任何一个具体工具或模型版本更新都重要。方法论的复利一旦滚起来会形成你自己的竞争力这个竞争力跟大模型版本更新没有关系跟 AI 能力的涨跌也没关系。你永远可以先一步把需求想清楚再让任何一款 AI 变成你的最强开发搭子。这段实践走下来我最直观的感受是SDD 加 AI 的组合让我从忙乱的“代码接线员”变成了更从容的“方案设计者”。如果你也被 AI 的不稳定搞得头疼建议下次新开一个项目时先花 30 分钟写一份极简规范再让 AI 动工。建议你先从一个小工具项目开始完整走一遍从需求到验收的闭环流程。只要试过一次你就会明白“先想清楚再写代码”这八个字的真正重量。
