1. 从“人写代码”到“人管意图”AI Native 团队到底在改什么先说一个我观察到的现象。过去两年很多团队把 Copilot 装进 IDE把聊天窗口挂在侧边栏然后宣布自己“AI 化了”。但真到交付节点节奏还是老样子需求评审两小时写代码三天联调两天测试一天上线前夜通宵改 bug。工具换了流程没换人还是那个瓶颈。AI Native 团队要动的不是工具是软件开发生命周期SDLC的骨架。传统 SDLC 里人负责从需求到代码到验证的全部环节AI 只是加速某一个点AI Native 的 SDLC 里人负责定义意图、设定边界、验收结果AI 负责在边界内自主完成从计划到执行到自检的闭环。这个转变听起来抽象落到具体操作上就是几个非常实在的东西一份写清楚项目约束的CLAUDE.md、一套让 AI 先想再做的 Plan Mode 工作流、一组能并行干活的 Agent 编排、以及一套防止 Agent 跑偏的安全与验收机制。我带的团队从去年开始按这套范式跑最直观的变化是一个中等复杂度的功能模块从“提需求”到“可合并的 PR”人介入的时间从原来的两三天压缩到半天以内而且代码风格一致性反而比纯人工写的时候更好。原因不复杂——AI 不会因为赶进度就偷懒跳过测试也不会因为心情不好就写出风格割裂的代码前提是你把规则喂给它。这篇手册面向的是正在或准备把团队往 AI Native 方向推的技术负责人、一线开发、以及想搞清楚“Agent 到底怎么落地”的工程师。我会把整套流程拆成可复制的步骤包括配置文件怎么写、Plan Mode 怎么用、多 Agent 怎么编排、并发怎么扛、安全怎么兜底。不堆概念只讲我实际跑通过的东西。2. 地基先打好CLAUDE.md 不是 README 的替代品2.1 为什么一份项目约束文件决定了 Agent 的上限很多人第一次用 Agent 写代码上来就丢一句“帮我实现一个用户登录功能”然后看着 Agent 自由发挥最后拿到一堆能跑但完全不符合项目规范的代码再花大量时间改。问题不在 Agent 笨在于你没告诉它这个项目的“家规”。CLAUDE.md这类项目级约束文件本质上是给 Agent 的常驻上下文。它和 README 的区别在于README 是给人看的讲的是“这个项目是什么”CLAUDE.md是给 Agent 看的讲的是“在这个项目里干活必须遵守什么”。前者是介绍后者是纪律。我踩过的第一个坑就是没写这个文件。当时让 Agent 加一个接口它用了项目里根本没引入的 HTTP 库还自作主张改了目录结构。后来我把约束写清楚同样类型的任务Agent 一次就能给出符合规范的代码。这个投入产出比极高——写一份好的约束文件大概花两小时但它能省下后面几十次返工。2.2 一份能用的 CLAUDE.md 应该包含哪些块我不建议照搬网上的模板因为每个项目的技术栈和纪律点都不一样。但结构上这几块是必须有的技术栈与版本锁定明确语言、框架、关键依赖的版本。比如“Node 20 TypeScript 5.4 Fastify 4.x禁止引入 Express”。Agent 在选型时最容易发散锁死版本能避免它用上你根本没装的库。目录结构与职责边界说清楚哪个目录放什么。比如“所有数据库访问必须走src/repo/业务逻辑放src/service/路由层只做参数校验和转发”。这样 Agent 新增文件时不会乱放。代码风格硬规则命名约定、错误处理方式、日志规范。比如“所有异步函数必须用 try/catch 包裹并记录结构化日志禁止裸抛异常”。测试要求什么级别的改动必须配什么级别的测试。比如“新增 service 方法必须配单元测试覆盖率不低于 80%”。禁止事项清单这一块最容易被忽略但最重要。比如“禁止修改migrations/下已存在的文件”“禁止在业务代码里硬编码密钥”“禁止绕过 lint 提交”。我习惯把这份文件控制在 200 行以内。太长了 Agent 反而抓不住重点而且维护成本高。核心原则是每一条规则都对应一个你真实踩过的坑或真实的团队约定不要写正确的废话。2.3 让约束文件“活”起来的维护节奏写完不是终点。我的做法是把它当成活的文档每次 Code Review 发现 Agent 犯了新类型的错误就补一条规则进去。比如有次 Agent 在循环里做数据库查询我就在约束里加了“禁止在循环体内发起 IO 操作批量场景必须用批量接口”。下次它就不会再犯。这里有个反直觉的经验约束文件不是越细越好而是越“可判定”越好。“代码要优雅”这种没法判定Agent 不知道怎么做“函数参数超过 4 个必须用对象传参”就可判定Agent 能严格执行。写规则的时候多问自己一句这条规则能不能用一句话判断对错不能就重写。3. Plan Mode让 Agent 先交方案再动手省下的返工时间远超想象3.1 直接让 Agent 写代码为什么大概率会翻车我做过一个对比实验。同一个需求“给订单模块加一个超时自动取消的功能”两种方式各跑五次。第一种直接下指令“实现订单超时自动取消”。五次里有四次 Agent 直接开始写代码结果分别是有的用了轮询、有的用了定时任务但没考虑分布式重复执行、有的改了订单状态机但没同步更新相关索引。能跑但都需要人再花时间修正。第二种先让 Agent 进入 Plan Mode输出实现方案我确认后再执行。五次里有四次方案是合理的唯一一次偏差是它没考虑时区问题我在方案阶段就指出来了改起来只是改几行文字。差距在哪代码是方案的下游方案错了代码写得再快也是白写。Plan Mode 的价值就是把纠错点前移到成本最低的阶段。改一行方案文字的成本和改一堆已经写好的代码的成本差着数量级。3.2 Plan Mode 的实操流程与确认清单具体怎么用我的标准流程是这样的下需求时明确要求先出计划。指令里带上“先不要写代码输出实现计划包括涉及的文件、改动点、潜在风险”。Agent 输出计划后逐项核对。我有一份固定的确认清单涉及的文件是否都在预期目录内有没有引入约束文件里禁止的依赖边界情况空值、并发、超时有没有覆盖测试计划是否包含有没有需要人工决策的取舍点确认或修正后再让 Agent 执行。执行阶段我通常不再干预除非它偏离了确认过的计划。这里有个技巧让 Agent 在计划里显式列出“我不确定的地方”。比如它会写“关于超时时间的配置来源我假设从环境变量读取如果不对请指出”。这种显式的不确定性标注能让你快速定位需要人工决策的点而不是等代码写完才发现假设错了。3.3 什么任务值得走 Plan Mode什么任务可以直接干不是所有任务都值得走完整计划流程。我的判断标准很简单任务类型是否走 Plan Mode理由新增完整功能模块必须涉及多文件、多决策点方案错了返工成本高修改核心业务逻辑必须容易影响下游需要先评估影响面修复明确的 bug可选如果根因清楚直接修更快改文案、调样式不需要改动局部直接干重构必须重构最怕方向错方案阶段必须对齐我一般的做法是凡是改动超过三个文件或者涉及状态变更、数据迁移、并发处理的一律先走 Plan Mode。其他情况灵活处理。这个阈值可以根据团队熟练度调整但核心逻辑不变——纠错越早越便宜。4. Agent 编排单打独斗和团队作战的边界在哪4.1 一个 Agent 干到底什么时候会力不从心单个 Agent 处理一个完整功能在中等复杂度下是够用的。但遇到这几种情况就会明显吃力任务跨度大比如“设计数据库表 写后端接口 写前端页面 配部署脚本”一个 Agent 在长上下文里容易丢失早期决策导致前后不一致。需要并行多个独立子任务本来可以同时推进单 Agent 只能串行。需要不同专长前端 Agent 和后端 Agent 关注点不同用同一套上下文反而互相干扰。我遇到过一次典型翻车让一个 Agent 同时改后端接口和前端调用结果它改了后端字段名但忘了同步前端联调时才发现。这不是 Agent 能力问题是任务编排问题。4.2 多 Agent 分工的三种常见模式根据我的实践多 Agent 编排主要有三种模式各有适用场景模式一流水线式。Agent A 出方案Agent B 按方案写代码Agent C 做代码审查。适合对质量要求高、需要多重校验的场景。缺点是链路长每个环节都要传递上下文。模式二并行分工式。把大任务拆成互不依赖的子任务多个 Agent 同时干。比如前端 Agent 和后端 Agent 按约定好的接口契约各自实现。适合模块化清晰的项目。关键是接口契约必须先定死否则并行出来的东西对不上。模式三主从式。一个 Orchestrator Agent 负责拆解任务和汇总结果多个 Worker Agent 负责执行。适合任务边界不太清晰、需要动态调整的场景。这种模式对 Orchestrator 的规划能力要求高。我团队目前主力用的是模式二因为大部分功能模块的前后端边界是清楚的。模式一用在核心模块上模式三还在小范围试验。4.3 编排中最容易出问题的三个衔接点多 Agent 协作问题几乎都出在衔接处。我总结的三个高频坑第一个坑上下文传递丢失。Agent A 做的决策Agent B 不知道。解决办法是把关键决策显式写进共享的上下文文件而不是依赖对话历史传递。比如接口契约写成一份api-contract.md所有 Agent 都读它。第二个坑职责重叠。两个 Agent 都以为对方会处理某个边界情况结果都没处理。解决办法是在任务拆解时明确“谁不负责什么”边界写清楚。第三个坑结果冲突。两个 Agent 改了同一个文件合并时冲突。解决办法是按文件或目录划分职责范围尽量避免多个 Agent 碰同一片区域。提示多 Agent 不是越多越好。我见过有团队为了“显得先进”上了五六个 Agent结果协调成本比省下的时间还多。两个 Agent 能搞定的事不要上三个。5. 并发与稳定性Agent 跑起来之后才真正开始的问题5.1 Agent 任务并发时资源竞争怎么处理当多个 Agent 同时干活最先撞上的就是资源竞争。最常见的是文件锁冲突和外部服务限流。文件层面如果两个 Agent 同时改同一个文件后写的会覆盖先写的。我的做法是在任务分配阶段就做文件级隔离一个文件同一时间只允许一个 Agent 操作。如果确实需要多人改同一文件就串行化或者拆成不同的文件再合并。外部服务层面比如多个 Agent 同时调数据库或第三方 API容易触发限流。解决办法是给 Agent 的调用加统一的速率控制或者让它们走同一个代理层由代理层统一排队。这个和传统后端的限流思路是一样的只是调用方从人变成了 Agent。5.2 长任务中断了怎么办断点续跑的设计Agent 跑长任务中途因为网络、超时、上下文超限中断是家常便饭。如果每次都从头再来成本很高。我的做法是让 Agent 把进度写到文件里。比如每完成一个子任务就往progress.md里追加一条记录包含已完成的部分和下一步要做什么。中断后重新启动先读这个文件从断点继续。这个机制听起来简单但效果很好。我有个重构任务Agent 跑了四十多分钟中断了三次靠进度文件每次都从断点续上最终完整跑完。如果没有这个机制三次重跑的时间成本会让人崩溃。5.3 怎么判断 Agent 是真的卡住了还是在正常思考这个判断很关键因为误判会导致你过早干预或过晚发现异常。我的经验是看输出节奏正常思考输出是断续的有工具调用、有中间结果、有阶段性文字。真卡住长时间没有任何输出或者反复调用同一个工具、反复读同一个文件。遇到后者不要干等。我的处理方式是先中断让它汇报当前状态和卡点再决定是调整任务还是换方案。干等十分钟和主动中断问一句后者效率高得多。6. 安全兜底Agent 能自主到什么程度红线在哪6.1 Agent 权限分级哪些操作必须人工确认Agent 自主性越高风险越大。我按操作的危险程度做了分级操作类型自主级别说明读文件、搜索代码完全自主无副作用写业务代码、加测试完全自主有版本控制兜底改配置文件需确认可能影响运行环境执行数据库变更需确认不可逆操作删除文件、改权限需确认高风险部署、发布禁止自主必须人工执行这个分级不是拍脑袋定的是踩坑踩出来的。有次 Agent 自作主张改了一个环境配置导致本地跑得好好的服务在测试环境起不来排查了半天。从那以后配置文件改动一律要人工过目。6.2 防止 Agent 跑偏的几道防线除了权限分级我还会设几道防线第一道约束文件里的禁止清单。前面提过把明确不能做的事写进去。第二道改动范围限制。给 Agent 划定它能碰的目录范围范围外的文件它无权修改。这个在工具层面可以配置。第三道提交前审查。Agent 的产出不直接合并必须经过人工或审查 Agent 过一遍。我团队的做法是所有 Agent 产出的 PR 都必须有人 review哪怕只是快速扫一眼。第四道可回滚。所有改动走版本控制出问题能一键回退。这是最后的保险。6.3 敏感信息处理别让 Agent 碰到不该碰的Agent 在自主工作时可能会读到包含密钥、凭证、用户数据的文件。我的处理原则是敏感信息不放在代码仓库里用环境变量或密钥管理服务Agent 读不到。给 Agent 的工作目录做隔离只挂载它需要的那部分代码。在约束文件里明确禁止 Agent 读取或输出任何凭证类内容。这几条不是杞人忧天。Agent 的输出可能被记录、被传递一旦敏感信息进了它的上下文就有泄露风险。把敏感信息从源头隔离掉比事后补救靠谱得多。7. 从零搭一套 AI Native 工作流的落地顺序7.1 第一周该做什么最小可用闭环不要一上来就搞全套。我的建议是第一周只做一件事把 CLAUDE.md 写好然后让 Agent 完成一个小功能走一遍 Plan Mode 流程。具体步骤花两小时写约束文件覆盖技术栈、目录结构、代码风格、测试要求、禁止事项。挑一个边界清晰的小需求让 Agent 先出计划。你确认计划Agent 执行。你 review 产出把发现的问题补进约束文件。这一周的目标不是提效是跑通流程、建立信任、积累约束。跑完这一轮你就知道这套东西在你们项目里大概是什么手感了。7.2 第二到四周把编排和并发加进来流程跑顺之后开始加复杂度引入多 Agent 分工先从两个 Agent 的前后端并行开始。加上进度文件机制让长任务能断点续跑。建立权限分级把高风险操作拦下来。开始积累“踩坑记录”把每次 Agent 犯的错变成约束文件里的新规则。这个阶段的关键是不要贪快。每加一个机制先在小范围验证稳定了再推广。我见过团队一次性把所有机制全上结果出了问题不知道是哪个环节的锅。7.3 稳定期怎么衡量这套流程到底有没有用跑了一两个月之后需要一些指标来判断效果。我关注的几个人介入时间占比一个功能从下需求到可合并人实际花的时间占比。健康值应该在 30% 以下。一次通过率Agent 产出不需要返工直接通过 review 的比例。这个指标反映约束文件的质量。返工原因分布返工是因为方案错、代码错还是规范错。方案错多说明 Plan Mode 没用好规范错多说明约束文件要补。这些指标不用搞得很复杂手工记几周就能看出趋势。关键是用数据驱动约束文件的迭代而不是凭感觉。8. 一些踩过坑之后才明白的事最后分享几条我在实际推行这套范式时踩过坑才想明白的经验。第一条Agent 的能力上限取决于你给它的上下文质量而不是模型本身。同一个模型喂了清晰约束和没喂产出质量差一大截。与其追新模型不如先把约束文件打磨好。第二条Plan Mode 的确认环节不能省但也不能过度。我一开始每个计划都逐字看效率很低。后来改成只看关键决策点——涉及数据变更、并发、外部依赖的部分重点看纯代码组织方式的部分快速扫过。找到适合自己的粒度很重要。第三条多 Agent 的协调成本是真实存在的。两个 Agent 协作沟通成本不是零是实打实的上下文传递和结果合并开销。只有当任务本身足够大、并行收益能覆盖协调成本时多 Agent 才划算。第四条安全机制要在流程设计阶段就考虑不能事后补。我最初没做权限分级Agent 改了一个不该改的配置排查花了很久。后来把权限分级加进流程这类问题再没出现过。安全不是限制效率是保护效率不被打断。第五条这套东西的收益是复利的。约束文件越写越全Agent 犯的错越来越少人介入的时间越来越短。前期投入的两三周看起来慢但三个月后回头看整个团队的交付节奏完全不一样了。