1. 从人写代码到人管意图AI Native 团队到底在变什么很多团队嘴上喊着 AI Native实际干的事还是老一套产品经理写 PRD开发照着文档敲代码测试等提测运维等上线。区别无非是 IDE 里多了个补全插件或者偶尔让模型帮忙写个正则。这不叫 AI Native这叫AI 辅助的传统开发。真正的 AI Native 团队变化发生在更底层的地方——交付单元从代码变成了意图 约束 验证。人不再逐行生产实现而是负责把需求拆成 Agent 能执行的原子任务、把团队规范固化成机器可读的上下文、把验收标准写成可自动跑的检查。代码只是 Agent 执行完之后的副产物。这个转变带来的连锁反应比想象中大得多。传统 SDLC 里需求、设计、编码、测试、部署是五个串行阶段每个阶段有明确的人为交接点。AI Native 的 SDLC 里这五个阶段被压缩成一个意图循环人定义目标 → Agent 规划 → Agent 执行 → 自动验证 → 人审查关键决策 → 回流修正。交接点从人给人交文档变成人给 Agent 交上下文Agent 给人交证据。我见过太多团队卡在中间态买了最好的模型配了最贵的算力结果 Agent 跑出来的东西没人敢合。根因不是模型不行是上下文没喂对、边界没划清、验证没自动化。这三件事没解决模型再强也只是个高级自动补全。所以这份手册不讲怎么调 API讲的是怎么把一支真实团队改造成 AI Native 的运转方式。适合三类人看正在推动团队转型的技术负责人、想搞清楚 Agent 工程化落地细节的一线开发、以及被AI 提效口号搞得很焦虑但不知道从哪下手的中小团队主程。下面按落地顺序拆开讲每一步都给可复现的做法和踩过的坑。2. 上下文工程CLAUDE.md 这类文件为什么是团队资产而不是配置文件2.1 上下文文件解决的是隐性知识无法传递问题传统团队里新人上手靠的是跟着老员工看两周。代码规范、目录约定、哪些模块不能动、提交信息怎么写、测试跑哪个命令——这些知识散落在老员工脑子里靠口口相传。人多了之后传递效率断崖式下跌同一个坑不同的人踩三遍。Agent 比新人更惨它没有看两周的机会每次对话都是从零开始。你不在上下文里告诉它这个项目的 service 层不允许直接调 mapper它就会按训练数据里的通用模式给你写一个跨层调用。你不在上下文里告诉它测试必须用 testcontainers 起真实数据库不许 mock它就会给你写一堆 mock 到失真的单测。所以CLAUDE.md或者AGENTS.md、.cursorrules、copilot-instructions.md本质是一回事不是给 AI 看的配置文件而是团队隐性知识的显性化载体。它把过去只存在于老员工脑子里的约定变成了版本可控、可 review、可迭代的团队资产。2.2 一份能用的上下文文件该写什么我试过很多版本最后稳定下来的结构是四块缺一块 Agent 就会在对应场景翻车第一块项目地图。用不超过 20 行说清楚这个仓库是干什么的、核心模块有哪些、每个模块的职责边界。不要贴目录树目录树 Agent 自己能扫。要写的是为什么这么分比如order模块只负责订单状态机所有支付相关逻辑在payment模块两者通过事件解耦不要在 order 里直接调 payment 的 service。第二块硬性约束。这是最容易被忽略但最值钱的部分。列出那些违反了就会出事的规则禁止直接操作生产数据库、禁止在循环里发 HTTP 请求、所有对外接口必须带幂等键、日志里禁止打印用户手机号。每条约束后面最好跟一句为什么Agent 理解了原因之后在边界情况下更容易做出正确判断。第三块常用命令。构建、测试、lint、本地起服务、跑单个测试用例的命令全部列出来。Agent 不需要猜直接抄。这一块能省掉大量Agent 跑了个不存在的命令然后卡住的无效轮次。第四块验证标准。明确告诉 Agent什么算做完。比如改完代码必须跑make test-unit全绿才算完成新增接口必须补 integration test覆盖率不低于 80%涉及数据库变更必须同时提供 up 和 down 迁移脚本。没有这一块Agent 会以代码写完了为完成标准而不是代码通过验证了。2.3 上下文文件的维护节奏一个常见的误区是把上下文文件当成一次性配置写完就不管了。实际上它应该跟着项目一起演进。我的做法是每次 Agent 犯了一个本可以避免的错误就往上下文文件里补一条规则。比如 Agent 第三次在测试里用了真实的外部 API 调用那就加一条所有外部依赖必须 mock 或使用本地 stub。这样积累两三个月上下文文件会变成团队最有价值的文档——因为它不是写给领导看的是写给会真的照着执行的 Agent 看的每一条都是被真实问题验证过的。注意上下文文件不要写太长。超过 500 行之后Agent 对后半部分的注意力会明显下降。如果规则太多拆成多个文件按场景加载比如CLAUDE.md放通用规则CLAUDE.frontend.md放前端专属规则。3. Plan Mode为什么先让 Agent 说清楚要干什么能省掉一半返工3.1 直接让 Agent 写代码的代价大部分人用 Agent 的方式是描述需求 → 等它输出代码 → 发现不对 → 重新描述 → 再等。这个循环里最贵的不是模型调用费用是你的审查时间。Agent 三十秒生成两百行代码你花二十分钟看懂它干了什么、发现方向错了、推翻重来。来回三次一下午没了。Plan Mode 的核心思路很简单在 Agent 动手之前先让它输出一份执行计划你审计划而不是审代码。计划通常只有十几行审查成本极低但能拦住 80% 的方向性错误。3.2 一份合格的执行计划长什么样我要求 Agent 输出的计划必须包含五个要素缺一个就打回目标复述用一句话说清楚它理解的任务是什么。这一步能立刻暴露理解偏差。影响范围列出它打算改哪些文件、新增哪些文件、删除哪些文件。看到删除两个字就要警惕。执行步骤按顺序列出它打算怎么做每步一句话。步骤超过 8 步通常意味着任务拆得不够细。验证方式它打算怎么证明自己做对了。跑哪些测试、检查哪些输出。风险点它认为这个改动可能影响哪些现有功能。举个真实例子。我让 Agent 给订单查询接口加一个按创建时间倒序的参数。它给的初版计划里影响范围包含修改OrderMapper.xml的查询语句。我一看就拦住了——这个项目的查询走的是 MyBatis-Plus 的 Wrapper改 XML 说明它没理解项目的查询层约定。如果直接让它写代码它会写出一段能跑但不符合项目规范的实现code review 时又得返工。3.3 Plan Mode 的适用边界不是所有任务都值得走 Plan Mode。我的经验是任务类型是否走 Plan Mode原因单文件小改动改个常量、修个 typo否计划成本高于执行成本跨模块功能开发是方向错了返工代价大重构类任务是影响范围需要提前确认排查线上问题是需要先确认排查思路再动手写测试用例视情况简单场景直接写复杂场景先列用例清单数据库迁移强制不可逆操作必须审计划关键判断标准是如果 Agent 做错了你推翻重来的成本有多高。成本高就走 Plan Mode成本低就直接干。3.4 把 Plan Mode 变成团队习惯个人用 Plan Mode 是技巧团队用 Plan Mode 是流程。我们的做法是在 code review 流程里加一道计划审查Agent 生成的计划先贴到 PR 描述里由提出需求的人确认方向确认后再让 Agent 执行。这样做的额外好处是PR 里留下了为什么这么改的完整推理链三个月后回头看还能看懂当时的决策逻辑。提示Plan Mode 下 Agent 有时会给出过于笼统的计划比如修改相关文件以支持新功能。遇到这种就打回要求它具体到文件名和函数名。笼统的计划等于没有计划。4. Agent 编排单 Agent 扛不住的时候怎么拆4.1 什么时候该从单 Agent 升级到多 Agent单 Agent 能处理的任务有明确上限。当任务满足以下任一条件时就该考虑拆成多 Agent任务需要不同领域的专业知识比如一个任务既要改后端接口又要改前端调用还要更新文档。单 Agent 在切换领域时容易把不同领域的约定搞混。任务上下文超出单次窗口需要读取的文件太多塞不进一个上下文。硬塞的结果是 Agent 对中间部分的文件视而不见。任务需要并行推进比如同时改三个独立模块串行做太慢。任务需要交叉验证一个 Agent 写另一个 Agent 审比同一个 Agent 自审靠谱得多。4.2 三种常见的编排模式模式一流水线式。Agent A 负责规划Agent B 负责实现Agent C 负责验证。每个 Agent 只干一件事上下文干净。适合流程固定的任务比如根据 issue 生成 PR。缺点是 Agent 之间的交接需要显式传递上下文传丢了就断链。模式二主管-工人式。一个主管 Agent 负责拆任务和汇总多个工人 Agent 并行执行子任务。适合可以并行的大任务比如给十个接口补测试。主管 Agent 的关键职责是任务边界划分——划分得不好两个工人改同一个文件就会冲突。模式三对抗式。一个 Agent 写一个 Agent 专门挑毛病。挑毛病的 Agent 的 prompt 里明确写你的任务是找出实现中的问题不要客气。这种模式在安全敏感、逻辑复杂的场景下特别有效因为写代码的 Agent 有确认偏误倾向于认为自己写的是对的。4.3 编排的工程化落地多 Agent 编排听起来很美好落地时最容易翻车的地方是状态管理。Agent A 改了文件Agent B 读到的还是旧版本Agent C 的验证结果没有回传给 Agent A。这些在 demo 里看不出来一上真实项目就暴露。我的做法是给每个 Agent 配一个共享的工作区状态用最简单的文件系统实现每个 Agent 执行完把自己的产出写到约定的目录下一个 Agent 从目录读。不要一上来就上消息队列、状态机这些重家伙文件系统在中小规模下足够用而且可调试——出问题时直接看目录里有什么。另一个坑是错误传播。Agent A 的输出有错Agent B 基于错误输入继续干错误被放大。解决办法是在每个 Agent 的输入处加一道校验Agent B 开始工作前先检查 Agent A 的产出是否符合预期格式和基本正确性不符合就拒绝执行并报错而不是硬着头皮往下做。注意多 Agent 不是越多越好。我见过一个团队把任务拆成七个 Agent结果调试编排逻辑的时间比直接干活还长。经验值是能用两个 Agent 解决的就别用三个编排复杂度是随 Agent 数量非线性增长的。5. 验证自动化Agent 说做完了之后你怎么知道它真做完了5.1 Agent 的完成和你的完成不是一回事Agent 判断任务完成的依据是我该输出的东西都输出了你判断任务完成的依据是功能真的能跑、没破坏别的东西、符合规范。这两个标准之间的差距就是所有返工的来源。所以 AI Native 团队必须把完成的定义从主观判断变成客观检查。做法是每类任务都配一套自动验证脚本Agent 执行完必须跑通脚本才算完成。脚本跑不过Agent 自己修修到跑通为止。5.2 分层验证的设计验证不能只有一层。我的经验是分三层每层的检查成本和覆盖范围不同第一层静态检查。lint、类型检查、格式检查。这层最快几秒钟出结果能拦住大部分低级错误。Agent 每次改完代码都应该自动跑。第二层单元测试和集成测试。这层验证逻辑正确性。关键是测试要真的能发现问题——如果测试全是 mockAgent 改错了 mock 的期望值就能让测试通过那这层验证就是摆设。所以集成测试必须覆盖核心路径用真实依赖testcontainers 起真实数据库、wiremock 模拟外部服务。第三层端到端验证。起真实服务跑真实请求检查真实响应。这层最慢但最接近真实。不是每个任务都需要但涉及接口变更、数据库变更、配置变更的任务必须跑。5.3 让 Agent 自己修验证失败验证脚本跑失败之后不要人工介入先把失败信息喂回给 Agent让它自己修。这一步能解决 70% 的问题。Agent 修不动的通常是两类一是环境问题依赖没装、端口被占二是需求本身有歧义Agent 不知道该往哪个方向修。对于第二类人工介入时要给的是决策而不是指令。比如不要说你把那个判断改成大于等于而要说这个场景下应该允许等于的情况因为业务上 X 和 Y 是等价的。给决策能让 Agent 理解意图下次遇到类似情况能自己判断给指令只能解决这一次。5.4 验证脚本本身也要维护一个容易被忽略的点验证脚本会随着项目演进失效。比如接口签名改了集成测试没跟着改跑起来就报错。这时候 Agent 会陷入修代码让测试通过还是修测试让代码通过的困惑。我的做法是验证脚本的修改必须和业务代码的修改在同一个 PR 里而且验证脚本的修改要单独标注出来code review 时重点看。防止 Agent 为了让测试通过而偷偷放宽测试标准——这种事它干得出来。6. 并发与安全Agent 跑起来之后才会暴露的那些问题6.1 Agent 并发执行时的资源冲突当多个 Agent 并行工作时最先撞上的问题是文件冲突。两个 Agent 同时改同一个文件后写的覆盖先写的而且没有任何报错。这个问题在串行执行时不存在一旦并行就必然出现。解决办法有两层。第一层是任务划分时保证文件不重叠主管 Agent 拆任务时检查每个子任务涉及的文件列表有重叠的就合并成一个任务或者串行执行。第二层是文件锁Agent 开始改文件前先申请锁改完释放。文件锁用最简单的.lock文件实现就行不需要上分布式锁。另一个并发问题是共享资源竞争多个 Agent 同时跑测试抢同一个测试数据库、同一个端口。解决办法是给每个 Agent 分配独立的资源命名空间比如测试数据库按 Agent ID 加后缀端口从固定范围里分配。6.2 Agent 的安全边界Agent 能执行命令、能读写文件、能发网络请求这意味着它的权限边界必须明确。我见过最危险的情况是 Agent 拿到了生产环境的凭证然后顺手跑了个数据库迁移。安全边界的设计原则是最小权限 显式授权Agent 默认只能访问项目目录不能访问用户主目录、系统目录。Agent 默认只能读写操作需要显式开启。涉及外部网络的请求走白名单不在白名单里的域名直接拒绝。生产环境凭证绝对不放进 Agent 能读到的任何文件里。危险操作删除文件、执行迁移、推送代码需要人工确认不能自动执行。这些限制听起来很繁琐但比起 Agent 误删生产数据的代价这点繁琐不算什么。6.3 敏感信息的处理Agent 的上下文里很容易混入敏感信息日志里的用户数据、配置文件里的密钥、测试数据里的真实手机号。这些信息一旦进入 Agent 的上下文就可能被写进代码、写进注释、写进提交信息。处理办法是在 Agent 的输入输出两端都加过滤。输入端喂给 Agent 的文件先过一遍脱敏密钥替换成占位符。输出端Agent 生成的代码在提交前扫一遍命中敏感信息模式就拦截。这个过滤不用做得很复杂正则匹配常见的密钥格式、手机号格式、身份证格式就够了。提示不要指望 Agent 自己记住不要泄露敏感信息。上下文里出现过的东西它就可能在任何地方复现。安全必须靠工程手段保证不能靠 prompt 约束。7. 团队协作模式的调整AI Native 之后人的角色怎么变7.1 从写代码的人到定义问题的人AI Native 团队里最稀缺的能力不是写代码是把模糊需求拆成 Agent 能执行的精确任务。这个能力要求你既懂业务又懂技术还得懂 Agent 的能力边界——知道什么任务它能做好什么任务它一定会翻车。举个具体例子。优化一下订单查询性能这种需求直接丢给 Agent 它会给你加缓存、加索引、改查询语句一通操作下来可能更快也可能更慢。正确的做法是拆成先让 Agent 分析慢查询日志找出 top 3 慢查询再针对每个慢查询分析执行计划再根据分析结果决定是加索引还是改查询。每一步都有明确的输入输出和验证标准。7.2 Code Review 的重点转移传统 code review 看的是代码写得对不对、好不好。AI Native 团队的 code review 看的是三件事第一意图对不对。Agent 实现的是不是你真的想要的东西。这个必须人来看Agent 自己判断不了。第二边界处理对不对。Agent 在正常路径上通常没问题问题都出在边界情况空输入、超长输入、并发冲突、网络超时。review 时重点看这些。第三有没有引入意外依赖。Agent 有时会为了解决问题引入一个新库而这个库可能和项目现有依赖冲突或者有安全漏洞。review 时检查依赖变更。代码风格、命名规范这些交给 lint 和格式化工具不要浪费人的时间。7.3 知识沉淀方式的变化传统团队的知识沉淀靠文档和口口相传。AI Native 团队的知识沉淀有三个新载体上下文文件团队约定和项目知识的机器可读版本。验证脚本什么算做对了的可执行定义。Agent 执行日志Agent 踩过的坑、走过的弯路都是宝贵的经验数据。第三点特别值得说。Agent 的执行日志里藏着大量这个项目特有的坑比如这个模块的测试必须按特定顺序跑这个接口在测试环境有速率限制。把这些从日志里提炼出来补进上下文文件团队的 Agent 就会越用越顺手。8. 落地节奏别想着一步到位8.1 从单点任务开始我见过太多团队一上来就想搞全流程 AI Native结果三个月过去还在调流程一个功能都没交付。正确的节奏是从单点任务开始跑通了再扩展。第一个月选一个边界清晰、验证标准明确的任务类型比如根据 issue 补单元测试或者修复 lint 报错。让 Agent 在这个任务类型上跑到稳定团队熟悉了 Agent 的工作方式和审查节奏。第二个月扩展到相邻任务类型比如从补测试扩展到补测试 修测试发现的 bug。同时开始积累上下文文件。第三个月开始尝试跨模块的功能开发引入 Plan Mode 和多 Agent 编排。这个节奏看起来慢但每一步都建立在上一部跑通的基础上不会出现流程搭好了但没人用的情况。8.2 度量什么AI Native 转型的度量指标不要用AI 生成了多少行代码这种虚荣指标。真正有意义的指标是从需求到合并的周期时间这是最终指标反映整体效率。返工率Agent 产出被推翻重做的比例。这个指标高说明上下文或验证有问题。人工介入次数每个任务平均需要人介入几次。这个指标应该随着上下文积累而下降。验证通过率Agent 第一次跑验证就通过的比例。这个指标反映 Agent 对项目规范的理解程度。这些指标不需要搞复杂的埋点从 git 记录和 CI 日志里就能算出来。8.3 常见的失败模式最后说几个我见过或踩过的失败模式帮你提前避开失败模式一上下文文件写成百科全书。什么都往里塞结果 Agent 抓不住重点。上下文文件要精不要全。失败模式二验证全靠人。Agent 说做完了人去看看完说不对Agent 再改。这个循环里人成了瓶颈效率还不如自己写。验证必须自动化。失败模式三Agent 权限放太开。图省事给 Agent 开了所有权限结果它顺手改了不该改的东西。权限要一点点放放之前先想清楚最坏情况。失败模式四不记录 Agent 的坑。同一个坑踩十遍每次都要人重新解释。Agent 犯的错要沉淀到上下文文件里让它下次不再犯。失败模式五追求全自动。想着人完全不用管结果 Agent 跑偏了没人发现最后交付的东西完全不能用。AI Native 不是无人化是把人的精力从执行转移到定义和审查上。我在实际推动团队转型的过程中最大的体会是AI Native 的瓶颈从来不在模型能力在团队的工程成熟度。上下文管理、验证自动化、权限控制、任务拆分这些全是传统软件工程里就有的东西只是 AI Native 把它们的重要性放大了十倍。工程底子好的团队转型会非常顺工程底子差的团队上了 AI 之后只是把混乱加速了。所以如果你正准备推动这件事先把工程基础打牢比追最新的模型和框架重要得多。