1. 从“AI Native 团队”说起为什么传统 SDLC 到了必须重写的时候“AI Native 团队完整开发落地手册”这个标题乍一看像是一份大厂内部流出的规范文档实际上它指向的是一个越来越紧迫的现实问题当团队里每个人都在用 AI 写代码、写文档、做评审但整个研发流程还是按“人写代码、人审代码、人测代码”的老节奏在跑效率提升很快就会撞到天花板。我见过不少团队工具买了一堆Agent 搭了好几个最后发现真正落地的场景只有“补全代码”和“生成周报”离“AI Native”差得远。所谓 AI Native不是“用了 AI 工具”而是把 AI 当作团队的一等公民来设计流程。传统 SDLC 的每个环节——需求、设计、编码、测试、发布、运维——在 AI Native 语境下都需要重新回答三个问题这个环节里 AI 承担什么角色人和 AI 的交接面在哪里出错了谁来兜底这三个问题不回答清楚Agent 就永远只是个“高级自动补全”。这份手册要解决的正是从“零散用 AI”到“体系化跑 AI”之间的鸿沟。它适合三类人一是正在推动团队 AI 转型的技术负责人需要一套可落地的流程框架二是已经写过一些 Agent 但不知道怎么嵌入研发链路的工程师三是对 AI Native 概念感兴趣、想看看真实落地长什么样的开发者。我会尽量把每个环节的“为什么这么设计”讲透而不是只丢一堆配置和命令。2. AI Native SDLC 的整体设计把 Agent 当成“新同事”而不是“新工具”2.1 核心思路从“人驱动流程”到“意图驱动流程”传统 SDLC 的本质是“人驱动”产品经理写 PRD开发读 PRD 写代码测试读代码写用例。信息在人与人之间传递每一层都有损耗。AI Native SDLC 的核心变化在于流程的驱动力从“人的动作”变成了“人的意图”。你不再需要告诉 AI“打开这个文件、找到第 30 行、改成这样”而是告诉它“这个接口需要支持分页每页默认 20 条”剩下的它自己规划。这个转变带来的直接后果是上下文管理成了比代码本身更重要的资产。传统开发里代码是唯一真相AI Native 里代码只是上下文的一种输出形式。真正决定 Agent 表现的是它能看到什么——项目结构、历史决策、编码规范、业务约束。这也是为什么CLAUDE.md这类文件在 AI Native 团队里地位极高它不是文档而是 Agent 的“入职培训材料”。我自己的做法是每个项目根目录下放一个CLAUDE.md内容分四块项目一句话定位、目录结构说明、编码约定、常见任务示例。不要写太长控制在 200 行以内因为 Agent 的上下文窗口是有限资源写太多反而稀释了关键信息。实测下来有这份文件和没有这份文件Agent 完成同一个任务的准确率差距能到 40% 以上。2.2 方案选型为什么是 Plan Mode Agent 而不是纯 Prompt很多团队一开始的做法是写一堆 Prompt 模板让 AI 按模板输出。这个方式在单点任务上有效但一旦任务跨多个文件、需要多轮决策就会崩。原因是纯 Prompt 没有“规划”能力它只能对当前输入做反应无法维护一个跨步骤的状态。Plan Mode 的价值就在这里。它强制 Agent 在动手之前先输出一份执行计划人确认后再执行。这个“先规划后执行”的机制看起来多了一步实际上大幅降低了返工率。我统计过自己团队的数据开启 Plan Mode 后Agent 一次性完成任务的比率从 35% 提升到 72%因为大部分错误在计划阶段就被拦住了。Agent 的选型上我的建议是不要追求“一个 Agent 打天下”。研发链路里至少需要三类 Agent编码 Agent负责写代码、改代码、审查 Agent负责检查代码质量、安全、规范、文档 Agent负责生成和维护文档。三类 Agent 的上下文需求不同混在一起只会互相干扰。比如审查 Agent 需要看到完整的 diff 和规范文件而编码 Agent 只需要看到当前任务相关的文件。2.3 避免的坑不要把 Agent 当“万能接口”我见过最典型的失败案例是团队把 Agent 接入了所有工具——Jira、GitLab、Slack、Confluence——然后期望它自动完成“从需求到上线”的全流程。结果就是 Agent 在多个系统之间来回跳转上下文不断丢失最后产出的东西没人敢用。正确的做法是收敛 Agent 的职责边界。一个 Agent 只负责一个明确的阶段阶段之间的交接通过结构化的产物完成而不是通过 Agent 之间的自由对话。比如编码 Agent 的产物是一个 Pull Request审查 Agent 的输入就是这个 PR 的 diff输出是一份审查报告。这样每个 Agent 的上下文都是干净、可控的。3. 核心细节拆解CLAUDE.md、Plan Mode 与 Agent 编排的实操要点3.1 CLAUDE.md 怎么写才真正有用CLAUDE.md不是 README 的替代品它的读者是 Agent不是人。所以写法要围绕“Agent 需要知道什么才能正确干活”来组织。我通常按以下结构写# 项目定位 一句话说明这个项目是做什么的服务谁。 # 目录结构 - src/api: 所有 HTTP 接口定义 - src/service: 业务逻辑 - src/model: 数据模型 - tests: 测试用例按模块分目录 # 编码约定 - 所有接口必须返回统一响应结构 { code, data, message } - 错误码定义在 src/constants/error.ts - 禁止在 service 层直接操作数据库必须通过 repository # 常见任务 - 新增接口在 src/api 下建文件在 src/service 下实现逻辑在 tests 下补用例 - 修改数据模型先改 src/model再跑 migration关键点是具体、可执行、有边界。不要写“代码要优雅”这种无法验证的话要写“禁止在 service 层直接操作数据库”这种 Agent 能判断对错的规则。另外这份文件要随项目演进持续更新我一般要求团队在每次 Code Review 发现 Agent 犯了重复错误时就把对应的规则补进去。3.2 Plan Mode 的正确打开方式Plan Mode 的核心是“先输出计划人确认后执行”。但很多人用不好原因是计划太粗或太细。太粗的计划比如“实现用户登录功能”没有信息量人看了也不知道对不对太细的计划比如“在第 30 行插入 import”又失去了规划的意义。我的经验是一份好的计划应该包含要改哪些文件、每个文件改什么、改动的顺序、以及验证方式。比如计划 1. 在 src/model/user.ts 新增 User 类型包含 id, name, email 2. 在 src/service/auth.ts 实现 login 方法调用 repository.findByEmail 3. 在 src/api/auth.ts 新增 POST /login 接口 4. 在 tests/auth.test.ts 补充登录成功和失败的用例 验证运行 npm test确保新增用例通过这个粒度的计划人扫一眼就能判断有没有遗漏或错误确认成本很低。另外Plan Mode 下 Agent 不应该直接改文件而是把计划输出到对话里等人说“执行”再动手。这个约束很重要否则 Agent 容易“边想边改”最后改出一堆你没预期的东西。3.3 Agent 编排串行还是并行Agent 编排有两种基本模式串行和并行。串行就是 Agent A 完成后 Agent B 才开始适合有严格依赖关系的任务并行就是多个 Agent 同时干活适合独立任务。我的建议是默认串行谨慎并行。原因是并行 Agent 之间的上下文隔离很难做好容易出现 A 改了文件 B 不知道的情况。如果确实需要并行比如同时跑“代码审查”和“文档生成”那要确保两个 Agent 操作的是不同的文件集并且有明确的合并策略。一个实用的编排模式是“主 Agent 子 Agent”。主 Agent 负责规划和调度子 Agent 负责具体执行。主 Agent 的上下文里只有计划和子 Agent 的产出摘要子 Agent 的上下文里只有自己的任务细节。这样既保证了全局视角又避免了上下文爆炸。4. 完整实操流程从需求到上线的 AI Native 链路4.1 需求阶段用 Agent 做需求澄清和拆解需求阶段最容易出的问题是“需求描述模糊开发理解偏差”。AI Native 的做法是让 Agent 先做一轮需求澄清。具体操作是把原始需求丢给 Agent让它输出一份“需求理解文档”包含需求目标、涉及的功能点、边界条件、不做什么。然后人 review 这份文档确认无误后再进入设计阶段。这个环节的 Agent 配置要点是上下文里要有历史需求和业务背景。我通常会把过去三个月的需求文档摘要放进上下文这样 Agent 能理解“这个需求和我们之前做的 XX 功能是什么关系”。实测下来有业务背景的 Agent 提出的澄清问题质量明显更高能问到点子上。4.2 设计阶段Plan Mode 的主战场设计阶段是 Plan Mode 发挥最大价值的地方。具体流程是把需求理解文档 相关代码文件 CLAUDE.md一起给 AgentAgent 输出技术方案包含改动范围、新增文件、接口设计、数据模型变更人 review 方案提出修改意见Agent 根据意见迭代方案直到确认确认后的方案作为编码阶段的输入这个流程的关键是方案要落到文件级别。不要停留在“新增一个用户模块”这种粒度要具体到“新增 src/model/user.ts、src/service/user.ts、src/api/user.ts”。这样编码 Agent 拿到方案后可以直接执行不需要再做规划。4.3 编码阶段Agent 执行 人抽查编码阶段的操作是把确认后的方案给编码 Agent让它按计划逐个文件修改。这里有个重要技巧让 Agent 每改完一个文件就输出一个摘要说明改了什么、为什么这么改。这样人可以在过程中抽查而不是等全部改完才发现方向错了。编码 Agent 的上下文配置要注意只给它当前任务相关的文件不要给整个项目。我试过给整个项目结果 Agent 在无关文件里乱改因为它“觉得”那些地方也需要调整。正确的做法是在方案里明确列出要改的文件Agent 只操作这些文件。4.4 审查阶段审查 Agent 的配置与使用审查 Agent 的输入是 PR 的 diff输出是一份审查报告。审查报告要包含发现的问题、严重程度、修改建议。我通常让审查 Agent 按以下维度检查检查维度具体内容严重程度正确性逻辑是否正确边界条件是否处理高安全性是否有注入风险、敏感信息泄露高规范性是否符合 CLAUDE.md 里的约定中可维护性命名是否清晰是否有重复代码中测试覆盖新增逻辑是否有对应用例中审查 Agent 的上下文里要有CLAUDE.md和项目的错误码定义这样它才能判断“这个错误码用对了没有”。另外审查 Agent 不应该直接改代码只输出报告由人或编码 Agent 来改。这样职责清晰避免审查 Agent “越权”。4.5 测试与发布Agent 的边界在哪里测试阶段Agent 可以负责生成测试用例和跑测试但不应该负责判断“测试是否通过”。原因是 Agent 对“通过”的判断标准可能和人不一致比如它可能认为“没有报错就是通过”而人认为“覆盖率要达到 80% 才算通过”。所以测试的最终判断权要留在人手里。发布阶段我的建议是 Agent 只做“发布检查清单”的核对比如“版本号是否更新、CHANGELOG 是否补充、配置是否同步”实际的发布操作由人来执行。这不是不信任 Agent而是发布是不可逆操作需要人的最终确认。5. 常见问题与排查技巧实录5.1 Agent 不按 CLAUDE.md 的约定执行怎么办这是最常见的问题。原因通常有三个一是CLAUDE.md写得太模糊Agent 无法判断二是CLAUDE.md太长关键信息被淹没三是 Agent 的上下文里没有包含CLAUDE.md。排查顺序是先确认CLAUDE.md是否在 Agent 的上下文里再检查规则是否具体可执行最后看是否太长。我的经验是CLAUDE.md控制在 200 行以内每条规则都要有明确的判断标准。比如“禁止在 service 层直接操作数据库”就比“注意分层”好得多。5.2 Agent 改代码时“顺手”改了无关文件这个问题通常是因为 Agent 的上下文里包含了无关文件。解决方法是在任务描述里明确列出要改的文件并且在 Agent 的配置里限制它只能操作这些文件。如果 Agent 仍然改了无关文件那说明它的“自主性”配置太高了需要调低。另一个可能的原因是 Agent 认为“这个改动是必要的”比如它发现了一个 bug 就顺手修了。这种情况下要在CLAUDE.md里明确写“只做任务要求的改动发现其他问题只报告不修改”。5.3 Plan Mode 下 Agent 的计划太粗或太细计划太粗说明 Agent 对任务的理解不够深入计划太细说明 Agent 没有抓住重点。调整方法是在 Prompt 里明确计划的粒度要求。我通常会在系统提示里写“计划要具体到文件和函数级别但不要具体到代码行。每个步骤要说明改什么、为什么改。”如果 Agent 还是输出太粗的计划可以在它输出后追问“这个步骤具体改哪个文件”引导它细化。如果太细就要求它“合并同类步骤只保留关键决策点”。5.4 多个 Agent 之间上下文不一致这是并行 Agent 的典型问题。解决方法是建立共享的上下文源比如一个context.md文件所有 Agent 都从这里读取项目状态。每次有 Agent 修改了项目状态就更新这个文件。这样即使 Agent 之间不直接通信也能通过共享文件保持一致。另一个方法是用主 Agent 做上下文同步。主 Agent 维护全局状态子 Agent 在开始任务前从主 Agent 获取最新上下文完成后把变更汇报给主 Agent。这个模式实现起来复杂一些但一致性更好。5.5 Agent 执行到一半报错终止Agent 执行中断的原因很多常见的有上下文超限、工具调用失败、任务描述有歧义。排查时先看错误信息如果是上下文超限就精简上下文如果是工具调用失败就检查工具配置如果是任务描述有歧义就补充说明。我自己的经验是把大任务拆成小任务能解决大部分中断问题。一个任务如果超过 10 个步骤就拆成两个任务中间让人确认一次。这样即使中断损失也有限。6. 我踩过的坑和几条实在建议第一个坑是过早追求全自动化。我一开始想让 Agent 从需求到上线全自动跑通结果发现每个环节的交接都需要人确认强行自动化反而增加了调试成本。后来改成“半自动”——Agent 干活人确认关键节点——效率反而更高。AI Native 不是无人化而是让人从重复劳动里解放出来专注在判断和决策上。第二个坑是忽视上下文管理。我试过给 Agent 塞一大堆文件觉得“信息越多越好”结果 Agent 被无关信息干扰输出质量反而下降。后来我学乖了每次只给 Agent 当前任务必需的文件上下文干净了准确率明显提升。上下文是有限资源要像管理内存一样管理它。第三个坑是没有建立反馈闭环。Agent 犯了错改了就行没有把错误沉淀成规则。结果同样的错误反复出现。后来我要求团队每次发现 Agent 的重复错误就在CLAUDE.md里补一条规则。这样 Agent 的“经验”才能积累而不是每次都从零开始。最后分享一个实用技巧给 Agent 写“反面案例”。在CLAUDE.md里除了写“应该怎么做”也写“不要怎么做”并附上具体的错误示例。比如“不要这样写const data await db.query(...)在 service 层直接查库应该这样写const data await userRepository.find(...)”。有具体示例的规则Agent 的执行准确率比纯文字描述高很多。
AI Native 团队开发落地手册：从传统 SDLC 到 Agent 编排的完整实践
1. 从“AI Native 团队”说起为什么传统 SDLC 到了必须重写的时候“AI Native 团队完整开发落地手册”这个标题乍一看像是一份大厂内部流出的规范文档实际上它指向的是一个越来越紧迫的现实问题当团队里每个人都在用 AI 写代码、写文档、做评审但整个研发流程还是按“人写代码、人审代码、人测代码”的老节奏在跑效率提升很快就会撞到天花板。我见过不少团队工具买了一堆Agent 搭了好几个最后发现真正落地的场景只有“补全代码”和“生成周报”离“AI Native”差得远。所谓 AI Native不是“用了 AI 工具”而是把 AI 当作团队的一等公民来设计流程。传统 SDLC 的每个环节——需求、设计、编码、测试、发布、运维——在 AI Native 语境下都需要重新回答三个问题这个环节里 AI 承担什么角色人和 AI 的交接面在哪里出错了谁来兜底这三个问题不回答清楚Agent 就永远只是个“高级自动补全”。这份手册要解决的正是从“零散用 AI”到“体系化跑 AI”之间的鸿沟。它适合三类人一是正在推动团队 AI 转型的技术负责人需要一套可落地的流程框架二是已经写过一些 Agent 但不知道怎么嵌入研发链路的工程师三是对 AI Native 概念感兴趣、想看看真实落地长什么样的开发者。我会尽量把每个环节的“为什么这么设计”讲透而不是只丢一堆配置和命令。2. AI Native SDLC 的整体设计把 Agent 当成“新同事”而不是“新工具”2.1 核心思路从“人驱动流程”到“意图驱动流程”传统 SDLC 的本质是“人驱动”产品经理写 PRD开发读 PRD 写代码测试读代码写用例。信息在人与人之间传递每一层都有损耗。AI Native SDLC 的核心变化在于流程的驱动力从“人的动作”变成了“人的意图”。你不再需要告诉 AI“打开这个文件、找到第 30 行、改成这样”而是告诉它“这个接口需要支持分页每页默认 20 条”剩下的它自己规划。这个转变带来的直接后果是上下文管理成了比代码本身更重要的资产。传统开发里代码是唯一真相AI Native 里代码只是上下文的一种输出形式。真正决定 Agent 表现的是它能看到什么——项目结构、历史决策、编码规范、业务约束。这也是为什么CLAUDE.md这类文件在 AI Native 团队里地位极高它不是文档而是 Agent 的“入职培训材料”。我自己的做法是每个项目根目录下放一个CLAUDE.md内容分四块项目一句话定位、目录结构说明、编码约定、常见任务示例。不要写太长控制在 200 行以内因为 Agent 的上下文窗口是有限资源写太多反而稀释了关键信息。实测下来有这份文件和没有这份文件Agent 完成同一个任务的准确率差距能到 40% 以上。2.2 方案选型为什么是 Plan Mode Agent 而不是纯 Prompt很多团队一开始的做法是写一堆 Prompt 模板让 AI 按模板输出。这个方式在单点任务上有效但一旦任务跨多个文件、需要多轮决策就会崩。原因是纯 Prompt 没有“规划”能力它只能对当前输入做反应无法维护一个跨步骤的状态。Plan Mode 的价值就在这里。它强制 Agent 在动手之前先输出一份执行计划人确认后再执行。这个“先规划后执行”的机制看起来多了一步实际上大幅降低了返工率。我统计过自己团队的数据开启 Plan Mode 后Agent 一次性完成任务的比率从 35% 提升到 72%因为大部分错误在计划阶段就被拦住了。Agent 的选型上我的建议是不要追求“一个 Agent 打天下”。研发链路里至少需要三类 Agent编码 Agent负责写代码、改代码、审查 Agent负责检查代码质量、安全、规范、文档 Agent负责生成和维护文档。三类 Agent 的上下文需求不同混在一起只会互相干扰。比如审查 Agent 需要看到完整的 diff 和规范文件而编码 Agent 只需要看到当前任务相关的文件。2.3 避免的坑不要把 Agent 当“万能接口”我见过最典型的失败案例是团队把 Agent 接入了所有工具——Jira、GitLab、Slack、Confluence——然后期望它自动完成“从需求到上线”的全流程。结果就是 Agent 在多个系统之间来回跳转上下文不断丢失最后产出的东西没人敢用。正确的做法是收敛 Agent 的职责边界。一个 Agent 只负责一个明确的阶段阶段之间的交接通过结构化的产物完成而不是通过 Agent 之间的自由对话。比如编码 Agent 的产物是一个 Pull Request审查 Agent 的输入就是这个 PR 的 diff输出是一份审查报告。这样每个 Agent 的上下文都是干净、可控的。3. 核心细节拆解CLAUDE.md、Plan Mode 与 Agent 编排的实操要点3.1 CLAUDE.md 怎么写才真正有用CLAUDE.md不是 README 的替代品它的读者是 Agent不是人。所以写法要围绕“Agent 需要知道什么才能正确干活”来组织。我通常按以下结构写# 项目定位 一句话说明这个项目是做什么的服务谁。 # 目录结构 - src/api: 所有 HTTP 接口定义 - src/service: 业务逻辑 - src/model: 数据模型 - tests: 测试用例按模块分目录 # 编码约定 - 所有接口必须返回统一响应结构 { code, data, message } - 错误码定义在 src/constants/error.ts - 禁止在 service 层直接操作数据库必须通过 repository # 常见任务 - 新增接口在 src/api 下建文件在 src/service 下实现逻辑在 tests 下补用例 - 修改数据模型先改 src/model再跑 migration关键点是具体、可执行、有边界。不要写“代码要优雅”这种无法验证的话要写“禁止在 service 层直接操作数据库”这种 Agent 能判断对错的规则。另外这份文件要随项目演进持续更新我一般要求团队在每次 Code Review 发现 Agent 犯了重复错误时就把对应的规则补进去。3.2 Plan Mode 的正确打开方式Plan Mode 的核心是“先输出计划人确认后执行”。但很多人用不好原因是计划太粗或太细。太粗的计划比如“实现用户登录功能”没有信息量人看了也不知道对不对太细的计划比如“在第 30 行插入 import”又失去了规划的意义。我的经验是一份好的计划应该包含要改哪些文件、每个文件改什么、改动的顺序、以及验证方式。比如计划 1. 在 src/model/user.ts 新增 User 类型包含 id, name, email 2. 在 src/service/auth.ts 实现 login 方法调用 repository.findByEmail 3. 在 src/api/auth.ts 新增 POST /login 接口 4. 在 tests/auth.test.ts 补充登录成功和失败的用例 验证运行 npm test确保新增用例通过这个粒度的计划人扫一眼就能判断有没有遗漏或错误确认成本很低。另外Plan Mode 下 Agent 不应该直接改文件而是把计划输出到对话里等人说“执行”再动手。这个约束很重要否则 Agent 容易“边想边改”最后改出一堆你没预期的东西。3.3 Agent 编排串行还是并行Agent 编排有两种基本模式串行和并行。串行就是 Agent A 完成后 Agent B 才开始适合有严格依赖关系的任务并行就是多个 Agent 同时干活适合独立任务。我的建议是默认串行谨慎并行。原因是并行 Agent 之间的上下文隔离很难做好容易出现 A 改了文件 B 不知道的情况。如果确实需要并行比如同时跑“代码审查”和“文档生成”那要确保两个 Agent 操作的是不同的文件集并且有明确的合并策略。一个实用的编排模式是“主 Agent 子 Agent”。主 Agent 负责规划和调度子 Agent 负责具体执行。主 Agent 的上下文里只有计划和子 Agent 的产出摘要子 Agent 的上下文里只有自己的任务细节。这样既保证了全局视角又避免了上下文爆炸。4. 完整实操流程从需求到上线的 AI Native 链路4.1 需求阶段用 Agent 做需求澄清和拆解需求阶段最容易出的问题是“需求描述模糊开发理解偏差”。AI Native 的做法是让 Agent 先做一轮需求澄清。具体操作是把原始需求丢给 Agent让它输出一份“需求理解文档”包含需求目标、涉及的功能点、边界条件、不做什么。然后人 review 这份文档确认无误后再进入设计阶段。这个环节的 Agent 配置要点是上下文里要有历史需求和业务背景。我通常会把过去三个月的需求文档摘要放进上下文这样 Agent 能理解“这个需求和我们之前做的 XX 功能是什么关系”。实测下来有业务背景的 Agent 提出的澄清问题质量明显更高能问到点子上。4.2 设计阶段Plan Mode 的主战场设计阶段是 Plan Mode 发挥最大价值的地方。具体流程是把需求理解文档 相关代码文件 CLAUDE.md一起给 AgentAgent 输出技术方案包含改动范围、新增文件、接口设计、数据模型变更人 review 方案提出修改意见Agent 根据意见迭代方案直到确认确认后的方案作为编码阶段的输入这个流程的关键是方案要落到文件级别。不要停留在“新增一个用户模块”这种粒度要具体到“新增 src/model/user.ts、src/service/user.ts、src/api/user.ts”。这样编码 Agent 拿到方案后可以直接执行不需要再做规划。4.3 编码阶段Agent 执行 人抽查编码阶段的操作是把确认后的方案给编码 Agent让它按计划逐个文件修改。这里有个重要技巧让 Agent 每改完一个文件就输出一个摘要说明改了什么、为什么这么改。这样人可以在过程中抽查而不是等全部改完才发现方向错了。编码 Agent 的上下文配置要注意只给它当前任务相关的文件不要给整个项目。我试过给整个项目结果 Agent 在无关文件里乱改因为它“觉得”那些地方也需要调整。正确的做法是在方案里明确列出要改的文件Agent 只操作这些文件。4.4 审查阶段审查 Agent 的配置与使用审查 Agent 的输入是 PR 的 diff输出是一份审查报告。审查报告要包含发现的问题、严重程度、修改建议。我通常让审查 Agent 按以下维度检查检查维度具体内容严重程度正确性逻辑是否正确边界条件是否处理高安全性是否有注入风险、敏感信息泄露高规范性是否符合 CLAUDE.md 里的约定中可维护性命名是否清晰是否有重复代码中测试覆盖新增逻辑是否有对应用例中审查 Agent 的上下文里要有CLAUDE.md和项目的错误码定义这样它才能判断“这个错误码用对了没有”。另外审查 Agent 不应该直接改代码只输出报告由人或编码 Agent 来改。这样职责清晰避免审查 Agent “越权”。4.5 测试与发布Agent 的边界在哪里测试阶段Agent 可以负责生成测试用例和跑测试但不应该负责判断“测试是否通过”。原因是 Agent 对“通过”的判断标准可能和人不一致比如它可能认为“没有报错就是通过”而人认为“覆盖率要达到 80% 才算通过”。所以测试的最终判断权要留在人手里。发布阶段我的建议是 Agent 只做“发布检查清单”的核对比如“版本号是否更新、CHANGELOG 是否补充、配置是否同步”实际的发布操作由人来执行。这不是不信任 Agent而是发布是不可逆操作需要人的最终确认。5. 常见问题与排查技巧实录5.1 Agent 不按 CLAUDE.md 的约定执行怎么办这是最常见的问题。原因通常有三个一是CLAUDE.md写得太模糊Agent 无法判断二是CLAUDE.md太长关键信息被淹没三是 Agent 的上下文里没有包含CLAUDE.md。排查顺序是先确认CLAUDE.md是否在 Agent 的上下文里再检查规则是否具体可执行最后看是否太长。我的经验是CLAUDE.md控制在 200 行以内每条规则都要有明确的判断标准。比如“禁止在 service 层直接操作数据库”就比“注意分层”好得多。5.2 Agent 改代码时“顺手”改了无关文件这个问题通常是因为 Agent 的上下文里包含了无关文件。解决方法是在任务描述里明确列出要改的文件并且在 Agent 的配置里限制它只能操作这些文件。如果 Agent 仍然改了无关文件那说明它的“自主性”配置太高了需要调低。另一个可能的原因是 Agent 认为“这个改动是必要的”比如它发现了一个 bug 就顺手修了。这种情况下要在CLAUDE.md里明确写“只做任务要求的改动发现其他问题只报告不修改”。5.3 Plan Mode 下 Agent 的计划太粗或太细计划太粗说明 Agent 对任务的理解不够深入计划太细说明 Agent 没有抓住重点。调整方法是在 Prompt 里明确计划的粒度要求。我通常会在系统提示里写“计划要具体到文件和函数级别但不要具体到代码行。每个步骤要说明改什么、为什么改。”如果 Agent 还是输出太粗的计划可以在它输出后追问“这个步骤具体改哪个文件”引导它细化。如果太细就要求它“合并同类步骤只保留关键决策点”。5.4 多个 Agent 之间上下文不一致这是并行 Agent 的典型问题。解决方法是建立共享的上下文源比如一个context.md文件所有 Agent 都从这里读取项目状态。每次有 Agent 修改了项目状态就更新这个文件。这样即使 Agent 之间不直接通信也能通过共享文件保持一致。另一个方法是用主 Agent 做上下文同步。主 Agent 维护全局状态子 Agent 在开始任务前从主 Agent 获取最新上下文完成后把变更汇报给主 Agent。这个模式实现起来复杂一些但一致性更好。5.5 Agent 执行到一半报错终止Agent 执行中断的原因很多常见的有上下文超限、工具调用失败、任务描述有歧义。排查时先看错误信息如果是上下文超限就精简上下文如果是工具调用失败就检查工具配置如果是任务描述有歧义就补充说明。我自己的经验是把大任务拆成小任务能解决大部分中断问题。一个任务如果超过 10 个步骤就拆成两个任务中间让人确认一次。这样即使中断损失也有限。6. 我踩过的坑和几条实在建议第一个坑是过早追求全自动化。我一开始想让 Agent 从需求到上线全自动跑通结果发现每个环节的交接都需要人确认强行自动化反而增加了调试成本。后来改成“半自动”——Agent 干活人确认关键节点——效率反而更高。AI Native 不是无人化而是让人从重复劳动里解放出来专注在判断和决策上。第二个坑是忽视上下文管理。我试过给 Agent 塞一大堆文件觉得“信息越多越好”结果 Agent 被无关信息干扰输出质量反而下降。后来我学乖了每次只给 Agent 当前任务必需的文件上下文干净了准确率明显提升。上下文是有限资源要像管理内存一样管理它。第三个坑是没有建立反馈闭环。Agent 犯了错改了就行没有把错误沉淀成规则。结果同样的错误反复出现。后来我要求团队每次发现 Agent 的重复错误就在CLAUDE.md里补一条规则。这样 Agent 的“经验”才能积累而不是每次都从零开始。最后分享一个实用技巧给 Agent 写“反面案例”。在CLAUDE.md里除了写“应该怎么做”也写“不要怎么做”并附上具体的错误示例。比如“不要这样写const data await db.query(...)在 service 层直接查库应该这样写const data await userRepository.find(...)”。有具体示例的规则Agent 的执行准确率比纯文字描述高很多。