1. 从AI辅助到AI原生团队开发范式到底变了什么大多数团队嘴上说着AI Native实际干的事还是老一套——产品经理写PRD开发照着文档敲代码测试等提测最后在某一步接入AI当作亮点。这不叫AI Native这叫AI点缀。真正的AI Native团队改变的不是某个环节的工具而是整个软件开发生命周期SDLC的组织方式Agent成为一等公民人从执行者变成编排者和审核者。我所在的团队从去年开始完整跑通了一套AI Native的开发流程从需求拆解、方案设计、编码实现、代码审查到测试验证全链路都有Agent参与。踩过的坑、验证过的模式、沉淀下来的规范构成了这份手册的全部内容。它适合三类人一是想搞清楚AI Native到底怎么落地的技术负责人二是正在搭建Agent工作流的一线开发者三是对SDLC重构感兴趣、想知道人机协作边界在哪的工程师。先说一个反直觉的结论AI Native团队最大的瓶颈从来不是模型能力而是上下文管理。模型再强如果它拿不到正确的项目背景、编码规范、历史决策产出的东西就是看起来对但用不了。所以这份手册的核心线索是围绕如何让Agent在正确的上下文中工作展开的——CLAUDE.md怎么组织、Plan Mode怎么用、Agent的边界怎么划、多Agent怎么编排、安全怎么兜底。下面逐层拆开讲。2. 上下文工程CLAUDE.md不是说明书是Agent的操作系统2.1 为什么大多数团队的CLAUDE.md写了等于没写我见过太多团队的CLAUDE.md打开一看就是一段本项目使用React TypeScript请遵循最佳实践——这种写法对Agent来说几乎零信息量。Agent需要的是可执行的约束不是泛泛而谈的原则。一份有效的CLAUDE.md本质上是给Agent的入职培训手册它要回答四个问题这个项目是干什么的、代码怎么组织、改代码要遵守什么规则、遇到不确定时该问谁。我们团队迭代了七版CLAUDE.md最终稳定下来的结构是这样的项目定位段一句话说清业务目标和技术栈不超过三行。Agent不需要读你的商业计划书。目录地图用树状结构标注每个目录的职责特别是那些看起来像但实际不同的目录。比如/utils和/helpers的区别不写清楚Agent一定会放错地方。编码铁律只写那些违反了一定会出问题的规则。比如所有API调用必须走request.ts封装禁止直接使用fetch、状态管理统一用Zustand禁止引入Redux。禁区清单明确列出Agent不能碰的文件和目录比如数据库迁移脚本、CI配置、密钥文件。决策记录索引指向/docs/adr目录让Agent在遇到架构选择时先查历史决策。提示CLAUDE.md的长度控制在500行以内。超过这个长度Agent的注意力会被稀释关键规则反而被忽略。我们的做法是把详细规范拆到/docs下CLAUDE.md只保留索引和铁律。2.2 上下文分层把永远要知道和用到才加载分开一开始我们把所有规范都塞进CLAUDE.md结果Agent每次对话都要吞掉大量无关信息token消耗高不说还经常抓错重点。后来我们做了分层层级内容加载时机载体L0 常驻项目定位、编码铁律、禁区每次对话CLAUDE.mdL1 按需模块设计文档、API契约涉及该模块时/docs/modules/*.mdL2 检索历史决策、踩坑记录Agent主动查询/docs/adr/*.mdL3 临时当前任务上下文任务开始时注入Plan Mode这个分层的关键在于L0必须极度精简。我们实测下来L0控制在300行以内时Agent对规则的遵守率明显高于塞满内容的版本。L1和L2通过文件路径引用Agent需要时会自己去读——前提是你在CLAUDE.md里告诉它遇到X情况去读Y文件。2.3 一个真实的翻车案例有次我们让Agent重构一个订单模块它在CLAUDE.md里读到状态管理用Zustand但没读到订单状态机必须走orderStateMachine.ts禁止直接setState。结果它自作主张用Zustand直接改了状态绕过了状态机的校验逻辑测试环境直接炸了。问题不在Agent在于我们把关键约束放在了L1文档里而那次任务没有触发L1加载。教训凡是违反了会导致线上事故的规则一律放L0。宁可CLAUDE.md长一点也不能让关键约束藏在按需加载的文档里。3. Plan Mode实战让Agent先想清楚再动手3.1 Plan Mode解决的是什么问题Agent最危险的行为模式是边想边做——它可能改到一半发现方向错了但已经动了好几个文件回滚成本极高。Plan Mode的核心价值就是强制Agent在动手前输出完整方案由人审核后再执行。这听起来简单但实际用起来有很多细节。我们的Plan Mode流程是这样的Agent接到任务后先输出一份计划包含要改哪些文件、每个文件改什么、为什么这么改、有什么风险。人审核通过后Agent才开始执行。审核不通过就打回重来。这个流程把返工成本从改错代码降到了改错计划效率提升非常明显。3.2 计划的质量取决于提示词的结构一开始Agent输出的计划很水就是修改A文件、修改B文件这种流水账。后来我们优化了提示词模板要求计划必须包含五个部分任务理解用自己的话复述需求确认理解无误。影响范围列出所有会被改动的文件标注新增/修改/删除。实现思路每个文件改什么、为什么这么改。风险点可能影响的其他功能、需要回归测试的范围。验证方案改完后怎么验证跑哪些测试。这个模板逼着Agent把想和做分开也让人审核时有了明确的检查清单。实测下来计划阶段多花5分钟执行阶段能省半小时。3.3 什么任务适合Plan Mode什么任务不适合不是所有任务都值得走Plan Mode。我们的经验是适合跨多文件的改动、涉及核心逻辑的重构、新增功能模块、数据库schema变更。不适合单文件的小修小补、格式化、改文案、加日志。判断标准很简单如果改错了回滚成本高不高。高就走Plan Mode低就直接干。我们团队有个不成文的规矩改动超过3个文件必须走Plan Mode。注意Plan Mode不是万能的。有些Agent会在计划里写得天花乱坠执行时却偷工减料。所以执行完成后一定要对照计划逐项验收不能只看任务完成的提示。4. Agent的边界与编排单Agent、多Agent、Agent Harness怎么选4.1 先搞清楚Agent、Harness、Skill的区别这三个词经常被混用但它们的职责完全不同。我用一个类比说明Agent是员工Harness是工位和工具Skill是员工掌握的技能。Agent具备自主决策能力的执行单元能理解任务、规划步骤、调用工具。HarnessAgent的运行环境负责工具注册、权限控制、上下文注入、执行监控。你可以理解为给Agent搭的工作台。SkillAgent可以调用的具体能力比如读文件跑测试查数据库。Skill是原子操作Agent负责编排。搞清楚这个区分很重要因为很多团队一上来就想搞多Agent协作结果连单Agent的Harness都没搭好Agent连文件都读不利索谈何协作。4.2 单Agent够用的场景别急着上多Agent我们团队80%的任务是单Agent完成的。单Agent的优势是上下文连贯、决策链路清晰、调试简单。什么时候该上多Agent我的判断标准是当任务可以清晰拆分成多个独立子任务且子任务之间不需要频繁交换上下文时。举个例子一个给现有API加缓存层的任务单Agent完全够用——它需要理解现有API、设计缓存策略、实现、测试这些步骤高度依赖同一个上下文。但如果任务是同时重构前端组件库和后端API这两个子任务上下文几乎不重叠就可以拆成两个Agent并行。多Agent的代价是上下文同步成本。两个Agent各自工作最后合并时经常发现接口对不上、命名不一致。我们的做法是多Agent任务必须先由人定义好接口契约Agent只能在这个契约内工作。4.3 Agent编排的三种模式我们实际用过的编排模式有三种各有适用场景串行编排Agent A的输出作为Agent B的输入。适合设计→实现→测试这种流水线。优点是上下文传递清晰缺点是慢且前一步错了后面全错。并行编排多个Agent同时处理独立子任务最后汇总。适合大范围重构。优点是快缺点是合并冲突多。监督编排一个监督Agent负责任务分解和结果验收多个执行Agent干活。适合复杂任务。优点是质量可控缺点是监督Agent本身的能力要求高容易成为瓶颈。我们目前的主力模式是串行为主、局部并行。核心链路串行保证质量独立的子任务比如同时改多个不相关的模块并行提速。4.4 Agent安全沙箱、权限、审计一个都不能少Agent能读文件、能执行命令、能调API这意味着它一旦跑偏破坏力比人大得多。我们的安全策略分三层第一层是沙箱隔离。Agent的所有操作在容器内进行网络访问白名单文件系统只挂载项目目录。这样即使Agent执行了危险命令影响范围也可控。第二层是权限分级。我们把操作分成三档只读操作读文件、查日志Agent可自主执行写操作改代码、建文件需要Plan Mode审核危险操作删文件、改配置、执行迁移必须人工确认。第三层是审计日志。Agent的每一次工具调用、每一条命令、每一个文件改动都记录在案。出问题时能完整回溯Agent当时看到了什么、做了什么决策。提示审计日志不要只记做了什么还要记为什么。我们的做法是要求Agent在每次关键操作前输出一句理由这句话会一起进日志。排查问题时这句理由往往比操作本身更有价值。5. 全链路SDLC改造每个环节Agent该干什么、人该干什么5.1 需求阶段Agent做拆解人做取舍需求阶段Agent能做的是结构化——把一段模糊的需求描述拆成可执行的任务列表标注依赖关系、预估复杂度、识别歧义点。但优先级排序和范围取舍必须由人做因为这里面涉及业务判断和资源约束Agent没有足够信息。我们的流程是产品经理写一段需求描述Agent输出一份任务拆解草案包含任务列表、依赖图、歧义点清单。然后人过一遍回答歧义点、调整优先级、砍掉不做的部分。这个环节Agent能省掉大概60%的整理时间。5.2 设计阶段Agent出方案人做决策设计阶段是Plan Mode的主场。Agent基于需求输出技术方案包括模块划分、接口设计、数据模型、关键流程。人审核方案重点看三件事是否符合现有架构、是否引入了不必要的复杂度、是否有遗漏的边界情况。这个环节有个坑Agent倾向于过度设计。它可能会给你搞出一套复杂的抽象层而实际上一个简单函数就够了。所以审核时要多问一句能不能更简单。5.3 编码阶段Agent写代码人做审查编码阶段Agent的产出质量直接取决于前两个阶段的上下文质量。如果需求和设计都清晰Agent写出来的代码基本可用如果前面含糊Agent就会自由发挥产出大量需要返工的东西。代码审查环节人重点看四类问题业务逻辑是否正确、边界条件是否处理、是否有安全隐患、是否符合团队规范。格式问题、命名问题这些交给linter和Agent自查人不用浪费时间。5.4 测试阶段Agent生成用例人做验收Agent生成测试用例的能力很强但有个通病它倾向于测试正常路径对异常路径覆盖不足。我们的做法是要求Agent必须为每个函数生成至少三类用例正常输入、边界输入、异常输入。人审核时重点看异常用例是否覆盖到位。验收环节必须由人做。Agent可以跑测试、报告结果但这个功能是否符合业务预期只有人能判断。5.5 各环节人机分工速查表环节Agent负责人负责关键产出需求拆解、识别歧义优先级、范围取舍任务列表设计出方案、画流程架构决策、简化技术方案编码写代码、自查逻辑审查、安全审查可运行代码测试生成用例、执行异常覆盖审核、验收测试报告部署生成配置、执行审批、监控上线记录6. 踩坑实录那些让我们返工三次以上的问题6.1 上下文污染Agent读到了过时的文档有次Agent根据一份三个月前的设计文档改了代码结果那份文档早就废弃了。问题根源是我们的/docs目录没有清理机制新旧文档混在一起Agent分不清哪个是当前有效的。解决方案所有文档加有效期标记过期文档移到/docs/archive并在CLAUDE.md里明确只读/docs/current下的文档。同时建立了文档更新责任制谁改代码谁更新对应文档。6.2 Agent的自信幻觉它说改完了其实没改Agent有时会报告已完成修改但实际上只改了一部分或者改错了文件。这种情况在任务复杂时尤其常见。解决方案不信任Agent的完成报告一律用git diff验证实际改动。我们的流程里加了一步改动核对——Agent报告完成后自动跑git diff --stat人对照计划检查文件列表是否一致。6.3 多Agent的命名冲突两个Agent并行工作时各自定义了同名的工具函数合并时直接冲突。更麻烦的是两个Agent对同一个概念用了不同的命名导致代码可读性极差。解决方案多Agent任务开始前先由人定义命名契约——核心概念的统一命名、公共工具的位置、接口的签名。Agent只能在这个契约内工作不能自行发明命名。6.4 Token消耗失控有次一个Agent任务跑了两个小时消耗了大量token最后发现它陷入了读文件→改文件→发现不对→再读→再改的循环。解决方案给Agent设置最大迭代次数和token预算超过阈值自动中止并报告。同时优化CLAUDE.md减少不必要的上下文加载。我们现在的做法是每个任务预设token上限超了就停下来人工介入。6.5 排查链路一次典型的Agent翻车复盘分享一次完整的排查过程。现象是Agent重构后某个API的响应时间从50ms涨到了800ms。第一步看审计日志确认Agent改了哪些文件。发现它把原本的缓存逻辑删了理由是简化代码。第二步看Agent的决策理由。日志里写着缓存层增加了复杂度且未发现明确的性能要求。问题找到了——CLAUDE.md里没有写该API有性能SLA要求。第三步修复。恢复缓存逻辑并在CLAUDE.md的L0层加上所有对外API必须保留缓存层性能要求见/docs/sla.md。第四步举一反三。检查CLAUDE.md里还有哪些隐含约束没写清楚补充了五条类似的规则。这次翻车的根因不是Agent能力问题是上下文缺失。Agent不知道性能要求自然做了看起来合理的简化。这印证了前面说的AI Native的瓶颈在上下文管理。7. 团队落地从试点到全面推行的节奏把控7.1 别一上来就全链路铺开我们最开始想一步到位结果处处出问题团队怨声载道。后来调整为单点突破先在一个小模块上跑通Plan Mode 编码 测试的闭环验证有效后再逐步扩展到其他环节。推荐的推进节奏是单模块试点2周→ 单项目推广1个月→ 跨项目复制2个月。每个阶段都要有明确的验收标准比如Agent产出的代码一次通过率超过70%。7.2 团队能力建设从会用工具到会设计工作流AI Native对团队的能力要求变了。以前强调代码写得快现在更强调能把任务拆清楚、能把上下文组织好、能审核Agent的产出。我们做了三件事建立提示词库把验证有效的提示词模板沉淀下来新人直接复用。定期复盘会每周花半小时复盘Agent翻车案例更新CLAUDE.md和流程。角色重新定义资深工程师从写代码转向设计工作流审核产出初级工程师从执行转向监督Agent执行。7.3 度量怎么知道AI Native真的提效了不能只看感觉快了要有数据。我们跟踪四个指标指标含义目标一次通过率Agent产出无需返工的比例70%人均产出每人每周完成的任务数提升50%返工率因Agent问题导致的返工比例15%上下文命中率Agent正确使用上下文的次数占比85%这些数据每周统计连续三周不达标就停下来复盘流程而不是继续硬推。8. 我个人的几条实操心得跑了大半年AI Native流程最后分享几条踩坑换来的经验都是文档里不会写的。第一条CLAUDE.md要当代码一样维护。它有版本、有review、有测试。我们每次Agent翻车第一反应都是CLAUDE.md是不是缺了什么而不是Agent怎么这么笨。这个思维转变很关键。第二条Plan Mode的审核不能走过场。我见过太多人扫一眼计划就点通过结果执行时才发现方向错了。审核计划的时间至少要是执行时间的五分之一。第三条Agent的产出永远要验证。不管它说得多自信git diff和测试结果才是真相。我们团队有个规矩Agent说完成之后必须有人跑一遍验证才能标记任务结束。第四条多Agent不是越多越好。两个Agent能搞定的事别上三个。每多一个Agent上下文同步成本就翻一倍。我们现在的原则是能单不双能双不三。第五条安全兜底要前置。别等出了事故才想起沙箱和权限。我们现在的做法是任何Agent上线前先过一遍安全检查清单沙箱配了吗、权限分级了吗、审计日志开了吗、危险操作拦截了吗。这四条缺一条不准上线。这套流程还在迭代每个月都会有新的坑和新的解法。但核心逻辑没变过Agent负责执行人负责判断上下文决定质量边界决定安全。把这两句话吃透AI Native落地就不会跑偏。 AI Native团队开发手册：上下文工程与Agent编排实战
1. 从AI辅助到AI原生团队开发范式到底变了什么大多数团队嘴上说着AI Native实际干的事还是老一套——产品经理写PRD开发照着文档敲代码测试等提测最后在某一步接入AI当作亮点。这不叫AI Native这叫AI点缀。真正的AI Native团队改变的不是某个环节的工具而是整个软件开发生命周期SDLC的组织方式Agent成为一等公民人从执行者变成编排者和审核者。我所在的团队从去年开始完整跑通了一套AI Native的开发流程从需求拆解、方案设计、编码实现、代码审查到测试验证全链路都有Agent参与。踩过的坑、验证过的模式、沉淀下来的规范构成了这份手册的全部内容。它适合三类人一是想搞清楚AI Native到底怎么落地的技术负责人二是正在搭建Agent工作流的一线开发者三是对SDLC重构感兴趣、想知道人机协作边界在哪的工程师。先说一个反直觉的结论AI Native团队最大的瓶颈从来不是模型能力而是上下文管理。模型再强如果它拿不到正确的项目背景、编码规范、历史决策产出的东西就是看起来对但用不了。所以这份手册的核心线索是围绕如何让Agent在正确的上下文中工作展开的——CLAUDE.md怎么组织、Plan Mode怎么用、Agent的边界怎么划、多Agent怎么编排、安全怎么兜底。下面逐层拆开讲。2. 上下文工程CLAUDE.md不是说明书是Agent的操作系统2.1 为什么大多数团队的CLAUDE.md写了等于没写我见过太多团队的CLAUDE.md打开一看就是一段本项目使用React TypeScript请遵循最佳实践——这种写法对Agent来说几乎零信息量。Agent需要的是可执行的约束不是泛泛而谈的原则。一份有效的CLAUDE.md本质上是给Agent的入职培训手册它要回答四个问题这个项目是干什么的、代码怎么组织、改代码要遵守什么规则、遇到不确定时该问谁。我们团队迭代了七版CLAUDE.md最终稳定下来的结构是这样的项目定位段一句话说清业务目标和技术栈不超过三行。Agent不需要读你的商业计划书。目录地图用树状结构标注每个目录的职责特别是那些看起来像但实际不同的目录。比如/utils和/helpers的区别不写清楚Agent一定会放错地方。编码铁律只写那些违反了一定会出问题的规则。比如所有API调用必须走request.ts封装禁止直接使用fetch、状态管理统一用Zustand禁止引入Redux。禁区清单明确列出Agent不能碰的文件和目录比如数据库迁移脚本、CI配置、密钥文件。决策记录索引指向/docs/adr目录让Agent在遇到架构选择时先查历史决策。提示CLAUDE.md的长度控制在500行以内。超过这个长度Agent的注意力会被稀释关键规则反而被忽略。我们的做法是把详细规范拆到/docs下CLAUDE.md只保留索引和铁律。2.2 上下文分层把永远要知道和用到才加载分开一开始我们把所有规范都塞进CLAUDE.md结果Agent每次对话都要吞掉大量无关信息token消耗高不说还经常抓错重点。后来我们做了分层层级内容加载时机载体L0 常驻项目定位、编码铁律、禁区每次对话CLAUDE.mdL1 按需模块设计文档、API契约涉及该模块时/docs/modules/*.mdL2 检索历史决策、踩坑记录Agent主动查询/docs/adr/*.mdL3 临时当前任务上下文任务开始时注入Plan Mode这个分层的关键在于L0必须极度精简。我们实测下来L0控制在300行以内时Agent对规则的遵守率明显高于塞满内容的版本。L1和L2通过文件路径引用Agent需要时会自己去读——前提是你在CLAUDE.md里告诉它遇到X情况去读Y文件。2.3 一个真实的翻车案例有次我们让Agent重构一个订单模块它在CLAUDE.md里读到状态管理用Zustand但没读到订单状态机必须走orderStateMachine.ts禁止直接setState。结果它自作主张用Zustand直接改了状态绕过了状态机的校验逻辑测试环境直接炸了。问题不在Agent在于我们把关键约束放在了L1文档里而那次任务没有触发L1加载。教训凡是违反了会导致线上事故的规则一律放L0。宁可CLAUDE.md长一点也不能让关键约束藏在按需加载的文档里。3. Plan Mode实战让Agent先想清楚再动手3.1 Plan Mode解决的是什么问题Agent最危险的行为模式是边想边做——它可能改到一半发现方向错了但已经动了好几个文件回滚成本极高。Plan Mode的核心价值就是强制Agent在动手前输出完整方案由人审核后再执行。这听起来简单但实际用起来有很多细节。我们的Plan Mode流程是这样的Agent接到任务后先输出一份计划包含要改哪些文件、每个文件改什么、为什么这么改、有什么风险。人审核通过后Agent才开始执行。审核不通过就打回重来。这个流程把返工成本从改错代码降到了改错计划效率提升非常明显。3.2 计划的质量取决于提示词的结构一开始Agent输出的计划很水就是修改A文件、修改B文件这种流水账。后来我们优化了提示词模板要求计划必须包含五个部分任务理解用自己的话复述需求确认理解无误。影响范围列出所有会被改动的文件标注新增/修改/删除。实现思路每个文件改什么、为什么这么改。风险点可能影响的其他功能、需要回归测试的范围。验证方案改完后怎么验证跑哪些测试。这个模板逼着Agent把想和做分开也让人审核时有了明确的检查清单。实测下来计划阶段多花5分钟执行阶段能省半小时。3.3 什么任务适合Plan Mode什么任务不适合不是所有任务都值得走Plan Mode。我们的经验是适合跨多文件的改动、涉及核心逻辑的重构、新增功能模块、数据库schema变更。不适合单文件的小修小补、格式化、改文案、加日志。判断标准很简单如果改错了回滚成本高不高。高就走Plan Mode低就直接干。我们团队有个不成文的规矩改动超过3个文件必须走Plan Mode。注意Plan Mode不是万能的。有些Agent会在计划里写得天花乱坠执行时却偷工减料。所以执行完成后一定要对照计划逐项验收不能只看任务完成的提示。4. Agent的边界与编排单Agent、多Agent、Agent Harness怎么选4.1 先搞清楚Agent、Harness、Skill的区别这三个词经常被混用但它们的职责完全不同。我用一个类比说明Agent是员工Harness是工位和工具Skill是员工掌握的技能。Agent具备自主决策能力的执行单元能理解任务、规划步骤、调用工具。HarnessAgent的运行环境负责工具注册、权限控制、上下文注入、执行监控。你可以理解为给Agent搭的工作台。SkillAgent可以调用的具体能力比如读文件跑测试查数据库。Skill是原子操作Agent负责编排。搞清楚这个区分很重要因为很多团队一上来就想搞多Agent协作结果连单Agent的Harness都没搭好Agent连文件都读不利索谈何协作。4.2 单Agent够用的场景别急着上多Agent我们团队80%的任务是单Agent完成的。单Agent的优势是上下文连贯、决策链路清晰、调试简单。什么时候该上多Agent我的判断标准是当任务可以清晰拆分成多个独立子任务且子任务之间不需要频繁交换上下文时。举个例子一个给现有API加缓存层的任务单Agent完全够用——它需要理解现有API、设计缓存策略、实现、测试这些步骤高度依赖同一个上下文。但如果任务是同时重构前端组件库和后端API这两个子任务上下文几乎不重叠就可以拆成两个Agent并行。多Agent的代价是上下文同步成本。两个Agent各自工作最后合并时经常发现接口对不上、命名不一致。我们的做法是多Agent任务必须先由人定义好接口契约Agent只能在这个契约内工作。4.3 Agent编排的三种模式我们实际用过的编排模式有三种各有适用场景串行编排Agent A的输出作为Agent B的输入。适合设计→实现→测试这种流水线。优点是上下文传递清晰缺点是慢且前一步错了后面全错。并行编排多个Agent同时处理独立子任务最后汇总。适合大范围重构。优点是快缺点是合并冲突多。监督编排一个监督Agent负责任务分解和结果验收多个执行Agent干活。适合复杂任务。优点是质量可控缺点是监督Agent本身的能力要求高容易成为瓶颈。我们目前的主力模式是串行为主、局部并行。核心链路串行保证质量独立的子任务比如同时改多个不相关的模块并行提速。4.4 Agent安全沙箱、权限、审计一个都不能少Agent能读文件、能执行命令、能调API这意味着它一旦跑偏破坏力比人大得多。我们的安全策略分三层第一层是沙箱隔离。Agent的所有操作在容器内进行网络访问白名单文件系统只挂载项目目录。这样即使Agent执行了危险命令影响范围也可控。第二层是权限分级。我们把操作分成三档只读操作读文件、查日志Agent可自主执行写操作改代码、建文件需要Plan Mode审核危险操作删文件、改配置、执行迁移必须人工确认。第三层是审计日志。Agent的每一次工具调用、每一条命令、每一个文件改动都记录在案。出问题时能完整回溯Agent当时看到了什么、做了什么决策。提示审计日志不要只记做了什么还要记为什么。我们的做法是要求Agent在每次关键操作前输出一句理由这句话会一起进日志。排查问题时这句理由往往比操作本身更有价值。5. 全链路SDLC改造每个环节Agent该干什么、人该干什么5.1 需求阶段Agent做拆解人做取舍需求阶段Agent能做的是结构化——把一段模糊的需求描述拆成可执行的任务列表标注依赖关系、预估复杂度、识别歧义点。但优先级排序和范围取舍必须由人做因为这里面涉及业务判断和资源约束Agent没有足够信息。我们的流程是产品经理写一段需求描述Agent输出一份任务拆解草案包含任务列表、依赖图、歧义点清单。然后人过一遍回答歧义点、调整优先级、砍掉不做的部分。这个环节Agent能省掉大概60%的整理时间。5.2 设计阶段Agent出方案人做决策设计阶段是Plan Mode的主场。Agent基于需求输出技术方案包括模块划分、接口设计、数据模型、关键流程。人审核方案重点看三件事是否符合现有架构、是否引入了不必要的复杂度、是否有遗漏的边界情况。这个环节有个坑Agent倾向于过度设计。它可能会给你搞出一套复杂的抽象层而实际上一个简单函数就够了。所以审核时要多问一句能不能更简单。5.3 编码阶段Agent写代码人做审查编码阶段Agent的产出质量直接取决于前两个阶段的上下文质量。如果需求和设计都清晰Agent写出来的代码基本可用如果前面含糊Agent就会自由发挥产出大量需要返工的东西。代码审查环节人重点看四类问题业务逻辑是否正确、边界条件是否处理、是否有安全隐患、是否符合团队规范。格式问题、命名问题这些交给linter和Agent自查人不用浪费时间。5.4 测试阶段Agent生成用例人做验收Agent生成测试用例的能力很强但有个通病它倾向于测试正常路径对异常路径覆盖不足。我们的做法是要求Agent必须为每个函数生成至少三类用例正常输入、边界输入、异常输入。人审核时重点看异常用例是否覆盖到位。验收环节必须由人做。Agent可以跑测试、报告结果但这个功能是否符合业务预期只有人能判断。5.5 各环节人机分工速查表环节Agent负责人负责关键产出需求拆解、识别歧义优先级、范围取舍任务列表设计出方案、画流程架构决策、简化技术方案编码写代码、自查逻辑审查、安全审查可运行代码测试生成用例、执行异常覆盖审核、验收测试报告部署生成配置、执行审批、监控上线记录6. 踩坑实录那些让我们返工三次以上的问题6.1 上下文污染Agent读到了过时的文档有次Agent根据一份三个月前的设计文档改了代码结果那份文档早就废弃了。问题根源是我们的/docs目录没有清理机制新旧文档混在一起Agent分不清哪个是当前有效的。解决方案所有文档加有效期标记过期文档移到/docs/archive并在CLAUDE.md里明确只读/docs/current下的文档。同时建立了文档更新责任制谁改代码谁更新对应文档。6.2 Agent的自信幻觉它说改完了其实没改Agent有时会报告已完成修改但实际上只改了一部分或者改错了文件。这种情况在任务复杂时尤其常见。解决方案不信任Agent的完成报告一律用git diff验证实际改动。我们的流程里加了一步改动核对——Agent报告完成后自动跑git diff --stat人对照计划检查文件列表是否一致。6.3 多Agent的命名冲突两个Agent并行工作时各自定义了同名的工具函数合并时直接冲突。更麻烦的是两个Agent对同一个概念用了不同的命名导致代码可读性极差。解决方案多Agent任务开始前先由人定义命名契约——核心概念的统一命名、公共工具的位置、接口的签名。Agent只能在这个契约内工作不能自行发明命名。6.4 Token消耗失控有次一个Agent任务跑了两个小时消耗了大量token最后发现它陷入了读文件→改文件→发现不对→再读→再改的循环。解决方案给Agent设置最大迭代次数和token预算超过阈值自动中止并报告。同时优化CLAUDE.md减少不必要的上下文加载。我们现在的做法是每个任务预设token上限超了就停下来人工介入。6.5 排查链路一次典型的Agent翻车复盘分享一次完整的排查过程。现象是Agent重构后某个API的响应时间从50ms涨到了800ms。第一步看审计日志确认Agent改了哪些文件。发现它把原本的缓存逻辑删了理由是简化代码。第二步看Agent的决策理由。日志里写着缓存层增加了复杂度且未发现明确的性能要求。问题找到了——CLAUDE.md里没有写该API有性能SLA要求。第三步修复。恢复缓存逻辑并在CLAUDE.md的L0层加上所有对外API必须保留缓存层性能要求见/docs/sla.md。第四步举一反三。检查CLAUDE.md里还有哪些隐含约束没写清楚补充了五条类似的规则。这次翻车的根因不是Agent能力问题是上下文缺失。Agent不知道性能要求自然做了看起来合理的简化。这印证了前面说的AI Native的瓶颈在上下文管理。7. 团队落地从试点到全面推行的节奏把控7.1 别一上来就全链路铺开我们最开始想一步到位结果处处出问题团队怨声载道。后来调整为单点突破先在一个小模块上跑通Plan Mode 编码 测试的闭环验证有效后再逐步扩展到其他环节。推荐的推进节奏是单模块试点2周→ 单项目推广1个月→ 跨项目复制2个月。每个阶段都要有明确的验收标准比如Agent产出的代码一次通过率超过70%。7.2 团队能力建设从会用工具到会设计工作流AI Native对团队的能力要求变了。以前强调代码写得快现在更强调能把任务拆清楚、能把上下文组织好、能审核Agent的产出。我们做了三件事建立提示词库把验证有效的提示词模板沉淀下来新人直接复用。定期复盘会每周花半小时复盘Agent翻车案例更新CLAUDE.md和流程。角色重新定义资深工程师从写代码转向设计工作流审核产出初级工程师从执行转向监督Agent执行。7.3 度量怎么知道AI Native真的提效了不能只看感觉快了要有数据。我们跟踪四个指标指标含义目标一次通过率Agent产出无需返工的比例70%人均产出每人每周完成的任务数提升50%返工率因Agent问题导致的返工比例15%上下文命中率Agent正确使用上下文的次数占比85%这些数据每周统计连续三周不达标就停下来复盘流程而不是继续硬推。8. 我个人的几条实操心得跑了大半年AI Native流程最后分享几条踩坑换来的经验都是文档里不会写的。第一条CLAUDE.md要当代码一样维护。它有版本、有review、有测试。我们每次Agent翻车第一反应都是CLAUDE.md是不是缺了什么而不是Agent怎么这么笨。这个思维转变很关键。第二条Plan Mode的审核不能走过场。我见过太多人扫一眼计划就点通过结果执行时才发现方向错了。审核计划的时间至少要是执行时间的五分之一。第三条Agent的产出永远要验证。不管它说得多自信git diff和测试结果才是真相。我们团队有个规矩Agent说完成之后必须有人跑一遍验证才能标记任务结束。第四条多Agent不是越多越好。两个Agent能搞定的事别上三个。每多一个Agent上下文同步成本就翻一倍。我们现在的原则是能单不双能双不三。第五条安全兜底要前置。别等出了事故才想起沙箱和权限。我们现在的做法是任何Agent上线前先过一遍安全检查清单沙箱配了吗、权限分级了吗、审计日志开了吗、危险操作拦截了吗。这四条缺一条不准上线。这套流程还在迭代每个月都会有新的坑和新的解法。但核心逻辑没变过Agent负责执行人负责判断上下文决定质量边界决定安全。把这两句话吃透AI Native落地就不会跑偏。