AI Native 团队开发落地手册：CLAUDE.md、Plan Mode 与 Agent 沙盒实战

1. 从“人肉流水线”到“AI Native 团队”：为什么开发范式必须换血

如果你现在还在用“需求文档→评审→排期→编码→联调→测试→上线”这套经典瀑布或敏捷流程来带团队，大概率已经感受到一种撕裂感：AI 编码工具已经能在一分钟内生成几百行可运行代码，但你的团队还在花三天时间对齐接口字段命名规范。这不是工具的问题，是研发范式的问题。

AI Native 团队的核心定义，不是“用了 AI 工具的团队”，而是默认 AI 是团队一等公民的研发组织。在这个组织里，SDLC（软件开发生命周期）的每一个环节都被重新设计：需求不再只写给人看，而是写成 AI 可解析的结构化意图；代码不再只由人评审，而是由 Agent 先跑一轮静态检查与逻辑推演；测试不再只靠 QA 手动点点点，而是由 Agent 自动生成边界用例并执行回归。

这套手册要解决的问题很具体：如何让一个 5 到 20 人的研发团队，在不增加管理成本的前提下，把 AI 真正嵌入到日常开发流里，而不是停留在“偶尔用 Copilot 补全几行代码”的玩具阶段。适合谁来读？技术负责人、一线架构师、带小团队的 Tech Lead，以及那些已经受够了“AI 工具买了一堆但效率没提升”的工程管理者。

我见过太多团队在 AI Native 转型上踩的坑：有人把 CLAUDE.md 当成 README 写，结果 Agent 每次执行都跑偏；有人开了 Plan Mode 但没人看计划，Agent 直接改坏了生产配置；还有人把 Agent 当万能胶，什么任务都往里塞，最后并发一上来整个系统雪崩。这些问题不是工具缺陷，是范式设计缺陷。

接下来的内容，我会从整体设计思路、核心细节拆解、实操落地流程、常见问题排查四个维度，把 AI Native 团队完整开发落地手册拆开揉碎讲清楚。每个环节都会告诉你“为什么这么设计”以及“我踩过哪些坑”。

2. 内容整体设计与思路拆解：AI Native SDLC 的骨架怎么搭

2.1 为什么传统 SDLC 在 AI 时代会失效

传统 SDLC 的底层假设是：人是唯一的执行主体，工具是辅助。所以流程设计围绕“人如何协作”展开——站会同步进度、评审对齐认知、文档传递上下文。但 AI Native 团队里，Agent 也是执行主体，而且它的工作方式和人完全不同。

Agent 不需要站会，它需要的是结构化上下文；Agent 不需要评审，它需要的是可验证的约束条件；Agent 不需要文档，它需要的是可执行的指令集。如果你把 Agent 硬塞进为人设计的流程里，结果就是：人觉得 Agent 不听话，Agent 觉得人给的指令太模糊。

我试过最蠢的做法，是让 Agent 参加每日站会——把会议纪要喂给它，让它总结任务。结果它每次输出的都是“根据会议内容，建议进一步明确需求”，等于什么都没说。后来我才想明白：Agent 的输入必须是结构化的、可执行的、带约束的，而不是自然语言的模糊描述。

所以 AI Native SDLC 的设计原则只有一条：每个环节的产出物，必须同时对人可读、对 Agent 可执行。这就是为什么 CLAUDE.md 这类文件如此关键——它不是文档，是 Agent 的“操作手册”。

2.2 AI Native 团队的三个核心角色重新定义

在传统团队里，角色是产品经理、开发、测试、运维。在 AI Native 团队里，这些角色依然存在，但工作内容发生了根本性偏移：

• 产品经理：从写 PRD 变成写“意图规格”。PRD 是给人看的，意图规格是给 Agent 看的。意图规格必须包含：目标状态、约束条件、验收标准、边界情况。我通常要求产品经理用 YAML 格式写需求，因为 Agent 解析 YAML 的准确率远高于自然语言。
• 开发工程师：从写代码变成“设计 Agent 工作流 + 审核 Agent 产出”。工程师的核心能力不再是手写算法，而是把复杂任务拆解成 Agent 可执行的子任务，并设计验证机制。一个不会拆任务的工程师，在 AI Native 团队里会非常吃力。
• 测试工程师：从写测试用例变成“设计验证策略 + 维护 Agent 测试沙盒”。测试工程师需要确保 Agent 生成的代码在沙盒里跑通所有边界条件，而不是手动去点每一个按钮。

这个角色偏移带来的最大挑战是：很多人不愿意放弃“亲手写代码”的掌控感。我见过一个资深工程师，坚持自己写所有核心逻辑，只让 Agent 写单元测试。结果他的产出速度只有隔壁用 Agent 生成代码 + 人工审核的团队的三分之一。不是他技术差，是他没转过弯来。

2.3 方案选型：为什么是 CLAUDE.md + Plan Mode + Agent 沙盒

市面上 AI 研发工具很多，但我最终选择这套组合，原因很实际：

CLAUDE.md 解决的是“上下文持久化”问题。每次和 Agent 对话，它都是失忆的。CLAUDE.md 相当于给 Agent 一个“项目记忆文件”，里面写清楚：项目结构、编码规范、常用命令、禁止操作。没有这个文件，你每次都要重复解释“我们用的是 TypeScript 不是 JavaScript”“数据库迁移用 Prisma 不是 TypeORM”。有了它，Agent 第一次执行就能对齐项目规范。

Plan Mode 解决的是“执行前验证”问题。Agent 最危险的地方在于：它会自信地执行错误操作。Plan Mode 强制 Agent 先输出执行计划，人工确认后再执行。我踩过的坑是：有一次 Agent 直接执行了数据库删除操作，因为它在上下文里看到“清理测试数据”的指令，但没区分测试环境和生产环境。Plan Mode 就是那道保险。

Agent 沙盒解决的是“安全隔离”问题。Agent 执行代码时，必须在隔离环境里跑。我见过太多团队让 Agent 直接在本地开发机执行命令，结果 Agent 把rm -rf跑到了错误目录。沙盒可以是 Docker 容器、虚拟机、或者云端的隔离环境。关键是：Agent 的任何写操作，都不能直接影响生产环境。

这三个组件的关系是：CLAUDE.md 提供上下文，Plan Mode 提供验证，沙盒提供隔离。缺一个，系统就不完整。

2.4 影响范围分析：从 5 人小队到 50 人部门

这套手册的适用范围，我实测下来是这样的：

小团队的优势是决策快，可以直接让 Agent 参与核心开发。大团队的挑战是权限管理复杂，必须设计 Agent 的访问控制。我见过一个 30 人团队，让所有 Agent 共享同一个 API Key，结果一个 Agent 的异常调用把整个团队的配额耗尽了。规模越大，Agent 的权限隔离越重要。

3. 核心细节解析与实操要点：CLAUDE.md、Plan Mode、Agent 沙盒怎么用

3.1 CLAUDE.md 的写法：不是 README，是 Agent 操作手册

很多人把 CLAUDE.md 写成项目介绍，这是最大的误区。CLAUDE.md 的读者是 Agent，不是人。所以它的写法必须遵循“指令优先”原则。

我常用的 CLAUDE.md 结构是这样的：

# 项目上下文 - 技术栈：TypeScript + Node.js 20 + PostgreSQL 15 - 包管理器：pnpm（禁止使用 npm 或 yarn） - 测试框架：Vitest（禁止使用 Jest） # 编码规范 - 所有函数必须显式声明返回类型 - 禁止使用 any，必须用 unknown 或具体类型 - 错误处理统一使用 Result 类型，禁止 throw # 常用命令 - 安装依赖：pnpm install - 运行测试：pnpm test - 数据库迁移：pnpm prisma migrate dev # 禁止操作 - 禁止直接修改 .env 文件 - 禁止执行 rm -rf 命令 - 禁止在 main 分支直接提交

这个文件的关键在于：每一条都是可验证的约束，而不是模糊的描述。“代码要整洁”是模糊的，“禁止使用 any”是可验证的。Agent 需要的是后者。

我踩过的坑是：一开始把 CLAUDE.md 写得太长，塞了 2000 多字，结果 Agent 每次执行都要花大量 token 解析这个文件，反而拖慢了速度。后来我把它压缩到 500 字以内，只保留最关键的约束，效果反而更好。CLAUDE.md 不是越长越好，是越精准越好。

3.2 Plan Mode 的正确打开方式：先看计划，再放行

Plan Mode 的核心价值是：让 Agent 先想清楚再动手。但很多团队开了 Plan Mode 却没人看计划，等于白开。

我的做法是：Plan Mode 输出的计划必须包含三个要素——操作步骤、影响范围、回滚方案。如果 Agent 输出的计划里没有回滚方案，直接打回重做。

举个例子，当 Agent 需要修改数据库 schema 时，它的计划应该是这样的：

计划： 1. 在 schema.prisma 中新增 User.avatarUrl 字段（类型：String?） 2. 生成迁移文件：pnpm prisma migrate dev --name add_avatar_url 3. 影响范围：User 表新增可空字段，不影响现有查询 4. 回滚方案：执行 pnpm prisma migrate resolve --rolled-back add_avatar_url

这个计划里，第 4 步是关键。没有回滚方案的计划，就是耍流氓。我要求团队里所有 Agent 操作，只要涉及数据变更，必须有回滚方案。

另一个实操要点是：Plan Mode 的确认人必须是熟悉该模块的工程师，不能随便找个人点“同意”。我见过一个团队让实习生确认 Agent 的数据库迁移计划，结果实习生看不懂，直接点了同意，导致生产环境多了一个冗余字段。确认人必须对操作后果负责。

3.3 Agent 沙盒的搭建：Docker 隔离 + 资源限制

Agent 沙盒的搭建，我推荐用 Docker 容器，原因是：隔离性好、启动快、资源限制方便。

一个典型的 Agent 沙盒 Dockerfile 是这样的：

FROM node:20-alpine # 创建非 root 用户 RUN adduser -D agentuser USER agentuser # 设置工作目录 WORKDIR /workspace # 限制资源（在 docker run 时指定） # --memory=2g --cpus=1.5 --network=agent-network # 安装依赖 COPY package.json pnpm-lock.yaml ./ RUN pnpm install --frozen-lockfile # 复制代码 COPY . . # 默认命令 CMD ["pnpm", "test"]

启动沙盒的命令：

docker run -d \ --name agent-sandbox-01 \ --memory=2g \ --cpus=1.5 \ --network=agent-network \ --read-only \ -v /tmp/agent-workspace:/workspace \ agent-sandbox:latest

这里有几个关键参数需要解释：

• --memory=2g：限制内存，防止 Agent 跑内存泄漏的代码把宿主机拖垮。
• --cpus=1.5：限制 CPU，防止 Agent 跑死循环。
• --read-only：文件系统只读，Agent 只能写入挂载的/workspace目录。
• --network=agent-network：独立网络，Agent 不能直接访问生产数据库。

我踩过的坑是：一开始没加--read-only，结果 Agent 在沙盒里执行了一个脚本，把宿主机的/etc/hosts改了。虽然没造成严重后果，但吓出一身冷汗。沙盒的第一原则是：假设 Agent 会做任何事，然后限制它只能做允许的事。

3.4 Agent 并发控制：别让 10 个 Agent 同时抢一个数据库

Agent 并发是很多团队忽略的问题。当你有多个 Agent 同时执行任务时，它们可能会竞争同一资源。我见过最惨的情况是：5 个 Agent 同时执行数据库迁移，结果迁移文件冲突，数据库 schema 直接乱掉。

我的解决方案是：引入 Agent 任务队列 + 资源锁。

任务队列用 Redis 实现，每个 Agent 执行前先申请锁：

import redis import time r = redis.Redis(host='localhost', port=6379) def acquire_lock(resource, timeout=300): lock_key = f"lock:{resource}" end = time.time() + timeout while time.time() < end: if r.set(lock_key, "locked", nx=True, ex=timeout): return True time.sleep(1) return False def release_lock(resource): r.delete(f"lock:{resource}")

Agent 执行数据库迁移前，必须先获取db:migration锁。获取不到就排队等待。这样保证同一时间只有一个 Agent 在操作数据库。

资源锁的粒度要设计好：太粗会影响并发效率，太细会增加管理复杂度。我的经验是：按资源类型加锁，而不是按具体表或文件加锁。比如db:migration、file:package.json、deploy:staging这样的粒度比较合适。

4. 实操过程与核心环节实现：从零搭建 AI Native 开发流

4.1 环境准备：10 分钟搭好基础骨架

在开始之前，你需要准备这些东西：

• 一台开发服务器（4 核 8G 起步，Agent 沙盒比较吃资源）
• Docker 和 Docker Compose
• Redis（用于任务队列和锁）
• 一个代码仓库（GitHub、GitLab 或自建 Gitea 都行）
• Agent 运行环境（Claude API、OpenAI API 或本地模型）

我通常用 Docker Compose 一键拉起所有服务：

version: '3.8' services: redis: image: redis:7-alpine ports: - "6379:6379" volumes: - redis-data:/data agent-runner: build: ./agent-runner depends_on: - redis environment: - REDIS_URL=redis://redis:6379 - AGENT_API_KEY=${AGENT_API_KEY} volumes: - ./workspace:/workspace - /var/run/docker.sock:/var/run/docker.sock volumes: redis-data:

这个配置里，agent-runner是 Agent 的调度服务，它负责从 Redis 队列里取任务，然后启动沙盒执行。/var/run/docker.sock挂载是为了让 agent-runner 能创建沙盒容器。

注意：挂载 Docker socket 有安全风险，建议只在内部网络使用，并且限制 agent-runner 的权限。

4.2 第一个 Agent 任务：让 Agent 写一个带测试的函数

环境搭好后，先跑一个最简单的任务，验证整条链路是否通畅。

任务描述：让 Agent 写一个calculateDiscount函数，输入原价和折扣率，输出折后价，要求处理边界情况（负数、超过 100% 的折扣）。

Agent 的执行流程是这样的：

1. 读取 CLAUDE.md：获取项目规范（TypeScript、Vitest、Result 类型）。
2. 进入 Plan Mode：输出计划。
3. 人工确认计划：工程师检查计划是否合理。
4. 在沙盒中执行：生成代码和测试。
5. 运行测试：在沙盒中执行pnpm test。
6. 输出结果：代码 + 测试报告。

Agent 生成的代码大概是这样：

type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }; export function calculateDiscount( originalPrice: number, discountRate: number ): Result<number, string> { if (originalPrice < 0) { return { ok: false, error: "原价不能为负数" }; } if (discountRate < 0 || discountRate > 1) { return { ok: false, error: "折扣率必须在 0 到 1 之间" }; } const finalPrice = originalPrice * (1 - discountRate); return { ok: true, value: Math.round(finalPrice * 100) / 100 }; }

测试代码：

import { describe, it, expect } from "vitest"; import { calculateDiscount } from "./discount"; describe("calculateDiscount", () => { it("正常折扣计算", () => { const result = calculateDiscount(100, 0.2); expect(result).toEqual({ ok: true, value: 80 }); }); it("原价为负数", () => { const result = calculateDiscount(-100, 0.2); expect(result.ok).toBe(false); }); it("折扣率超过 100%", () => { const result = calculateDiscount(100, 1.5); expect(result.ok).toBe(false); }); it("折扣率为 0", () => { const result = calculateDiscount(100, 0); expect(result).toEqual({ ok: true, value: 100 }); }); });

这个任务跑通后，你就有了一个可用的 AI Native 开发流。接下来就是把这个流程复制到更多任务上。

4.3 参数计算：Agent 沙盒的资源配额怎么定

沙盒资源配额不是拍脑袋定的，需要根据任务类型计算。我的经验公式是：

内存配额 = 基础运行时内存 + 任务峰值内存 × 1.5

比如 Node.js 基础运行时占 200MB，跑测试时峰值 800MB，那内存配额就是200 + 800 × 1.5 = 1400MB，取整 1.5G。

CPU 配额 = 任务并行度 × 单任务 CPU 需求

如果 Agent 任务主要是 IO 密集型（比如调 API、读写文件），CPU 配额可以低一些，1 核就够。如果是计算密集型（比如跑机器学习推理），需要 2 核以上。

我实测下来的推荐配置：

超时时间很关键。Agent 有时候会陷入死循环，没有超时限制会一直跑下去。我一般设置超时后强制 kill 沙盒，并记录日志供排查。

4.4 实操现场记录：一次完整的 Agent 任务执行

让我记录一次真实的 Agent 任务执行过程，方便你对照复现。

任务：给用户模块新增“修改密码”接口。

Step 1：产品经理写意图规格

task: 新增修改密码接口 endpoint: POST /api/user/change-password input: - oldPassword: string, 必填 - newPassword: string, 必填, 最少 8 位, 包含大小写和数字 output: - success: boolean - message: string constraints: - 旧密码必须验证通过 - 新密码不能与旧密码相同 - 修改成功后使所有已签发 token 失效 acceptance: - 旧密码错误返回 401 - 新密码格式不合规返回 400 - 修改成功后旧 token 无法访问受保护接口

Step 2：Agent 进入 Plan Mode

Agent 输出的计划：

1. 在 User 模型新增 passwordUpdatedAt 字段 2. 创建 changePassword 控制器 3. 实现密码验证逻辑（bcrypt.compare） 4. 实现新密码格式校验（正则） 5. 更新所有 token 的签发时间检查逻辑 6. 编写单元测试和集成测试 7. 回滚方案：删除 passwordUpdatedAt 字段，回滚控制器代码

Step 3：人工确认

工程师检查计划，发现第 5 步“使所有已签发 token 失效”的实现方式需要明确。Agent 补充：在 JWT payload 中加入passwordUpdatedAt时间戳，验证时对比 token 签发时间和passwordUpdatedAt，如果 token 签发时间早于passwordUpdatedAt，则拒绝。

Step 4：沙盒执行

Agent 在沙盒中生成代码，运行测试。测试报告显示：12 个测试用例全部通过。

Step 5：人工审核代码

工程师审核 Agent 生成的代码，发现一个边界情况没处理：如果用户连续两次修改密码，第二次修改时passwordUpdatedAt会覆盖第一次的值，导致第一次修改后签发的 token 也被失效。这其实是符合预期的，但需要确认产品逻辑。

Step 6：合并代码

确认无误后，合并到主分支，触发 CI/CD 流程。

这次任务从开始到合并，总共用了 25 分钟。如果纯人工写，大概需要 2 小时。效率提升是明显的，但前提是意图规格写得足够清晰。

5. 常见问题与排查技巧实录：Agent 不听话怎么办

5.1 Agent 执行偏离预期：先查 CLAUDE.md，再查上下文

Agent 执行偏离预期是最常见的问题。排查顺序应该是：

1. 检查 CLAUDE.md 是否包含相关约束。如果 Agent 用了 npm 而不是 pnpm，先看 CLAUDE.md 里有没有写“禁止使用 npm”。
2. 检查上下文是否过长。如果对话历史超过 50 轮，Agent 可能会“忘记”早期的约束。解决方案是定期清理上下文，或者把关键约束放在 CLAUDE.md 里而不是对话历史里。
3. 检查任务描述是否模糊。如果任务描述是“优化一下这个函数”，Agent 可能会做过度优化。任务描述必须具体，比如“把这个函数的执行时间从 200ms 降到 50ms 以内”。

我踩过的坑是：有一次让 Agent 重构一个模块，任务描述写的是“让代码更整洁”。结果 Agent 把整个模块重写了，引入了新的依赖，还改了对外接口。后来我把任务描述改成“在不改变对外接口的前提下，把函数长度从 200 行拆分成不超过 50 行的子函数”，Agent 就执行得很精准。任务描述越具体，Agent 执行越可靠。

5.2 Agent 沙盒启动失败：资源不足还是镜像问题

沙盒启动失败通常有两个原因：资源不足或镜像问题。

排查步骤：

# 查看 Docker 日志 docker logs agent-sandbox-01 # 查看资源使用情况 docker stats --no-stream # 检查镜像是否存在 docker images | grep agent-sandbox

如果是资源不足，错误信息通常是Cannot allocate memory或no space left on device。解决方案是清理无用容器和镜像，或者增加宿主机资源。

如果是镜像问题，错误信息通常是image not found或pull access denied。解决方案是检查镜像名称和仓库权限。

我遇到过一次诡异的问题：沙盒启动后立即退出，日志显示exec format error。排查后发现是镜像构建时用了 ARM 架构的基础镜像，但宿主机是 x86 架构。构建镜像时一定要指定平台：docker build --platform linux/amd64。

5.3 Agent 并发冲突：锁没生效还是粒度不对

并发冲突的表现是：多个 Agent 同时修改同一文件，导致代码冲突或数据不一致。

排查步骤：

1. 检查锁是否生效。在 Redis 里查看锁的 key 是否存在：redis-cli keys "lock:*"。
2. 检查锁的粒度是否合适。如果锁的粒度太细（比如按文件加锁），Agent 可能同时修改不同文件但产生依赖冲突。
3. 检查锁的超时时间。如果超时时间太短，Agent 还没执行完锁就释放了，会导致并发冲突。

我的经验是：锁的超时时间应该设置为任务平均执行时间的 2 倍。比如任务平均执行 3 分钟，锁的超时时间设为 6 分钟。这样既能防止死锁，又能保证任务执行期间锁不会意外释放。

5.4 常见问题速查表

5.5 独家避坑技巧：我踩过的三个大坑

坑一：CLAUDE.md 写成了技术文档。一开始我把 CLAUDE.md 写成了项目架构说明，结果 Agent 每次执行都要花大量 token 解析这个文件，反而拖慢了速度。后来我把它压缩到 500 字以内，只保留最关键的约束，效果反而更好。

坑二：Plan Mode 确认人随便找。我见过一个团队让实习生确认 Agent 的数据库迁移计划，结果实习生看不懂，直接点了同意，导致生产环境多了一个冗余字段。确认人必须对操作后果负责。

坑三：沙盒没加只读限制。一开始没加--read-only，结果 Agent 在沙盒里执行了一个脚本，把宿主机的/etc/hosts改了。虽然没造成严重后果，但吓出一身冷汗。沙盒的第一原则是：假设 Agent 会做任何事，然后限制它只能做允许的事。

6. Agent 安全与权限管理：别让 Agent 变成内鬼

6.1 Agent 权限分级：最小权限原则

Agent 的权限必须分级，不能所有 Agent 都用同一个 API Key。我的分级方案是：

大部分 Agent 只需要 L2 权限。L3 和 L4 权限的 Agent 必须经过严格审批，并且所有操作都要记录审计日志。

6.2 Agent 审计日志：记录每一次操作

审计日志是事后排查的关键。我要求所有 Agent 操作都必须记录以下信息：

{ "timestamp": "2025-01-15T10:30:00Z", "agent_id": "agent-codegen-01", "task_id": "task-20250115-001", "operation": "file_write", "target": "/workspace/src/user/change-password.ts", "result": "success", "duration_ms": 1200, "plan_approved_by": "engineer@example.com" }

审计日志要存储在独立的日志系统中，不能和 Agent 沙盒在同一台机器上。这样即使沙盒被攻破，审计日志也不会丢失。

6.3 Agent 安全红线：这些事绝对不能让 Agent 做

根据我的经验，以下操作绝对不能让 Agent 自主执行：

• 直接操作生产数据库：Agent 只能生成迁移脚本，执行必须由人工完成。
• 修改 CI/CD 密钥：Agent 不能访问任何密钥管理服务。
• 删除代码仓库：Agent 不能执行git push --force或删除远程分支。
• 访问外部网络：Agent 沙盒默认不能访问外网，需要白名单才能访问特定 API。

这些红线不是限制 Agent 的能力，而是保护团队的安全。我见过一个团队让 Agent 自主部署到生产环境，结果 Agent 把 staging 配置部署到了 production，导致生产环境连了测试数据库。Agent 可以辅助决策，但不能替代决策。

7. 从单 Agent 到多 Agent 协作：进阶玩法

7.1 多 Agent 协作的适用场景

单 Agent 适合线性任务：写代码→测试→提交。但复杂任务需要多 Agent 协作，比如：

• 代码审查：一个 Agent 写代码，另一个 Agent 审查代码，第三个 Agent 跑安全扫描。
• 跨模块重构：多个 Agent 分别负责不同模块，最后合并。
• 端到端测试：一个 Agent 生成测试用例，另一个 Agent 执行测试，第三个 Agent 分析结果。

多 Agent 协作的核心挑战是通信和协调。我的做法是：用一个 Orchestrator Agent 负责任务分发和结果汇总，其他 Agent 只负责执行子任务。

7.2 Orchestrator Agent 的设计

Orchestrator Agent 的职责是：

1. 接收任务，拆解成子任务。
2. 把子任务分发给对应的 Agent。
3. 收集子任务结果，判断是否完成。
4. 如果子任务失败，决定重试还是上报。

Orchestrator Agent 的伪代码：

class OrchestratorAgent: def __init__(self, agents): self.agents = agents # {agent_type: agent_instance} def execute(self, task): subtasks = self.plan(task) results = [] for subtask in subtasks: agent = self.agents[subtask.type] result = agent.execute(subtask) if not result.success: if subtask.retryable: result = agent.execute(subtask) else: return self.escalate(subtask, result) results.append(result) return self.merge(results)

这个设计的关键是：Orchestrator 不执行具体任务，只负责协调。这样每个 Agent 的职责清晰，出问题时容易定位。

7.3 多 Agent 协作的坑：通信开销和状态同步

多 Agent 协作最大的坑是通信开销。我试过让 5 个 Agent 协作重构一个模块，结果它们花了 80% 的时间在互相发消息，只有 20% 的时间在干活。

解决方案是：减少 Agent 之间的直接通信，改用共享状态。比如所有 Agent 都读写同一个 Redis 状态存储，而不是互相发消息。Orchestrator 只负责在关键节点同步状态。

另一个坑是状态同步。如果 Agent A 修改了文件，Agent B 还在用旧版本的文件，就会产生冲突。解决方案是：每次 Agent 读取文件前，先检查文件版本号。如果版本号变了，重新读取。

8. 我个人在实际操作中的体会

这套 AI Native 开发流，我带着团队跑了半年多，最大的体会是：Agent 不是替代人，是放大人。一个思路清晰的工程师，用 Agent 后产出能翻三倍；一个思路混乱的工程师，用 Agent 后只会制造更多混乱。

我见过最成功的案例，是一个 8 人团队用这套流程，把版本迭代周期从 4 周压缩到 1 周。他们的秘诀不是 Agent 多厉害，而是意图规格写得足够清晰。产品经理花 2 小时写 YAML 规格，Agent 花 30 分钟生成代码，工程师花 1 小时审核，剩下的时间都在做真正有价值的架构设计。

我也见过失败的案例。一个团队买了最贵的 Agent 工具，但 CLAUDE.md 写得乱七八糟，Plan Mode 没人看，沙盒没加限制。结果 Agent 把生产数据库的索引删了，导致线上服务瘫痪 2 小时。工具再好，流程不对，照样出事。

最后分享一个小技巧：每周花 30 分钟复盘 Agent 的执行日志。看看哪些任务 Agent 执行得好，哪些执行得差。执行得差的任务，往往是意图规格写得不够清晰。持续优化意图规格，Agent 的准确率会越来越高。这个习惯我坚持了半年，现在团队里 Agent 的任务成功率从最初的 60% 提升到了 92%。

这套手册后续还可以这样扩展：引入 Agent 性能监控，追踪每个 Agent 的 token 消耗和执行时间；建立 Agent 知识库，把常见任务的意图规格模板化；探索多模态 Agent，让 Agent 能直接解析设计稿生成前端代码。这些方向我都在尝试，有新的心得再分享。