企业官网建设流程全解析

最近把SDD（Spec-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: 字符串数组，每个标签长度不超过20
  • created_at: 时间戳，自动生成

接口约定

• 新增：POST /bookmarks，body为{url, title?, tags[]}
• 删除：DELETE /bookmarks/{id}
• 修改：PUT /bookmarks/{id}，body为{title?, tags[]}
• 筛选：GET /bookmarks?tag=xxx
• 随机：GET /bookmarks/random?tag=xxx，无记录时返回404

验收标准

• A1 新增一条合法收藏项后，再通过列表能查看到该记录
• A2 删除不存在的id返回404
• A3 修改时标题为空则报400
• A4 标签筛选只返回包含该标签的记录
• 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 问题速查表

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没有改变一个事实，就是任务定义的质量直接决定交付质量。最后送一个对我帮助最大的小技巧：不管项目多小，先写一个两百字的规格文件再开始，就当给未来的自己留一份地图。养成这个习惯之后，你大概率会回来感谢那个愿意多花半个小时的自己。