1. 为什么“AI Native 团队”不是加个 Copilot 就算数这两年“AI Native”这个词被用得太泛了。很多团队把 IDE 里装个代码补全插件、在 CI 里挂一个自动 review 的机器人就对外宣称自己是 AI Native 团队。我实际跟过几个这样的团队结论很直接工具换了流程没换产出没变。真正的 AI Native 团队改变的不是“用什么写代码”而是整个 SDLC软件开发生命周期的运转方式——需求怎么进来、方案怎么定、代码谁来写、评审看什么、测试怎么跑、上线后谁负责每一环的“人机分工”都要重新设计。这份手册想解决的问题很具体一个已经有一定工程基础的团队怎么把 AI Native 的研发范式真正落地而不是停留在 demo 阶段。它适合三类人看——正在推动团队转型的技术负责人、想搞清楚 Agent 在真实项目里怎么用的资深工程师、以及刚接触 Agent 开发但需要一套完整参照系的新人。我不会只讲概念会把CLAUDE.md怎么写、Plan Mode 怎么用、Agent 怎么编排、并发怎么扛、记忆怎么存这些实操细节全部摊开讲。先给一个我自己的判断标准一个团队是否 AI Native看它的“上下文资产”是否可复用。如果每个新任务都要重新给 AI 讲一遍项目背景、代码规范、目录结构那它只是“用了 AI 工具”如果这些上下文被沉淀成结构化文件任何 Agent 接手都能快速进入状态那才叫 AI Native。这个判断标准会贯穿整篇手册。2. AI Native SDLC 的整体设计与思路拆解2.1 传统 SDLC 和 AI Native SDLC 的本质差异传统 SDLC 的核心假设是“人是执行主体工具是辅助”。需求评审、方案设计、编码、测试、部署每个环节都由人主导工具只是提效。AI Native SDLC 的核心假设变了Agent 是执行主体人是编排者和审核者。这个转变听起来简单实际影响是连锁的。我拿一个真实场景对比。传统模式下一个后端接口开发任务是产品写需求文档 → 技术负责人拆任务 → 工程师写代码 → 提交 PR → 同事 review → 测试 → 合并。AI Native 模式下同样的任务是产品写需求 → 技术负责人把需求转成结构化任务描述 → 编排 Agent 执行读上下文、出方案、写代码、自测→ 人审核 Agent 的产出 → 合并。区别在于中间那段“工程师写代码 自测”被 Agent 接管了但前面的任务结构化和后面的审核变得更重。这就是很多人踩的第一个坑以为 AI Native 就是让 Agent 全自动干活。实际上任务结构化的工作量不减反增。你得把原本靠口头沟通、靠默契传递的信息全部显式写出来Agent 才能理解。这也是为什么CLAUDE.md这类上下文文件如此关键。2.2 方案选型为什么是“上下文文件 Plan Mode Agent 编排”这套组合市面上做 AI Native 研发的方案大致有三类。第一类是纯工具派堆各种 AI 插件靠工具能力覆盖第二类是纯平台派上一套企业级 Agent 平台所有任务走平台第三类是上下文派核心是把项目知识结构化让 Agent 能读懂。我选的是第三类为主、第一类为辅的组合。原因很实际工具会换平台会变但结构化的项目上下文是长期资产。你今天用这个 Agent 框架明天可能换另一个但只要CLAUDE.md、任务模板、代码规范这些上下文文件在迁移成本就很低。反过来如果你把一切都绑在某个平台上平台一改版你的流程就崩了。具体到三个核心组件CLAUDE.md作为上下文锚点它不是简单的 README而是给 Agent 看的“项目说明书”。包含项目结构、技术栈、代码规范、常见陷阱、构建命令、测试方式。Agent 每次接手任务第一件事就是读它。Plan Mode 作为方案闸门Agent 不能直接开写必须先出方案人确认后才执行。这一步拦住的是“Agent 理解偏差导致的返工”。Agent 编排作为执行引擎不同任务用不同 Agent或者多个 Agent 协作。比如一个负责读代码一个负责写一个负责测。提示不要一上来就搞多 Agent 协作。我见过太多团队单 Agent 还没跑顺就急着上多 Agent结果调试成本爆炸。先把单 Agent Plan Mode 跑通再考虑编排。2.3 这套方案能解决什么、不能解决什么能解决的重复性编码任务、跨文件重构、测试用例生成、文档同步更新、代码规范检查。这些任务的特点是“规则明确、上下文可描述、结果可验证”。不能解决的需要大量业务判断的架构决策、涉及多方利益权衡的技术选型、需要跟人反复对齐的需求澄清。这些还是得人来。我自己的经验是AI Native 团队里Agent 能接管大约 60% 到 70% 的编码工作量但方案设计和最终审核的工作量几乎没减少。所以别指望“人少干一半活”更现实的预期是“同样的人产出翻倍但审核压力也翻倍”。3. 核心细节解析与实操要点3.1CLAUDE.md到底该写什么一份可复用的模板CLAUDE.md是整套体系的基石。写得好Agent 上手快写得烂Agent 天天犯低级错误。我踩过的坑是一开始写得太简略Agent 不知道项目用了什么构建工具每次都猜后来写得太详细把整个架构文档塞进去Agent 读半天读不完反而抓不住重点。我的经验是CLAUDE.md控制在 200 到 400 行分六个部分# 项目上下文 ## 1. 项目概览 一句话说明项目做什么核心模块有哪些。 ## 2. 技术栈 语言、框架、数据库、构建工具、测试框架精确到版本。 ## 3. 目录结构 关键目录的用途哪些是自动生成的不要改。 ## 4. 代码规范 命名约定、错误处理方式、日志规范、注释要求。 ## 5. 常用命令 构建、测试、lint、本地启动直接给可复制的命令。 ## 6. 已知陷阱 这个项目里容易踩的坑比如某个模块有历史包袱、某个依赖有版本限制。第六部分是最容易被忽略但最有价值的。比如你项目里有个老模块用的是废弃的 APIAgent 不知道就会照着写结果引入新 bug。把这些写进去Agent 就绕开了。注意CLAUDE.md要跟着项目演进更新。我建议每次 code review 发现 Agent 犯了重复性错误就把对应的规则补进去。它是活的文档不是一次性写完就扔那的。3.2 Plan Mode 的正确用法让 Agent 先想后做Plan Mode 的核心是“强制 Agent 先输出方案人确认后再执行”。很多人用不好是因为把 Plan Mode 当成了“走个形式”Agent 出个方案看都不看就点确认。这样用等于没用。我的用法是Plan Mode 输出的方案必须包含四个要素任务理解Agent 用自己的话复述一遍任务确认理解没偏差。改动清单要改哪些文件、新增哪些文件、删除哪些文件。实现思路关键逻辑怎么实现有没有多种方案选了哪种为什么。验证方式改完怎么验证跑哪些测试预期结果是什么。人审核的时候重点看第一和第三。第一看理解对不对第三看思路合不合理。第二和第四是执行细节扫一眼就行。我实测下来加了 Plan Mode 之后Agent 返工率从大概 40% 降到 15% 左右。多花的那点审核时间完全值得。3.3 Agent 编排单 Agent、多 Agent 怎么选Agent 编排是这套体系里最容易过度设计的地方。我的建议很明确能用单 Agent 解决的绝不上多 Agent。单 Agent 适合任务边界清晰、上下文能一次性加载、不需要并行处理的场景。比如“给这个模块加一个接口”“把这个函数重构成异步”“给这个类补测试”。多 Agent 适合任务可以拆成独立子任务、子任务之间依赖少、需要不同专长的场景。比如“前端改 UI 后端加接口 写集成测试”这三个可以并行用三个 Agent 分别做。多 Agent 的坑在于协调成本。Agent 之间怎么传递上下文、怎么处理冲突、怎么汇总结果这些都要设计。我见过一个团队搞了五个 Agent 协作结果光调试 Agent 之间的通信就花了两周产出还不如单 Agent。提示多 Agent 协作时给每个 Agent 明确的输入输出契约。比如“Agent A 输出一份接口定义Agent B 根据接口定义写实现”契约清晰了协调成本就低了。3.4 Agent 记忆与存储working memory 怎么设计Agent 的记忆分两类短期记忆working memory和长期记忆。短期记忆是当前任务执行过程中的上下文长期记忆是跨任务复用的知识。短期记忆的关键是“够用就好”。Agent 执行任务时不需要把整个项目加载进来只需要加载跟当前任务相关的文件。我通常的做法是Plan Mode 阶段确定要改哪些文件执行阶段只加载这些文件加上它们的直接依赖。长期记忆的关键是“结构化存储”。我一般用两层一层是CLAUDE.md这种项目级上下文一层是任务级的经验沉淀。比如某个任务踩了坑解决后把经验写进一个lessons.md下次 Agent 接手类似任务时先读它。存储方案上小团队用文件系统就够了CLAUDE.mdlessons.md 任务目录。大团队可以考虑上向量数据库把历史任务和代码片段做索引Agent 按需检索。但别一上来就上向量库文件系统能解决 80% 的问题。4. 实操过程与核心环节实现4.1 从零搭建一个 AI Native 任务流完整步骤我拿一个真实任务走一遍给一个已有的用户服务加一个“批量查询用户”的接口。第一步任务结构化。技术负责人把需求写成结构化描述## 任务新增批量查询用户接口 ### 背景 现有 /user/{id} 接口只支持单个查询前端批量展示时需要多次请求性能差。 ### 要求 - 新增 POST /user/batch 接口 - 请求体{ ids: [1,2,3] } - 响应用户列表保持请求顺序 - 单次最多 100 个 id - 需要鉴权 ### 验收标准 - 接口能正确处理正常请求 - 超过 100 个 id 返回 400 - 无权限返回 401 - 单元测试覆盖以上场景第二步Agent 加载上下文。Agent 读CLAUDE.md了解项目结构、技术栈、代码规范。然后读现有的/user/{id}接口实现作为参考。第三步Plan Mode 出方案。Agent 输出## 任务理解 新增批量查询接口支持最多 100 个 id保持顺序需要鉴权。 ## 改动清单 - 修改src/controllers/userController.js新增 batchGetUsers 方法 - 修改src/routes/userRoutes.js新增路由 - 新增src/services/userService.js 中的 batchGetUsers 方法 - 新增tests/userController.test.js 中的批量查询测试 ## 实现思路 1. 路由层POST /user/batch挂鉴权中间件 2. 控制器层校验 ids 参数数组、长度 100调用 service 3. 服务层批量查询用 IN 查询结果按 ids 顺序重排 4. 错误处理参数错误返回 400无权限由中间件返回 401 ## 验证方式 - 跑 tests/userController.test.js - 手动测试正常请求、超长请求、无权限请求第四步人审核方案。我看了一遍发现 Agent 没考虑“ids 里有重复 id 怎么办”。补了一条要求去重后查询但返回结果按原始 ids 顺序。Agent 更新方案。第五步Agent 执行。Agent 按方案改代码改完自己跑测试。第六步人审核产出。我看 diff重点看参数校验是否完整、SQL 是否有注入风险、顺序重排逻辑是否正确。发现一个边界问题ids 为空数组时应该返回空列表而不是报错。让 Agent 补上。第七步合并。测试通过合并。整个流程走下来从任务结构化到合并大概 40 分钟。传统模式下这个任务大概要 2 到 3 小时。但注意我的审核时间占了大概 15 分钟这部分不能省。4.2 参数计算与选择并发、超时、重试怎么定Agent 执行任务时涉及几个关键参数定不好会出问题。并发数如果多个 Agent 并行执行并发数怎么定我的经验是并发数不超过 CPU 核心数的一半。比如 8 核机器并发 4 个 Agent。原因是每个 Agent 执行时都要加载上下文、跑测试资源消耗不小。并发太高机器扛不住Agent 之间还会抢资源。超时时间单个 Agent 任务超时怎么定看任务复杂度。简单任务改一个文件给 5 分钟中等任务改多个文件 测试给 15 分钟复杂任务跨模块重构给 30 分钟。超时后 Agent 会被终止这时候要看它执行到哪一步了能不能续上。重试策略Agent 执行失败要不要重试我的做法是只对“环境类失败”重试不对“逻辑类失败”重试。环境类失败比如网络超时、依赖下载失败重试一次通常能过。逻辑类失败比如测试不通过、代码有语法错误重试没用得人介入看方案哪里有问题。注意Agent 执行终止execution terminated due to error是常见情况别慌。先看日志判断是环境问题还是逻辑问题再决定重试还是人工介入。4.3 一个完整的 Agent 配置示例我拿一个实际用的 Agent 配置举例基于常见的 Agent 框架结构agent: name: code-writer model: claude-sonnet context: - CLAUDE.md - lessons.md - {{task.related_files}} plan_mode: true max_iterations: 20 timeout: 900 tools: - read_file - write_file - run_test - run_lint output: - diff - test_report - summary关键配置说明context里加载CLAUDE.md和lessons.md加上任务相关文件。注意related_files是动态的由 Plan Mode 阶段确定。plan_mode: true强制先出方案。max_iterations: 20限制 Agent 最多迭代 20 轮防止死循环。timeout: 90015 分钟超时。tools只给必要的工具别给太多工具越多 Agent 越容易乱用。output要求输出 diff、测试报告、总结方便人审核。这套配置我用了大半年稳定性不错。唯一要调的是max_iterations复杂任务可能要调到 30。5. 常见问题与排查技巧实录5.1 Agent 理解偏差为什么它总是改错地方这是最高频的问题。Agent 改错地方根因通常是上下文不足或任务描述模糊。排查思路先看 Agent 的 Plan Mode 输出它的“任务理解”部分是不是跟你的预期一致。如果不一致说明任务描述有问题补充细节。如果一致但执行还是错说明上下文不足Agent 不知道某些约束。我踩过的一个坑让 Agent 改一个函数它把函数签名也改了导致调用方全挂。原因是CLAUDE.md里没写“公共接口签名变更需要同步更新调用方”。补上这条规则后再没出过这个问题。5.2 并发场景下 Agent 互相干扰多个 Agent 并行改同一个项目容易出现文件冲突。比如 Agent A 和 Agent B 同时改userService.js后写的覆盖先写的。解决办法有两个。一是任务拆分时保证文件不重叠每个 Agent 负责不同的文件。二是用 git worktree 隔离每个 Agent 在自己的 worktree 里改最后合并。我推荐第二种隔离彻底冲突好处理。5.3 Agent 执行卡住或超时Agent 卡住通常是因为任务太复杂、上下文太大、工具调用失败。排查顺序先看日志最后一步在干什么再看上下文大小是不是超了最后看工具调用有没有报错。我的经验是上下文超过 100K token 后Agent 表现明显下降。这时候要拆分任务或者精简上下文只加载必要的文件。5.4 常见问题速查表问题现象可能原因排查方法解决方式Agent 改错文件上下文不足看 Plan Mode 输出补充CLAUDE.md规则测试不通过方案有逻辑漏洞看测试报告人工审核方案补充边界条件执行超时任务太复杂看日志最后一步拆分任务或增加超时时间并发冲突文件重叠看 git diff用 worktree 隔离重复犯同一错误经验没沉淀看历史任务把经验写进lessons.mdAgent 不读上下文上下文文件太大看 token 数精简上下文只留必要部分5.5 几个我踩过的坑和对应的技巧坑一CLAUDE.md写成了 README。一开始我把项目介绍、安装步骤全塞进去Agent 读半天抓不住重点。后来改成“只写 Agent 需要知道的”删掉了一半内容效果反而更好。坑二Plan Mode 审核走过场。有段时间任务多Plan Mode 输出我扫一眼就确认结果返工率飙升。后来强制自己每个方案至少看 2 分钟重点看任务理解和实现思路返工率降下来了。坑三多 Agent 协作没定契约。五个 Agent 各干各的最后汇总时发现接口对不上。后来给每个 Agent 定了明确的输入输出格式问题解决。坑四忘了更新lessons.md。同一个坑踩了三次才想起来沉淀。现在养成习惯每次 code review 发现 Agent 犯重复错误立刻补进lessons.md。6. Agent 安全与团队协作的边界6.1 Agent 能碰什么、不能碰什么Agent 安全的核心是“最小权限”。我给 Agent 的权限原则是能读的尽量多能写的严格限。能读项目代码、文档、测试、配置文件。这些读了没风险还能帮 Agent 理解上下文。能写只给任务相关的文件写权限。比如任务只改userService.js就不给userController.js的写权限。这样即使 Agent 理解偏差也不会改错地方。不能碰生产配置、密钥文件、CI/CD 配置、数据库迁移脚本。这些一旦改错影响面太大。我通常把这些文件加进 Agent 的黑名单Agent 尝试写时直接拒绝。注意Agent 生成的代码在合并前必须经过人审核。别搞“Agent 直接推 main”这种操作出事是迟早的。6.2 团队协作人和 Agent 怎么分工AI Native 团队里人的角色变了但没消失。我的分工建议是技术负责人负责任务结构化、方案审核、最终把关。这是最关键的岗位Agent 干得好不好很大程度取决于任务描述得清不清楚。资深工程师负责复杂任务的方案设计、Agent 搞不定的硬骨头、CLAUDE.md和lessons.md的维护。初级工程师负责 Agent 产出的审核、测试补充、文档更新。这个岗位的工作重心从“写代码”转向“审代码 补测试”。Agent负责重复性编码、重构、测试生成、文档同步。这个分工下团队产出能提升但对人的审核能力要求更高了。审核 Agent 的产出比审核人的产出更累因为 Agent 的错误往往更隐蔽。6.3 怎么衡量 AI Native 转型是否成功别用“Agent 写了多少行代码”这种指标没意义。我用的指标是三个任务周期时间从任务创建到合并的时间。转型成功的团队这个指标应该下降 40% 以上。返工率Agent 产出被人打回重做的比例。健康值在 15% 以下。上下文复用率新任务中有多少上下文是从CLAUDE.md和lessons.md直接复用的。这个指标越高说明上下文资产沉淀得越好。我实测下来一个团队从开始转型到稳定运行大概需要 2 到 3 个月。前一个月主要在搭上下文、调 Agent 配置中间一个月在磨合流程最后一个月才看到明显的效率提升。别指望一周见效。7. 我个人的一些实操体会这套体系我用了大半年最大的体会是AI Native 的瓶颈不在 Agent 能力在人的任务结构化能力。Agent 再强你任务描述得含糊它也干不好。反过来任务描述清楚了用一般的 Agent 也能出好结果。另一个体会是别追求全自动。我见过一些团队非要搞“需求进去、代码出来”的全自动流水线结果质量一塌糊涂。更现实的做法是“人机协作”Agent 干执行人干判断各司其职。最后分享一个小技巧每周花半小时 review 一遍lessons.md把重复出现的坑合并、把过时的规则删掉。这个习惯坚持下来Agent 的表现会越来越稳。上下文资产是养出来的不是一次性建出来的。