1. 从用AI写代码到和AI一起交付AI Native团队到底改变了什么大多数团队对AI的用法还停留在补全几行代码生成一个函数这个层面工具是工具人是人AI只是编辑器里的一个插件。但AI Native团队的玩法完全不同——它把AI Agent当成团队里一个真实的、有职责边界的成员从需求拆解、方案设计、编码实现、测试验证到文档沉淀整条SDLC软件开发生命周期链路都围绕人和Agent协作重新设计。这不是把Copilot装进IDE就完事了而是研发范式的整体迁移。我所在的团队从去年开始系统性地做这件事踩了不少坑也沉淀出一套能跑通的落地方法。这篇手册不讲概念只讲我们实际怎么做的怎么给Agent定义角色、怎么用CLAUDE.md这类上下文文件约束它的行为、怎么用Plan Mode把想清楚和动手做分开、怎么在Agent执行出错时快速定位、怎么构建评测集验证Agent的产出质量。适合正在考虑或已经开始把Agent引入研发流程的团队负责人、一线工程师以及想搞清楚AI Native研发到底长什么样的从业者。先说一个反直觉的结论AI Native团队最大的成本不是Token而是上下文管理。我们统计过一个中等复杂度的功能模块Agent消耗的Token里有超过60%花在重新理解项目背景上。如果上下文组织得好同样的任务Token消耗能降一半产出质量还更稳定。所以这篇手册会把大量篇幅放在上下文工程上这是整个体系的基石。2. 团队角色重定义Agent在SDLC里到底站哪个位置2.1 先想清楚哪些环节适合交给Agent不是所有研发环节都适合Agent介入。我们内部做过一个简单的评估矩阵从任务确定性上下文依赖度错误可逆性三个维度打分决定某个环节是Agent主导人机协作还是人主导。研发环节任务确定性上下文依赖度错误可逆性推荐模式需求拆解低高高人主导Agent辅助技术方案设计中高中人机协作编码实现高中高Agent主导单元测试编写高低高Agent主导代码审查中高高人机协作集成测试中中中人机协作文档沉淀高低高Agent主导线上故障排查低极高低人主导Agent辅助这张表的核心逻辑是错误可逆性高的环节放心让Agent主导。写错了代码可以回滚测试写错了可以重跑文档写错了改一下就行。但线上故障排查这种错误不可逆、上下文极度依赖实时状态的环节必须人主导Agent只做信息聚合和初步分析。2.2 Agent的职责边界要用文件固化下来我们给每个Agent角色都建了一个独立的配置文件放在项目根目录的.agents/文件夹下。比如coder.agent.md定义编码Agent的职责、技术栈偏好、代码规范、禁止事项reviewer.agent.md定义审查Agent的关注点、检查清单、输出格式。这里有个关键经验职责边界要写得足够窄。一开始我们写得很宽泛比如你是一个资深工程师负责编写高质量代码结果Agent什么都想干改需求、调架构、写文档最后哪个都没做好。后来改成你只负责根据给定的接口定义和测试用例实现对应的函数体不修改接口签名不新增依赖不重构无关代码产出质量立刻稳定了。2.3 人机协作的交接点设计Agent和人之间的交接点我们统一用结构化产物来定义。也就是说人交给Agent的不是一段自然语言描述而是一个结构化的任务卡片包含任务目标、输入相关文件路径、接口定义、约束条件技术栈、规范、禁止事项、验收标准测试用例、预期输出。反过来Agent交给人的也是结构化产物变更摘要、影响范围、测试结果、待确认事项。这样做的原因是自然语言的模糊性在Agent这里会被放大。你说优化一下这个函数Agent可能重写整个文件你说加个日志Agent可能加十行日志。结构化产物把模糊性降到最低。3. 上下文工程CLAUDE.md这类文件为什么是整套体系的命脉3.1 上下文文件解决的核心问题Agent每次执行任务都是失忆的。它不知道你的项目用什么框架、代码规范是什么、哪些目录不能动、历史上有哪些坑。如果每次都要人在对话里重新交代一遍效率极低且容易遗漏。上下文文件我们内部叫项目记忆文件常见的有CLAUDE.md、AGENTS.md等就是解决这个问题的——把项目的常识固化成一个Agent每次启动都会读取的文件。我们项目的CLAUDE.md大概长这样# 项目上下文 ## 技术栈 - 后端Python 3.11 FastAPI SQLAlchemy 2.0 - 前端React 18 TypeScript Vite - 数据库PostgreSQL 15 - 测试pytest vitest ## 目录约定 - src/api/ 路由层只做参数校验和调用service - src/service/ 业务逻辑层禁止直接操作数据库 - src/repo/ 数据访问层所有SQL写在这里 - tests/ 测试文件命名规则 test_模块名.py ## 代码规范 - 所有函数必须有类型注解 - 禁止使用 print统一用 logger - 异常必须捕获具体类型禁止裸 except - 新增依赖必须先在 pyproject.toml 中声明 ## 禁止事项 - 禁止修改 src/core/config.py 中的配置项 - 禁止在业务代码中硬编码密钥 - 禁止删除现有测试用例3.2 上下文文件的分层策略一个文件装不下所有信息我们做了三层拆分第一层项目级上下文CLAUDE.md所有Agent都读包含技术栈、目录约定、全局规范。控制在200行以内太长Agent会忽略中间部分。第二层模块级上下文各模块目录下的MODULE.md只在该模块相关任务时读取包含模块职责、对外接口、内部数据结构、已知问题。第三层任务级上下文任务卡片本身每次任务动态生成包含本次任务的具体目标、输入、约束、验收标准。这个分层的关键在于按需加载。Agent处理src/service/order.py的任务时只需要读项目级上下文加src/service/MODULE.md不需要读前端模块的上下文。这样既保证了信息完整又控制了Token消耗。3.3 上下文文件的维护机制上下文文件最大的风险是腐化——代码变了文件没更新Agent基于过时信息做决策。我们的做法是把上下文文件的更新纳入代码审查流程。任何PR如果修改了目录结构、技术栈、核心规范必须同步更新对应的上下文文件否则审查不通过。另外我们每周做一次上下文文件的体检用Agent自己来检查把当前代码库的实际结构和上下文文件描述做对比找出不一致的地方。这个检查本身也是Agent主导的任务因为它是确定性的、错误可逆的。提示上下文文件不要写应该怎么做这种模糊表述要写必须怎么做禁止怎么做这种可判定的规则。Agent对模糊表述的处理方式是不可预测的。4. Plan Mode实战把想清楚和动手做彻底分开4.1 为什么需要Plan Mode早期我们让Agent直接执行任务结果经常出现方向错了但执行很完美的情况——Agent花了大量Token写了一堆代码但整体思路和我们的预期完全不符只能全部推翻重来。Plan Mode的核心思想是先让Agent输出执行计划人确认后再执行。这一步看似增加了交互轮次实际上大幅降低了返工率。我们的数据是引入Plan Mode后复杂任务涉及3个以上文件修改的一次通过率从不到40%提升到了75%以上。因为大部分错误在计划阶段就被发现了而不是等到代码写完。4.2 Plan Mode的具体操作流程我们的流程分四步第一步任务输入。人把结构化任务卡片交给Agent明确要求先输出计划不要执行。第二步计划输出。Agent输出一份执行计划格式我们做了约定## 执行计划 ### 涉及文件 - src/service/order.py修改 - src/repo/order_repo.py修改 - tests/test_order.py新增 ### 执行步骤 1. 在 order_repo.py 中新增 get_orders_by_status 方法 2. 在 order.py 中新增 list_orders_by_status 服务方法调用repo层 3. 在 test_order.py 中新增3个测试用例覆盖正常/空/异常场景 ### 风险点 - 步骤1需要确认数据库索引是否支持status字段查询 - 步骤2需要确认是否需要分页 ### 待确认事项 - 分页参数默认值是多少第三步计划审查。人审查计划重点看涉及文件是否合理、步骤是否有遗漏、风险点是否识别到位、待确认事项是否明确。有问题就在这一步打回让Agent修改计划。第四步执行。计划确认后Agent按步骤执行每完成一步输出进度。4.3 Plan Mode的常见坑坑一计划太粗。Agent有时候会输出修改order模块实现订单查询功能这种一句话计划完全没有可审查性。解决办法是在任务卡片里明确要求计划必须细化到文件级别和函数级别。坑二计划太细。另一个极端是Agent把每一行代码都写进计划里计划本身就有几百行审查成本比直接看代码还高。我们的经验是计划细化到函数签名核心逻辑描述这个粒度最合适再细就是浪费。坑三计划执行偏离。Agent在执行过程中可能发现计划有问题然后自作主张调整。我们的规则是执行中如果发现计划需要调整必须停下来重新走计划审查流程不允许Agent自行修改计划。这个规则一开始Agent经常违反后来我们在上下文文件里明确写了执行中禁止偏离已确认的计划如需调整必须暂停并说明情况才好转。5. Agent执行出错时的排查链路5.1 先分类再排查Agent执行出错第一件事不是看代码而是分类。我们总结了四类常见错误错误类型典型表现根因方向上下文缺失Agent用了不存在的API、引用了错误的模块上下文文件不完整或未加载指令歧义Agent理解的任务和预期不符任务卡片描述模糊能力边界Agent反复尝试同一错误方案任务超出Agent能力范围环境问题依赖缺失、权限不足、网络超时执行环境配置问题分类之后排查方向就清晰了。上下文缺失就去补上下文文件指令歧义就去改任务卡片能力边界就换人做或拆解任务环境问题就去修环境。5.2 一个真实的排查案例有一次Agent在实现一个订单导出功能时反复报找不到export_utils模块。我们按链路排查第一步确认Agent是否读取了正确的上下文。检查日志发现Agent读取的是项目级上下文但export_utils是某个模块内部的工具只在模块级上下文里有记录。根因是模块级上下文没有被加载。第二步为什么没被加载检查任务卡片发现任务描述里只写了实现订单导出功能没有指定涉及哪个模块。Agent不知道要读哪个模块的上下文。第三步修复方案。在任务卡片里明确写本任务涉及src/modules/export/模块请先读取该模块的MODULE.md。同时我们在项目级上下文里加了一条规则如果任务涉及特定模块必须在任务卡片中指明模块路径。这个问题从发现到修复花了大概20分钟其中大部分时间花在定位为什么没加载模块上下文上。排查Agent错误的关键是看它的信息输入是什么而不是看它的输出是什么。输出错了根因往往在输入。5.3 建立错误知识库每次排查完一个Agent错误我们都会把错误现象-根因-修复方案记录到一个错误知识库里。这个知识库本身也是Agent可读的放在.agents/errors.md。当Agent遇到类似错误时会先查这个知识库。运行三个月下来这个知识库积累了大概40条记录覆盖了80%的常见错误。新加入的Agent比如换了模型或者新配置的Agent遇到问题时查知识库能解决大部分情况大幅减少了人工介入。6. Agent评测集怎么证明你的Agent真的靠谱6.1 为什么必须建评测集感觉Agent挺好用的这种主观判断在团队协作里是灾难。A觉得好用B觉得不好用谁也说服不了谁。评测集的作用是把主观感受变成客观数据给定一组标准任务Agent的通过率是多少平均耗时多少Token消耗多少。我们的评测集包含50个任务覆盖编码、测试、文档、审查四类每类任务按难度分三档。每个任务都有明确的输入任务卡片和验收标准测试用例或人工检查清单。6.2 评测集的构建方法任务来源从历史真实任务中抽取。不要自己编造任务编造的任务往往过于理想化测不出真实问题。我们是从过去三个月的Git提交记录里挑选出有代表性的任务还原成任务卡片。难度分级简单单文件修改逻辑清晰无外部依赖中等2-3个文件修改涉及模块间调用困难跨模块、涉及数据库或外部服务、有边界条件验收标准能用自动化测试的就用自动化测试不能的就用人工检查清单。我们的比例大概是7:370%的任务有自动化验收30%需要人工判断比如文档质量、代码可读性。6.3 评测的执行与解读评测不是跑一次就完事我们固定在两个时机跑换模型时跑验证新模型是否比旧模型好、改上下文文件时跑验证改动是否带来负面影响。解读评测结果时我们关注三个指标通过率整体通过率低于70%说明Agent配置有问题需要排查难度分布简单任务通过率应该接近100%如果简单任务都过不了说明基础配置有问题Token效率同样任务Token消耗突然增加往往意味着上下文膨胀或Agent在反复试错有一次我们换了一个新模型整体通过率从78%降到了65%。拆开看发现简单任务通过率没变但困难任务通过率大幅下降。进一步分析发现新模型在长上下文场景下容易丢失中间信息。这个发现直接影响了我们的模型选型决策——评测集的价值就在于把感觉变成证据。7. 落地三个月后我总结出的几条硬经验7.1 上下文文件的ROI最高优先投入如果只能做一件事我会选择把上下文文件写好。我们在这上面投入了大概两周时间产出的回报是Agent任务一次通过率提升30%以上人工介入频率下降一半。相比之下换更强的模型带来的提升远没有这么大。上下文是Agent的操作系统模型只是CPU操作系统不行CPU再强也跑不出好结果。7.2 不要追求全流程自动化我们一开始的野心是从需求到上线全自动试了两个月发现不现实。现在的做法是在确定性高的环节做自动化在确定性低的环节做人机协作。比如编码实现、测试编写、文档生成这三个环节基本全自动需求拆解、方案设计、故障排查这三个环节人主导。整体效率提升大概40%但如果强行全自动效率反而会下降因为返工和纠错的成本太高。7.3 Agent的记忆要主动管理Agent没有真正的长期记忆它的记忆就是我们喂给它的上下文。所以上下文管理本质上就是Agent的记忆管理。我们的做法是项目级上下文保持稳定模块级上下文随代码演进更新任务级上下文用完即弃。不要试图让Agent记住所有东西那样只会让上下文膨胀、Token爆炸、效果下降。7.4 评测集要持续迭代评测集不是建一次就完事。我们的评测集每季度更新一次淘汰过时的任务补充新的任务。因为项目在演进Agent的能力边界也在变化去年的评测集测不出今年的问题。评测集的质量直接决定了你对Agent能力的判断质量这件事值得持续投入。7.5 最后分享一个提高Agent产出稳定性小技巧在任务卡片里加一条输出前自检清单让Agent在完成任务后自己对照检查。比如编码任务的清单是是否所有函数都有类型注解是否所有异常都被捕获是否新增了测试用例是否更新了相关文档这个自检动作看起来简单但实测能把低级错误率降低一半以上。因为Agent在生成和检查两种模式下的注意力分布不同自检能捕捉到生成时忽略的问题。这个技巧的本质是把质量检查前置到Agent内部而不是等到人工审查时才发现问题。人工审查应该关注方向对不对设计好不好这种高价值判断而不是有没有写类型注解这种机械检查。让Agent自己做机械检查人做价值判断这才是AI Native团队该有的分工。