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:3，70%的任务有自动化验收，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团队该有的分工。
