写代码这行当干了十几年，最近半年我几乎天天泡在AI coding工具里，越用越觉得有个概念被大家混得厉害：spec和plan。不少人跟我抱怨，说让AI先做plan再写代码，结果写完还是一堆bug，甚至方向直接跑偏。我问他，你给AI的"plan请求"里到底写了什么？他说"帮我把登录功能做了"。问题就出在这儿——你以为你在要plan，实际上你给的是个愿望，AI给你的是个PPT。真正的plan，得从一个具体的、可验收的spec出发，不然就是空中楼阁。
这篇文章不聊那些虚的，就围绕spec和plan在AI coding里的定位差异、配合方式、以及现在各家coding plan和token plan到底该怎么选，把我在实际项目里踩过的坑和验证过的做法一次说清楚。适合正在用Claude plan mode、Copilot plan agent、或者各类国产AI编码平台的老铁，尤其是团队协作中需要统一AI开发口径的人。
1. spec与plan：两个容易混淆的AI编码概念
1.1 一次典型的"plan翻车"现场
我先说个真实案例。上个月朋友所在的小团队接了一个内部数据报表系统的重构，他们用的是某款AI编码助手的plan模式。组长让组员把需求发给AI，让它先输出一份开发计划。AI确实给了一份看起来非常专业的plan：分模块、排工期、列接口、标注风险点，洋洋洒洒两千字。组员们看了都觉得稳了，开始按plan逐条执行。
结果做到第二个模块就发现问题：AI理解的"报表导出"是导出当前筛选条件下的明细数据，而业务方要的是按日汇总的统计表。就是因为最初的需求描述里没有对"导出内容"做明确约定，plan做得再漂亮，也只是把错误的理解结构化地细化了一遍。整个模块返工，前后浪费了三天。
这个案例特别典型。我在复盘的时候意识到一个问题：plan的效率上限，取决于它上游spec的质量。如果你的spec本身是一团浆糊，plan就是把浆糊装进了一个更精致的容器里。
1.2 spec是"定义正确的问题"，plan是"设计正确的路径"
先给个基本定义，这俩概念单独看都很清楚，但放到AI编码的上下文里就容易打架。
spec（specification的缩写），中文通常叫规格说明或需求规格。它回答的是"系统应该做什么、做到什么程度、怎么算完成"。一份好的spec包含：功能定义、输入输出约定、边界条件、验收标准。比如"用户点击导出按钮后，系统按当前时间范围筛选订单，生成按日汇总的CSV文件，包含订单数、总金额、退款金额三列，文件命名格式为report_YYYYMMDD.csv"——这就是spec。它描述的是目标状态，不关心你用什么技术栈、分几步实现。
plan（计划），回答的是"用什么顺序、什么方式把这个spec落地"。一份好的plan包含：任务拆解、依赖关系、技术选型、风险应对、验证方式。它的输入是spec，输出是执行路线图。换句话说，spec是"什么"，plan是"怎么一步步做到"。
这个区分在传统软件工程里是老生常谈，但在AI coding的场景下，很多人把它们揉在了一起。因为AI编码工具界面上总是把plan作为一个功能按钮呈现，导致大家误以为"只要按了plan模式，AI就能帮我把项目想明白"。但AI的plan能力再强，它也是基于你给的spec去推演。而你如果压根没给spec，AI就会自己脑补一个出来——这就是翻车的根源。
1.3 一个容易被忽略的细节：spec的颗粒度决定plan的质量
我做过一组对比实验，同一个"用户注册功能"，分别用两种方式让同一个AI agent做plan。
第一种，spec模糊版："帮我写个用户注册功能，包括用户名、密码、邮箱，做好了发验证邮件。"
第二种，spec明确版："实现一个用户注册功能，要求：用户名3-20位字符，仅限字母数字下划线，唯一索引；密码至少8位，必须包含大小写字母和数字，存储使用bcrypt加盐哈希；邮箱格式校验，注册后发送验证邮件，链接24小时内有效；接口返回统一JSON结构，成功返回code=0，失败返回code=4001并附带message字段；注册成功后自动创建默认用户资料表记录。"
结果非常明显：模糊版的plan只有6个步骤，看起来"很顺"，但遗漏了密码策略、邮件验证失效时间、唯一索引冲突处理、接口统一返回格式等关键点。明确版的plan有14个步骤，每一步都对应spec里的一条可验证规则。
这告诉我们一个朴素的道理：给AI一份好spec，它的plan才有据可依；不给spec，AI的plan就是在帮你的模糊想法编理由。这不是AI不行，而是上游输入的质量决定了输出的上限。
2. 再说plan mode：从Claude的plan agent到各家coding plan
2.1 plan模式是AI编码进入"半自主"阶段的标志
如果你用过Claude的plan mode，会发现一个明显的交互变化：AI不是上来就写代码，而是先阅读代码库、分析需求、提出一系列问题、最后输出一份带具体改动的实施计划，等你确认后才进入编码阶段。这个设计的核心价值在于：把"理解需求"和"执行编码"分成了两个阶段，避免AI在理解不充分的情况下贸然动手。
我在实际使用中体会很深的一点是：plan mode真正解决的，不是AI的编码能力问题，而是沟通成本问题。以前的AI编码是"你一句它一版"，大多数时候你需要在多轮对话里不断纠偏。而plan mode通过前置的分析和提问，把大量潜在的误解消灭在执行之前。
但注意，Claude的plan mode本身并不会替你把spec写好——它只会基于你提供的需求和你项目里已有的上下文去生成plan。如果上游需求本身模糊，它通常会反过来问你问题。这时候很多人的做法是"随便回答一下让plan快点出来"，结果plan出来了，spec依然缺位。
2.2 build agent和plan agent的分工逻辑
最近大家讨论比较多的还有build agent和plan agent的区别。我在团队协作里观察到一个很清晰的分工模式：
plan agent负责方案设计。它读需求、看代码、定技术路线，输出的是文档级成果，比如改动方案、接口设计、数据库变更方案。它的产出不是代码，而是决策记录。
build agent负责执行实施。它拿到plan agent输出的方案，按照方案去改代码、写测试、跑验证。它的产出是实际的可运行代码。
这个拆分的背后逻辑，其实是把人类的"架构师"和"程序员"职责映射到了AI agent上。plan agent承担的是需要全局视野和判断力的工作，build agent承担的是执行力和确定性的工作。两者配合，比一个agent从头干到尾更稳，因为plan阶段形成的约束会传导到build阶段，减少build阶段的随意发挥。
如果你在团队里用AI编码，我建议尽量让plan agent和build agent分开，哪怕你用的是同一个模型，也要在prompt和使用流程上做区分。混在一起用，很容易出现"plan了一半就开始写代码，写到一半发现方案有问题又回去改plan"的低效循环。
2.3 各家coding plan套餐到底在卖什么
现在各大平台都推出了带"coding plan"字样的产品，比如火山方舟的coding plan、阿里云百炼的coding plan、GLM coding plan等等。我研究了一圈，发现它们背后的逻辑不只是"给你一个AI编码助手"，而是把AI编码能力变成了可量化、可管理的套餐体系。
这里有个容易混淆的点：plan这个词在"coding plan套餐"里，和"plan模式"是两个维度。plan模式是AI的工作方式，coding plan是商业化套餐。但两者有一个隐含的关联：这些套餐通常都把plan能力作为核心卖点，因为它代表了"AI+IDE"从简单的代码补全走向"理解需求-制定方案-执行编码"的完整链路。
具体到某个平台，coding plan套餐通常包含：额度内的高频调用权限、更长的上下文窗口、plan agent和build agent的使用权限、团队协作和权限管理功能等。这其实是把企业级的AI编码能力打包成了标准化的订阅服务。
2.4 为什么coding plan里都有"plan"却各说各话
有意思的是，不同厂商的coding plan设计思路差异很大。拿阿里云百炼和火山方舟来说，它们的coding plan虽然都强调agent能力，但侧重点不同：有的更强调企业知识库的接入，有的更强调多agent协作框架，有的更强调模型本身的能力上限。
选哪家其实取决于你的场景。如果你是个人开发者，核心诉求是代码生成质量和IDE集成体验；如果你是团队负责人，关注的是权限管理、知识库纳管、审计日志这类治理能力；如果你在已有大模型服务商生态里，更看重的是和现有API服务的打通程度。
我在实际选型里给出的建议是：先把你的需求spec搞清楚，再去对比plan套餐。你连自己需要什么都说不清，看十家竞品对比表也都是白看。
3. spec的价值：AI编码里的"契约"与"验收标准"
3.1 用机械硬盘的SMART spec来理解什么是真正的"明确"
最近有个热搜词我挺意外的——"机械硬盘和固态硬盘smart spec"。老玩家都知道，硬盘的SMART属性（Self-Monitoring, Analysis and Reporting Technology，自我监测分析与报告技术）是一种规范，它规定了硬盘应该监测哪些指标、每个指标的含义、阈值是多少。比如"C5 Current Pending Sector"表示待重映射扇区数，超过某个阈值就应该警惕了。
为什么我会联想到spec？因为SMART本质上就是一份"硬盘健康状态的spec"：它定义了什么叫正常、什么叫异常、阈值边界在哪、异常后有什么表现。硬盘厂商按照这份spec去实现监测逻辑，用户按照这份spec去理解硬盘状态。
AI编码里的spec也一样。一份好的spec，本质上就是一份"验收契约"：它定义了什么叫"功能做对了"。比如"密码字段少于8位时接口返回4001并提示'密码长度不符合要求'"——这就是一条验收标准。AI写完代码后，你不需要全靠人眼去看代码逻辑，只需要对照spec的验收清单逐条测试即可。
3.2 把spec写成"AI可执行"的三个层次
在AI编码的实践里，spec不是越长越好，关键是层级清晰。我总结了一套三层写法：
第一层：功能目标。用一两句话说清楚这个功能是干嘛的，核心用户是谁，解决什么问题。这一层是给人和AI建立共同语境的。
第二层：功能规则。逐条列出具体的功能行为，每条规则都应该是"如果...那么..."的可验证句式。比如"如果用户未登录访问个人中心，则返回302重定向到登录页"。
第三层：验收标准。定义"完成的定义"，包括正常流程、异常流程、边界条件、性能要求。每条验收标准都对应一个可执行的测试用例。
这里给你一个我在项目里实际用过的模板片段：
功能目标：实现用户密码找回功能。 功能规则：
- 用户在登录页点击"忘记密码"，输入注册邮箱。
- 系统校验邮箱是否存在，如不存在则提示"该邮箱未注册"。
- 存在则生成一次性重置链接，有效期30分钟，发送至邮箱。
- 用户点击链接进入重置页，输入新密码，要求8位以上且含大小写字母。
- 重置成功后强制重新登录，旧密码立即失效。 验收标准：
- 未注册邮箱提交后返回提示，不发送任何邮件。
- 已过期链接访问后返回"链接已失效"。
- 重置成功后旧密码登录返回"密码错误"。
这份spec大概两百字，但AI拿到它之后生成plan，基本不会跑偏。关键就在于每条规则都是"可测试的断言"，而不是"应该支持邮件找回"这种模糊描述。
3.3 spec在AI编码里的三类"坑"和补救手段
第一类坑：写成了方案而非规格。很多人写的spec里大量出现"使用Redis做缓存、采用JWT做鉴权、用消息队列解耦"这类技术方案描述。这在spec层面是越权的——spec应该描述"行为"，plan才描述"技术实现"。如果spec里写死了技术栈，plan就没有优化空间了。
第二类坑：边界条件缺失。最常见的就是只写正常流程，不写异常分支。比如"用户上传头像"的spec里，如果不写文件大小限制、格式白名单、重名处理、存储失败提示，AI就可能用一个最简单的实现糊弄过去，等你上线后才发现问题。
第三类坑：验收标准没法验证。比如"保证系统性能良好"这种验收标准，AI无法执行。应该写成"在1000并发下接口P95响应时间低于500ms"。凡是不能转化为测试断言的标准，在AI编码链路里就是无效信息。
补救手段也很简单：如果发现spec有缺失，先把缺失补上再让AI出plan。不要省这一步。在AI编码场景里，spec返工一次的代价，远小于plan执行到一半发现方向错了的代价。
4. plan与spec的协作链路：从spec到plan再到执行的完整工作流
4.1 我在真实项目里固定下来的四步工作流
用了半年AI编码，我最终沉淀出一套固定的工作流，四个步骤，每个步骤对应一个明确的成果物：
第一步，写spec。这一步我通常手工完成，或者先用AI草拟再手动修订。成果物是一份可以验收的需求规格说明。
第二步，让plan agent基于spec产出plan。plan agent需要做的事包括：理解spec的每一条规则、评估现有代码库的改动范围、设计技术方案、拆解任务顺序、识别风险和依赖。成果物是一份可执行的开发计划。
第三步，让build agent基于plan逐个任务实施。每个任务的完成标准，就是spec里的对应验收项。build agent在实施过程中如果发现spec有歧义或者plan有漏洞，需要停下来提问，而不是自行决定。
第四步，对照spec做验收。逐条验证spec里的验收标准，形成测试记录。没通过的部分回到第二步或第三步修复。
这套工作流的核心思想，是让spec成为整个AI编码链路里唯一的"需求事实源"。plan是对spec的翻译，代码是对plan的实现，验收是对spec的回归。任何一环出现偏差，都能快速定位到是spec的问题、plan的问题还是build的问题。
4.2 一个完整的spec到plan落地示例
我再用一个具体case演示这个流程。假设我要让AI帮我实现一个"订单自动取消"功能，业务规则是：用户下单后30分钟内未支付，订单状态自动变为已取消，并释放库存。
第一步spec，我写成这样：
规则1：订单创建后启动30分钟倒计时，基于数据库服务器时间，非客户端时间。
规则2：到时间后，若订单状态仍为PENDING_PAYMENT，则更新为CANCELLED。
规则3：状态更新后，自动回补锁定库存数量。
规则4：若订单在倒计时内完成支付，取消计时不影响已支付订单。
验收标准：
- 创建订单29分钟后手动查询状态仍为PENDING_PAYMENT。
- 创建订单31分钟后查询状态为CANCELLED。
- 取消后库存数量恢复为下单前数量。
- 支付成功后再触发定时任务，订单状态不变。
第二步，plan agent基于这份spec生成的plan大概包括：
- 方案评估：MySQL定时任务 vs 消息队列延迟消息 vs 应用层调度器，各自优劣势。
- 技术选型：基于当前项目已有的定时任务框架，选择应用层调度器+数据库轮询。
- 任务拆解：
- 新增订单超时查询SQL。
- 实现取消订单服务方法，包含状态校验和库存回补事务。
- 配置定时任务调度周期为每分钟执行一次。
- 增加幂等保护，避免重复取消。
- 编写对应单元测试。
第三步，build agent按这个plan执行，每一步都会引用spec里的规则，并且在完成一条规则后标记完成状态。
第四步，验收测试按spec的验收标准逐条跑。这个流程走下来的好处是，每个环节都有据可查，即使AI在某个环节做错了，你也能清楚知道是spec没写清、plan选型错了、还是build实现偏了。
4.3 什么时候可以跳过spec直接plan
当然，也不是所有场景都需要完整的三层spec。我自己总结了几种可以简化的情况：
原型验证类：比如你想快速验证某个技术方案的可行性，或者做一个demo给团队演示，这时spec可以压缩成两三句话，重点在plan的技术路线评估上。
单文件改动：如果只是一个函数、一个组件的局部修改，写完整spec反而累赘。这时候用简短的"需求描述+验收标准"就够了。
临时脚本：一次性脚本、数据迁移、日志分析之类的工作，不值得写spec。给AI一个明确的目标和输入输出约定，直接让build agent执行就行。
但凡是涉及多模块联动、数据库变更、对外接口、多人协作的功能，我强烈建议别省spec。省了这一步，后面省下来的时间大概率会在返工中加倍还回去。
5. 团队协作中的spec治理与coding plan搭配
5.1 团队级AI编码最容易崩的地方：spec口径不统一
团队协作里的AI编码，最大的挑战不是单点的AI能力，而是大家给AI的输入没有统一口径。我见过一个团队，四个人都在用AI编码助手，但每个人写的prompt风格完全不同，导致同一个功能的AI产出风格千差万别，代码review成本暴涨。
这也是为什么现在很多coding plan套餐都会强调团队协作能力——本质上它们是冲着"让团队的AI使用体验变成可治理的工程实践"去的。比如企业知识库接入可以让AI统一理解团队的规范，权限管理可以限制不同成员的agent使用范围，审计日志可以追溯每一次AI交互。
但工具只是辅助，核心还是要在团队层面建立一套spec的书写规范。我建议团队里至少统一以下几个约定：spec文件放哪里、用什么格式写、验收标准怎么措辞、AI的plan输出在哪里确认、build的代码如何走review流程。
5.2 token plan和coding plan：钱花在哪更值
热搜词里还有一个高频词"token plan"，它和coding plan经常被放在一起讨论，但俩不是一个层面的东西。
简单说，token plan管的是"用多少量"，coding plan管的是"用什么能力"。Token plan通常指按token使用量计费的套餐，适合调用API做自动化处理的场景；coding plan通常指IDE里AI编码助手的订阅，包含的是plan agent、build agent、代码补全、代码解释、测试生成这些端到端能力。
个人开发者的建议是：如果你只是偶尔写写代码，按量付费的token plan更灵活；如果你是每天高频使用AI编码的重度用户，coding plan的固定套餐通常更划算，因为它的定价已经把高频使用的边际成本摊平了。
团队场景我建议优先看coding plan里的团队治理能力，而不是单看token价格。AI编码的隐性成本大头在成果审查和纠错，不在token消耗。一个能稳定产出高质量plan和代码的coding plan，哪怕token单价贵一点，综合成本反而更低。
5.3 train等工具的plan能力与生态现状
最近大家在讨论trae能不能使用scnet的token plan，以及trae里添加模型报错"the api key or ak/sk in the request is mis..."。这类问题本质上是生态打通的问题。
我的看法是：工具链的打通程度确实是选型时要重点考察的指标。AI编码工具正在从单一的编辑器插件，变成一个agent工作平台。你在IDE里配模型、配token plan、配agent流程，本质上是在建立一套自己的AI开发基础设施。
但也不用为了追新工具频繁切换。我个人的建议是：先把核心工作流跑通，也就是"spec+plan+build+验收"这条链路，在哪个工具上跑通就用哪个。工具会迭代，但流程价值是可持续的。
6. 选型建议与个人实测的几条经验
6.1 AI编码工具的"plan能力"怎么测
很多朋友问我，怎么判断一个AI编码工具的plan能力到底行不行。我提供一个简单的测试方法：拿一个你非常熟悉的、已经实现过的功能，用这个工具重新走一遍spec到plan的流程，然后对比它生成的plan和你当时实际做的方案，看差异在哪。
我测过一个工具，它给一个简单CRUD接口生成plan时，方案里居然引入了消息队列。不能说它错，但明显是大炮打蚊子，说明它没有结合项目实际情况去裁剪方案。好的plan能力，不只是能生成步骤，而是能根据代码库上下文和spec约束，给出合理复杂度的方案。
第二个测试维度是提问质量。优秀的plan agent会在plan前主动提问澄清模糊点，而不是不懂装懂直接开干。如果工具在你给的需求明显模糊的情况下还闷头生成plan，那它的plan质量在复杂项目里大概率不可靠。
第三个测试维度是plan的可追溯性。生成plan后，它能不能把plan里的每个步骤关联回spec里的对应规则？能关联的，才是一个可验收的plan，否则plan和spec就是两张皮。
6.2 我踩过的几个plan相关坑
坑一：让AI在plan阶段过度设计。有一次我给它一个简单的内部工具需求，它的plan里引入了权限体系、分布式锁、多租户架构。我盯着plan看了半天，反应过来它是在"炫技"。后来的办法是，在spec里明确加上"技术方案应保持最小可用复杂度，不允许引入未明确要求的中间件和架构组件"。
坑二：plan确认流于形式。刚开始用plan模式时，AI输出plan后我扫一眼就点确认，结果后面实现阶段出了幺蛾子才回头细看，发现plan里有一个明显不合理的设计当时我压根没注意到。现在我的习惯是，每个plan至少要留出十分钟的review时间，重点看任务拆解是否完整覆盖spec、技术选型是否有依据、风险处理是否有应对方案。
坑三：spec中途变更后plan没有同步更新。开发过程中需求调整是常事，但如果spec改了，之前的plan就失效了。我现在的要求是：spec变更必须走变更记录流程，plan agent要基于新spec重新生成受影响的plan部分，然后再让build agent继续。跳过plan直接让build改代码，往往会越改越乱。
6.3 从"AI能写代码"到"团队会用AI交付"的关键一跃
写到这里我想起一个朋友的话：AI编码工具刚开始给人的感觉是"哇它能写代码"，用久了你会发现，真正的分水岭不在AI能不能写，而在于你们的协作流程能不能把AI的产出变成可靠交付。
现在很多团队用AI编码，效率确实提升了，但提升的是"代码生产"环节的效率。而spec、plan review、验收这些环节的效率如果没有同步提升，AI生产出来的代码就会成为新的瓶颈——生成快、审查慢、返工多。
这就是我为什么反复强调spec的价值。它不是一种文档负担，而是AI编码时代的质量基础设施。有了spec，plan才有了方向；有了plan，build才有了边界；有了build，验收才有了依据。这四者的闭环，才是AI编码真正进入工程化的标志。
根据我个人的实测经验，一个团队如果能把"spec先行、plan确认、build执行、验收闭环"这套流程跑顺，哪怕团队成员对AI工具的使用水平参差不齐，整体交付质量也会比你预期的高。关键是流程本身要把AI能力约束在一个稳定的轨道上，而不是让每个人凭感觉去和AI协作。最后再送给大家一句话：别急着让AI写代码，先让AI理解你定义的"正确"是什么。想清楚了这件事，你手里的AI coding工具，才能真正从"玩具"变成"生产力"。
