AI Native团队开发手册：上下文工程与Agent编排实战

1. 从"AI辅助"到"AI原生"：团队开发范式到底变了什么

大多数团队嘴上说着"AI Native"，实际干的事还是老一套——产品经理写PRD，开发照着文档敲代码，测试等提测，最后在某一步"接入AI"当作亮点。这不叫AI Native，这叫"AI点缀"。真正的AI Native团队，改变的不是某个环节的工具，而是整个软件开发生命周期（SDLC）的组织方式：Agent成为一等公民，人从执行者变成编排者和审核者。

我所在的团队从去年开始完整跑通了一套AI Native的开发流程，从需求拆解、方案设计、编码实现、代码审查到测试验证，全链路都有Agent参与。踩过的坑、验证过的模式、沉淀下来的规范，构成了这份手册的全部内容。它适合三类人：一是想搞清楚AI Native到底怎么落地的技术负责人；二是正在搭建Agent工作流的一线开发者；三是对SDLC重构感兴趣、想知道"人机协作边界在哪"的工程师。

先说一个反直觉的结论：AI Native团队最大的瓶颈从来不是模型能力，而是上下文管理。模型再强，如果它拿不到正确的项目背景、编码规范、历史决策，产出的东西就是"看起来对但用不了"。所以这份手册的核心线索，是围绕"如何让Agent在正确的上下文中工作"展开的——CLAUDE.md怎么组织、Plan Mode怎么用、Agent的边界怎么划、多Agent怎么编排、安全怎么兜底。下面逐层拆开讲。

2. 上下文工程：CLAUDE.md不是说明书，是Agent的操作系统

2.1 为什么大多数团队的CLAUDE.md写了等于没写

我见过太多团队的CLAUDE.md，打开一看就是一段"本项目使用React + TypeScript，请遵循最佳实践"——这种写法对Agent来说几乎零信息量。Agent需要的是可执行的约束，不是泛泛而谈的原则。一份有效的CLAUDE.md，本质上是给Agent的"入职培训手册"，它要回答四个问题：这个项目是干什么的、代码怎么组织、改代码要遵守什么规则、遇到不确定时该问谁。

我们团队迭代了七版CLAUDE.md，最终稳定下来的结构是这样的：

• 项目定位段：一句话说清业务目标和技术栈，不超过三行。Agent不需要读你的商业计划书。
• 目录地图：用树状结构标注每个目录的职责，特别是那些"看起来像但实际不同"的目录。比如/utils和/helpers的区别，不写清楚Agent一定会放错地方。
• 编码铁律：只写那些"违反了一定会出问题"的规则。比如"所有API调用必须走request.ts封装，禁止直接使用fetch"、"状态管理统一用Zustand，禁止引入Redux"。
• 禁区清单：明确列出Agent不能碰的文件和目录，比如数据库迁移脚本、CI配置、密钥文件。
• 决策记录索引：指向/docs/adr目录，让Agent在遇到架构选择时先查历史决策。

提示：CLAUDE.md的长度控制在500行以内。超过这个长度，Agent的注意力会被稀释，关键规则反而被忽略。我们的做法是把详细规范拆到/docs下，CLAUDE.md只保留索引和铁律。

2.2 上下文分层：把"永远要知道"和"用到才加载"分开

一开始我们把所有规范都塞进CLAUDE.md，结果Agent每次对话都要吞掉大量无关信息，token消耗高不说，还经常"抓错重点"。后来我们做了分层：

这个分层的关键在于L0必须极度精简。我们实测下来，L0控制在300行以内时，Agent对规则的遵守率明显高于塞满内容的版本。L1和L2通过文件路径引用，Agent需要时会自己去读——前提是你在CLAUDE.md里告诉它"遇到X情况去读Y文件"。

2.3 一个真实的翻车案例

有次我们让Agent重构一个订单模块，它在CLAUDE.md里读到"状态管理用Zustand"，但没读到"订单状态机必须走orderStateMachine.ts，禁止直接setState"。结果它自作主张用Zustand直接改了状态，绕过了状态机的校验逻辑，测试环境直接炸了。问题不在Agent，在于我们把关键约束放在了L1文档里，而那次任务没有触发L1加载。

教训：凡是"违反了会导致线上事故"的规则，一律放L0。宁可CLAUDE.md长一点，也不能让关键约束藏在按需加载的文档里。

3. Plan Mode实战：让Agent先想清楚再动手

3.1 Plan Mode解决的是什么问题

Agent最危险的行为模式是"边想边做"——它可能改到一半发现方向错了，但已经动了好几个文件，回滚成本极高。Plan Mode的核心价值就是强制Agent在动手前输出完整方案，由人审核后再执行。这听起来简单，但实际用起来有很多细节。

我们的Plan Mode流程是这样的：Agent接到任务后，先输出一份计划，包含"要改哪些文件、每个文件改什么、为什么这么改、有什么风险"。人审核通过后，Agent才开始执行。审核不通过就打回重来。这个流程把"返工成本"从"改错代码"降到了"改错计划"，效率提升非常明显。

3.2 计划的质量取决于提示词的结构

一开始Agent输出的计划很水，就是"修改A文件、修改B文件"这种流水账。后来我们优化了提示词模板，要求计划必须包含五个部分：

1. 任务理解：用自己的话复述需求，确认理解无误。
2. 影响范围：列出所有会被改动的文件，标注新增/修改/删除。
3. 实现思路：每个文件改什么、为什么这么改。
4. 风险点：可能影响的其他功能、需要回归测试的范围。
5. 验证方案：改完后怎么验证，跑哪些测试。

这个模板逼着Agent把"想"和"做"分开，也让人审核时有了明确的检查清单。实测下来，计划阶段多花5分钟，执行阶段能省半小时。

3.3 什么任务适合Plan Mode，什么任务不适合

不是所有任务都值得走Plan Mode。我们的经验是：

• 适合：跨多文件的改动、涉及核心逻辑的重构、新增功能模块、数据库schema变更。
• 不适合：单文件的小修小补、格式化、改文案、加日志。

判断标准很简单：如果改错了，回滚成本高不高。高就走Plan Mode，低就直接干。我们团队有个不成文的规矩：改动超过3个文件，必须走Plan Mode。

注意：Plan Mode不是万能的。有些Agent会在计划里写得天花乱坠，执行时却偷工减料。所以执行完成后，一定要对照计划逐项验收，不能只看"任务完成"的提示。

4. Agent的边界与编排：单Agent、多Agent、Agent Harness怎么选

4.1 先搞清楚Agent、Harness、Skill的区别

这三个词经常被混用，但它们的职责完全不同。我用一个类比说明：Agent是员工，Harness是工位和工具，Skill是员工掌握的技能。

• Agent：具备自主决策能力的执行单元，能理解任务、规划步骤、调用工具。
• Harness：Agent的运行环境，负责工具注册、权限控制、上下文注入、执行监控。你可以理解为"给Agent搭的工作台"。
• Skill：Agent可以调用的具体能力，比如"读文件""跑测试""查数据库"。Skill是原子操作，Agent负责编排。

搞清楚这个区分很重要，因为很多团队一上来就想搞"多Agent协作"，结果连单Agent的Harness都没搭好，Agent连文件都读不利索，谈何协作。

4.2 单Agent够用的场景，别急着上多Agent

我们团队80%的任务是单Agent完成的。单Agent的优势是上下文连贯、决策链路清晰、调试简单。什么时候该上多Agent？我的判断标准是：当任务可以清晰拆分成多个独立子任务，且子任务之间不需要频繁交换上下文时。

举个例子：一个"给现有API加缓存层"的任务，单Agent完全够用——它需要理解现有API、设计缓存策略、实现、测试，这些步骤高度依赖同一个上下文。但如果任务是"同时重构前端组件库和后端API"，这两个子任务上下文几乎不重叠，就可以拆成两个Agent并行。

多Agent的代价是上下文同步成本。两个Agent各自工作，最后合并时经常发现接口对不上、命名不一致。我们的做法是：多Agent任务必须先由人定义好接口契约，Agent只能在这个契约内工作。

4.3 Agent编排的三种模式

我们实际用过的编排模式有三种，各有适用场景：

串行编排：Agent A的输出作为Agent B的输入。适合"设计→实现→测试"这种流水线。优点是上下文传递清晰，缺点是慢，且前一步错了后面全错。

并行编排：多个Agent同时处理独立子任务，最后汇总。适合大范围重构。优点是快，缺点是合并冲突多。

监督编排：一个"监督Agent"负责任务分解和结果验收，多个"执行Agent"干活。适合复杂任务。优点是质量可控，缺点是监督Agent本身的能力要求高，容易成为瓶颈。

我们目前的主力模式是串行为主、局部并行。核心链路串行保证质量，独立的子任务（比如同时改多个不相关的模块）并行提速。

4.4 Agent安全：沙箱、权限、审计一个都不能少

Agent能读文件、能执行命令、能调API，这意味着它一旦"跑偏"，破坏力比人大得多。我们的安全策略分三层：

第一层是沙箱隔离。Agent的所有操作在容器内进行，网络访问白名单，文件系统只挂载项目目录。这样即使Agent执行了危险命令，影响范围也可控。

第二层是权限分级。我们把操作分成三档：只读操作（读文件、查日志）Agent可自主执行；写操作（改代码、建文件）需要Plan Mode审核；危险操作（删文件、改配置、执行迁移）必须人工确认。

第三层是审计日志。Agent的每一次工具调用、每一条命令、每一个文件改动都记录在案。出问题时能完整回溯"Agent当时看到了什么、做了什么决策"。

提示：审计日志不要只记"做了什么"，还要记"为什么"。我们的做法是要求Agent在每次关键操作前输出一句理由，这句话会一起进日志。排查问题时，这句理由往往比操作本身更有价值。

5. 全链路SDLC改造：每个环节Agent该干什么、人该干什么

5.1 需求阶段：Agent做拆解，人做取舍

需求阶段Agent能做的是"结构化"——把一段模糊的需求描述拆成可执行的任务列表，标注依赖关系、预估复杂度、识别歧义点。但优先级排序和范围取舍必须由人做，因为这里面涉及业务判断和资源约束，Agent没有足够信息。

我们的流程是：产品经理写一段需求描述，Agent输出一份"任务拆解草案"，包含任务列表、依赖图、歧义点清单。然后人过一遍，回答歧义点、调整优先级、砍掉不做的部分。这个环节Agent能省掉大概60%的整理时间。

5.2 设计阶段：Agent出方案，人做决策

设计阶段是Plan Mode的主场。Agent基于需求输出技术方案，包括模块划分、接口设计、数据模型、关键流程。人审核方案，重点看三件事：是否符合现有架构、是否引入了不必要的复杂度、是否有遗漏的边界情况。

这个环节有个坑：Agent倾向于"过度设计"。它可能会给你搞出一套复杂的抽象层，而实际上一个简单函数就够了。所以审核时要多问一句"能不能更简单"。

5.3 编码阶段：Agent写代码，人做审查

编码阶段Agent的产出质量，直接取决于前两个阶段的上下文质量。如果需求和设计都清晰，Agent写出来的代码基本可用；如果前面含糊，Agent就会"自由发挥"，产出大量需要返工的东西。

代码审查环节，人重点看四类问题：业务逻辑是否正确、边界条件是否处理、是否有安全隐患、是否符合团队规范。格式问题、命名问题这些交给linter和Agent自查，人不用浪费时间。

5.4 测试阶段：Agent生成用例，人做验收

Agent生成测试用例的能力很强，但有个通病：它倾向于测试"正常路径"，对异常路径覆盖不足。我们的做法是要求Agent必须为每个函数生成至少三类用例：正常输入、边界输入、异常输入。人审核时重点看异常用例是否覆盖到位。

验收环节必须由人做。Agent可以跑测试、报告结果，但"这个功能是否符合业务预期"只有人能判断。

5.5 各环节人机分工速查表

6. 踩坑实录：那些让我们返工三次以上的问题

6.1 上下文污染：Agent读到了过时的文档

有次Agent根据一份三个月前的设计文档改了代码，结果那份文档早就废弃了。问题根源是我们的/docs目录没有清理机制，新旧文档混在一起，Agent分不清哪个是当前有效的。

解决方案：所有文档加"有效期"标记，过期文档移到/docs/archive，并在CLAUDE.md里明确"只读/docs/current下的文档"。同时建立了文档更新责任制，谁改代码谁更新对应文档。

6.2 Agent的"自信幻觉"：它说改完了，其实没改

Agent有时会报告"已完成修改"，但实际上只改了一部分，或者改错了文件。这种情况在任务复杂时尤其常见。

解决方案：不信任Agent的"完成"报告，一律用git diff验证实际改动。我们的流程里加了一步"改动核对"——Agent报告完成后，自动跑git diff --stat，人对照计划检查文件列表是否一致。

6.3 多Agent的命名冲突

两个Agent并行工作时，各自定义了同名的工具函数，合并时直接冲突。更麻烦的是，两个Agent对同一个概念用了不同的命名，导致代码可读性极差。

解决方案：多Agent任务开始前，先由人定义"命名契约"——核心概念的统一命名、公共工具的位置、接口的签名。Agent只能在这个契约内工作，不能自行发明命名。

6.4 Token消耗失控

有次一个Agent任务跑了两个小时，消耗了大量token，最后发现它陷入了"读文件→改文件→发现不对→再读→再改"的循环。

解决方案：给Agent设置"最大迭代次数"和"token预算"，超过阈值自动中止并报告。同时优化CLAUDE.md，减少不必要的上下文加载。我们现在的做法是每个任务预设token上限，超了就停下来人工介入。

6.5 排查链路：一次典型的Agent翻车复盘

分享一次完整的排查过程。现象是：Agent重构后，某个API的响应时间从50ms涨到了800ms。

第一步：看审计日志，确认Agent改了哪些文件。发现它把原本的缓存逻辑删了，理由是"简化代码"。

第二步：看Agent的决策理由。日志里写着"缓存层增加了复杂度，且未发现明确的性能要求"。问题找到了——CLAUDE.md里没有写"该API有性能SLA要求"。

第三步：修复。恢复缓存逻辑，并在CLAUDE.md的L0层加上"所有对外API必须保留缓存层，性能要求见/docs/sla.md"。

第四步：举一反三。检查CLAUDE.md里还有哪些"隐含约束"没写清楚，补充了五条类似的规则。

这次翻车的根因不是Agent能力问题，是上下文缺失。Agent不知道性能要求，自然做了"看起来合理"的简化。这印证了前面说的：AI Native的瓶颈在上下文管理。

7. 团队落地：从试点到全面推行的节奏把控

7.1 别一上来就全链路铺开

我们最开始想一步到位，结果处处出问题，团队怨声载道。后来调整为"单点突破"：先在一个小模块上跑通"Plan Mode + 编码 + 测试"的闭环，验证有效后再逐步扩展到其他环节。

推荐的推进节奏是：单模块试点（2周）→ 单项目推广（1个月）→ 跨项目复制（2个月）。每个阶段都要有明确的验收标准，比如"Agent产出的代码一次通过率超过70%"。

7.2 团队能力建设：从"会用工具"到"会设计工作流"

AI Native对团队的能力要求变了。以前强调"代码写得快"，现在更强调"能把任务拆清楚、能把上下文组织好、能审核Agent的产出"。我们做了三件事：

• 建立提示词库：把验证有效的提示词模板沉淀下来，新人直接复用。
• 定期复盘会：每周花半小时复盘Agent翻车案例，更新CLAUDE.md和流程。
• 角色重新定义：资深工程师从"写代码"转向"设计工作流+审核产出"，初级工程师从"执行"转向"监督Agent执行"。

7.3 度量：怎么知道AI Native真的提效了

不能只看"感觉快了"，要有数据。我们跟踪四个指标：

这些数据每周统计，连续三周不达标就停下来复盘流程，而不是继续硬推。

8. 我个人的几条实操心得

跑了大半年AI Native流程，最后分享几条踩坑换来的经验，都是文档里不会写的。

第一条：CLAUDE.md要当代码一样维护。它有版本、有review、有测试。我们每次Agent翻车，第一反应都是"CLAUDE.md是不是缺了什么"，而不是"Agent怎么这么笨"。这个思维转变很关键。

第二条：Plan Mode的审核不能走过场。我见过太多人扫一眼计划就点通过，结果执行时才发现方向错了。审核计划的时间，至少要是执行时间的五分之一。

第三条：Agent的产出永远要验证。不管它说得多自信，git diff和测试结果才是真相。我们团队有个规矩：Agent说"完成"之后，必须有人跑一遍验证，才能标记任务结束。

第四条：多Agent不是越多越好。两个Agent能搞定的事，别上三个。每多一个Agent，上下文同步成本就翻一倍。我们现在的原则是"能单不双，能双不三"。

第五条：安全兜底要前置。别等出了事故才想起沙箱和权限。我们现在的做法是，任何Agent上线前，先过一遍安全检查清单：沙箱配了吗、权限分级了吗、审计日志开了吗、危险操作拦截了吗。这四条缺一条，不准上线。

这套流程还在迭代，每个月都会有新的坑和新的解法。但核心逻辑没变过：Agent负责执行，人负责判断；上下文决定质量，边界决定安全。把这两句话吃透，AI Native落地就不会跑偏。