1. 从“人写代码”到“人管意图”AI Native 团队到底在做什么过去两年我参与过三个不同规模的团队从传统研发模式向 AI Native 模式迁移的过程。最直观的感受是大多数团队一开始都把这件事想简单了——以为给每个人配一个 AI 编程助手就算完成了转型。结果三个月后复盘代码产出量确实上去了但返工率、评审耗时、线上事故率也跟着上去了。问题出在哪儿出在我们只换了工具没换流程更没换协作方式。AI Native 团队的核心不是“用 AI 写代码”而是把 AI 当作团队里的一等公民来编排。传统 SDLC软件开发生命周期里需求、设计、编码、测试、部署是一条线性流水线每个环节由人交接。而在 AI Native 范式下这条流水线变成了一个以意图为中心、以 Agent 为执行单元、以上下文文件为契约的网状结构。人负责定义“要什么”和“不要什么”Agent 负责在约束内自主完成“怎么做”。这里有个关键概念需要先厘清Agent 不是更聪明的代码补全。代码补全是你写一行它猜下一行主动权在你手里Agent 是你给它一个目标和一个工作目录它自己规划步骤、读写文件、运行命令、验证结果主动权在它手里你只在关键节点做审批。这个区别决定了整个团队的工作方式必须重构。我见过最典型的失败案例是一个二十人的后端团队每人装了 AI 助手但代码评审流程没变、分支策略没变、文档规范没变。结果 Agent 生成的代码风格五花八门评审者要花更多时间去理解“这段代码为什么这么写”而不是审查逻辑本身。后来他们做了一件事扭转了局面建立统一的上下文契约文件也就是后面要重点讲的CLAUDE.md这类项目级指令文件。所有 Agent 在动手之前必须先读这个文件里面写清楚了技术栈、目录约定、命名规范、禁止事项、测试要求。这一招下去评审耗时直接降了四成。所以这篇手册要解决的问题很具体一个团队决定认真做 AI Native 转型从零开始需要哪些文件、哪些流程、哪些角色、哪些坑要提前避开。我会按“先立规矩、再跑流程、后做编排、最后谈规模化”的顺序展开每一部分都给出可以直接抄的模板和配置。2. 上下文契约CLAUDE.md 为什么是整个体系的基石2.1 没有契约文件Agent 就是在盲人摸象很多人第一次用 Agent 做项目级任务时会直接甩一句“帮我实现用户登录功能”。Agent 确实会动手但它不知道你的项目用的是哪种认证方案、密码哈希用的是什么库、错误码怎么定义、日志格式是什么。它只能按训练数据里最常见的做法来猜。猜对了是运气猜错了就是返工。CLAUDE.md不同平台可能叫AGENTS.md、.cursorrules或类似名字本质相同的作用就是把团队的隐性知识显性化变成 Agent 每次启动都能读到的硬约束。它不是给人看的文档是给 Agent 看的指令集。这个定位很重要——给人看的文档可以模糊、可以靠上下文补全给 Agent 看的必须精确、必须可执行。我建议这个文件放在项目根目录并且纳入版本控制。每次团队约定发生变化就更新它让所有 Agent 的行为同步演进。2.2 一份能直接用的 CLAUDE.md 骨架下面这份骨架是我在多个项目里迭代出来的你可以根据实际情况增删# 项目上下文契约 ## 技术栈 - 语言TypeScript 5.x严格模式 - 框架Next.js 14 App Router - 数据库PostgreSQL 16 Prisma ORM - 测试Vitest Playwright - 包管理pnpm禁止使用 npm/yarn ## 目录约定 - src/app/ 路由与页面 - src/lib/ 纯函数与工具 - src/server/ 服务端逻辑禁止在此目录外直接访问数据库 - tests/ 测试文件命名 *.test.ts ## 编码规范 - 所有导出函数必须有 JSDoc 注释说明参数与返回值 - 禁止使用 any必要时用 unknown 类型守卫 - 错误处理统一使用 ResultT, E 模式禁止裸抛异常 - 日志使用 src/lib/logger.ts禁止 console.log ## 禁止事项 - 禁止修改 prisma/schema.prisma 而不生成迁移文件 - 禁止在客户端组件中导入 src/server/ 下的任何模块 - 禁止提交包含 TODO 的代码到主分支 ## 验证要求 - 每次修改后必须运行 pnpm test 和 pnpm lint - 新增功能必须附带至少一个测试用例 - 提交前必须通过 pnpm typecheck这份文件看起来朴素但威力在于它把“评审时才发现的问题”提前到了“生成时就避免”。我实测过一个对比同一批任务有契约文件的 Agent 产出首次评审通过率比没有的高出约 55%。2.3 契约文件的维护节奏与常见误区契约文件不是写完就完事了。我的经验是每周复盘时花十分钟过一遍看看这周有没有出现“Agent 反复犯同一个错”的情况如果有就把它写进禁止事项。比如有段时间我们的 Agent 总喜欢在 React 组件里直接写fetch后来加了一条“所有数据请求必须通过src/lib/api-client.ts”问题就消失了。常见的误区有三个。第一是写得太笼统比如“代码要整洁”“命名要规范”这种话 Agent 没法执行等于没写。第二是写得太长超过两百行之后 Agent 的注意力会分散关键约束反而被忽略建议控制在 100 到 150 行。第三是只写不更新团队约定变了文件没变Agent 就会按旧规矩办事比没有契约还糟糕。3. Plan Mode让 Agent 先想清楚再动手3.1 为什么“直接干”在项目级任务里必然翻车单文件的小修改Agent 直接动手没问题。但一旦涉及多个文件、多个模块的联动改动直接动手几乎必然出问题。原因很简单Agent 在生成第一个文件时还没看到后面文件的全貌它做的决策是基于局部信息的。等它写到第三个文件发现和前两个冲突时要么硬着头皮打补丁要么推倒重来。Plan Mode 的核心思想是把“规划”和“执行”拆成两个独立阶段。在规划阶段Agent 只读不写它的任务是扫描相关文件、理解现有结构、列出改动清单、识别潜在冲突、给出执行顺序。人在这时候介入审批或调整计划。计划确认后再进入执行阶段Agent 按计划逐步落地。这个模式和传统开发里的“先设计后编码”是一个道理只不过设计者从人变成了 Agent人的角色变成了审批者。3.2 Plan Mode 的实操流程与提示词模板我通常这样触发 Plan Mode请先不要修改任何文件。阅读 src/server/auth/ 下的所有文件 以及 prisma/schema.prisma 中 User 模型的定义。 然后给出一份计划说明要实现“支持邮箱验证码登录”需要 1. 修改哪些文件每个文件改什么 2. 新增哪些文件 3. 数据库是否需要迁移 4. 可能影响哪些现有功能 5. 建议的执行顺序Agent 返回计划后我会重点看三件事改动范围是否合理有没有动不该动的文件、依赖顺序是否正确有没有先改调用方再改被调用方、风险识别是否到位有没有提到可能破坏的现有功能。确认无误后再发一条“计划确认开始执行”。这里有个技巧让 Agent 在计划里显式列出“我不确定的地方”。比如它会说“我不确定现有的验证码存储用的是 Redis 还是数据库表”。这种不确定性就是你需要补充上下文的地方提前解决比执行到一半卡住要好得多。3.3 计划粒度的把握太粗和太细都是坑计划粒度是个需要反复调试的参数。太粗比如“实现登录功能”等于没规划太细比如“在第 47 行插入一个 if 判断”又失去了 Agent 自主执行的意义。我的经验是按“可独立验证的改动单元”来划分。一个改动单元应该满足改完之后可以单独跑测试验证、可以单独提交、出问题可以单独回滚。比如“新增验证码生成接口”是一个单元“新增验证码校验逻辑”是另一个单元“前端接入验证码输入框”是第三个单元。每个单元内部 Agent 自主决定怎么写单元之间的边界由计划确定。这样划分的好处是执行过程中如果某个单元卡住了不会影响已经完成的单元而且每个单元的产出都是可评审、可测试的。4. Agent 编排从单打独斗到流水线协作4.1 单 Agent 的能力边界在哪里一个 Agent 再强它的上下文窗口也是有限的。当项目大到一定程度让一个 Agent 同时理解前端、后端、数据库、部署配置它的表现会明显下降——不是它不聪明是信息量超过了它的处理能力。我做过一个测试让单个 Agent 完成一个涉及 15 个文件的重构任务成功率大约在 40% 左右失败的主要原因是“改到后面忘了前面”。而把同样的任务拆给三个各管一块的 Agent成功率能到 75% 以上。这就是多 Agent 编排的价值不是让一个全能选手干所有事而是让多个专才各管一摊通过明确的接口和契约协作。4.2 三种实用的编排模式模式一流水线式。适合有明确先后顺序的任务。比如“需求分析 Agent → 接口设计 Agent → 实现 Agent → 测试 Agent”。每个 Agent 的产出是下一个的输入。这种模式的关键是定义清楚交接物比如接口设计 Agent 必须输出一份 OpenAPI 格式的接口定义实现 Agent 严格按这份定义来写。模式二并行分片式。适合可以独立拆分的任务。比如一个大型重构按模块拆给多个 Agent 同时进行每个 Agent 负责一个模块最后统一合并。这种模式的关键是提前锁定共享接口否则各改各的会冲突。我通常会让一个“协调 Agent”先产出接口冻结文档再分发给各执行 Agent。模式三主从式。一个“主 Agent”负责规划和调度多个“从 Agent”负责执行具体子任务。主 Agent 不写代码只做任务分解、进度跟踪、冲突仲裁。这种模式最接近人类团队的管理结构适合复杂项目。三种模式没有优劣看任务性质选。我个人的偏好是新功能开发用流水线式大规模重构用并行分片式长期维护的项目用主从式。4.3 编排中的状态传递与冲突处理多 Agent 协作最容易出问题的地方是状态传递。Agent A 改了文件 XAgent B 不知道又基于旧版本改了文件 X冲突就产生了。解决办法有两个层面。流程层面用版本控制做隔离每个 Agent 在自己的分支上工作合并时统一处理冲突。工具层面给 Agent 提供“读取最新文件状态”的能力并且在契约文件里明确要求“动手前先读最新版本”。冲突处理的原则是谁的计划更靠后谁负责适配。比如接口设计 Agent 先定了接口实现 Agent 后动手那实现 Agent 就要按接口来不能反过来要求接口改。这个原则要写进契约文件让所有 Agent 都遵守。5. 并发与稳定性Agent 扛并发的真实经验5.1 Agent 并发和传统服务并发的本质区别传统服务扛并发核心是资源隔离和限流。Agent 扛并发核心是上下文隔离和状态一致性。因为每个 Agent 实例都在读写文件、执行命令它们之间会互相干扰。我踩过最惨的一次坑同时跑了五个 Agent 做不同模块的改动结果有两个 Agent 同时修改了package.json一个加了依赖一个改了脚本合并时直接冲突而且因为依赖版本不一致装出来的node_modules是坏的排查了两个小时。5.2 并发安全的四条硬规矩规矩一共享文件串行化。像package.json、tsconfig.json、数据库 schema 这类全局文件同一时间只允许一个 Agent 修改。其他 Agent 如果需要变更先提交请求排队处理。规矩二工作目录隔离。每个 Agent 在自己的工作副本里干活不要直接在同一个目录下并发操作。用 git worktree 或者复制目录都可以关键是物理隔离。规矩三外部资源加锁。如果 Agent 要操作数据库、调用外部 API、写共享缓存必须有锁机制。最简单的做法是约定“同一时间只有一个 Agent 能碰数据库”复杂一点可以用分布式锁。规矩四失败快速回滚。Agent 执行失败时不要让它自己重试而是回滚到干净状态重新规划。因为失败往往意味着前提假设错了重试只会重复犯错。5.3 监控 Agent 执行状态的实用手段Agent 执行是黑盒你不知道它内部在干什么。所以我强烈建议给 Agent 加日志。不是让它自己打印日志而是在编排层记录每个 Agent 什么时候启动、读了哪些文件、执行了哪些命令、产出了什么、什么时候结束、成功还是失败。这些日志在排查问题时价值极高。有一次一个 Agent 卡了二十分钟没动静看日志发现它在反复读同一个文件——因为文件里有个循环引用它一直在试图理解结构。如果没有日志你只会看到“卡住了”有了日志就能精准定位。6. 安全边界Agent 能碰什么、不能碰什么6.1 权限最小化原则在 Agent 场景的应用Agent 的权限必须按需授予默认拒绝。不要图省事给它一个万能账号那等于把整个系统交出去了。具体来说读权限可以放宽因为读操作风险低写权限要收紧尤其是对生产环境、对敏感配置、对密钥文件。执行命令的权限更要谨慎像rm -rf、DROP TABLE、git push --force这类破坏性操作必须有人工确认环节。我的做法是给 Agent 一个白名单明确列出它可以用哪些命令、可以写哪些目录。白名单之外的操作一律拒绝需要时再申请。6.2 敏感信息的隔离策略Agent 在处理任务时可能会接触到密钥、令牌、用户数据。这些信息绝对不能进入 Agent 的上下文否则可能被写进日志、写进代码、甚至被发送到外部。隔离策略有三层。第一层敏感信息不放在项目目录里用环境变量注入Agent 读不到文件。第二层如果必须放在文件里用.gitignore排除并且在契约文件里明确禁止 Agent 读取这些文件。第三层在编排层做过滤Agent 的输出如果包含疑似密钥的字符串自动拦截。6.3 代码审查在 AI Native 流程中的新定位传统代码审查是“看逻辑对不对”AI Native 下的审查要加一层“看意图对不对”。因为 Agent 可能写出逻辑正确但意图偏离的代码——比如你要它加个缓存它给你加了个全局单例逻辑上能跑但架构上错了。所以审查者要问的问题变了不是“这段代码有没有 bug”而是“这段代码是不是我想要的东西”。这要求审查者更早介入最好在 Plan Mode 阶段就参与而不是等到代码写完。7. 落地节奏一个团队从零到跑通的四周计划7.1 第一周立规矩不写业务代码第一周的目标是把基础设施搭好把契约文件写出来。具体做四件事选定 Agent 平台和工具链、编写CLAUDE.md、建立分支策略和评审流程、跑通一个最小示例。这一周不要碰业务代码因为规矩没立好就动手后面全是返工。我见过太多团队急着出成果第一周就开始用 Agent 写功能结果第三周发现契约文件没写、流程没定前面写的东西全要重来。7.2 第二周小范围试点选低风险任务第二周选一个低风险、边界清晰、可独立验证的任务做试点。比如“给现有接口补充参数校验”“把某个工具函数重构成纯函数”“补充单元测试”。这类任务的特点是即使 Agent 做错了影响也可控。试点的目的是验证流程不是验证 Agent 能力。重点观察契约文件够不够用、Plan Mode 的计划质量如何、评审环节能不能发现问题、回滚机制顺不顺畅。根据观察结果调整流程。7.3 第三周扩大范围引入多 Agent 编排流程跑顺之后第三周开始引入多 Agent 编排。先从一个简单的流水线开始比如“设计 Agent → 实现 Agent → 测试 Agent”跑通之后再尝试并行分片。这一周的关键是建立冲突处理机制。多 Agent 一定会冲突提前定好规则比事后救火强。规则包括谁先谁后、冲突时谁让步、如何回滚。7.4 第四周复盘固化形成团队手册第四周做全面复盘把前三周的经验教训固化下来。更新契约文件、完善流程文档、整理常见问题清单、明确各角色的职责。复盘的产出应该是一份团队自己的 AI Native 开发手册而不是照搬别人的。因为每个团队的技术栈、业务特点、风险偏好都不同只有自己踩过的坑才是最适合自己的规矩。8. 那些没人告诉你但一定会遇到的坑8.1 Agent 的“过度自信”问题Agent 有个很讨厌的特点它不知道自己不知道。你问它一个它没见过的库怎么用它会编一个看起来很像那么回事的用法而且语气非常肯定。如果你不验证就信了编译报错是轻的逻辑错误才要命。应对办法是强制验证。契约文件里写清楚“任何不确定的 API 用法必须先查文档或搜索确认禁止凭记忆编写”。同时在评审环节对 Agent 生成的、涉及不熟悉库的代码重点审查。8.2 上下文窗口的“遗忘曲线”Agent 处理长任务时会逐渐“忘记”前面的内容。表现是改到第十个文件时忘了第一个文件的约定。这不是 bug是上下文窗口的物理限制。缓解办法有三个。一是把任务拆小每个任务控制在 Agent 能完整记住的范围内。二是关键约束反复强调在每次交互时都带上核心约定。三是用外部记忆把重要决策写进文件让 Agent 随时能读。8.3 测试通过不等于功能正确Agent 很擅长让测试通过但它可能用的是“作弊”的方式——比如把断言改宽松、把测试用例删掉、把异常吞掉。所以测试代码本身也要审查不能只看测试结果。我的做法是Agent 生成的测试代码必须由人过一遍确认它测的是真需求而不是为了让测试变绿而写的假测试。8.4 团队成员的接受度差异不是所有人都愿意接受 AI Native 的工作方式。有人觉得被冒犯有人觉得不靠谱有人干脆抵触。这个不能强推要用结果说话。我的经验是先让愿意尝试的人跑出成果用数据展示效率提升和质量改善再逐步推广。同时要给抵触的人留出过渡期允许他们继续用传统方式但要求他们参与评审 AI 生成的代码慢慢建立信任。9. 我个人的几条实操心得第一契约文件的更新频率比内容质量更重要。一份每周都在更新的粗糙契约比一份写了三个月没动过的完美契约有用得多。因为团队在变Agent 在变契约必须跟着变。第二Plan Mode 的审批不要省。我理解赶进度的时候想跳过审批直接执行但省下的那十分钟往往要用一小时的返工来还。审批环节是性价比最高的质量保障。第三多 Agent 编排先从两个开始。不要一上来就搞五个 Agent 的复杂流水线两个 Agent 的简单协作先跑通理解清楚状态传递和冲突处理的机制再逐步增加。第四给 Agent 的日志要像给生产服务一样认真。Agent 执行是黑盒日志是你唯一的观测手段。日志的质量直接决定了你排查问题的速度。第五不要追求全自动。AI Native 不是无人化人的判断在关键节点不可替代。把 Agent 当成能力很强但需要明确指令的同事而不是当成可以完全放手的工具。这个心态摆正了很多问题自然就有答案了。