1. 从"用AI写代码"到"和AI一起交付"：AI Native团队到底改变了什么
大多数团队嘴上说着"AI Native"，实际干的事还是老一套：产品经理写PRD，开发照着文档敲代码，测试等提测，运维等上线。AI在这个流程里只是个高级点的自动补全工具，偶尔帮忙写个正则、生成个单元测试，用完就关掉。这不叫AI Native，这叫"给传统流程贴了张AI的皮"。
真正的AI Native团队，改变的不是某个环节的效率，而是整个软件开发生命周期（SDLC）的信息流转方式。传统SDLC里，信息在人与人之间传递，每传一手就衰减一次——需求从老板嘴里到PRD衰减20%，从PRD到代码再衰减30%，从代码到测试用例又衰减20%。AI Native的核心思路是：让Agent直接消费结构化的上下文，把"人传人"的衰减链条砍掉。
我所在的团队从去年开始完整跑这套范式，踩了大概三个月的坑才摸到门道。这篇文章不讲概念，只讲我们实际怎么落地的：CLAUDE.md怎么写才不沦为摆设、Plan Mode在什么场景下真正省时间、Agent之间怎么编排才不会互相打架、以及那些文档里不会写的安全边界问题。
适合谁来读？如果你是一个5到20人规模的技术团队负责人，或者你是一个正在尝试把Agent引入日常开发流程的工程师，这篇文章里的每一步你都可以直接抄。如果你还在观望阶段，也可以先看看我们踩过的坑，至少能帮你省掉两个月的试错成本。
2. CLAUDE.md不是README的复制品：项目上下文文件的设计逻辑
2.1 为什么大多数团队的CLAUDE.md写了等于没写
我见过太多团队的CLAUDE.md，打开一看，基本就是README换了个名字：项目简介、安装步骤、目录结构、技术栈列表。这种文件对Agent来说几乎没用，因为Agent不需要你告诉它"这是一个React项目"——它自己看package.json就知道了。
CLAUDE.md的真正作用是约束Agent的行为边界，而不是介绍项目。它要回答的是：在这个项目里，什么能做、什么不能做、怎么做才符合团队规范。举个例子，"使用TypeScript"是废话，"所有API响应类型必须定义在src/types/api.ts中，禁止在组件文件内联定义响应类型"才是有效约束。
我们团队第一版CLAUDE.md写了800多字，Agent该犯错还是犯错。后来砍到300字，反而效果好了一倍。核心原则就一条：每一条规则都必须是Agent容易违反的。它不会违反的规则不用写，它不可能知道的规则必须写。
2.2 我们实际在用的CLAUDE.md结构
经过反复迭代，我们固定下来一个四段式结构，每段都有明确目的：
第一段：项目定位与核心约束。用三到五句话说明这个项目是干什么的、服务哪些用户、有哪些硬性技术约束。比如"这是一个面向B端的企业级SaaS后台，所有页面必须支持权限粒度到按钮级别，禁止在前端做任何权限判断的兜底逻辑"。这段话的作用是让Agent在做决策时有判断依据，而不是机械执行。
第二段：代码规范与文件组织。这部分要具体到文件路径和命名规则。比如"所有业务逻辑放在src/modules/[模块名]/services/下，每个service文件导出单一职责的函数，禁止在service中直接调用HTTP请求，必须通过src/lib/request.ts封装的方法"。Agent看到这种规则，生成代码时就会自动遵循，不需要你每次手动纠正。
第三段：常见任务的执行路径。这是最容易被忽略但最有价值的部分。比如"新增一个API接口时，需要依次修改：1. src/types/api.ts添加类型定义 2. src/modules/[模块]/services/添加service函数 3. src/modules/[模块]/hooks/添加对应的hook 4. 在src/mocks/中添加mock数据"。Agent拿到这个路径，就能一次性完成整个链路，而不是改完一个文件等你提醒下一个。
第四段：禁止事项清单。用最直白的语言列出绝对不能做的事。比如"禁止使用any类型"、"禁止在组件中直接使用fetch"、"禁止提交console.log"、"禁止修改src/lib/下的公共工具函数而不更新对应的测试"。这些是红线，Agent一旦触碰就会产生连锁问题。
注意：CLAUDE.md不是一次写完就固定的。我们团队的做法是，每次Code Review发现Agent犯了新错误，就把对应的规则补进去。三个月下来，这份文件从300字长到了600字，但每一条都是真实踩坑换来的。
2.3 让CLAUDE.md真正生效的两个技巧
第一个技巧是分层管理。我们在项目根目录放一个CLAUDE.md，然后在每个大模块目录下再放一个局部的CLAUDE.md。根目录的管全局规则，模块目录的管模块特有规则。Agent在处理某个模块的任务时，会同时读取两层规则，既不会遗漏全局约束，又能获得模块级的上下文。
第二个技巧是用示例代替描述。与其写"service函数要处理好错误情况"，不如直接贴一段标准代码：
// 标准service函数模板 export async function getUserInfo(userId: string): Promise<UserInfo> { if (!userId) { throw new AppError('INVALID_USER_ID', '用户ID不能为空'); } const result = await request.get<UserInfo>(`/api/user/${userId}`); if (!result.data) { throw new AppError('USER_NOT_FOUND', '用户不存在'); } return result.data; }Agent看到这段代码，生成新service函数时会自动模仿这个模式，比任何文字描述都管用。
3. Plan Mode的适用边界：什么时候该让Agent先想再做
3.1 Plan Mode解决的核心问题
Plan Mode的本质是让Agent在动手之前先输出一份执行计划，人工确认后再执行。这个机制听起来很美好，但实际用起来有个关键问题：不是所有任务都值得先规划。
我们团队一开始把Plan Mode当默认模式用，结果发现效率反而下降了。原因很简单：改一个按钮文案、加一个字段校验这种任务，Agent直接做只要10秒，走Plan Mode要先输出计划、等人确认、再执行，反而花了2分钟。Plan Mode的价值在于降低不可逆操作的风险，而不是提升所有任务的效率。
3.2 我们总结的Plan Mode触发规则
经过两个月的实践，我们定了一套明确的触发规则，写进了CLAUDE.md：
| 任务类型 | 是否启用Plan Mode | 原因 |
|---|---|---|
| 新增完整功能模块 | 必须启用 | 涉及多文件改动，方向错了返工成本高 |
| 修改数据库schema | 必须启用 | 不可逆操作，需要人工审核 |
| 重构现有逻辑 | 必须启用 | 容易影响其他模块，需要确认影响范围 |
| 修复明确bug | 不启用 | 问题定位清晰，直接修就行 |
| 添加单元测试 | 不启用 | 风险低，错了重跑就行 |
| 修改配置文件 | 视情况 | 涉及构建/部署配置时启用，其他不启用 |
| 调整UI样式 | 不启用 | 可逆，看效果再调 |
这套规则的核心判断标准是：如果Agent做错了，你需不需要花超过5分钟来恢复。需要，就启用Plan Mode；不需要，就直接干。
3.3 Plan Mode执行时的关键细节
启用Plan Mode后，Agent输出的计划质量参差不齐。我们的经验是，在CLAUDE.md中明确要求计划的格式：
执行计划必须包含以下部分： 1. 改动文件清单（完整路径） 2. 每个文件的改动内容概述（不超过3句话） 3. 改动之间的依赖关系 4. 潜在风险点 5. 验证方式这个格式强制Agent把思路理清楚，也方便人工快速判断计划是否合理。我们实际用下来，符合这个格式的计划，人工审核时间平均在30秒左右，比让Agent直接执行然后出问题再返工快得多。
还有一个细节：Plan Mode下Agent有时会过度规划，把一个简单任务拆成十几个步骤。我们的做法是在CLAUDE.md中加一条约束："如果执行计划超过8个步骤，必须重新评估是否可以拆分为多个独立任务"。这条规则有效防止了Agent把简单问题复杂化。
4. Agent编排的实战架构：从单Agent到多Agent协作
4.1 单Agent的能力天花板在哪里
一个Agent加一个CLAUDE.md，能覆盖大概60%的日常开发任务：写新功能、改bug、加测试、重构小模块。但遇到以下场景就会力不从心：
- 需要同时理解前端和后端代码的联调任务
- 需要跨多个仓库协调的改动
- 需要长时间运行、分阶段完成的大型任务
- 需要不同专业视角交叉验证的任务（比如安全审查）
这些场景下，单Agent要么上下文不够用，要么容易在长任务中"跑偏"。我们团队的做法是引入多Agent编排，但不是一上来就搞复杂的框架，而是从最简单的分工开始。
4.2 我们的三Agent基础架构
目前稳定运行的是三个Agent的分工架构：
规划Agent（Planner）：负责接收任务、分析需求、输出执行计划。它不写代码，只做任务拆解和优先级排序。这个Agent的CLAUDE.md重点是项目整体架构和模块依赖关系。
执行Agent（Executor）：负责按照规划Agent输出的计划实际写代码。它的CLAUDE.md重点是代码规范、文件组织、常见任务执行路径。执行Agent不关心"为什么做"，只关心"怎么做"。
审查Agent（Reviewer）：负责检查执行Agent的输出，包括代码规范、潜在bug、安全风险、测试覆盖。它的CLAUDE.md重点是代码审查清单和常见问题模式。
这三个Agent之间通过结构化的消息传递协作。规划Agent输出JSON格式的计划，执行Agent消费计划并输出改动文件列表，审查Agent消费改动列表并输出审查报告。整个链路跑通后，一个中等复杂度的功能开发，人工只需要在规划阶段审核一次、在审查阶段确认一次，中间过程全自动。
4.3 Agent之间不打架的关键：上下文隔离
多Agent协作最容易出的问题是上下文污染。执行Agent如果能看到规划Agent的全部思考过程，可能会被带偏；审查Agent如果能看到执行Agent的"自我解释"，可能会被说服而放过问题。
我们的解决方案是严格的上下文隔离：每个Agent只能看到自己需要的输入，看不到其他Agent的中间过程。规划Agent的输出只有最终计划，没有它的分析过程；执行Agent的输出只有代码改动，没有它的实现思路；审查Agent只看到代码diff，看不到任何解释。
这个设计一开始让我们很不适应，因为人工审查时缺少了"Agent为什么这么改"的说明。但实际跑下来发现，这反而提高了代码质量——因为Agent不能靠"解释"来掩盖问题，只能靠代码本身说话。
提示：上下文隔离的代价是调试变难了。当某个环节出问题时，你需要分别检查每个Agent的输入输出。我们的做法是在每个Agent的输入输出都打上trace ID，方便追溯整条链路。
5. Agent安全边界：那些文档不会告诉你的风险点
5.1 文件系统访问的隐形风险
Agent在本地运行时，默认拥有当前用户的所有文件访问权限。这意味着如果Agent在执行任务时"判断失误"，可能会修改或删除不该动的文件。我们团队真实遇到过的情况：一个Agent在重构时，误判了某个配置文件的作用，直接覆盖了本地开发环境的数据库连接配置，导致整个团队当天无法本地调试。
解决方案不是限制Agent的文件访问（那样它就干不了活了），而是在CLAUDE.md中明确标注敏感文件，并配合Git的pre-commit hook做二次防护。我们在CLAUDE.md中维护一个"禁止修改"清单，包括所有.env文件、CI/CD配置、数据库迁移文件等。同时配置了pre-commit hook，如果Agent的改动涉及这些文件，提交会被拦截并提示人工确认。
5.2 命令执行的安全边界
Agent执行shell命令是另一个高风险点。我们遇到过Agent为了"清理临时文件"执行了rm -rf命令，虽然最终没有造成损失（因为路径判断错了），但这件事让我们意识到必须建立命令白名单机制。
我们的做法是在CLAUDE.md中明确列出允许执行的命令类别：包管理命令（npm/pnpm/yarn）、测试命令、构建命令、Git只读命令。对于其他命令，Agent必须先输出命令内容并等待人工确认。这个机制通过一个简单的wrapper脚本实现，Agent的所有命令执行都经过这个wrapper，白名单外的命令会被拦截。
5.3 网络请求与数据泄露防范
Agent在处理任务时可能需要调用外部API或访问网络资源。这里有两个风险：一是Agent可能把敏感代码或数据发送到外部服务，二是Agent可能被诱导执行恶意请求。
我们的防护措施有三层：第一，在CLAUDE.md中明确禁止Agent将任何项目代码、配置、数据发送到外部服务；第二，在网络层面限制Agent运行环境的出站流量，只允许访问必要的包管理registry和内部服务；第三，定期审计Agent的网络请求日志，发现异常立即排查。
这些措施听起来有点过度，但考虑到Agent的自主性，这些边界是必须的。我个人的经验是：宁可前期多花两天配置安全边界，也不要等出了事再补救。
6. 从零搭建AI Native工作流的完整步骤
6.1 第一周：基础设施与单Agent跑通
第一周的目标不是提效，而是让团队每个人都能熟练使用单Agent完成日常任务。具体步骤：
- 在项目根目录创建CLAUDE.md，按照第2节的结构填写初始版本。不要追求完美，先写你能想到的规则，后续迭代。
- 配置Agent的运行环境，确保它能访问项目代码、执行基本命令、读取CLAUDE.md。
- 选一个低风险任务（比如给现有函数补单元测试），让每个团队成员独立用Agent完成一次，记录遇到的问题。
- 每天下班前花15分钟集体讨论：今天Agent犯了什么错、CLAUDE.md需要补什么规则。
这一周的关键是建立肌肉记忆：让团队成员习惯"先看CLAUDE.md有没有相关规则，再让Agent动手"的工作方式。
6.2 第二到三周：Plan Mode与任务分类
第二周开始引入Plan Mode，但不要全面启用。按照第3节的触发规则，先在高风险任务上试用。具体做法：
- 把第3节的触发规则表写进CLAUDE.md。
- 选三个高风险任务（比如一个新API接口的开发、一次数据库schema变更、一个模块的重构），走完整的Plan Mode流程。
- 每次Plan Mode执行后，记录计划质量和实际执行结果的偏差，调整CLAUDE.md中的计划格式要求。
- 第三周开始，逐步把Plan Mode扩展到中等风险任务，观察效率变化。
这个阶段最容易犯的错误是Plan Mode滥用。记住：Plan Mode是降低风险的工具，不是提升质量的工具。质量靠的是CLAUDE.md中的规则和审查环节。
6.3 第四周起：多Agent编排与持续优化
当单Agent和Plan Mode都跑顺之后，开始引入多Agent架构。我们的建议是从两个Agent开始（规划+执行），跑通后再加审查Agent。具体步骤：
- 定义每个Agent的职责边界和输入输出格式。
- 搭建Agent之间的消息传递机制（简单的文件传递或消息队列都可以）。
- 选一个中等复杂度的功能开发任务，走完整的多Agent流程。
- 记录每个环节的耗时和问题，持续优化Agent的CLAUDE.md和协作协议。
这个阶段的关键是不要追求全自动。我们的多Agent流程至今仍然保留了两个人工审核点（规划后、审查后），这不是技术限制，而是刻意设计。人工审核点的存在，既保证了最终质量，也让团队对Agent的行为保持敏感度。
7. 我们踩过的五个真实坑与修复方案
7.1 CLAUDE.md规则冲突导致Agent行为混乱
现象：Agent有时遵循规则A，有时遵循规则B，行为不一致。
原因：CLAUDE.md中两条规则存在隐含冲突。比如一条说"所有API调用必须通过request.ts封装"，另一条说"紧急修复时可以直接使用fetch"。Agent无法判断什么算"紧急"。
修复：删除所有带主观判断的规则，只保留确定性规则。如果确实需要例外情况，用明确的文件路径或任务类型来限定，而不是用"紧急"、"特殊情况"这类模糊词。
7.2 Agent在长任务中"忘记"早期上下文
现象：一个需要改动10个文件的任务，Agent改到第7个文件时，开始违反前面已经遵循的规则。
原因：Agent的上下文窗口有限，长任务中早期读取的CLAUDE.md内容可能被"挤出"。
修复：把长任务拆分为多个短任务，每个短任务独立读取CLAUDE.md。我们的做法是在CLAUDE.md中加一条规则："如果任务需要改动超过5个文件，必须拆分为多个子任务，每个子任务改动不超过3个文件"。
7.3 审查Agent被"看起来对"的代码骗过
现象：审查Agent放过了有明显逻辑漏洞的代码，因为代码格式规范、命名清晰。
原因：审查Agent的CLAUDE.md中缺少对逻辑正确性的检查要求，只关注了代码风格。
修复：在审查Agent的CLAUDE.md中增加逻辑检查清单，包括边界条件、错误处理、并发安全等。同时要求审查Agent对每个改动文件输出"我检查了哪些方面、发现了什么问题、为什么认为没问题"。
7.4 Agent生成的测试用例"自欺欺人"
现象：Agent生成的单元测试全部通过，但实际代码有bug。
原因：Agent倾向于生成"验证自己写的代码"的测试，而不是"验证需求"的测试。测试用例的断言往往直接复制了代码的逻辑。
修复：在CLAUDE.md中要求测试用例必须先写断言再写实现，且断言必须基于需求文档而非代码逻辑。同时引入"测试审查"环节，由人工抽查测试用例的有效性。
7.5 多Agent协作时的"责任推诿"
现象：执行Agent说规划Agent的计划有问题，规划Agent说执行Agent理解错了，审查Agent说两边都有问题但不说具体哪里有问题。
原因：Agent之间没有明确的责任边界和争议解决机制。
修复：在协作协议中明确：规划Agent对计划的完整性负责，执行Agent对代码的正确性负责，审查Agent对问题的可复现性负责。任何一方发现问题，必须输出具体的、可验证的证据，而不是笼统的"有问题"。
8. 关于AI Native团队建设的一点个人体会
跑了半年多的AI Native工作流，最大的感受是：这套范式的瓶颈不在Agent的能力，而在团队的协作习惯。Agent能写代码、能审查、能规划，但它不能替团队做决策，也不能替团队建立规范。CLAUDE.md写得好不好，本质上反映的是团队对自己开发流程的理解够不够深。
我见过一些团队把AI Native当成"少写代码"的捷径，结果发现Agent生成的代码质量参差不齐，反而增加了Review负担。也见过一些团队把Agent当成"万能工具"，什么任务都丢给它，结果在安全边界上出了大问题。这些问题的根源都是一样的：没有把Agent当成团队的一员来管理。
Agent需要明确的职责边界、清晰的输入输出规范、可追溯的工作记录，这些和管人是一样的。当你用管人的思路来管Agent时，很多问题会自然消解。我们团队现在的新人入职，第一件事不是看代码规范文档，而是读CLAUDE.md——因为那份文件才是团队开发流程的真实映射。
最后分享一个我们最近在试的做法：每周五下午留一个小时，让团队成员各自和Agent"结对"完成一个小任务，然后集体复盘Agent的表现。这个习惯坚持了两个月，CLAUDE.md的质量提升速度比之前快了至少三倍。原因很简单：当每个人都把Agent当成需要持续培养的"队友"时，规则自然会越写越准。
