今年依托 AI 完成了两个 Vue + Node 全栈项目并成功上线。摸索出一套完整的 AI 开发链路：有产品想法后，先让 DeepSeek 发散思路、然后提出建议完善计划、输出项目计划书，再将完整方案直接交给 CodeBuddy 落地编码。代码生成完成后，通过浏览器直观验收效果，针对页面报错、功能异常反复迭代修改，多轮调试后完成项目上线。这套流程可以跑通，意味着我们已经可以使用AI完成初级的项目从计划到开发再到上线了。但复盘了两个上线项目后发现，这套模式存在结构性、根本性的缺陷：整个开发链路高度依赖「单人决策 + 单一主智能体」，无职责分离、无独立校验、无标准化约束，本质是粗放的人工驱动模式，这是典型的AI指令式开发。
AI指令式开发看似是极速落地的开发模式，背后藏着三个致命问题，也是后期 Bug 频发、维护成本飙升的根源。
第一：需求方案是描述性的，而非可验收的。
AI 生成的项目计划书，只会定义「要做什么」，不会定义「做到什么标准才算合格」。比如方案只会写「实现账号登录功能」，但不会明确边界规则：空输入禁用提交按钮、非法格式实时校验、密码错误脱敏提示、高频错误账号锁定等核心细节。当我们直接把模糊方案交给 CodeBuddy 时，AI 会默认需求已经完全闭环，直接启动编码工作，最终产出的代码必然缺失大量边界逻辑。
第二：验收靠主观体感，而非标准化验证
过去判断功能是否完成的标准非常简单：页面能打开、主流程能跑通，就算验收通过。但真实业务的边界场景、异常处理、并发冲突、容错机制，完全没有系统性覆盖。这些被忽略的隐性问题，不会在开发阶段暴露，只会在项目上线后转化为用户投诉、线上报错、半夜紧急修 Bug，极大拉高了运维和迭代成本。
第三：实战经验碎片化，无法沉淀复用。
我们能清晰感知到「CodeBuddy 容易遗漏接口异常处理」「AI 代码缺少边界校验」等问题，但无法系统化总结根因，更无法形成可复用的规范。每开启一个新项目，都要重复踩坑、重复试错，经验无法沉淀为团队、个人的工程资产。这并非工具本身的缺陷，而是交互模式的底层问题。传统「我指令、AI 执行」的指令式开发，适配的是快速试错的小需求；而企业级、可维护的 AI 开发，必须切换为规范驱动模式：提前定义标准、明确验收规则，让 AI 按规格落地，让人独立校验结果。
两种模式的本质差异，是「事后补救」与「事前约束」的工程思维差距； 模式转变的核心真谛：把质量判断、标准定义，从执行之后提前到执行之前。
| 维度 | 指令式开发 | 规范驱动开发 |
|---|---|---|
| 输入依据 | 模糊想法 + 粗略计划书 | 可落地 Spec + 严格接口契约 |
| AI 角色定位 | 被动执行人工指令 | 按规范生成、按契约对齐、按标准验收 |
| 质量保障时机 | 代码生成后，人工事后审查 | 代码生成前，提前定义完成标准 |
| 可维护性逻辑 | 依赖事后修补、迭代救火 | 依赖事前约束、标准化落地 |
| 经验沉淀方式 | 碎片化、不可复用、无法传承 | 固化为项目 Rules、Spec 模板、工程规范 |
在讲具体方法之前，我们需要先把后面会用到的核心概念过一遍。这些名词在文档和社区里频繁出现，但很少有人把它们之间的关系讲清楚。我会尽量简短解释每个概念，重点说明它们各自解决什么问题、以及和相邻概念的区别。 如果你想深入了解每个概念的底层机制、配置方式与适用场景，文末附带独立文章链接。
1、模型（纯大脑，只会想、不会动）
模型即大语言模型，例如 Claude Opus、GPT-5.5、DeepSeek V3。它的本质是文本的输入和输出。你问它“怎么写一个 Vue 组件”，它会给出代码建议，但它无法自行修改文件、运行测试、查看报错。模型是大脑，但没有手，它能告诉你怎么做，自己无法帮你做。
2、Harness（让大脑能稳定干活的整套操作系统）
Harness 是模型之外的全部基础设施。微软 Agent Framework 的官方定义：Agent Harness 是运行时脚手架，负责把语言模型转化成可以执行工作的 Agent。它包含以下组件：
完整公式：Agent = Model + Harness。
3、智能体 Agent（会思考、会动手、会闭环干活）
智能体是模型加上 Harness 之后形成的完整形态：拿到一句模糊需求，它可以自主思考分析、拆解任务、规划步骤、调用工具、校验结果，发现问题后迭代调整。你只需要说“帮我实现登录功能”，它会自行判断优先读取哪些文件、先写前端还是后端、完成后如何验证。用计算机架构类比更容易理解：
打个比方：模型是大脑，Harness 是操作系统和工具箱，智能体是能独立干活的人。大脑提供推理能力，Harness 提供执行环境，两者组合起来才形成智能体。
工具和智能体的核心区别在于自主规划能力。 工具能执行，但不会自己决定“先做什么、后做什么”；智能体能拆解任务、规划步骤、判断依赖关系。这个“规划”能力，来自 Harness 里的编排逻辑。
4、三个层次在真实产品中的对应关系
这些产品本质上都是专用人工智能（ANI），不是 通用人工智能（AGI）。它们的能力边界受限于 模型、Harness 的配置——配置了哪些工具、哪些 Skills、什么编排逻辑，决定了它能做什么、不能做什么。
智能体存在一个核心矛盾：它需要掌握大量项目知识，但上下文窗口容量有限。如果把所有规范、流程、项目背景全部塞进系统提示词，会稀释模型注意力，降低执行效果。Rules、Skills、Memory 就是用来解决这个矛盾的三层机制。
1、Rules 是项目的“宪法”
解决是：在这个项目里，我们永远怎么做事。 核心特征是始终生效。规则内容会自动追加到每一轮对话上下文的开头，AI 在生成任何代码前，就知晓项目规范。 Rules 适合存放高频、简短、可机械执行的约束：代码风格、技术栈偏好、目录结构约定。CodeBuddy 支持多层级规则：项目规则存放在 .codebuddy/rules/，纳入版本控制，可团队共享；用户规则全局生效，跨项目复用。实践约束：规则尽量控制在500行以内，过长反而稀释模型注意力。
2、Skills 是按需加载的“操作手册”
解决的是：遇到这类任务时，按哪些步骤执行。 Skills 和 Rules 最本质差异是加载时机：Rules 常驻上下文；Skills 仅当 Agent 判断任务相关时才加载。Skills 使用渐进式披露机制：会话初始只加载每个 Skill 的名称与简介（约100词）；当匹配任务时，才将完整 SKILL.md 载入上下文。 Skills 适合存放多步骤可复用流程：代码审查清单、发布检查步骤、安全审计流程、故障排查手册。
3、Memory 是自动积累的“经验笔记”
解决的是：上次发生了什么。 它和人工编写的静态约束 Rules 互为补充。CodeBuddy 的 Auto Memory 系统支持跨会话持久记忆检索：用户级记忆保存在 ~/.codebuddy/CODEBUDDY.md，项目级记忆放在项目根目录 CODEBUDDY.md。 Memory 存在明显局限：如果有知识需要稳定可靠复用，应该写成 Rule，不要依赖自动生成的 Memory。记忆会不断累积、过期，甚至互相冲突。
一句话概括三层分工：Rules 管“人设与红线”，Skills 管“怎么把某类活干对”，Memory 管“记住上次的教训”。
1、MCP（模型上下文协议）
解决的是：Agent 怎么连接外部世界。 MCP 是标准化AI应用对接外部工具、数据源的开放协议。有了MCP，不必为每个AI工具单独开发数据库、Git、文件系统对接能力，协议定义统一接口。MCP基于JSON-RPC 2.0，在Hosts、Clients、Servers之间建立通信。核心能力是动态工具发现：Agent可以自动读取MCP服务暴露的工具列表与描述。CodeBuddy、Claude Code、GitHub Copilot均已支持MCP。
2、A2A（Agent-to-Agent Protocol）
解决的是：Agent 怎么和另一个 Agent 协作。 简单区分：MCP是给Agent装上“手”，用来访问文件、Git、数据库；A2A是让Agent找到“同事”，可以把任务委派给其他智能体，不需要暴露自身内部逻辑。一个实用判断：如果你打算写MCP服务来协调多个Agent，那方向错了，这类场景应该使用A2A。
3、Hooks：比Rules更强的硬约束
Rules属于软约束——它告诉AI应该怎么做，但AI理论上可以忽略。Hooks是硬约束，在Agent生命周期的指定节点强制执行shell命令或HTTP处理器，AI无法绕过。典型场景：拦截危险命令、提交前自动执行lint、写入文件前扫描敏感信息。Claude Code文档把Hooks定位为：必须发生的事情，交给Hook。放到工程实践上，Hooks补齐了一个关键认知：规范驱动不只有“告诉AI怎么做”，还包含“强制AI必须做到”。
前面讲的 Rules、Skills、Memory 都是单个智能体的内部机制。当任务复杂到需要多个智能体协作时，Harness 的编排层就派上用场了。当前主流工具提供了三种编排形态，它们的核心差异在于谁持有编排计划。 这里我们讲得细一点，第四章直接讲怎么用。
1、 Subagents（子代理）
当主 Agent 遇到与某个子代理专业领域匹配的任务时，它会将该任务委派给子代理，子代理独立工作并返回结果。Subagents( 子代理 )有独立的上下文窗口和受限的工具权限，干完活把结果交回给主 Agent，中间探索过程不污染主对话。核心价值在于上下文保留——子代理在自己的上下文中运行，防止主对话被污染，同时通过专业化知识提高特定任务的成功率。
接地气的比喻 零工市场 ：你家装修，需要一个人帮你盯着某个环节。你去零工市场叫了一个电工，告诉他“把厨房的插座都换成带开关的”，他干完活给你一个总结“换好了，一共 6 个，线路没问题”，然后就走。你不知道他在过程中试了几种接线方式，也不关心——你只拿到结果。
两种调用模式
1、自动模式由主 Agent 判断调用时机，子代理拥有独立上下文，执行时不污染主会话，但调用过程中不能中途干预；
2、 手动模式允许用户主动选择并完全替代主 Agent，适用于需要深度定制交互流程的场景。两者在行业里已成为通用范式——自动模式让主 Agent 自行判断何时派发，手动模式由用户明确触发。不同工具命名不同，Claude Code 用 auto / default 区分，Windsurf 用 Interactive / Automatic 区分。
两种执行方式：
1、串行执行是默认行为：主 Agent 逐轮决策——派一个子代理出去，等它回来，再根据结果决定下一步。这种方式适合有依赖关系的任务链。
2、并行执行需要显式触发。主流工具都支持并行子代理，只是触发方式不同：CodeBuddy 通过省略 subagent_type 参数进入 Fork 模式，Claude Code 通过 fork 模式创建继承完整上下文的子代理，Cursor 用 /multitask 命令启用异步并行，GitHub Copilot CLI 用 /fleet 派发并行子代理，Codex 则要求用户显式请求并行。并行执行能显著缩短多任务总耗时——传统串行模式下重构、测试、审查三个任务约需 47 分钟，并行后总耗时缩短至约 19 分钟。
Subagents 分两个级别：project 级只在当前工作区生效，user 级适用于所有项目，配置一次即可跨项目复用。
典型使用场景：代码审查、代码库探索、日志总结、单模块生成。判定标准是“只要结果，不需要讨论”。
Agent Teams，可以协调多个 agent 实例组成团队协作的机制。通过共享任务列表、成员间消息通信和集中式管理完成复杂任务。一个会话作为团队领导（team-lead），负责协调工作、分配任务和汇总成果；其余成员各自独立工作，拥有自己的上下文窗口，并通过消息系统直接相互沟通 。
接地气的比喻驻场项目组：你有一个装修项目，需要同时推进水电、木工、油漆三个环节。你组了一个项目组：一个工头（Lead）负责分配任务和协调，三个工人各自负责一个环节，工人之间可以直接喊话——“我这边电线走完了，你可以开始封墙了”。工头不用传话，工人自己对进度。
和 Subagents 最本质的区别是通信拓扑：Subagents 只能向主 Agent 汇报结果，而 Agent Teams 的成员之间可以直接发消息，你甚至可以绕过领导直接 @ 某个成员对话。团队成员共享一个任务列表，任务有三个状态（待处理、进行中、已完成），支持依赖关系——某个任务依赖的前置任务没完成，它就不能被认领。
Token 消耗显著高于单会话，因为每个成员都是独立的完整实例。成员之间不隔离文件修改，必须手动划分文件所有权，否则会互相覆盖。
典型使用场景：研究与评审（多个成员同时调研问题的不同方面，然后分享和质疑彼此的发现）、新模块开发（每个成员负责独立模块）、竞争性假设调试（并行测试不同假设）、跨层协调（前端、后端、测试各由不同成员负责）。判定标准是“任务需要协商和讨论，且可以拆成互不重叠的文件范围”。
Workflows是一段 JavaScript 编排脚本，可以在后台调度数十甚至数百个子代理协作完成任务。 脚本本身可读、可改、可重跑，包含agent()、parallel() 等调用，每次 agent() 都派出一个独立子代理工作；脚本拿到中间结果后，可以分支、可以并行、可以再投递给下一批子代理。
接地气的比喻固定流水线：你要批量处理 500 个文件。你不会一个个叫零工，而是写一份施工计划：第一步派 10 个工人同时扫描前 50 个文件，第二步把结果汇总，第三步对发现问题的文件派 3 个工人交叉验证，第四步生成报告。计划写好后，你不在现场盯着，流水线自己跑。每个工人干完活，结果自动传给下一个环节。
Workflows 和 Subagents、Agent Teams 最本质的区别是“谁持有编排计划”。Subagents 和 Agent Teams 的下一步动作都由主agent逐轮决策，所有中间结果都落进上下文窗口；而 Workflow 把循环、分支、中间结果都交给脚本本身管理，主agent的上下文里只剩最终答案。
这意味着编排逻辑可读、可改、可重跑。Workflow 脚本保存在 session 目录下，你可以打开阅读它的逻辑。如果某个编排流程你会反复使用（比如每次分支都跑的审查流程），可以用 /save-workflow 保存为项目级或用户级命令，之后用 /名字 直接调用。
Workflows 支持对抗性验证：可以让独立代理在报告之前对彼此的发现进行审查，或从多个角度起草方案再相互权衡，单次结果的可信度比“一遍过”高得多。
典型使用场景：全 monorepo 的接口契约巡检、一组 issue 的批量分诊、跨多个仓库的交叉印证调研、大型迁移。判定标准是“任务规模大、需要对抗验证、且流程可复用”。
1、Subagents 是“叫个零工来干活，干完汇报”——主 Agent 逐轮决策，结果汇总回主上下文。
2、Agent Teams 是“组个项目组，工人之间能互相喊话”——领导协调，成员自行协商，共享任务列表。
3、Workflows 是“写份施工计划，流水线自己跑”——脚本持有编排逻辑，中间结果存在脚本变量里，不占用主对话上下文。
使用这三种形态的前提是：Craft 主 Agent 已经判断“这个任务需要协作”，或者你主动触发。我们平时在对话框里直接说需求、改 Bug，用的是 Craft 主 Agent 模式，它自己规划、自己执行、自己验证，相当于一个人单线程干所有活，不属于这三种编排形态中的任何一种。 这些编排模式不是 CodeBuddy 独有的。Claude Code 有几乎完全对应的三件套，Cursor 有异步子代理和 worktree 隔离，Codex 有并行多 agent 支持，GitHub Copilot 有自定义代理和 handoff 链。我在第四章会详细展开它们的适用场景和实操方式。
Spec 属于任务输入层的核心工件，解决的是：这次任务要做什么，怎么才算完成、做对。 它和Rules、Skills不在同一层级：Rules、Skills是长期可复用资产；Spec是单次功能交付的输入。
一份合格Spec包含：摘要（一两句话描述功能）、用户故事（谁、要做什么、目的）、验收标准（可测试、可观察条件）、功能需求、非功能需求、边界条件。 验收标准必须是可观察事实。例如写“无效订阅源URL会展示明确错误提示”，而不是模糊描述“系统要妥善处理错误”。
Spec定义“做什么”，Plan定义“怎么做”，二者需要分离。你投入撰写Spec的精力，应当和手动开发这个功能相当。这部分实践细节，第三章展开。
大众普遍存在一个认知误区：认为 AI 天生容易写出烂代码、漏洞代码。但 2025 年多项工程实证研究给出了相反结论：在常规业务场景下，AI 生成代码的缺陷率、复杂度、规范性，并不劣于人工手写代码。AI 开发真正的质量危机，不是生成能力差，而是人类审查机制失效。传统人工编码存在天然质量闸门：看不懂就写不顺、写不顺就会自查、逻辑不通不敢提交。但 AI 输出的代码天生工整、命名规范、结构自洽，极易让人产生「解释深度错觉」——看似完全读懂，实则忽略了隐性边界、异常分支、架构偏差、并发漏洞，直接放行合并。这就是 AI 项目 Bug 隐性爆发的根源：问题不在编码环节，而在审查环节的松懈与缺失。因此，现代 AI 工程的质量校验，早已从「开发结束后的末端卡点」，升级为全流程持续验证体系：自动化 Lint、单元测试、对抗式独立审查、端到端工作流校验，缺一不可。质量不再靠人工体感，而是靠工程体系兜底。
AI 开发最大的工程风险，不是单文件代码不整洁，而是高速迭代带来的架构漂移与技术债扩散。人工开发速度慢，问题是点状、可控的；但 AI 生成代码效率极高，一旦没有前置约束、统一规范，每一次迭代都会把不标准写法、不统一架构、不严谨逻辑批量扩散到整个项目，后期重构与修复成本呈指数级上涨。规范驱动开发的核心变革，一句话讲透：把质量治理从「事后修补」，彻底提前为「事前定义、事中约束、全程可校验」。规范驱动不是堆砌文档、不是形式主义，而是将验收标准、边界条件、接口契约、架构约束、项目红线，全部转化为 AI 可识别、可执行、可落地的 Spec、Rules、Skills。让 AI 告别「自由发挥、凭猜测编码」，转变为「按规格交付、按流程执行、按标准验收」。同时，将零散的临时提示、碎片化经验沉淀为标准化 Skills，还能彻底解决 AI 开发中最头疼的指令膨胀、上下文腐化问题，长期保持智能体执行精准、逻辑稳定、不跑偏。
经过前面所有概念拆解，我们用一张总表，收束整套 Harness 工程体系。所有能力各司其职、共同构成可控、可维护的 AI 开发架构。
| 概念 | 在 Harness 中的位置 | 回答的问题 |
|---|---|---|
| Rules | 系统提示词层 | 永远怎么做、红线是什么 |
| Skills | 工具/能力层 | 这类任务按什么步骤做对 |
| Memory | 记忆层 | 上次发生了什么、经验是什么 |
| Spec | 任务输入层 | 这次做什么、怎么算做对 |
| Subagents/Teams/Workflows | 编排层 | 谁来做、如何分工协同 |
| MCP | 工具连接层 | 怎么连接外部工具与资源 |
| A2A | 跨智能体通信层 | 怎么把任务委派给其他 Agent |
| Hooks | 强制执行层 | 流程必须执行、不可绕过的约束 |
大模型决定 AI 的脑力上限，而 Harness 整套工程体系，决定了 AI 开发项目的质量下限和可维护性上限。从指令式开发走向规范驱动开发，本质就是从依赖模型玄学，走向可控、可沉淀、可复用的工程体系。如果你想深入了解每个概念的机制、配置方式和适用场景，我单独写了一篇《AI 应用开发核心概念与词汇扫盲》。下面直接进入正题：怎么从「扔想法」转向「写规格」。
前两章中，我们区分了「指令式开发」与「规范驱动开发」的本质差异，也厘清了模型、Harness、Rules、Skills、Spec 等整套 AI 工程底层体系。绝大多数人 AI 开发翻车、项目越做越乱、Bug 源源不断、迭代越改越崩，根本原因不是不会写代码，而是开发启动前没有定义清楚合格标准。传统人工开发可以靠经验兜底，但 AI 开发极度依赖前置约束。没有标准，AI 就只能靠模型概率“猜需求”，开发者只能靠肉眼体感“做验收”。而 Spec 驱动的核心价值，不是让代码写得更快，而是让每一次开发都可验证、可追溯、可维护、可迭代。把质量标准从事后补救，提前为事前定义；把主观感觉的验收，升级为客观标准的清单。这就是规范驱动 AI 工程体系的核心基石。本章我们落地整套最关键的实操转型：放弃扔想法式开发，全面进入 Spec 规格驱动开发。
我早期的 AI 开发流程，也是业内最主流的方式：有了产品想法后，先和大模型发散梳理，然后产出一份项目计划书，再直接整段交给 AI 去写代码。这套流程虽然能快速跑通 Demo、实现业务主流程，但完全撑不起工程级、可维护、低返工的正式项目。它存在一个结构性的致命缺陷：项目计划书本质是 Plan，只回答 “要怎么做”，却不回答 “怎么算做完、怎么算做对”。它只会规划模块顺序与实现步骤，但不会定义完成标准、边界规则和异常处理。最终开发者只能凭体感验收 —— 主流程能跑、页面能打开，就判定开发完成，导致所有边界场景、异常逻辑、安全约束与极端用例全部处于失控状态。而 Spec 恰好补齐了这套流程的短板：它的核心价值不是描述功能，而是定义验收标准，把模糊的主观感受，转化为客观、可测试、可逐条核对的工程落地清单。
Spec 是规范驱动开发的核心工件，拥有固定、通用、可落地、可复用的标准结构。一份合格的 Spec，必须覆盖「是什么、谁来用、做什么、怎么算对、不能做什么」。下面是可直接复用的生产级 Spec 模板以及具体如何写：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# Spec: [功能名称] ## 摘要 [一两句话说明这个功能解决什么问题，给谁用] ## 用户故事 作为 [角色]，我想 [做什么]，以便 [达到什么目的]。 ## 验收标准 [每条都是可观察、可测试的事实，用复选框列出] ## 功能需求 [系统必须实现的具体行为与底层规则] ## 非功能需求 [性能、安全、兼容性、稳定性等量化约束] ## 边界条件 [异常输入、极端场景、并发、网络、权限等边界] ## 不做什么 [明确排除的范围，防止 AI 过度发挥] |
摘要：控制在一两句话，只定义功能定位，不写实现细节。作用是让人和 AI 统一认知，避免理解跑偏。示例：「用户设置页，允许已登录用户修改头像、昵称和密码，完成个人信息管理」。
用户故事：固定句式：「作为…我想…以便…」。这个句式的核心价值，是强制你写清楚使用者、行为、业务价值。写不出“以便”的功能，大概率是冗余需求，可以直接不做。
验收标准（最重要）：验收标准是 Spec 的灵魂，也是后续编码、审查、测试、上线的唯一依据。每一条验收标准必须满足：前置条件明确 + 操作明确 + 结果可观察。下面是典型的优劣对比：
| 模糊写法（错误） | 可验收写法（正确） |
|---|---|
| 处理密码错误 | 密码错误时，页面顶部显示“用户名或密码错误”，不透露具体错误类型 |
| 支持头像上传 | 选择超过 2MB 的图片时，提示“图片不能超过 2MB”，不执行上传 |
| 保证账号安全 | 连续 5 次密码错误后，账号锁定 15 分钟，期间正确密码也无法登录 |
模糊写法的通病：没有对错判定标准，AI 怎么写都不算错，你永远无法彻底验收。可验收写法的核心：任何人拿着标准，都能统一判断通过或不通过。
功能需求：和验收标准互为补充。验收标准是「用户视角的表现」，功能需求是「系统视角的规则」。例如验收标准是“密码错误统一提示”，功能需求是“用户密码必须经过 bcrypt 哈希存储，禁止明文保存”。
非功能需求：必须量化、禁止空话。不要写“性能好、安全性高”，要写：登录接口 P95 响应 ≤ 500ms、全程 HTTPS、Token 有效期 24 小时、刷新 Token 7 天。
边界条件：AI 最容易遗漏的部分，也是线上 Bug 最多的地方。固定六个枚举维度：空值输入、格式错误、内容超限、重复并发、网络异常、权限越界。只要按这六点遍历，绝大多数边界问题都能提前覆盖。
不做什么：和“做什么”同样重要。明确排除范围，避免 AI 擅自扩展功能、过度开发，导致项目臃肿、架构漂移、需求不可控。
Spec 不需要文采，只需要规范。掌握四个技巧，就能写出工业级可验收规格。
不要自己苦思冥想写全 Spec，正确方式是「人机协同澄清需求」。
specs/ 文件夹，每个功能一个 md 文件。Spec 和代码同等重要，需求变更必须先改 Spec，再改代码。只写 Spec 没用，默认情况下 AI 不会主动读取和遵守。必须通过 Rules 将 Spec 变成强制约束。在 .codebuddy/rules/ 新建 spec-driven.md。配置完成后，新开对话测试：让 AI 实现对应功能，先读 Spec、再写代码即代表规则生效。
|
1 2 3 4 5 6 7 8 9 |
--- alwaysApply: true --- ## Spec 驱动开发规则 1. 所有代码生成必须引用 `specs/` 目录下对应的 Spec 文件。 2. 实现必须覆盖 Spec 中所有验收标准，不得遗漏。 3. 如果 Spec 中没有定义某个行为，不要自行发挥，先询问确认。 4. 如果实现过程中发现 Spec 有矛盾或遗漏，先更新 Spec，再改代码。 5. 功能完成后，逐条对照验收标准输出检查结果。 |
验证是 Spec 驱动中最容易被跳过、也最不能跳过的环节。原因很简单：生成代码的 AI 和验证代码的 AI，不能是同一个会话。 自己评自己永远偏正面——它知道自己为什么这么写，会默认自己的实现是合理的。独立验证者没有这层心理包袱，它只拿着 Spec 逐条对照，看到的只是代码实际写了什么。 独立验证的核心操作只有一条：开一个干净的新会话，不继承生成阶段的任何上下文。
验证发现的问题分三类处理
验证过程中发现实现和 Spec 不一致，不要直接改代码。先判断是哪种类型的不一致，再决定改哪个。
验证频率按风险分级
完整行为验证的成本不低，如果每个任务都做，整体效率会被拖慢。把验证资源集中在高风险任务上，才能在质量和效率之间取得平衡 。不需要每个任务都做完整的端到端验证。按任务风险分级：
很多人写 Spec 要么太泛、要么太死，核心边界只有一句话：Spec 管结果和标准，不管实现和过程。Spec 只定义“做什么、怎么算对”，不定义“具体怎么写、用什么方案”。写太细会锁死 AI 优化空间，让架构和代码强耦合。同时要分清四大工程工件的层级关系： 通用约束放 Rules、单次需求放 Spec、流程步骤放 Skills、经验教训放 Memory，互不重叠、各司其职。
| 工件 | 内容定位 | 生命周期 |
|---|---|---|
| Spec | 本次功能的需求、边界、验收标准 | 单次功能周期 |
| Rules | 项目永久编码红线、规范 | 长期全局生效 |
| Skills | 可复用流程、审查步骤、标准动作 | 按需加载复用 |
| Memory | 历史经验、踩坑记录、项目偏好 | 动态积累 |
本节用真实项目的「用户设置页」，完整走一遍从需求澄清、Spec 定稿、任务拆分、开发验证到上线归档的全流程。每个阶段都有具体的操作、产出和判断依据，读者可以照着做。
阶段一：需求澄清，让 AI 先提问
阶段二：Spec 定稿，完整文件结构
Spec 管“做什么”和“怎么算做对”，不管“怎么做”。功能需求写“密码必须哈希存储”，不写“用 bcrypt 具体怎么实现”；验收标准写“密码错误时显示统一提示”，不写“用 try-catch 捕获错误”。 把澄清结果整理成 specs/user-settings.md。下面是一份完整的 Spec 文件结构：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
<strong># Spec: 用户设置页</strong> <strong>## 摘要</strong> 已登录用户可以修改头像、昵称和密码，完成个人信息管理。 <strong>## 用户故事</strong> 作为已登录用户，我想修改头像、昵称和密码，以便管理我的个人资料。 <strong>## 验收标准</strong> - [ ] 头像区域显示当前头像，未设置时显示默认头像 - [ ] 点击头像可选择本地图片，支持 jpg/png/webp 格式 - [ ] 选择超过 2MB 的图片时，显示“图片不能超过 2MB”，不上传 - [ ] 上传成功后，刷新获取新头像 URL 并实时更新 - [ ] 上传失败时，展示具体失败原因 - [ ] 昵称输入框回显当前昵称，最大 20 字符 - [ ] 昵称清空后，提交按钮禁用，输入框出现视觉警示 - [ ] 昵称修改成功后，显示“保存成功”提示，3 秒消失 - [ ] 密码修改需输入旧密码、新密码、确认新密码 - [ ] 新密码不足 8 位提示“密码至少 8 位” - [ ] 两次密码不一致给出对应提示 - [ ] 旧密码错误给出对应提示 - [ ] 改密成功刷新 token，不强制登出 - [ ] 所有请求期间按钮 loading 禁用 <strong>## 功能需求</strong> - 密码必须经过 bcrypt 哈希后存储，禁止明文保存 - 头像上传接口为异步，前端需轮询获取新 URL - 改密成功后刷新 token，不强制用户重新登录 <strong>## 非功能需求</strong> - 头像上传接口 P95 响应时间 ≤ 2s - 所有请求全程 HTTPS - Token 有效期 24 小时，刷新 Token 有效期 7 天 <strong>## 边界条件</strong> - [ ] 未登录访问自动跳转登录页 - [ ] 网络异常提交给出错误提示 - [ ] 连续点击只触发一次请求 - [ ] 上传中途取消无状态残留 <strong>## 不做什么</strong> - 不支持第三方绑定 - 不支持邮箱修改 - 不支持多因素认证 |
阶段三：可行性检查，修正 Spec 矛盾
Spec 初稿写完后，先让 AI 读一遍，检查三个问题：有没有互相矛盾的要求？有没有技术上做不到或成本过高的？有没有遗漏的依赖？ 这个阶段改 Spec 只要五分钟，写完之后再发现要改代码，可能要半天。可行性检查是成本最低的修正时机。 AI 排查出两处冲突：
| 问题 | 原 Spec | 冲突原因 | 修正后 |
|---|---|---|---|
| 头像更新 | 上传后立即更新 | 后端接口为异步，无法即时获取 | 上传成功后刷新获取新头像 URL |
| 改密后行为 | 强制重新登录 | 现有架构不支持强制下线 | 刷新 token，不强制登出 |
阶段四：拆任务、标依赖、定顺序（含并行调度）
让 AI 根据 Spec 拆分任务清单，每个任务标注依赖关系、文件范围、对应的验收标准、同时判断哪些任务可以并行。
| 任务 | 依赖 | 文件范围 | 对应验收标准 | 可否并行 |
|---|---|---|---|---|
| 后端接口 | 无 | server/routes/settings.js | 6、8、13 | ✅ 可与昵称组件并行 |
| 前端头像组件 | 后端接口 | src/views/Settings/AvatarUploader.vue | 1-5 | ❌ 依赖后端 |
| 前端昵称组件 | 无 | src/views/Settings/NicknameEditor.vue | 6-8 | ✅ 可与后端并行 |
| 前端密码组件 | 后端接口 | src/views/Settings/PasswordEditor.vue | 9-13 | ❌ 依赖后端 |
| 集成测试 | 全部组件 | tests/settings.spec.ts | 1-14 | ❌ 依赖全部 |
阶段五：按依赖顺序生成代码（含并行调度）
按依赖拓扑排序执行。无依赖且可并行的任务同时启动，有依赖的任务等前置完成后启动。 并行执行的前提是文件所有权不重叠。如果两个任务改同一个文件，必须串行执行，否则会互相覆盖。Agent Teams 的成员之间不隔离文件修改，必须手动划分文件所有权。在拆任务阶段就把文件范围标注清楚，执行时严格按照标注分配，是避免冲突的关键。
如果你使用的是支持 Agent Teams 或类似协作机制的工具，可以用更结构化的方式描述团队分工："创建一个团队：一个成员负责后端接口 server/routes/settings.js，一个成员负责前端昵称组件 src/views/Settings/NicknameEditor.vue。两者文件不重叠，不需要协商。后端接口完成后，@前端头像组件成员和@前端密码组件成员分别开始工作。"
到这里，需求已经澄清、Spec 已定稿、任务已拆分、代码已生成。接下来四个阶段全部围绕“验证”展开：先逐模块验证，再端到端验证，再根据验证结果决定改 Spec 还是改代码，最后归档。
阶段六：逐模块独立验证
每个模块写完后，立刻在隔离环境中验证它自己负责的验收标准。 不要等全部写完再验证。 这个阶段的核心是尽早发现问题。一个模块写完立刻验证，比全部写完再验证，返工量少得多。但验证的粒度是“模块级”，完整功能——端到端验证放到下面。前后端功能模块验证示例：
|
1 2 3 4 5 |
#前端昵称组件完成后，写一个最小的 Vitest 用例，测试“昵称清空后提交按钮禁用” test('昵称清空后提交按钮禁用', () => { render(NicknameEditor, { props: { nickname: '' } }) expect(screen.getByRole('button', { name: '保存' })).toBeDisabled() }) |
|
1 2 3 |
# 后端接口完成后，用 curl 验证： curl -X GET /api/settings/profile -H "Authorization: Bearer <token>" # 断言返回 200，且响应体包含 nickname、avatar 字段 |
阶段七：全新会话端到端独立验证
所有模块完成后，开一个干净的新会话，在真实运行环境中验证完整用户路径。 验证者需要拿到三样东西：Spec 文件、实现代码、运行环境。验证者打开浏览器，逐条执行 14 条验收标准，输出结构化报告：
|
1 2 3 4 5 6 7 8 9 10 11 |
<strong>## 验证报告：user-settings</strong> <strong>### 通过项</strong> - [x] 第 1-6 条：全部通过 ✅ - [x] 第 8-14 条：全部通过 ✅ <strong>### 未通过项</strong> - [ ] 第 7 条：昵称清空后，提交按钮显示为禁用状态 - 实际表现：按钮确实禁用，但输入框没有视觉警示 - 问题类型：实现错误 - 建议处理：输入框边框变红 |
阶段八：先改 Spec，再改代码
阶段九：Spec 归档入库
specs/user-settings.md 成为这个功能的唯一事实来源。后续如果产品经理说“昵称长度改成 30 字符”，先改 Spec 第 6 条，再让 AI 按新 Spec 重新生成。新人接手时，Spec 就是最好的功能文档。 如果改造的是存量功能，还需要做对等验证。 本节案例是新建功能，不涉及原有行为。但如果你改造的是一个已经上线的旧功能，需要在改造前先记录它的当前行为——输入什么、输出什么、什么情况下报错。改造完成后，用同一组输入跑一遍新实现，对比输出是否一致。
怎么记录当前行为： 打开浏览器，把核心路径手动走一遍，记录每一步的输入和输出。如果原有代码有测试用例，直接跑一遍，把结果保存下来。
怎么对比： 改造完成后，用同一组输入跑一遍新实现。如果原有测试用例还在，直接跑；如果没有，手动走一遍核心路径，逐条对比输出是否一致。不需要覆盖所有场景，但核心路径和关键边界条件必须覆盖。
对等验证是存量项目改造最大的风险点——新功能不对可以再改，但原有行为被破坏，可能上线后才发现，修复成本高得多。
前面八节分别讲了 Spec 的写法、约束、验证和完整案例。这一节把所有落地相关的内容收拢到一起，方便你直接照着执行。
目录与版本管理
Spec 统一放在项目根目录的 specs/ 下。功能少时扁平存放，功能多时按模块分组（specs/auth/、specs/user/）。命名用 功能名.md 或 编号-功能名.md，保持一致性比选哪种更重要。功能上线后 Spec 不删除，需求变更时先改 Spec 再改代码，两者放在同一个 commit 里提交。每季度审查一次 Spec 目录，超过半年没更新且功能已稳定的归档，和代码不一致的更新或删除。
依赖管理与评审机制
一个功能往往依赖另一个功能。在每个 Spec 文件顶部加 dependencies 段落，写清楚依赖哪个 Spec 的哪个接口或数据结构。按依赖拓扑排序执行，被依赖的先做。如果两个 Spec 互相依赖，说明拆分有问题——应该合并或重新划分边界。
评审机制分两种：个人项目隔一天再看一遍，刚写完时你觉得每句话都清楚，隔一天再看往往会发现模糊点；团队项目让至少一个其他人评审，核心任务是回答“我能不能看懂每条验收标准并判断通过还是不通过”。评审聚焦三个重点：验收标准是否可测试、边界条件是否完整、功能需求和用户故事是否一致。评审意见写在 Spec 文件末尾的“评审记录”段落里。
效果度量
用四个指标判断 Spec 驱动有没有真正起作用：
不需要精确统计，用一两周记录就能看出趋势。四个指标都在向好，说明流程在起作用；某个指标持续恶化，针对性地调整。
与其他方法论的关系
Spec 驱动和 TDD、BDD、ADR 不冲突，是互补关系：
docs/adr/，Spec 放 specs/，两者共存。Spec 驱动的价值不是取代已有工程实践，而是在 AI 开发场景下补充了一个环节：把“怎么算做对了”从模糊感觉变成可执行清单。
常见失败模式与避坑
必须由人决策的内容：功能范围、验收取舍、安全性能底线、Spec 变更确认。其余实现、枚举、验证、修复可交由 AI。判断标准：如果一个决策会影响“什么算做对了”，它必须由人决定；如果只影响“怎么做”，可以交给 AI。
五种常见失败模式：
specs/ 目录里有超过半年没更新也没有归档的文件。在第二章中，我们已经厘清了 Subagents、Agent Teams、Workflows 三种智能体编排形态的核心定义与基础差异，但知晓概念不等于具备落地能力，绝大多数开发者都卡在同一个瓶颈：能分清三种形态是什么，却不知道在真实项目里该不该拆分、怎么拆分、该用哪一种。本章将补齐这一关键实践闭环，通过三组真实对照实验，直观验证多智能体形态的适用边界、落地前提与典型踩坑点，并沉淀出一套可直接复用的智能体拆分判断框架；同时我们必须明确：多 Agent 不是开发标配，只是工程工具箱里的一种工具，有明确的适用范围与固有弊端，拆分从来不是目的，合适才是，盲目堆叠多智能体只会造成协调成本飙升、上下文割裂、逻辑冲突等问题，最终效果反而不如单 Agent，因此本章的核心目标不是教你一味拆分，而是帮你建立落地判断力：精准区分什么时候该拆、什么时候坚决不拆，让你在任意项目中都能合理选择单智能体或多智能体协作方案。
在开始之前，先明确一个核心立场：多 Agent 不是必须的，它只是工具箱里的一件工具，有明确的适用边界，也有实实在在的弊端。 拆分不是目的，合适才是目的。盲目堆叠多 Agent 会带来协调成本飙升、文件冲突、上下文割裂等问题，反而比单 Agent 更糟。这一章的目标不是教你“怎么拆”，而是教你“什么时候该拆，什么时候不该拆”。
我们先澄清一个最容易混淆的点：你平时在对话框里说需求、改 Bug，用的是 Craft 主 Agent 模式，不属于 Subagents、Agent Teams、Workflows 中的任何一种。这四种模式的核心区别在于 谁持有计划，以及你在哪里启动它。下面把每种模式的创建/启动方式说清楚。
创建方式有两种：
方式一：在 IDE 设置页创建（推荐） 。打开设置页的 Agent Tab，点击 Create Agent 按钮。选中的是 User Agent Tab 则创建 user 级别的 Subagent（全局生效），反之则是 project 级别（仅当前项目生效）。
方式二：在 CLI 中创建。 运行 /agents 命令打开子代理管理界面，选择“创建新代理”，然后选择项目级或用户级，用自然语言描述这个子代理的用途和适用场景，AI 会帮你生成配置，你可以在编辑器中微调系统提示词和工具权限。
创建完成后，Subagent 存储为带有 YAML 前置内容的 Markdown 文件。项目级位于 .codebuddy/agents/，用户级位于 ~/.codebuddy/agents/。
调用方式：
你也可以在对话中显式指定，比如：“用 code-reviewer 子代理检查我最近的更改”。
适用场景：聚焦型独立任务——代码审查、代码库探索、日志总结、单模块生成。判定标准是“只要结果，不需要讨论”。
启动方式：不需要预先配置，也不需要写脚本。你直接在对话里用自然语言告诉 CodeBuddy 你想要什么样的团队，它会根据你的描述自动创建团队、生成成员、分配任务。
比如你说：“创建一个团队从不同角度探索这个问题：一个负责用户体验，一个负责技术架构，一个扮演挑刺者。”Agent就会创建团队和共享任务列表，为每个角色生成独立的成员，并协调各成员的工作。
调用方式：团队创建完成后，终端会显示所有成员及其状态。你可以用 @成员名 直接和任意成员对话，不需要经过领导中转。输入 @all 可以向所有成员广播消息。
适用场景：需要协商和讨论的复杂任务——全栈功能开发（前后端需要对齐契约）、跨层协调、竞争性假设调试。判定标准是“任务需要协商和讨论，且可以拆成互不重叠的文件范围”。
Workflows不需要我们自己写脚本。 脚本由Agent根据你的任务描述现场生成。你要做的是两件事：第一，把任务描述清楚——比如“扫描 src/ 下所有组件的类型安全问题，对发现问题的文件派两个独立代理交叉验证，最后输出报告”；第二，脚本生成后阅读它的编排逻辑，确认没问题再运行。如果某个编排流程你会反复使用，可以保存为命名命令，之后直接调用。 它的启动方式有三种:
ultracode 关键词。 当输入中出现 ultracode 时，CodeBuddy 会为这个任务写一份 JavaScript 编排脚本。/effort ultracode 命令把 effort 等级设到最高，之后会话里每一个有分量的任务，CodeBuddy 都会先规划成 Workflow 再执行。运行方式：Workflow 在后台运行，你的会话保持响应。脚本保存在 session 目录下，你可以打开阅读它的编排逻辑。如果某个编排流程你会反复使用，可以用 /save-workflow 保存为项目级或用户级命令，之后直接调用。
适用场景：代码库级审计、大规模迁移、需要交叉验证的研究任务。判定标准是“任务规模大、需要对抗验证、且流程可复用”。
| 模式 | 怎么启动 | 谁持有计划 | 适用场景 |
|---|---|---|---|
| Craft 主 Agent | 直接在对话框说话 | Craft 自己 | 日常开发、原子性改动 |
| Subagents | 先 /agents 创建，再自动或手动调用 | Craft 主 Agent | 聚焦型独立任务 |
| Agent Teams | 用自然语言描述团队 | 团队领导 + 成员协商 | 多域可独立并行 |
| Workflows | 加 ultracode 或直接请求 | 脚本代码 | 大规模、可复用流程 |
为什么要先区分这个：日常改 Bug、写功能，Craft 主 Agent 已经够用。多 Agent 协作解决的不是“日常效率”问题，而是“单 Agent 装不下”的问题——上下文太长、需要独立验证、需要并行推进。后面三个实验验证的，就是这些场景。
实验设计：为验证 AI 自主开发的质量盲区，我设计了一组严格对照实验：使用同一个会话的 CodeBuddy 承担代码生成角色，完整开发指定功能；再开启一个完全独立、无任何上下文继承的干净会话，让 AI 手持标准化 Spec 验收标准，对成品代码进行逐条校验、全维度审查。
为什么必须新开独立会话: 上下文共享是 AI 自查失效的核心根源。如果生成者与验证者在同一会话，验证 AI 会天然继承生成过程的前置认知，默认认可现有代码逻辑，产生自我正向偏差，最终变成“自圆其说式自查”，无法客观找错。全新会话无固有认知、无思维惯性，只会严格对标 Spec 标准，机械、客观、严苛地校验所有逻辑，最大化规避主观包庇问题。
实验结果: 生成会话仅完整实现了登录功能的核心主流程，顺利完成基础登录、页面跳转等显性能力，但完全遗漏了所有边界约束逻辑，包括“连续5次密码错误锁定账号15分钟”“异常提示统一化”等关键规则。而独立验证会话，精准抓取到所有遗漏边界、缺失规则与隐性漏洞，实现了质量兜底。
核心收获: 任何自评自查都存在天然偏差，双角色对抗验证是 AI 开发最低成本的质量保障方案。这也是 Subagents 最朴素、最高频的落地形态：无需一开始搭建复杂的多智能体架构，先跑通「单 Agent 生成 + 独立 Subagent 验证」的最小双角色闭环，就能解决 80% 的 AI 开发质量盲区，彻底告别“主流程能跑就是完成”的粗放开发思维。
工程化演进方向: 本实验对应手动独立验证的最小工程形态。后续可持续迭代为自动化质量门禁：将人工发起的独立校验，固化为自动化工作流程，代码迭代完成后自动触发 Spec 对标校验、边界巡检、漏洞筛查，实现无需人工介入的常态化质量兜底。
实验设计：为验证 Agent Teams 的并行协作能力，我尝试用该形态落地用户设置页全功能开发：拆分前后端双角色团队，前端 Agent 负责页面渲染、参数组装与接口请求，后端 Agent 负责接口逻辑、数据校验、数据库读写，开发前提前约定基础接口契约，开启双向并行开发。
核心踩坑：模糊契约等于无契约。本次实验仅约定了接口基础返回结构 { success, data }，没有细化 data 内部的字段结构、数据类型、参数含义与边界规则。在无统一细化契约的前提下，前后端智能体自主推演逻辑、各自实现适配，最终出现致命偏差：前端默认 data.avatar 为纯字符串链接，后端实际返回 { url, thumb } 对象结构，字段层级、数据类型完全不匹配，直接导致联调彻底报错、并行开发成果无法复用。
核心教训：跨角色、跨端的并行协作，粗粒度的契约毫无价值。接口契约必须细化到字段级别、类型级别、边界级别，杜绝模糊结构。最优工程方案是直接使用 TypeScript 类型定义作为唯一统一契约，让前后端实现强对齐。
踩坑之后我重新做了一遍，这次跑通了。关键操作有三步：
{ success, data }，而是用 TypeScript 类型定义作为唯一契约：interface UserProfileResponse { success: boolean, data: { nickname: string,avatar: { url: string} } }。前端和后端都拿这份类型定义作为实现依据，任何一方改契约，另一方必须同步 src/views/Settings/，后端成员只改 server/routes/settings.js。两边文件不重叠，不存在互相覆盖的风险。avatar 是不是 { url, thumb } 结构，后端检查前端是否正确解析了这个结构。这次跑通的核心不是“Agent Teams 变强了”，而是契约从模糊变精确、文件从重叠变隔离。同样的工具，同样的任务，改了两个前提条件，结果完全不同。
Agent Teams 适用边界（实验验证结论）：只有同时满足以下三个条件，Agent Teams 才能发挥并行协作的效率优势，否则协调成本会完全吞噬并行收益：1. 任务可按文件、模块、职责清晰拆分，无重叠业务范围；2. 多角色可通过标准化契约实现强对齐；3. 各 Agent 负责的工作范围相互独立、无强耦合依赖。
工程化演进方向：本实验对应契约驱动协作的最小工程形态。后续可迭代为质量门禁的核心环节：实现接口契约自动化巡检，但凡接口结构、字段类型、返回规则发生变更，自动触发前后端契约一致性校验，提前拦截适配问题，避免联调报错。
实验设计：为探明智能体拆分的反向边界，我尝试做反向实践：将「登录表单验证 Bug 修复」这一简单迭代任务，强行拆分为前端、后端两个独立子任务，交由不同智能体分别开发。
核心踩坑：原子性任务拆分即冗余。落地后发现，表单校验属于强耦合原子逻辑：前端输入校验规则、后端参数校验规则、错误提示文案、边界拦截逻辑必须完全统一、同步变更。强行拆分后，两个智能体各自独立修改，出现前后端校验规则错位、拦截逻辑冲突、提示文案不统一等一系列问题，原本几分钟能完成的修复，反而产生了大量协调、对齐、改造成本。
最终最优方案：放弃多智能体拆分，回退为单会话单 Agent 闭环开发，在统一上下文内一次性完成前后端的同步修改、规则对齐与逻辑校验，高效解决问题。
核心收获：任务拆分的依据，从来不是技术域，而是逻辑依赖关系。强耦合、原子性、需要多方同步变更的任务，强行拆分只会徒增成本、制造问题，无法提升效率。这类任务必须由单一 Agent 在统一上下文内闭环完成，保证逻辑一致性。
工程化演进方向：本实验对应任务拆分边界判断的最小工程形态。后续可迭代为自动化依赖分析能力：由工具自动识别任务耦合度、依赖关系，智能判定当前任务适合单 Agent 闭环，还是多 Agent 并行，从根源杜绝无效拆分。
基于三组对照实验的正反案例，我沉淀出一套三层可落地智能体拆分判断框架，无需主观经验，可直接对标场景落地。
核心判断标准：改动存在强绑定依赖，必须多方同步变更、同时生效。即便任务横跨前端、后端、测试等多个技术域，也不允许拆分，必须由单 Agent 在统一上下文内一次性闭环。典型场景：
如果你已经拆了，发现协调成本大于收益，果断回退。 实验三就是这种情况拆完之后发现前后端校验规则对不上，反复沟通的成本远高于一个人改。这时候不要硬撑着拆，回退到单 Agent 闭环，在统一上下文里一次性改完。拆分的目的是提高效率，如果拆了之后效率更低，拆分本身就错了。
聚焦型独立任务 → 选用 Subagents任务目标单一、无需多方协商、只需最终结果，无复杂协作流程。适用于代码审查、代码库检索、日志分析、单模块独立生成、批量格式化等纯执行类场景。多域解耦可并行任务 → 选用 Agent Teams任务可按模块、文件、职责完全拆分，边界清晰无重叠，可通过统一契约对齐协作，需要轻度协商沟通。适用于前后端并行开发、多模块同步迭代、业务与测试并行落地等场景。大规模、可复用、需对抗验证任务 → 选用 Workflows任务体量庞大、流程固定可复用、需要多角色交叉校验、多层对抗兜底。适用于全项目接口契约巡检、代码批量迁移、全量规范整改、大规模测试覆盖等工程级任务。
核心切割准则（微软官方智能体设计原则）：在功能接口处切割任务边界。单个智能体的输出必须是完整、独立、可直接复用的成果物，其他智能体无需关注其内部实现，仅对接输出成果即可完成协作。边际效益最优法则：行业实测数据印证，1-3个智能体协作时，项目质量提升24%，资源消耗仅增加31%，性价比达到峰值；当智能体数量超过3个后，质量提升微乎其微，但协调成本、资源损耗会大幅飙升。因此，绝大多数业务项目的智能体数量，3-5个为最优落地上限，严禁为了堆砌工程化效果盲目扩容多智能体团队。
| 场景特征 | 判断标准 | 推荐形态 |
|---|---|---|
| 逻辑强耦合、原子改动 | 改动存在强依赖，必须同步处理、统一生效 | 单主 Agent 闭环 |
| 聚焦型独立任务 | 只需最终结果，无需多方协商协作 | 单 Subagent |
| 多域可并行任务 | 边界无重叠，可通过契约对齐，支持并行开发 | Agent Teams |
| 大规模、可复用、需对抗验证 | 体量庞大、流程固定、需要多角色交叉兜底 | Workflows |
通过第三章、第四章的内容，你已经掌握了 AI 工程化开发的最小可用闭环：以 Spec 规范驱动单 Agent 高质量开发，基于任务依赖按需启用多智能体协作，实现可验收、可追溯、低返工的开发模式。这套体系可以直接落地所有常规业务项目。在此基础上，工程化体系还有三大进阶方向，支撑大型、复杂、长期迭代项目：
以上进阶内容，我已整合为《AI 开发的工程化全景：从 Harness 到质量门禁》专项内容，可供深度研习。落地核心建议：先跑通最小闭环，再追求完整体系。不要一上来堆砌全量工程化配置，避免陷入“配置繁琐、落地为空”的误区，优先掌握基础规范与协作逻辑，再逐步迭代进阶能力。
本章完成了 AI 多智能体开发的核心跃迁：从「认知概念」升级为「场景判断」。多智能体协作的核心价值，从来不是“架构拆分得更漂亮”，而是让每一个智能体的产出可独立验证、可结构化对齐、可纳入标准化工程链路。我们通过三组实验明确了核心落地逻辑：强耦合原子任务坚决不拆分、独立聚焦任务用 Subagent、解耦并行任务用 Agent Teams、大规模流程化任务用 Workflows。同时用行业数据印证了智能体数量的最优边界，杜绝盲目堆叠的工程化伪优化，多 Agent 不是目的，合适才是目的。 工具箱里有四种模式，不代表每个任务都要用满四种。大多数日常开发用 Craft 主 Agent 就够了，只有当任务确实超出单 Agent 的能力边界时，才考虑引入多 Agent 协作。
如果你已经用指令式开发做了项目并且上线了，现在想转工程化，路径和新项目不同。新项目可以从零开始按 Spec 驱动做，存量项目需要先诊断现状、补齐基线、选一个功能试点、再逐步推广。核心路径是四步：
完整的方法——包括诊断清单、基线 Spec 示例、对等验证操作、双轨并行的扩链条件、度量体系、七种常见失败模式——我单独写了一篇《存量项目的 AI 工程化迁移：从诊断到推广的完整路径》，想深入了解的可以点过去看。
回顾整篇文章，我们完成了一次从“指令式开发”到“规范驱动工程化”的完整跃迁。
AI 开发的上限由模型决定，但项目的下限由工程思维决定。 工具解决“写得快”，规范、Spec、契约、验证体系解决“写得稳、改得动、活得久”。如果你正在用 AI 开发，不妨从下一个功能开始，坚持先写 Spec，再做开发。你会发现：AI 开发真正的省时，从来不是代码生成的速度，而是少踩坑、少返工、少堆积技术债务的长期安稳。