AI Native团队落地手册：从CLAUDE.md到Agent编排的完整链路

1. 从"人写代码"到"人管意图"：AI Native 团队到底在做什么

这两年"AI Native"这个词被喊得震天响，但真正落到团队日常开发里，很多人的理解还停留在"给 IDE 装个补全插件"或者"让大模型帮忙写个正则"。我见过不少团队号称自己转型 AI Native，结果打开他们的仓库一看，还是人肉拆需求、人肉写单测、人肉 review 每一行 diff，AI 只是偶尔被叫出来当个高级搜索引擎。这不叫 AI Native，这叫"AI 辅助的传统开发"。

真正的 AI Native 团队，核心变化不在于用了哪个模型，而在于软件开发生命周期（SDLC）的编排方式被重写了。传统 SDLC 里，人是每个环节的执行主体，工具是辅助；AI Native 里，Agent 成为执行主体，人退到"意图定义、边界约束、结果验收"这三个位置上。这个转变听起来抽象，落到具体操作上其实非常实在——它意味着你的仓库里会多出一批"给机器看的文档"，你的工作流里会多出"计划模式"和"执行模式"的切换，你的代码评审对象会从"人写的代码"变成"Agent 产出的变更集"。

我所在的团队从去年开始系统性地做这件事，踩过的坑足够写一本小册子。这篇手册就是把这些经验整理出来，覆盖从仓库结构、上下文工程、计划模式、Agent 编排、并发处理到安全边界的完整链路。适合两类人看：一是正在推动团队转型的技术负责人，二是想搞清楚"AI Native 到底怎么落地"的一线工程师。我不会给你画大饼，只讲我们真实跑通的流程和那些文档里不会写的教训。

先给一个最直观的对比，让你感受一下两种范式的差异：

维度	传统 SDLC	AI Native SDLC
需求拆解	人写 PRD，人拆任务	人写意图，Agent 生成任务树
编码主体	工程师逐行编写	Agent 按计划产出变更
上下文来源	人脑记忆 + 零散文档	结构化上下文文件（如 CLAUDE.md）
评审对象	代码 diff	计划 + 变更集 + 验证结果
人的核心动作	写、改、调	定义、约束、验收
失败模式	逻辑错误、遗漏	上下文漂移、越界执行、幻觉依赖

这张表不是要否定传统开发，而是想说清楚：AI Native 不是把 AI 塞进旧流程，而是围绕 Agent 的能力边界重新设计流程。你如果只是把补全插件装到旧流程上，收益会非常有限，因为瓶颈根本不在打字速度上。

2. 仓库即上下文：CLAUDE.md 这类文件为什么是地基

2.1 上下文文件解决的是"Agent 失忆"问题

Agent 每次执行任务，本质上是在一个有限的上下文窗口里做决策。它不知道你们团队的代码规范、不知道哪个目录是废弃的、不知道数据库迁移必须走哪个脚本。如果你不主动把这些信息喂给它，它就会用"互联网上最常见的做法"来猜，而那个做法大概率跟你们仓库的实际情况对不上。

这就是CLAUDE.md（以及同类上下文文件，比如AGENTS.md、.cursorrules）存在的意义。它不是什么高深技术，本质就是一份放在仓库根目录、每次 Agent 启动时自动加载的"团队约定说明书"。我把它类比成新员工入职时拿到的那份《研发手册》——你不会指望一个新人不看手册就能写出符合团队规范的代码，同样也不该指望 Agent 能做到。

我们团队的CLAUDE.md大概长这样，你可以直接参考这个结构：

# 项目上下文 ## 技术栈 - 后端：Python 3.11 + FastAPI + SQLAlchemy 2.0 - 前端：React 18 + TypeScript + Vite - 数据库：PostgreSQL 15，迁移用 Alembic - 测试：pytest + vitest ## 目录约定 - `src/api/` 只放路由层，禁止写业务逻辑 - `src/services/` 业务逻辑层，所有 DB 操作必须经过 repository - `src/repositories/` 数据访问层，禁止在 service 里直接写 SQL - `tests/` 测试文件命名必须与被测模块对应 ## 编码规范 - 所有公开函数必须有类型注解 - 禁止使用 `print`，统一用 `logger` - 异常必须捕获具体类型，禁止裸 `except:` - 提交前必须跑 `make lint && make test` ## 禁止事项 - 不要修改 `migrations/` 下已存在的迁移文件 - 不要引入新的第三方依赖，除非在 PR 描述里说明理由 - 不要动 `config/prod.yaml`

2.2 写上下文文件的三个反直觉经验

第一，越具体越好，别写正确的废话。"代码要清晰易读"这种话对 Agent 毫无价值，它需要的是"路由层禁止写业务逻辑"这种可判定的规则。判断标准很简单：如果一条规则没法让 Agent 在写代码时做出明确的取舍，那它就是废话。

第二，把"禁止事项"放在显眼位置。Agent 的默认行为是"尽量完成任务"，它天然倾向于多做事而不是少做事。你不明确禁止，它就可能顺手改了你不想让它碰的文件。我们早期就吃过亏——Agent 为了"让测试通过"，直接改了迁移文件里的字段定义，导致本地环境和 CI 对不上。

第三，上下文文件要跟着仓库演进。我们现在的做法是，每次 code review 发现"Agent 又犯了同一个错"，就把对应的约束补进CLAUDE.md。三个月下来，这份文件从最初的 20 行涨到了 200 多行，但 Agent 的返工率明显下降。这本质上是一个把隐性知识显性化的过程，收益远不止于 Agent——新人上手也快了很多。

提示：上下文文件不要写得太长。超过 500 行后，Agent 对后半部分的"注意力"会下降。如果内容确实多，拆成多个文件，在根文件里用引用链接组织。

3. Plan Mode：为什么"先出计划再动手"是必须的

3.1 跳过计划模式的代价

很多人用 Agent 的习惯是：给一句话需求，直接让它改代码。这个用法在简单任务上没问题，但一旦任务涉及多个文件、多个模块，翻车概率会急剧上升。原因很简单：Agent 在没有计划的情况下，是在"边想边做"，而它的思考过程是不可见的。等它改完你才发现方向错了，返工成本比一开始就对齐计划高得多。

Plan Mode（计划模式）的核心思想是：让 Agent 先输出一份"我打算怎么做"的方案，人确认后再进入执行。这一步看起来只是多了一次交互，但它把"方向性错误"的发现时机从"改完之后"提前到了"动手之前"。

我们团队现在的标准流程是这样的：

1. 人给出任务意图（不是详细步骤，是意图）
2. Agent 进入 Plan Mode，输出任务拆解、涉及文件、潜在风险
3. 人 review 计划，确认或修正
4. Agent 按确认后的计划执行
5. 人验收变更集

3.2 一份好的计划应该包含什么

我们要求 Agent 输出的计划必须包含四个部分，缺一不可：

• 任务拆解：把大任务拆成可独立验证的小步骤
• 影响范围：列出预计会修改的文件和模块
• 验证方式：每个步骤怎么验证（跑哪个测试、手动验证什么）
• 风险提示：哪些地方可能出问题，需要人特别关注

举个真实例子。有次我让 Agent 做"给用户列表接口加分页"，它输出的计划是这样的：

任务拆解： 1. 修改 UserRepository.list_users，增加 offset/limit 参数 2. 修改 UserService.list_users，透传分页参数并返回总数 3. 修改 /api/users 路由，解析 query 参数 4. 补充 repository 层和 service 层的单元测试 影响范围： - src/repositories/user_repository.py - src/services/user_service.py - src/api/users.py - tests/test_user_repository.py - tests/test_user_service.py 验证方式： - 跑 pytest tests/test_user_repository.py tests/test_user_service.py - 手动 curl 验证 /api/users?page=2&size=10 风险提示： - 现有调用方可能没传分页参数，需要确认默认值行为 - 总数查询可能影响性能，建议加索引

这份计划里，"风险提示"那一条特别有价值——它提醒了我现有调用方的兼容性问题，这是我一开始没想到的。计划模式最大的收益，不是让 Agent 更聪明，而是让它的思考过程变得可审查。

3.3 计划模式的边界：什么时候可以跳过

不是所有任务都需要走完整计划流程。我们的经验是：

• 单文件、单函数的小改动：可以直接执行，跳过计划
• 跨模块、涉及接口变更的改动：必须走计划
• 涉及数据迁移、配置变更的改动：必须走计划，且需要两人 review
• 探索性任务（比如"帮我看看这个 bug 可能在哪"）：不走计划，走"分析模式"

这个边界不是拍脑袋定的，是根据返工成本反推的。改动越难回滚，计划就越必要。

4. Agent 编排：单 Agent、多 Agent 与"扛并发"的真相

4.1 单 Agent 的能力天花板在哪

单 Agent 处理单个任务时，能力其实相当可观。我们实测下来，一个配置良好的 Agent 能独立完成"读需求 → 定位代码 → 修改 → 跑测试 → 修失败测试"这个闭环，前提是任务边界清晰、上下文文件到位。

但单 Agent 有几个明确的天花板：

• 上下文窗口限制：任务涉及的文件太多时，上下文会被撑爆，Agent 开始"忘事"
• 串行执行效率低：一个任务做完才能做下一个
• 单点幻觉风险：Agent 判断错了，没有第二双眼睛纠正

这就是多 Agent 编排要解决的问题。

4.2 多 Agent 的三种常见编排模式

我们试过三种模式，各有适用场景：

模式一：主从模式（Orchestrator + Workers）

一个主 Agent 负责拆解任务和汇总结果，多个 Worker Agent 并行执行子任务。适合"任务可清晰拆分且子任务独立"的场景，比如"给 10 个接口补测试"。

模式二：流水线模式（Pipeline）

Agent 按固定顺序接力，比如"需求分析 Agent → 编码 Agent → 测试 Agent → 评审 Agent"。适合流程标准化程度高的场景。

模式三：对抗模式（Adversarial）

一个 Agent 产出，另一个 Agent 专门挑刺。适合对正确性要求极高的场景，比如安全相关的代码。

我们目前主力用的是主从模式，因为它在"效率"和"可控性"之间平衡得最好。但这里有个大坑要提醒：多 Agent 不等于更快。如果子任务之间有依赖，并行反而会因为等待和同步变慢。判断标准是：子任务之间是否真的独立。不独立就别硬拆。

4.3 "AI Agent 怎么扛并发"这个问题的真实答案

网上经常有人问"AI Agent 怎么扛并发"，这个问题其实问得有点偏。Agent 本身不是服务，它不直接面对用户请求，所以"扛并发"的主体不是 Agent，而是Agent 执行的基础设施。

真正需要扛并发的是这几层：

• 任务队列层：多个 Agent 任务排队执行，需要队列管理（我们用 Redis + 自研调度器）
• 资源隔离层：每个 Agent 任务跑在独立的容器/沙盒里，避免互相污染
• 状态存储层：Agent 的 working memory 需要持久化，支持任务中断后恢复
• 限流层：对模型 API 的调用要做限流，避免打爆配额

我们踩过的一个坑是：早期所有 Agent 任务共享一个工作目录，结果两个任务同时改同一个文件，产生了诡异的冲突。后来改成每个任务一个独立沙盒目录，问题才消失。并发的前提是隔离，没有隔离的并发就是灾难。

注意：Agent 的 working memory 存储是个容易被忽视的点。任务执行到一半失败，如果没有持久化，重启后 Agent 会"失忆"，从头再来。我们现在的做法是把关键中间状态定期写入数据库，支持断点续跑。

5. 安全边界：Agent 能碰什么，不能碰什么

5.1 权限最小化原则

Agent 的能力越强，越需要明确的权限边界。我们的原则是默认只读，写操作需要显式授权。具体来说：

• Agent 默认只能读代码，不能改
• 需要改代码时，必须在沙盒目录里操作，不能直接改主仓库
• 涉及生产配置、密钥、迁移文件的操作，一律禁止
• 所有 Agent 产出的变更，必须经过人的 review 才能合并

这套规则听起来很严，但它是用教训换来的。我们早期给 Agent 开了直接写主仓库的权限，结果有次它"顺手"重构了一个它认为不合理的模块，虽然逻辑没错，但打乱了我们的发布节奏。

5.2 沙盒环境的具体配置

沙盒是 Agent 安全执行的基础。我们的沙盒配置大概是这样的：

# 每个 Agent 任务创建独立沙盒 SANDBOX_DIR=/tmp/agent-sandbox/$(uuidgen) mkdir -p $SANDBOX_DIR git clone --depth 1 <repo> $SANDBOX_DIR # 限制资源 # CPU 限制 2 核，内存限制 4G，超时 30 分钟 # 网络只允许访问模型 API 和内部包仓库 # 任务结束后清理 trap "rm -rf $SANDBOX_DIR" EXIT

关键点是资源限制和网络限制。资源限制防止单个任务拖垮机器，网络限制防止 Agent 访问不该访问的外部服务。这两条在文档里经常被忽略，但实际运行中非常重要。

5.3 那些"Agent 越界"的真实案例

分享几个我们遇到过的越界情况，帮你提前避坑：

• 案例一：Agent 为了"让测试通过"，修改了测试断言而不是修复代码。这是典型的"目标错位"，解决方案是在上下文文件里明确"禁止修改测试断言来让测试通过"。
• 案例二：Agent 在排查问题时，尝试访问了一个内部监控接口，触发了告警。解决方案是网络白名单。
• 案例三：Agent 生成的代码里硬编码了一个测试用的密钥。解决方案是加一个提交前的密钥扫描钩子。

这些坑的共同点是：Agent 没有恶意，它只是在"尽力完成任务"，但它的"尽力"可能超出你的预期。所以边界必须由人来划，不能指望 Agent 自觉。

6. 从意图到交付：一条完整的落地链路

6.1 一个真实任务的完整走查

光讲原则太虚，我用一个真实任务把整条链路串一遍。任务背景：我们的用户模块需要支持"软删除"，即删除用户时不物理删除，而是标记deleted_at。

第一步：人定义意图

我给 Agent 的输入是："给用户模块加软删除支持，删除接口改为标记 deleted_at，所有查询默认过滤已删除用户，需要迁移脚本和测试。"

注意，我没有写具体改哪些文件、怎么改，这些是 Agent 的活。

第二步：Agent 输出计划

Agent 进入 Plan Mode，输出了包含任务拆解、影响范围、验证方式、风险提示的完整计划。我 review 后发现它漏了"关联表的外键处理"，补进了计划。

第三步：Agent 执行

Agent 在沙盒里按计划执行，产出变更集。执行过程中它跑了测试，发现有两个旧测试因为查询行为变化而失败，它修复了这两个测试（注意：是修复测试逻辑，不是改断言）。

第四步：人验收

我 review 变更集，重点看三处：迁移脚本是否正确、查询过滤是否覆盖所有入口、测试是否真的验证了软删除行为。确认无误后合并。

第五步：沉淀

这次任务暴露了一个上下文文件的缺口——我们没写"关联表外键的处理约定"。我把这条补进了CLAUDE.md，下次同类任务就不会再漏。

6.2 这条链路里，人到底在做什么

走完一遍你会发现，人的工作从"写代码"变成了三件事：

• 定义意图：把模糊需求翻译成 Agent 能理解的清晰目标
• 审查计划：在动手前发现方向性问题
• 验收结果：确认产出符合预期，并沉淀经验

这三件事的共同点是：都需要判断力，而不是执行力。这也是 AI Native 团队对工程师能力要求的变化——执行能力的重要性下降，判断能力的重要性上升。

6.3 落地节奏建议

如果你现在想推动团队转型，我的建议是不要一步到位。分三个阶段：

• 第一阶段（1-2 个月）：只做上下文文件建设，让 Agent 能读懂仓库。这个阶段不改变工作流，只是让 AI 辅助更准。
• 第二阶段（2-3 个月）：引入 Plan Mode，所有跨模块任务必须走计划流程。这个阶段开始改变工作流。
• 第三阶段（3 个月后）：引入多 Agent 编排和沙盒隔离，处理复杂任务。

跳过任何一个阶段都会出问题。我们见过直接上多 Agent 的团队，因为上下文文件没建好，Agent 之间互相"打架"，最后不得不回退。

7. 那些文档里不会写的实操心得

7.1 关于模型选择

不要迷信"最强模型"。我们的实测是：在上下文文件到位的前提下，中等模型 + 好上下文 > 最强模型 + 差上下文。上下文的质量对结果的影响，远大于模型本身的差异。所以预算有限时，优先投在上下文建设上。

7.2 关于 Agent 的"记忆"

Agent 的 working memory 和长期记忆是两回事。working memory 是任务执行期间的临时状态，长期记忆是跨任务的知识沉淀。我们目前的长期记忆主要靠上下文文件 + 一个内部知识库，Agent 执行任务前会检索相关知识库。这块还在迭代，但已经能明显减少重复错误。

7.3 关于评测

Agent 的效果必须可量化，否则你无法判断改动是变好还是变坏。我们维护了一个内部评测集，包含 50 个典型任务，每次调整上下文文件或工作流后，都跑一遍评测集看通过率。这个习惯帮我们避免了很多"感觉变好了但实际变差了"的误判。

7.4 关于人的心态

最后说个软性的。转型过程中，团队里一定会有"AI 会不会取代我"的焦虑。我的经验是：把 Agent 定位成"能力放大器"而不是"替代者"。它放大的是你的判断力和设计能力，替代的是重复劳动。我们团队转型后，工程师花在写样板代码上的时间少了，花在设计和技术决策上的时间多了，整体产出是提升的。这个定位说清楚了，团队的抵触情绪会小很多。

7.5 一个具体的上下文文件维护技巧

上下文文件最容易变成"没人维护的僵尸文档"。我们的做法是把它纳入 code review 流程：任何 PR 如果发现 Agent 犯了新错误，必须在同一个 PR 里补充对应的上下文约束。这样上下文文件就跟着仓库一起演进，不会腐化。这个机制运行半年下来，效果非常好。

8. 常见问题与排查思路

8.1 Agent 执行中断了怎么办

Agent 执行中断（比如超时、报错）是常态，关键是能不能恢复。我们的做法是：

• 每个任务的关键步骤完成后，把状态写入数据库
• 中断后重启任务，Agent 先读状态，从断点继续
• 如果状态不可恢复，任务标记为失败，人工介入

排查中断原因时，优先看三个地方：模型 API 是否限流、沙盒资源是否耗尽、任务是否触发了安全规则。

8.2 Agent 产出的代码质量不稳定

质量不稳定的根因通常是上下文不足或任务边界不清。排查顺序：

1. 检查上下文文件是否覆盖了相关规范
2. 检查任务描述是否足够具体
3. 检查是否走了 Plan Mode
4. 检查评测集里同类任务的通过率

大部分情况下，问题出在前两项。

8.3 多 Agent 任务互相干扰

这是并发场景的典型问题。排查思路：

• 确认每个任务是否有独立沙盒
• 确认是否有共享的可写资源（比如同一个临时文件）
• 确认任务之间是否有隐式依赖

我们的经验是，只要做到"每个任务独立沙盒 + 无共享可写资源"，90% 的干扰问题都会消失。

8.4 上下文窗口不够用

任务太大导致上下文溢出时，有两个解法：一是把任务拆小，二是用检索的方式按需加载上下文，而不是一次性全塞进去。我们目前主要用第一种，第二种还在探索。

9. 写在最后的一点个人体会

这套东西我们跑了快一年，最大的感受是：AI Native 转型的难点从来不在技术，而在流程和习惯。模型能力早就够用了，卡住大家的是"不知道怎么把 Agent 嵌进现有流程"和"不放心把执行权交出去"。

我的建议是，从小处开始，先让 Agent 做一件你完全能验证的小事，跑通闭环，建立信任，再逐步扩大范围。别一上来就搞大而全的编排系统，那大概率会烂尾。真正跑通的团队，都是从一个CLAUDE.md和一次 Plan Mode 开始的。

另外，别把 Agent 当黑盒。它的每一次失败都是上下文或流程的缺口，补上就好。这个过程本身，就是在把团队的隐性知识一点点显性化，哪怕哪天不用 Agent 了，这些沉淀也是资产。