1. 从“用AI写代码”到“和AI一起交付”AI Native团队到底改变了什么过去两年我参与过三个不同规模的研发团队从传统模式向AI Native模式迁移的过程。最深的感受是大多数团队对“AI Native”的理解还停留在“给每个人配一个Copilot账号”的阶段这跟真正的AI Native差着十万八千里。AI Native不是给旧流程贴一层AI皮肤而是把AI Agent当作团队的一等公民来重新设计整个软件开发生命周期SDLC。这个手册要解决的问题很具体当一个团队决定“我们要AI Native”之后第二天早上坐下来到底该怎么干活代码谁来写、谁来审、谁来测Agent的权限边界在哪里上下文怎么在人和Agent之间传递这些问题不解决AI Native就是一句挂在OKR里的口号。适合读这篇手册的人正在推动团队AI转型的技术负责人、想在自己的项目里引入Agent协作的独立开发者、以及已经在用Claude Code或类似工具但感觉“没用到点子上”的工程师。我会把整个落地过程拆成可操作的模块包括CLAUDE.md怎么写、Plan Mode怎么用、Agent之间怎么编排、安全边界怎么设全部基于实际项目踩过的坑来讲。2. AI Native SDLC的整体设计为什么不能照搬传统流程2.1 传统SDLC在AI Native场景下的三个断裂点传统SDLC的核心假设是“人是最小的执行单元”——需求由人写、代码由人写、测试由人跑、部署由人操作。AI Native打破了这个假设Agent可以承担其中大部分执行工作但传统流程里没有任何一个环节是为“非人类执行者”设计的。第一个断裂点是上下文传递。传统流程里需求文档写完给开发看开发看完给测试讲信息在人的脑子里流转。但Agent没有“脑子里的隐性知识”你给它什么上下文它就只能基于什么上下文工作。CLAUDE.md这个文件之所以重要就是因为它承担了“把团队隐性知识显性化”的职责。第二个断裂点是审查粒度。人写代码Review的时候看逻辑、看边界、看风格。Agent写代码速度是人的十倍如果还用同样的粒度去ReviewReview本身就成了瓶颈。你需要重新设计审查策略——哪些交给自动化检查、哪些必须人看、哪些可以让另一个Agent来审。第三个断裂点是错误恢复。人写错了代码自己知道哪里可能有问题。Agent写错了代码它可能非常自信地告诉你“这个实现是正确的”。你需要设计一套机制来捕获Agent的“自信错误”这比传统Debug复杂得多。2.2 AI Native团队的角色重定义在AI Native团队里人的角色从“执行者”变成了“编排者”和“审查者”。具体来说团队里会出现三种新角色Agent编排者Orchestrator负责设计Agent的工作流决定什么任务交给什么AgentAgent之间怎么传递上下文。这个角色需要同时懂业务逻辑和Agent的能力边界。上下文工程师Context Engineer负责维护CLAUDE.md、项目知识库、Agent可访问的文档。这个角色的核心工作是“让Agent在正确的信息环境下工作”。质量守门人Quality Gatekeeper负责设计自动化检查规则、Review Agent的输出、处理Agent无法判断的边界情况。这个角色需要比传统Reviewer更敏锐因为Agent的错误往往更隐蔽。这三个角色不一定由三个人担任小团队里一个人可能同时承担多个角色。但关键是要意识到这些职责的存在不能像以前一样“写完需求就扔给开发”。2.3 工具链选型的核心考量AI Native团队的工具链选型核心不是“哪个工具功能多”而是“哪个工具能让Agent和人的协作摩擦最小”。我试过几种组合最终稳定下来的方案是环节工具类型选型理由代码生成CLI Agent如Claude Code终端内操作上下文切换成本低适合快速迭代任务编排Plan Mode 自定义脚本先规划再执行避免Agent“跑偏”上下文管理CLAUDE.md 项目Wiki结构化知识Agent可读人也可维护代码审查Agent Review 人工抽检Agent审明显问题人审架构和边界测试Agent生成 人工验证用例Agent写测试快但用例设计需要人把关这个选型的核心逻辑是让Agent做它擅长的快速生成、模式匹配、重复劳动让人做人擅长的架构判断、边界决策、质量把关。不要试图让Agent做所有事也不要让人做Agent能做的事。3. CLAUDE.mdAI Native团队的“团队宪法”3.1 CLAUDE.md到底应该写什么CLAUDE.md不是README的替代品也不是代码规范文档。它的核心作用是让Agent在打开项目的第一时间就知道这个项目的“游戏规则”。我见过很多团队的CLAUDE.md写成了“项目介绍”这是完全跑偏的。Agent不需要知道“这个项目是做什么业务的”它需要知道的是“在这个项目里写代码哪些事能做、哪些事不能做、怎么做才对”。一个有效的CLAUDE.md应该包含以下模块# 项目约定 ## 代码风格 - 使用TypeScript strict模式 - 组件文件使用PascalCase工具函数使用camelCase - 禁止使用any类型必要时用unknown 类型守卫 ## 目录结构 - src/components/ 放UI组件 - src/lib/ 放工具函数 - src/services/ 放API调用 - 新增文件必须放在对应目录禁止在根目录创建文件 ## 提交规范 - commit message格式type(scope): description - type只能是feat/fix/refactor/test/docs/chore - 每次提交只做一件事禁止混合提交 ## 禁止事项 - 禁止直接修改package.json的依赖版本 - 禁止在组件里直接调用fetch必须通过services层 - 禁止提交console.log这个文件的关键在于具体、可执行、无歧义。“使用TypeScript strict模式”比“注意代码质量”有用一百倍因为Agent能直接判断自己是否违反了规则。3.2 怎么写才能让Agent真正遵守写CLAUDE.md最大的坑是你写了一大堆规则Agent该违反还是违反。原因通常有两个规则太模糊或者规则太多。规则要可判定。“代码要有良好的注释”这种规则Agent没法执行因为它不知道什么叫“良好”。改成“每个导出函数必须有JSDoc注释包含param和returns”Agent就能判断自己是否做到了。规则要分层。把规则分成“必须遵守”和“建议遵守”两层。必须遵守的规则用“禁止”“必须”开头建议遵守的用“推荐”“尽量”开头。Agent对“禁止”的敏感度明显高于“推荐”。规则要定期清理。项目在变规则也要变。我建议每两周Review一次CLAUDE.md把已经过时的规则删掉把新出现的约定加进去。一个超过200行的CLAUDE.mdAgent的执行率会明显下降。3.3 实操心得CLAUDE.md的迭代节奏我的做法是项目启动时先写一个最小版本的CLAUDE.md只包含最核心的5-10条规则。然后在实际协作中每次发现Agent犯了同样的错误就把对应的规则加进去。这样长出来的CLAUDE.md每一条都是“用血换来的”执行率自然高。另外一个小技巧在CLAUDE.md里加一个“常见错误”章节把Agent经常犯的错误列出来。比如“不要用moment.js用date-fns”“不要用index作为key”。Agent看到这些具体例子比看抽象规则更容易记住。4. Plan Mode让Agent先想清楚再动手4.1 为什么Plan Mode是AI Native开发的关键环节直接让Agent写代码最大的问题是“它可能理解错了你的意图但写得很自信”。等你发现方向错了已经生成了几百行代码改起来比重新写还麻烦。Plan Mode的核心价值是在Agent动手之前先让它把“打算怎么做”说出来你确认后再执行。这就像装修房子先看设计图再施工而不是让工人直接砸墙。我实测下来使用Plan Mode之后Agent返工率下降了大约60%。虽然前期多花了几分钟确认计划但省下的返工时间远远超过这个投入。4.2 Plan Mode的实操流程以Claude Code为例Plan Mode的使用流程大致如下描述任务用自然语言告诉Agent你要做什么。比如“给用户列表页加一个搜索功能支持按用户名和邮箱搜索”。Agent生成计划Agent会输出一个执行计划包括要改哪些文件、每个文件改什么、新增哪些文件。人工审查计划你检查计划是否合理。重点看有没有遗漏的边界情况、有没有改错文件、有没有引入不必要的依赖。确认执行计划没问题就确认Agent开始写代码。有问题就指出Agent修改计划后重新确认。执行后验证Agent写完代码后你验证结果是否符合预期。这个流程的关键在第3步。很多人嫌麻烦直接跳过结果就是Agent按自己的理解写完了你发现不对再返工。花30秒看计划省30分钟改代码这笔账怎么算都划算。4.3 计划审查的检查清单审查Agent的计划时我通常会看这几个点文件范围Agent打算改的文件是否都在预期范围内有没有意外改到不该改的文件依赖变更计划里有没有新增依赖新增的依赖是否必要边界情况计划里有没有考虑空值、异常、并发等边界情况测试计划Agent打算怎么验证自己的实现有没有写测试的计划回滚方案如果实现有问题怎么回滚改动是否可逆这个清单看起来简单但能拦住大部分“方向性错误”。我踩过的坑包括Agent为了加一个搜索功能把整个数据层重构了Agent引入了一个重型依赖其实用现有工具就能实现Agent改了公共组件的接口影响了其他页面。4.4 什么时候不该用Plan ModePlan Mode不是万能的。对于以下场景直接让Agent执行可能更高效单文件小改动比如改一个变量名、加一行日志。这种改动计划本身比执行还费时间。明确的重复性任务比如“把所有console.log改成logger.debug”。任务足够明确不需要规划。探索性任务比如“帮我看看这个bug可能出在哪里”。这种任务需要Agent先探索再判断不适合先做计划。判断标准很简单如果任务本身需要思考“怎么做”就用Plan Mode如果任务只是“执行一个已知的操作”就直接做。5. Agent编排从单Agent到多Agent协作5.1 单Agent的能力边界在哪里一个Agent再强也有它的能力边界。我总结下来单Agent在以下场景会明显吃力跨领域任务既需要前端知识又需要后端知识的任务单Agent容易顾此失彼。长链路任务超过10个步骤的任务Agent容易在中途“忘记”前面的上下文。需要多视角的任务比如代码审查一个Agent很难同时扮演“实现者”和“审查者”两个角色。这时候就需要引入多Agent协作。但要注意多Agent不是越多越好。每增加一个Agent就增加一层上下文传递的成本和出错的可能。我的经验是3-5个Agent的编排是甜点区超过5个之后协调成本会急剧上升。5.2 常见的Agent编排模式根据任务类型的不同我常用的编排模式有三种流水线模式PipelineAgent A的输出是Agent B的输入依次传递。适合有明确阶段划分的任务比如“需求分析 → 代码生成 → 代码审查 → 测试生成”。并行模式Parallel多个Agent同时处理不同的子任务最后汇总。适合任务可以拆分成独立子任务的场景比如“同时生成前端组件和后端API”。监督模式Supervisor一个Agent负责规划和协调其他Agent负责执行。适合复杂任务监督Agent根据执行结果动态调整下一步。选择哪种模式取决于任务的耦合度。子任务之间耦合低就用并行耦合高就用流水线需要动态决策就用监督模式。5.3 Agent之间怎么传递上下文多Agent协作最大的坑是“上下文丢失”。Agent A生成了代码Agent B审查的时候不知道Agent A的设计意图就容易提出错误的修改意见。解决这个问题的关键是让每个Agent的输出都包含“为什么”。不只是说“我改了这三个文件”而是说“我改了这三个文件因为要实现XX功能选择了YY方案原因是ZZ”。具体做法是在Agent的Prompt里加一条要求“输出时包含决策理由格式为改动内容 改动原因 备选方案”。这样下一个Agent拿到的不只是结果还有决策上下文。另外我会维护一个共享的“任务上下文文件”所有Agent都可以读写。这个文件记录当前任务的背景、已做的决策、待解决的问题。每个Agent开始工作前先读这个文件工作结束后更新这个文件。5.4 实操案例一个完整的多Agent协作流程以“给项目加一个用户反馈功能”为例我的Agent编排流程是这样的第一步需求分析Agent。输入是产品需求描述输出是技术方案包括数据模型、API设计、前端组件拆分。这个Agent的Prompt里强调“不要写代码只输出方案”。第二步方案审查Agent。输入是需求分析Agent的输出输出是审查意见。这个Agent的Prompt里强调“找出方案中的漏洞和边界情况”。第三步代码生成Agent。输入是审查后的方案输出是代码实现。这个Agent按模块拆分每个模块单独生成。第四步代码审查Agent。输入是生成的代码输出是审查意见和修改建议。第五步测试生成Agent。输入是代码和方案输出是测试用例。整个流程跑下来大概需要15-20分钟产出是一个完整的功能实现加测试。人工只需要在第一步和第三步之后做确认其他环节可以自动流转。6. Agent安全权限边界与风险控制6.1 Agent能做什么、不能做什么Agent安全的核心问题是给Agent多大的权限。给少了Agent干不了活给多了Agent可能闯祸。我的原则是Agent的权限应该刚好够它完成当前任务不多不少。具体来说文件系统Agent可以读写项目目录下的文件但不能访问项目目录之外的文件。网络访问Agent可以访问白名单内的API但不能随意访问外部网络。命令执行Agent可以执行构建、测试、lint等开发命令但不能执行删除、部署等危险命令。依赖管理Agent可以读取依赖信息但新增依赖需要人工确认。这些边界不是靠“信任Agent”来维持的而是靠工具层面的限制。比如Claude Code有权限确认机制每次执行危险操作前会要求人工确认。你要做的是配置好这些机制而不是每次都点“允许”。6.2 常见的安全风险与应对风险一Agent误删文件。Agent在执行“清理”类任务时可能删掉不该删的文件。应对方法是所有删除操作必须经过人工确认或者先用git commit保存当前状态。风险二Agent泄露敏感信息。Agent在生成代码时可能把API Key、数据库密码等敏感信息硬编码进去。应对方法是在CLAUDE.md里明确禁止硬编码敏感信息并配置自动化检查。风险三Agent引入不安全依赖。Agent可能为了快速实现功能引入有安全漏洞的依赖。应对方法是新增依赖必须人工审查并定期运行依赖安全扫描。风险四Agent执行危险命令。Agent可能执行rm -rf、git push --force等危险命令。应对方法是配置命令白名单危险命令必须人工确认。6.3 安全配置的实操建议在Claude Code的配置里我通常会做以下设置{ permissions: { allow: [ Read, Glob, Grep, Bash(npm run *), Bash(git status), Bash(git diff *) ], deny: [ Bash(rm *), Bash(git push *), Bash(curl *), Write(.env*) ] } }这个配置的逻辑是读操作全部放开构建和测试命令放开但删除、推送、网络请求、写环境变量文件全部禁止。需要执行这些操作时人工介入。另外我强烈建议在项目里加一个.agentignore文件列出Agent不应该访问的文件和目录。比如.env、secrets/、node_modules/等。这个文件的作用类似于.gitignore但针对的是Agent。7. 常见问题与排查技巧实录7.1 Agent不遵守CLAUDE.md怎么办这是最常见的问题。Agent明明看到了CLAUDE.md里的规则但执行的时候还是违反了。排查思路如下第一步检查规则是否可判定。把规则读一遍问自己“这条规则能不能用是/否来判断”。如果不能规则需要改写。第二步检查规则是否冲突。有时候两条规则互相矛盾Agent不知道该听谁的。比如一条规则说“所有函数必须有注释”另一条说“简单函数不需要注释”。这种冲突会让Agent随机选择。第三步检查规则是否太多。如果CLAUDE.md超过200行Agent的执行率会明显下降。考虑把一些规则移到子目录的CLAUDE.md里按需加载。第四步在Prompt里重申关键规则。对于特别重要的规则可以在每次任务的Prompt里再强调一遍。比如“记住不要用any类型”。7.2 Agent生成的代码质量不稳定Agent生成代码的质量波动通常和上下文质量有关。排查方向上下文是否充足Agent是否看到了相关的代码文件是否理解了项目的架构任务描述是否清晰任务描述是否包含足够的细节有没有模糊的地方是否有参考示例项目里有没有类似的实现可以让Agent参考我的经验是给Agent一个“参考实现”比写一段详细的文字描述更有效。比如“参考src/services/userService.ts的实现方式写一个orderService”。7.3 Agent执行到一半卡住了Agent执行长任务时可能在中途卡住表现为不再输出或输出重复内容。常见原因和解决方法现象可能原因解决方法不再输出上下文超限拆分任务减少单次任务的范围输出重复内容陷入循环中断执行重新描述任务输出无关内容上下文污染清理对话历史重新开始执行报错权限不足检查权限配置补充必要权限7.4 多Agent协作时上下文丢失多Agent协作时Agent B可能不知道Agent A做了什么。解决方法维护共享的上下文文件每个Agent开始前先读要求每个Agent的输出包含决策理由在Agent之间传递信息时使用结构化的格式而不是自由文本7.5 实操避坑清单最后整理一份我踩过的坑供参考不要在CLAUDE.md里写“尽量”“建议”这类模糊词汇Agent会忽略不要让Agent直接操作生产环境所有操作先在本地或测试环境验证不要信任Agent的“自我验证”它说“测试通过”不代表真的通过不要一次性给Agent太大的任务拆成小任务成功率更高不要忘记定期Review Agent的产出再好的Agent也会犯错不要在Agent执行危险操作时点“全部允许”逐条确认更安全不要忽略Agent的“不确定”信号它说“可能有问题”的时候通常真的有问题8. 从零搭建AI Native团队的实施路线8.1 第一周基础设施搭建第一周的目标是让团队每个人都能用Agent干活。具体任务安装和配置CLI Agent工具编写最小版本的CLAUDE.md5-10条核心规则配置权限和安全边界跑通一个完整的“需求 → 代码 → 测试”流程这一周的关键是“跑通”不要追求完美。CLAUDE.md可以后面慢慢加权限可以后面慢慢调。先让团队体验到Agent协作的基本流程。8.2 第二到四周流程磨合这个阶段的目标是找到适合团队的协作节奏。具体任务根据实际使用情况迭代CLAUDE.md尝试Plan Mode找到适合用Plan Mode的任务类型引入代码审查Agent建立Agent Review 人工抽检的审查机制记录每次Agent出错的情况分析原因并改进这个阶段会遇到很多问题这是正常的。关键是要有记录和复盘的习惯每次问题都是一次改进的机会。8.3 第二个月多Agent编排当单Agent协作跑顺之后可以开始尝试多Agent编排。具体任务识别适合多Agent协作的任务类型设计Agent之间的上下文传递机制建立共享的任务上下文文件跑通至少一个完整的多Agent协作流程这个阶段不要贪多先把一个流程跑通再复制到其他场景。8.4 第三个月及以后持续优化AI Native不是一次性的项目而是持续迭代的过程。后续的优化方向定期Review和更新CLAUDE.md收集Agent出错的案例建立“错误模式库”优化Agent的Prompt提高输出质量探索新的Agent应用场景我在实际推进过程中最大的体会是AI Native的落地技术只占30%流程和习惯占70%。工具再好如果团队的工作习惯不改变效果也出不来。反过来即使工具一般只要流程设计得当团队也能获得明显的效率提升。另一个体会是不要追求一步到位。我见过一些团队一开始就想搭建完美的多Agent协作系统结果花了大量时间在工具配置上实际产出反而下降了。正确的做法是先用最简单的方案跑起来在用的过程中发现问题、解决问题让系统自然生长。最后分享一个实用技巧每周花15分钟让Agent自己总结这一周的工作包括做了什么、遇到了什么问题、有什么改进建议。这个总结不仅能帮你了解Agent的工作情况还能发现一些你没想到的优化点。