1. 从“人写代码”到“人管 Agent”AI Native 团队到底在变什么这两年“AI Native”这个词被喊得太多多到有点廉价。很多团队嘴上说自己是 AI Native实际干的事无非是给 IDE 装个补全插件或者让大模型帮忙写几段样板代码。这不叫 AI Native这叫“AI 辅助的传统开发”。真正的 AI Native 团队研发范式发生的是结构性变化人从“写代码的人”变成“定义任务、编排 Agent、审查产出的人”SDLC 的每个环节都被重新切分。我所在的团队从去年开始把整条研发链路往 AI Native 方向迁移踩了非常多的坑也沉淀出一套能落地的完整手册。这套手册覆盖的不是“怎么让 AI 帮你写个函数”这种小打小闹而是从需求进入、任务拆解、Agent 编排、上下文管理、代码审查到上线验证的全流程。核心关键词就几个AI Native、SDLC、Agent、CLAUDE.md、Plan Mode。如果你是一个正在琢磨“怎么把 Agent 真正塞进研发流程”的工程师、Tech Lead 或者团队负责人这篇内容应该能帮你少走至少半年的弯路。先说清楚这套手册解决什么问题。传统 SDLC 里需求、设计、编码、测试、部署是一条线性流水线每个环节由人接力。AI Native 的 SDLC 里这条线被打散成一个个可被 Agent 承接的任务单元人负责的是“定义边界”和“验收结果”。听起来很美但真正落地时会遇到三个致命问题上下文怎么喂、Agent 怎么编排、产出怎么保证质量。这三个问题不解决Agent 就是个玩具。下面我按实际落地顺序把整套手册拆开讲。2. 整体设计思路为什么是“Agent 编排”而不是“AI 补全”2.1 传统 AI 辅助开发的三个天花板大部分团队用 AI 的方式停留在补全层面代码补全、注释生成、单测生成。这种方式有三个绕不过去的天花板。第一是上下文割裂补全工具只能看到当前文件或附近几个文件它不知道你的项目架构、不知道业务约束、不知道历史决策所以生成的代码经常“局部正确、全局错误”。第二是任务粒度太细补全解决的是“这一行怎么写”但研发真正的成本在“这个功能怎么拆、模块怎么交互、边界怎么处理”这些补全工具帮不上忙。第三是无法闭环补全工具生成完就结束了它不会去跑测试、不会去验证、不会根据失败结果自我修正。我见过太多团队买了 AI 编码工具用了两周发现“也就那样”根本原因是他们把 AI 当成了更快的打字机而不是一个能承接完整任务的执行体。要突破这三个天花板必须把粒度从“行”提升到“任务”把角色从“补全器”升级为“Agent”。2.2 Agent 编排的核心把 SDLC 切成可委派的任务单元AI Native 团队的核心动作是把原本由人串行完成的 SDLC切成一个个边界清晰、可独立验收、上下文自包含的任务单元然后把这些单元委派给 Agent。这里的关键不是“切得越细越好”而是“切到 Agent 能独立完成且人能快速验收”的粒度。我们实践下来一个理想的任务单元大概长这样输入是一段明确的需求描述加相关上下文输出是一个可运行、可测试的代码变更验收标准是明确的测试用例或行为断言。比如“给用户模块增加手机号登录接口需要参数校验、错误码定义、单元测试”这就是一个合格的任务单元。而“优化一下系统性能”这种就是不合格的因为它没有边界、没有验收标准Agent 接了也不知道从哪下手。切分粒度直接决定了 Agent 的成败。切太粗Agent 上下文爆炸、容易跑偏切太细人编排的成本比自己做还高。我们的经验值是一个任务单元对应 Agent 一次完整执行产出控制在 200 到 500 行代码变更之间这个粒度下 Agent 的成功率最高人的验收成本也最低。2.3 为什么选 CLAUDE.md 作为上下文锚点Agent 编排里最容易被低估的是上下文管理。Agent 不是人它没有“项目常识”你不告诉它它就瞎猜。我们试过很多种上下文注入方式最后稳定下来的方案是用CLAUDE.md作为项目的上下文锚点文件。CLAUDE.md 的本质是一个放在项目根目录的 Markdown 文件里面写清楚这个项目是什么、技术栈是什么、目录结构怎么组织、有哪些约定俗成的规范、常见的坑有哪些。Agent 每次执行任务前先读这个文件就相当于拿到了“项目入职手册”。这个设计的好处是上下文集中维护、版本可控、所有 Agent 共享同一份事实来源。我们团队的 CLAUDE.md 大概包含这几块内容项目概述一段话说清楚做什么、技术栈清单语言、框架、关键依赖及版本、目录结构说明每个目录放什么、编码规范命名、错误处理、日志规范、测试规范用什么框架、覆盖率要求、常见陷阱比如某个模块不能直接改、某个接口有副作用。这份文件我们要求每个 PR 如果改动了架构或约定必须同步更新否则 review 不通过。提示CLAUDE.md 不要写成百科全书控制在 200 行以内。太长 Agent 读起来也累重点写“Agent 不知道就会犯错”的信息通用常识不用写。2.4 Plan Mode让 Agent 先想后做Agent 最容易翻车的场景是“上来就写代码”。它可能理解错了需求可能选错了方案等你看代码的时候已经写了几百行改起来比重写还累。我们的解法是强制 Agent 进入Plan Mode先输出一份执行计划人确认后再动手。Plan Mode 的具体做法是在给 Agent 的任务描述里明确要求“先输出你的实现计划包括要改哪些文件、每个文件改什么、用什么方案、有什么风险点等我确认后再开始编码”。Agent 输出的计划通常包含任务拆解、文件清单、关键决策点。人只需要花一两分钟扫一眼就能发现方向性问题比如“它居然想直接改数据库 schema”或者“它没意识到这个接口有并发问题”。这个环节看起来多了一步实际省下的是大量返工时间。我们统计过加了 Plan Mode 之后Agent 产出的一次通过率从大概 40% 提升到了 75% 以上。原因很简单方向错了写得再快也是白写。3. 核心细节解析Agent 编排的四个关键机制3.1 任务描述模板把模糊需求变成 Agent 能懂的指令Agent 不是人它不会“揣摩意图”。你给它一句“加个登录功能”它可能给你整出一套完全不符合项目规范的实现。所以任务描述必须模板化。我们团队固定用一套模板包含五个部分背景、目标、约束、验收标准、参考。背景写清楚这个任务在什么场景下产生为什么做。目标写清楚要达成什么效果越具体越好。约束写清楚不能碰什么、必须遵守什么规范。验收标准写清楚怎么判断做完了最好是可执行的测试。参考写清楚有没有类似实现可以借鉴。举个例子同样是“加登录功能”模板化之后是这样背景当前用户只能通过邮箱密码登录产品要求支持手机号验证码登录。 目标新增 POST /api/auth/login-by-phone 接口接收手机号和验证码返回 token。 约束 - 复用现有 token 生成逻辑不要新写一套 - 验证码校验走已有的 SmsService - 错误码遵循项目统一的 ErrorCode 枚举 - 必须写单元测试覆盖成功、验证码错误、手机号不存在三种情况 验收标准单元测试全部通过接口文档同步更新。 参考参考 /api/auth/login 的实现结构。这样一段描述Agent 拿到之后基本不会跑偏。模板化的价值在于消除歧义把“我以为你懂”变成“白纸黑字写清楚”。3.2 上下文分层项目级、任务级、会话级上下文管理是 Agent 编排里最考验工程能力的部分。我们的做法是分三层项目级上下文、任务级上下文、会话级上下文。项目级上下文就是前面说的 CLAUDE.md所有任务共享相对稳定。任务级上下文是这次任务特有的信息比如相关的需求文档、设计稿、涉及的模块代码。会话级上下文是 Agent 执行过程中的中间状态比如它读了哪些文件、做了哪些决策、遇到了什么错误。分层的意义在于控制上下文窗口的占用。Agent 的上下文窗口是有限的如果什么都往里塞很快就会爆掉导致它“忘记”前面的关键信息。我们的策略是项目级常驻任务级按需加载会话级滚动清理。具体实现上任务级上下文通过文件引用方式注入Agent 需要时自己去读而不是一股脑塞进 prompt。注意上下文不是越多越好。我们踩过的坑是给 Agent 塞了太多“可能有用”的信息结果它抓不住重点反而在无关细节上纠结。宁可少给让它主动问。3.3 Agent 分工不同角色用不同配置一个 Agent 干所有事效果往往不好。我们的做法是按角色拆分 Agent每个角色有独立的配置规划 Agent、编码 Agent、审查 Agent、测试 Agent。规划 Agent 负责把需求拆成任务单元输出执行计划它需要强推理能力对代码细节要求不高。编码 Agent 负责按计划写代码它需要强代码能力对项目规范要熟。审查 Agent 负责检查产出它需要能发现问题配置上要偏向“挑刺”。测试 Agent 负责补测试和跑验证它需要理解测试框架和边界条件。不同角色的 Agent 用不同的 prompt 模板、不同的上下文注入策略、甚至不同的模型。比如规划 Agent 用推理强的模型编码 Agent 用代码能力强的模型审查 Agent 用长上下文模型。这种分工看起来复杂实际是把“一个全能 Agent”拆成“几个专精 Agent”每个的成功率都更高。3.4 人在回路哪些环节必须人确认AI Native 不等于“全自动”。有些环节必须人确认否则风险不可控。我们划了三条红线架构变更、数据变更、对外接口变更这三类必须人工 review 后才能执行。架构变更包括新增模块、调整依赖关系、改变通信方式。数据变更包括 schema 修改、数据迁移、索引调整。对外接口变更包括 API 签名变化、返回结构变化、错误码变化。这三类变更一旦出错影响面大、回滚成本高必须人把关。其他环节比如内部函数实现、单元测试、日志调整可以放手让 Agent 做人只在最后验收。这个“红线 放手”的组合既保证了安全又释放了效率。4. 实操过程从需求到上线的完整链路4.1 第一步需求进入与任务拆解需求进来之后第一件事不是写代码是拆任务。我们用一个“需求拆解 Agent”来做这件事。输入是需求文档或产品描述输出是一份任务清单每个任务包含前面说的五要素模板。拆解 Agent 的 prompt 大概是这样的你是一个资深技术负责人请把以下需求拆解成可独立执行的任务单元每个任务单元要满足边界清晰、可独立验收、上下文自包含、代码变更量在 200 到 500 行之间。输出格式用我们约定的模板。拆完之后人要做一次 review重点看三件事任务粒度是否合适、依赖关系是否清晰、有没有遗漏。这一步大概花 10 到 15 分钟但能省下后面大量的返工。4.2 第二步Plan Mode 生成执行计划任务确认后把单个任务交给编码 Agent但要求它先进入 Plan Mode。Agent 会输出一份执行计划包含要改的文件清单、每个文件的改动点、关键实现决策、潜在风险。人 review 这份计划重点看方案是否合理、有没有踩到红线、有没有更好的实现方式。如果计划有问题直接让 Agent 重新规划不要让它带着错误计划往下走。这一步大概花 5 分钟。计划确认后Agent 开始编码。编码过程中Agent 会按需读取相关文件、参考已有实现、遵循 CLAUDE.md 里的规范。这个过程通常几分钟到十几分钟不等取决于任务复杂度。4.3 第三步审查 Agent 与测试 Agent 接力编码完成后不直接给人看先过审查 Agent。审查 Agent 的职责是检查代码质量命名是否规范、错误处理是否完整、有没有明显的 bug、是否符合项目约定。审查 Agent 会输出一份问题清单编码 Agent 根据清单自我修正。修正完成后测试 Agent 接手补单元测试、跑测试、报告结果。如果测试失败测试 Agent 分析失败原因反馈给编码 Agent 继续修。这个“编码-审查-测试”的循环通常跑一到两轮就能收敛。4.4 第四步人工验收与合并Agent 循环收敛后产出交给人验收。人重点看三件事功能是否符合需求、有没有触碰红线、测试是否充分。验收通过后合并不通过则打回附上具体问题让 Agent 继续修。整个链路走下来一个中等复杂度的任务从需求到合并大概 30 到 60 分钟其中人的实际投入时间大概 10 到 15 分钟其余都是 Agent 在执行。相比传统方式效率提升是明显的但更重要的是人的精力从写代码转移到了定义和验收这才是 AI Native 的真正价值。5. 常见问题与排查技巧实录5.1 Agent 跑偏了怎么办Agent 跑偏是最常见的问题表现是它做的事和你的预期不一致。排查思路是从上下文找原因。先看任务描述是否清晰有没有歧义。再看 CLAUDE.md 是否覆盖了相关规范。最后看 Agent 读的文件是否包含了误导性信息。我们遇到过一个典型案例Agent 在实现一个接口时参考了一个废弃的旧实现导致用了过时的错误码。排查发现是 CLAUDE.md 里没有标注哪些实现已废弃。后来我们在 CLAUDE.md 里加了一节“废弃模块清单”问题就解决了。5.2 上下文爆炸怎么处理上下文爆炸的表现是 Agent 执行到一半开始“胡言乱语”或者忘记前面的关键信息。根因是上下文窗口被塞满了。处理方式是精简上下文注入只给必要信息让 Agent 按需读取。具体做法任务描述控制在 500 字以内CLAUDE.md 控制在 200 行以内任务级上下文用文件引用而非全文注入。如果 Agent 需要更多信息它会主动去读文件这时候读进来的内容才是真正相关的。5.3 Agent 之间互相甩锅怎么办多 Agent 协作时容易出现“编码 Agent 说审查 Agent 要求不合理审查 Agent 说编码 Agent 没改对”的循环。我们的解法是设定仲裁规则审查 Agent 提出的问题必须附带具体理由和修改建议编码 Agent 如果不同意必须说明理由双方僵持时由人仲裁。实践中大部分“甩锅”是因为审查 Agent 的要求太模糊比如“代码不够优雅”。后来我们要求审查 Agent 的问题必须可执行比如“这个函数超过 50 行建议拆成两个”问题就少了很多。5.4 常见问题速查表问题现象可能原因排查方向解决方式Agent 产出不符合规范CLAUDE.md 缺失相关约定检查规范覆盖度补充 CLAUDE.mdAgent 理解错需求任务描述有歧义重读任务模板细化任务描述Agent 执行到一半跑偏上下文爆炸检查注入内容量精简上下文多 Agent 循环不收敛审查标准模糊检查审查输出要求可执行建议测试一直失败验收标准不清检查测试用例明确断言条件5.5 几个踩坑心得第一个心得是不要迷信全自动。我们早期尝试过让 Agent 全自动跑完整条链路结果是一旦某个环节出错后面全崩排查成本极高。后来加了人工确认点整体效率反而更高。第二个心得是CLAUDE.md 要持续维护。它不是写完就完事的文档而是活的上下文。每次发现 Agent 犯了新错误就想想是不是 CLAUDE.md 缺了对应约定补上之后同类错误就不会再犯。第三个心得是任务粒度宁细勿粗。粗粒度任务看起来省事实际 Agent 成功率低、返工多。细粒度任务编排成本高一点但成功率高、验收快总体更划算。6. 工具选型与团队适配别照搬要裁剪6.1 Agent 框架怎么选市面上 Agent 框架很多LangChain、Dify、CrewAI 各有侧重。我们的选型逻辑是看团队规模和任务复杂度。小团队、任务简单用轻量框架甚至自己写编排逻辑就够了引入重框架反而是负担。中大团队、任务复杂、需要多 Agent 协作才考虑用成熟框架。选型时重点看三个维度上下文管理能力、多 Agent 编排能力、可观测性。上下文管理决定了 Agent 能不能记住关键信息编排能力决定了多 Agent 能不能协作可观测性决定了出问题时能不能排查。这三个维度比“支持多少模型”重要得多。6.2 不同规模团队的落地节奏10 人以下团队建议从单 Agent 加 CLAUDE.md 起步先把上下文管理跑通再考虑多 Agent。这个阶段重点是让团队习惯“写任务描述”和“review 计划”这两件事。10 到 50 人团队可以引入多 Agent 分工建立任务模板和审查规范。这个阶段重点是标准化把成功的实践固化成模板和流程。50 人以上团队需要考虑 Agent 编排的平台化统一上下文管理、统一任务分发、统一质量度量。这个阶段重点是治理避免各团队各搞一套导致混乱。6.3 度量什么才算落地成功判断 AI Native 是否真的落地不看“用了多少 AI 工具”看三个指标Agent 任务一次通过率、人均有效产出、返工率。一次通过率反映任务描述和上下文管理的质量人均有效产出反映整体效率返工率反映质量控制的水平。我们团队迁移半年后一次通过率从 40% 提升到 75%人均有效产出提升约 60%返工率下降约一半。这些数字不是靠堆工具堆出来的是靠把任务拆解、上下文管理、审查机制这三件事做扎实换来的。7. 我个人的几点体会这套手册不是理论推演是我们团队一行一行代码、一次一次翻车攒出来的。最大的体会是AI Native 的难点不在 AI在工程。Agent 能力再强如果任务描述不清、上下文管理混乱、验收标准模糊照样产出垃圾。反过来把工程基础打扎实哪怕用能力一般的模型也能跑出不错的效果。另一个体会是人的角色变了但没消失。以前人是执行者现在人是定义者和验收者。定义清楚要做什么、验收清楚做得对不对这两件事的价值比写代码更高。团队里适应得快的人都是那些擅长把模糊问题拆成清晰任务的人。最后分享一个小技巧每次 Agent 犯错别急着骂它先问自己“我是不是没告诉它”。十有八九问题出在上下文缺失或任务描述模糊。把每次犯错当成一次上下文补全的机会CLAUDE.md 会越来越厚Agent 会越来越准你的团队也会越来越顺。