今年依托 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、 工具（纯手脚，只会动、不会想）
工具是包裹在模型外层的能力，让模型可以读取文件、编写代码、执行命令。Cursor、CodeBuddy 插件、GitHub Copilot 都属于这类。但工具不具备自主规划能力：你需要明确告诉它要做什么，它才会执行。它默认前提是：需求已经由人思考完整。
3、 智能体 Agent（会思考、会动手、会闭环干活）
智能体是工具进一步演化而来：拿到一句模糊需求，它可以自主拆解任务、规划步骤、调用工具、校验结果，发现问题后迭代调整。你只需要说“帮我实现登录功能”，它会自行判断优先读取哪些文件、先写前端还是后端、完成后如何验证。
打个比方：模型是大脑，工具是身体，智能体是可以独立干活的人。但这个比喻还缺一块：一个能干活的人，还需要工具箱、操作手册、记忆和一套操作系统。这整套东西，就是 Harness。
4、 Harness（让智能体能稳定干活的整套操作系统）
Harness 是模型之外的全部基础设施。微软 Agent Framework 的官方定义：Agent Harness 是运行时脚手架，负责把语言模型转化成可以执行工作的 Agent。用计算机架构类比更容易理解：
完整公式：Agent = Model + Harness。后文提到的 Rules、Skills、Memory、MCP、Hooks，全部属于 Harness 的组成组件。
补充：市面上不同产品本质是不同形态的 Agent。
智能体存在一个核心矛盾：它需要掌握大量项目知识，但上下文窗口容量有限。如果把所有规范、流程、项目背景全部塞进系统提示词，会稀释模型注意力，降低执行效果。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（零工市场）
接地气的比喻：你家装修，需要一个人帮你盯着某个环节。你去零工市场叫了一个电工，告诉他“把厨房的插座都换成带开关的”，他干完活给你一个总结“换好了，一共 6 个，线路没问题”，然后就走。你不知道他在过程中试了几种接线方式，也不关心——你只拿到结果。
真实特点：Subagents 是主 Agent 派出去的专家工人。每个 Subagent 有独立的上下文窗口和受限的工具权限，干完活把结果交回给主 Agent，中间探索过程不污染主对话。
关键机制在于：Subagents 由主 Agent（在 CodeBuddy 里是 Craft Agent）自动判断调用时机。当主 Agent 发现某个子任务会产生大量中间产物（搜索结果、日志、文件内容），而这些产物你后面不会引用，它就会派一个 Subagent 去处理。Subagent 在执行期间不能被中途干预，要么等它完成，要么手动中断整个对话。
Subagents 分两个级别：project 级只在当前工作区生效，user 级适用于所有项目，配置一次即可跨项目复用。
典型使用场景：代码审查、代码库探索、日志总结、单模块生成。判定标准是“只要结果，不需要讨论”。
接地气的比喻：你有一个装修项目，需要同时推进水电、木工、油漆三个环节。你组了一个项目组：一个工头（Lead）负责分配任务和协调，三个工人各自负责一个环节，工人之间可以直接喊话——“我这边电线走完了，你可以开始封墙了”。工头不用传话，工人自己对进度。
真实特点：Agent Teams 是多个独立 CodeBuddy 实例的协作团队。一个会话作为团队领导（team-lead），负责协调工作、分配任务和汇总成果；其余成员各自独立工作，拥有自己的上下文窗口，并通过消息系统直接相互沟通。
和 Subagents 最本质的区别是通信拓扑：Subagents 只能向主 Agent 汇报结果，而 Agent Teams 的成员之间可以直接发消息，你甚至可以绕过领导直接 @ 某个成员对话。团队成员共享一个任务列表，任务有三个状态（待处理、进行中、已完成），支持依赖关系——某个任务依赖的前置任务没完成，它就不能被认领。
Token 消耗显著高于单会话，因为每个成员都是独立的完整实例。成员之间不隔离文件修改，必须手动划分文件所有权，否则会互相覆盖。
典型使用场景：研究与评审（多个成员同时调研问题的不同方面，然后分享和质疑彼此的发现）、新模块开发（每个成员负责独立模块）、竞争性假设调试（并行测试不同假设）、跨层协调（前端、后端、测试各由不同成员负责）。判定标准是“任务需要协商和讨论，且可以拆成互不重叠的文件范围”。
接地气的比喻：你要批量处理 500 个文件。你不会一个个叫零工，而是写一份施工计划：第一步派 10 个工人同时扫描前 50 个文件，第二步把结果汇总，第三步对发现问题的文件派 3 个工人交叉验证，第四步生成报告。计划写好后，你不在现场盯着，流水线自己跑。每个工人干完活，结果自动传给下一个环节。
真实特点：Workflows 是一段 JavaScript 编排脚本，由 CodeBuddy 为你的任务现场编写，运行时在后台执行，你的会话保持响应。脚本里包含 agent()、parallel() 等调用，每次 agent() 都派出一个独立子代理工作；脚本拿到中间结果后，可以分支、可以并行、可以再投递给下一批子代理。
和 Subagents、Agent Teams 最本质的区别是“谁持有编排计划”。Subagents 和 Agent Teams 的下一步动作都由 CodeBuddy 逐轮决策，所有中间结果都落进上下文窗口；而 Workflow 把循环、分支、中间结果都交给脚本本身管理，CodeBuddy 的上下文里只剩最终答案。
这意味着编排逻辑可读、可改、可重跑。Workflow 脚本保存在 session 目录下，你可以打开阅读它的逻辑。如果某个编排流程你会反复使用（比如每次分支都跑的审查流程），可以用 /save-workflow 保存为项目级或用户级命令，之后用 /名字 直接调用。
Workflows 支持对抗性验证：可以让独立代理在报告之前对彼此的发现进行审查，或从多个角度起草方案再相互权衡，单次结果的可信度比“一遍过”高得多。
典型使用场景：全 monorepo 的接口契约巡检、一组 issue 的批量分诊、跨多个仓库的交叉印证调研、大型迁移。判定标准是“任务规模大、需要对抗验证、且流程可复用”。
Subagents 是“叫个零工来干活，干完汇报”——主 Agent 逐轮决策，结果汇总回主上下文。
Agent Teams 是“组个项目组，工人之间能互相喊话”——领导协调，成员自行协商，共享任务列表。
Workflows 是“写份施工计划，流水线自己跑”——脚本持有编排逻辑，中间结果存在脚本变量里，不占用主对话上下文。
这三种形态不是 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 开发流程非常主流：有产品想法后，让大模型发散梳理，产出一份项目计划书，然后直接把整篇文档丢给 AI 写代码。这套流程能跑通demo、能做出主流程，但绝对撑不起工程级、可维护、低返工的项目。它存在一个结构性缺陷：计划书只回答“要做什么”，从来不回答“怎么算做完、怎么算做对”。以最常见的「登录功能」为例，常规计划书一般这样写：实现登录功能，支持用户名密码登录，登录成功后跳转到首页。需要处理错误情况，保证安全性。这段话看起来完整、通顺、没有问题，但在工程落地层面，藏着三个致命模糊点，也是 90% AI 隐性 Bug 的来源。第一，“处理错误情况”没有枚举边界。用户名不存在算不算错误？密码错误算不算？空提交、非法格式、网络超时、接口 500 需不需要处理？每种错误分别给用户展示什么文案？计划书全部留白。AI 只能靠模型默认逻辑自行实现，猜对是运气，猜错必返工。第二，“保证安全性”没有量化标准。密码是否加密传输？是否防暴力破解？错误几次锁定、锁定多久？Token 存在哪里、过期多久、怎么刷新？模糊的安全描述，只会让 AI 按照“最宽松、最省事”的默认方案实现，最终埋下大量安全隐患。第三，流程细节缺失，导致后续架构不统一。登录成功后的凭证如何存储？localStorage、sessionStorage 还是 cookie？是否自动携带请求头？这些看似微小的细节，直接决定后续权限体系、接口请求、会话维持的整体逻辑。总结一句话：计划书最大的问题，不是写得简略，而是没有提供可验收的依据。开发者最终只能凭感觉验收：主流程能跑通、页面能打开，就算做完。所有边界场景、异常处理、安全约束、极端用例，全部处于失控状态。而 Spec 要解决的就是这个核心问题：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 允许迭代完善，但禁止带着未知项进入开发。一旦存在待定，AI 会自行猜测补全规则，结果大概率偏离预期。
不要自己苦思冥想写全 Spec，正确方式是「人机协同澄清需求」。第一步：禁止先写代码，先让 AI 反向提问。新开对话直接输入：我要实现 [功能描述]。先不要写代码。针对这个需求，列出你还需要我确认的边界条件和验收标准，每个问题给出你的建议选项。这一步会挖出大量你完全想不到的隐性规则。第二步：逐条确认，不模糊、不敷衍、不“你看着办”。你一旦说“你看着办”，AI 一定会选择最省事、最不严谨、最不安全的实现方式。不确定的内容标记待定，开发前统一清零。第三步：整理成文件，纳入版本控制。在项目根目录建立 specs/ 文件夹，每个功能一个 md 文件。Spec 和代码同等重要，需求变更必须先改 Spec，再改代码。
只写 Spec 没用，默认情况下 AI 不会主动读取和遵守。必须通过 Rules 将 Spec 变成强制约束。在 .codebuddy/rules/ 新建 spec-driven.md：
|
1 2 3 4 5 6 7 8 9 |
--- alwaysApply: true --- ## Spec 驱动开发规则 1. 所有代码生成必须引用 `specs/` 目录下对应的 Spec 文件。 2. 实现必须覆盖 Spec 中所有验收标准，不得遗漏。 3. 如果 Spec 中没有定义某个行为，不要自行发挥，先询问确认。 4. 如果实现过程中发现 Spec 有矛盾或遗漏，先更新 Spec，再改代码。 5. 功能完成后，逐条对照验收标准输出检查结果。 |
配置完成后，新开对话测试：让 AI 实现对应功能，先读 Spec、再写代码即代表规则生效。
本节用真实项目的「用户设置页」，完整走一遍从需求澄清、Spec 定稿、任务拆分、开发验证到上线归档的全流程。
初稿写完后，先让 AI 校验可行性，排查出两处冲突：1. Spec 写“头像上传后立即更新”，但后端接口为异步刷新，无法即时获取；2. Spec 写“改密码后强制重新登录”，现有架构不支持强制下线。优先修正 Spec，适配技术现实，保证规格可落地。
根据 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 |
先后端、后前端；先无依赖、后有依赖。每完成一个模块立刻对照 Spec 验收，不堆积问题。
开发完成后新开干净会话，让 AI 打开页面逐条验收。本次验证发现：原 Spec 要求“昵称清空后提示不能为空”，但实际交互是直接禁用提交按钮，用户无法触发提交，规则不匹配。
问题根源是 Spec 不合理，而非代码错误。优先修改验收标准为「昵称清空后提交按钮禁用，输入框出现视觉警示」，再让代码对齐新规则。
全部验收通过后，Spec 提交 Git，作为后续迭代、修复、重构的唯一依据。以下是最终定稿的核心验收内容：
|
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 |
## 验收标准 - [ ] 头像区域显示当前头像，未设置时显示默认头像 - [ ] 点击头像可选择本地图片，支持 jpg/png/webp 格式 - [ ] 选择超过 2MB 的图片时，显示“图片不能超过 2MB”，不上传 - [ ] 上传成功后，刷新获取新头像 URL 并实时更新 - [ ] 上传失败时，展示具体失败原因 - [ ] 昵称输入框回显当前昵称，最大 20 字符 - [ ] 昵称清空后，提交按钮禁用，输入框出现视觉警示 - [ ] 昵称修改成功后，显示“保存成功”提示，3 秒消失 - [ ] 密码修改需输入旧密码、新密码、确认新密码 - [ ] 新密码不足 8 位提示“密码至少 8 位” - [ ] 两次密码不一致给出对应提示 - [ ] 旧密码错误给出对应提示 - [ ] 改密成功刷新 token，不强制登出 - [ ] 所有请求期间按钮 loading 禁用 ## 边界条件 - [ ] 未登录访问自动跳转登录页 - [ ] 网络异常提交给出错误提示 - [ ] 连续点击只触发一次请求 - [ ] 上传中途取消无状态残留 ## 不做什么 - 不支持第三方绑定 - 不支持邮箱修改 - 不支持多因素认证 |
高质量验证必须具备三样东西：Spec、源码、可运行环境。只有文档和代码，只能静态看逻辑；有运行环境，才能验证真实用户行为。所有验证问题分为三类固定处理：1. Spec 错误：规则本身不合理 → 先改文档，再改代码。2. 实现错误：代码不符合 Spec → 直接修复代码。3. Spec 遗漏：场景有效但文档未定义 → 先补 Spec，再补代码。每次验证输出结构化报告，区分通过、未通过、遗漏项，问题类型清晰可复盘。同时按风险分级：高风险功能全量验证，中风险关键路径验证，低风险静态检查即可。
很多人写 Spec 要么太泛、要么太死，核心边界只有一句话：Spec 管结果和标准，不管实现和过程。Spec 只定义“做什么、怎么算对”，不定义“具体怎么写、用什么方案”。写太细会锁死 AI 优化空间，让架构和代码强耦合。同时要分清四大工程工件的层级关系：
| 工件 | 内容定位 | 生命周期 |
|---|---|---|
| Spec | 本次功能的需求、边界、验收标准 | 单次功能周期 |
| Rules | 项目永久编码红线、规范 | 长期全局生效 |
| Skills | 可复用流程、审查步骤、标准动作 | 按需加载复用 |
| Memory | 历史经验、踩坑记录、项目偏好 | 动态积累 |
通用约束放 Rules、单次需求放 Spec、流程步骤放 Skills、经验教训放 Memory，互不重叠、各司其职。
目录规范：统一放在 specs/，模块多时分子目录，命名统一、长期归档。需求变更必须文档代码同步提交。效果度量：关注四个指标——返工率、验收覆盖率、Spec 修改频率、问题类型分布。不需要精准统计，趋势向好即可。与其他方法论互补：Spec 和 TDD、BDD、ADR 不冲突。验收标准可转测试用例、句式对齐 BDD、架构决策用 ADR 沉淀，整套体系可以共存且互相增强。
依赖管理：Spec 头部标注依赖关系，按拓扑顺序开发，杜绝循环依赖。评审机制：个人隔日自审、团队交叉评审，重点检查是否可测试、边界是否完整、需求是否自洽。工具通用：纯 Markdown 不绑定工具，主流 AI 开发工具均可通过规则引用生效。渐进落地：先试点、再固化、再全量推广，存量功能迭代时补写 Spec，避免一次性文档爆炸。
必须由人决策的内容：功能范围、验收取舍、安全性能底线、Spec 变更确认。其余实现、枚举、验证、修复可交由 AI。常见失败模式：Spec 形式化、标准不可测、文档代码漂移、过度僵化、文档堆积失维。个人渐进路径：第一周先提问、第二周写文档、第三周配规则、第四周做验证，循序渐进完成转型。
specs/ 目录从「扔想法」到「写规格」，是 AI 开发最关键的一次思维跃迁。传统计划书只能定义「要做什么」，导致 AI 靠猜测开发、人靠体感验收。而 Spec 驱动的核心价值，不是让代码写得更快，而是让每一次开发都可验证、可追溯、可维护、可迭代。把质量标准从事后补救，提前为事前定义；把主观感觉的验收，升级为客观标准的清单。这就是规范驱动 AI 工程体系的核心基石。
在第二章中，我们已经厘清了 Subagents、Agent Teams、Workflows 三种智能体编排形态的核心定义与基础差异。但“知道概念”不等于“会落地”。绝大多数开发者卡在同一个瓶颈：能分清三种形态是什么，却不知道真实项目中该用哪一种、该不该拆分、怎么拆分。本章将补齐这一关键闭环：通过三组真实对照实验，直观验证三种多智能体形态的适用边界、踩坑痛点、落地前提，并基于实验结论沉淀一套可直接复用的「智能体拆分判断框架」。读完本章，你将彻底摆脱盲目堆叠多 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 类型定义作为唯一统一契约，让前后端实现强对齐。
只有同时满足以下三个条件，Agent Teams 才能发挥并行协作的效率优势，否则协调成本会完全吞噬并行收益：1. 任务可按文件、模块、职责清晰拆分，无重叠业务范围；2. 多角色可通过标准化契约实现强对齐；3. 各 Agent 负责的工作范围相互独立、无强耦合依赖。
本实验对应契约驱动协作的最小工程形态。后续可迭代为质量门禁的核心环节：实现接口契约自动化巡检，但凡接口结构、字段类型、返回规则发生变更，自动触发前后端契约一致性校验，提前拦截适配问题，避免联调报错。
为探明智能体拆分的反向边界，我尝试做反向实践：将「登录表单验证 Bug 修复」这一简单迭代任务，强行拆分为前端、后端两个独立子任务，交由不同智能体分别开发。
落地后发现，表单校验属于强耦合原子逻辑：前端输入校验规则、后端参数校验规则、错误提示文案、边界拦截逻辑必须完全统一、同步变更。强行拆分后，两个智能体各自独立修改，出现前后端校验规则错位、拦截逻辑冲突、提示文案不统一等一系列问题，原本几分钟能完成的修复，反而产生了大量协调、对齐、改造成本。
放弃多智能体拆分，回退为单会话单 Agent 闭环开发，在统一上下文内一次性完成前后端的同步修改、规则对齐与逻辑校验，高效解决问题。
任务拆分的依据，从来不是技术域，而是逻辑依赖关系。强耦合、原子性、需要多方同步变更的任务，强行拆分只会徒增成本、制造问题，无法提升效率。这类任务必须由单一 Agent 在统一上下文内闭环完成，保证逻辑一致性。
本实验对应任务拆分边界判断的最小工程形态。后续可迭代为自动化依赖分析能力：由工具自动识别任务耦合度、依赖关系，智能判定当前任务适合单 Agent 闭环，还是多 Agent 并行，从根源杜绝无效拆分。
基于三组对照实验的正反案例，我沉淀出一套三层可落地智能体拆分判断框架，无需主观经验，可直接对标场景落地。
核心判断标准：改动存在强绑定依赖，必须多方同步变更、同时生效。即便任务横跨前端、后端、测试等多个技术域，也不允许拆分，必须由单 Agent 在统一上下文内一次性闭环。典型场景：1. Bug 修复需要同时调整前端调用逻辑与后端返回结构；2. 表单校验、参数拦截、错误提示等前后端必须统一的规则迭代；3. 接口参数、数据结构变更，需要全链路同步适配的改动。
聚焦型独立任务 → 选用 Subagents任务目标单一、无需多方协商、只需最终结果，无复杂协作流程。适用于代码审查、代码库检索、日志分析、单模块独立生成、批量格式化等纯执行类场景。多域解耦可并行任务 → 选用 Agent Teams任务可按模块、文件、职责完全拆分，边界清晰无重叠，可通过统一契约对齐协作，需要轻度协商沟通。适用于前后端并行开发、多模块同步迭代、业务与测试并行落地等场景。大规模、可复用、需对抗验证任务 → 选用 Workflows任务体量庞大、流程固定可复用、需要多角色交叉校验、多层对抗兜底。适用于全项目接口契约巡检、代码批量迁移、全量规范整改、大规模测试覆盖等工程级任务。
核心切割准则（微软官方智能体设计原则）：在功能接口处切割任务边界。单个智能体的输出必须是完整、独立、可直接复用的成果物，其他智能体无需关注其内部实现，仅对接输出成果即可完成协作。边际效益最优法则：行业实测数据印证，1-3个智能体协作时，项目质量提升24%，资源消耗仅增加31%，性价比达到峰值；当智能体数量超过3个后，质量提升微乎其微，但协调成本、资源损耗会大幅飙升。因此，绝大多数业务项目的智能体数量，3-5个为最优落地上限，严禁为了堆砌工程化效果盲目扩容多智能体团队。
| 场景特征 | 判断标准 | 推荐形态 |
|---|---|---|
| 逻辑强耦合、原子改动 | 改动存在强依赖，必须同步处理、统一生效 | 单主 Agent 闭环 |
| 聚焦型独立任务 | 只需最终结果，无需多方协商协作 | 单 Subagent |
| 多域可并行任务 | 边界无重叠，可通过契约对齐，支持并行开发 | Agent Teams |
| 大规模、可复用、需对抗验证 | 体量庞大、流程固定、需要多角色交叉兜底 | Workflows |
通过第三章、第四章的内容，你已经掌握了 AI 工程化开发的最小可用闭环：以 Spec 规范驱动单 Agent 高质量开发，基于任务依赖按需启用多智能体协作，实现可验收、可追溯、低返工的开发模式。这套体系可以直接落地所有常规业务项目。在此基础上，工程化体系还有三大进阶方向，支撑大型、复杂、长期迭代项目：第一，验证全自动化（质量门禁）本章的独立验证仍为人工发起模式，进阶工程化可将校验逻辑嵌入 Agent 工作循环：代码修改完成后，自动触发 Lint 校验、Spec 对标、单元测试、边界巡检，发现问题自动修复、自动重试，实现无人值守的常态化质量门禁。第二，对抗角色多元化基础闭环仅实现「生成者+验证者」双角色对抗，进阶可拆解为多角色专项对抗：专属 Agent 负责功能实现、专属 Agent 校验 Spec 契约一致性、专属 Agent 遍历边界异常、专属 Agent 完成测试用例覆盖。单角色单点深耕，质量兜底更彻底。第三，记忆体系知识库化第二章提到的 Memory 是 AI 自动积累的轻量化经验，进阶工程化可将其升级为可检索、可筛选、可精准注入的结构化知识库。解决三大核心问题：跨会话状态丢失、上下文内容膨胀、无效信息污染推理，让 AI 每次开发仅加载最相关的项目经验与规范。以上进阶内容，我已整合为《AI 开发的工程化全景：从 Harness 到质量门禁》专项内容，可供深度研习。落地核心建议：先跑通最小闭环，再追求完整体系。不要一上来堆砌全量工程化配置，避免陷入“配置繁琐、落地为空”的误区，优先掌握基础规范与协作逻辑，再逐步迭代进阶能力。
本章完成了 AI 多智能体开发的核心跃迁：从「认知概念」升级为「场景判断」。多智能体协作的核心价值，从来不是“架构拆分得更漂亮”，而是让每一个智能体的产出可独立验证、可结构化对齐、可纳入标准化工程链路。我们通过三组实验明确了核心落地逻辑：强耦合原子任务坚决不拆分、独立聚焦任务用 Subagent、解耦并行任务用 Agent Teams、大规模流程化任务用 Workflows。同时用行业数据印证了智能体数量的最优边界，杜绝盲目堆叠的工程化伪优化。
结合前三章的完整演进逻辑，我们可以真正系统化地定义 AI 开发工程化。整套体系始终贯穿三条核心升级主线：从“随意扔想法”升级为“标准化写规格”，从“单 Agent 盲目开发”升级为“多 Agent 按需协作”，从“主观体感验收”升级为“客观清单校验”。这三层转变，共同构成了 AI 工程化的完整内核，也区分了“用 AI 写代码”和“用 AI 做工程”的本质差距。在此基础上，AI 工程化拥有三大确定性标志：可重复、可验证、可维护。可重复，代表 Spec 模板、Rules 规范、验证流程、协作模式能够跨功能、跨项目复用，让稳定产出依靠体系，而非单次经验与运气。可验证，代表每一次开发产出、每一轮迭代变更，都有明确、客观、可逐条落地的验收依据，全程可核对、可追溯、可复盘，彻底告别“看着没问题”的主观体感验收。可维护，代表项目拥有唯一事实来源，需求迭代与架构调整永远是“先改 Spec、再改代码”，从根源解决代码与文档双向漂移、项目越做越乱的顽疾。在这套体系中，规范驱动是 AI 工程化的核心手段。传统人工开发的质量保障是后置的，靠人工查漏补缺、上线修 Bug、事后兜底；而工程化 AI 开发的质量是前置的，靠 Spec 提前定义标准、靠 Rules 锁定编码红线、靠多角色对抗验证层层兜底。这套思维不依赖特定工具，是开发者工程认知的根本性升级。而多智能体协作，是工程化复杂度提升后的自然延伸。多 Agent 从来不是用来炫技的架构噱头，而是复杂项目解耦与质量管控的必然选择。智能体拆分的核心不是技术分层，而是逻辑解耦；协作的核心不是简单任务分摊，而是契约对齐、边界清晰、独立可验证。也正因如此，我们不能盲目堆叠智能体，必须根据任务依赖判断拆分边界，让协作效率大于协调成本。深耕 AI 落地开发后，我彻底想通了 AI 开发的终极瓶颈：AI 开发的上限由大模型能力决定，但项目的稳定性、可维护性、可迭代下限，由人的工程思维决定。工具解决了“写得快”的问题，而规范、Spec、契约、验证、协作体系，解决了“写得稳、改得动、活得久”的问题。从指令式的粗放试错，走向规范驱动的工程化落地，是每一个 AI 开发者的必经成长之路。如果你正在用 AI 开发项目，不妨从下一个功能开始，坚持先写 Spec，再做开发。你会发现：AI 开发真正的省时，从来不是代码生成的速度，而是少踩坑、少返工、少堆积技术债务的长期安稳。
暂无相关文章!