AI Native团队研发流程重构：上下文工程与Agent编排落地手册

1. 从用AI写代码到和AI一起交付AI Native团队到底改变了什么大多数团队对AI的用法还停留在补全一段函数解释一段报错的层面工具是工具流程还是老流程。而AI Native团队的本质区别在于交付流程本身被重新设计了。不是给旧SDLC贴一层AI皮肤而是从需求进入的那一刻起人和Agent就在同一套上下文里协作直到代码合入、验证通过。我所在的团队从去年开始把整条研发链路往这个方向迁移中间踩了不少坑也沉淀出一套能跑通的落地方法。这篇手册面向的是正在或准备把AI深度嵌入研发流程的工程师、Tech Lead和平台建设者。它不讲概念讲的是一个需求从进入到交付人和Agent各自负责什么、上下文怎么组织、并发怎么扛、安全边界画在哪里、哪些环节必须留人工卡点。先给一个整体判断AI Native SDLC软件开发生命周期的核心不是更强的模型而是上下文的组织方式和编排层的设计。模型能力是水位编排决定你能用多高的水位干多少活。下面按落地顺序拆开讲。2. 上下文工程CLAUDE.md这类文件为什么是整个体系的基石2.1 没有持久上下文的Agent每次都在从零开始Agent最容易被低估的成本是重新理解项目。你让它改一个接口它得先搞清楚项目用什么框架、目录怎么分、命名规范是什么、测试怎么跑、哪些模块不能碰。这些信息如果每次都靠对话临时喂一是慢二是必然遗漏三是不同会话之间不一致。解决办法是把项目级上下文固化成一个Agent每次都会读取的文件。业界比较通行的做法是在仓库根目录放一个约定命名的说明文件比如CLAUDE.md、AGENTS.md这类内容不是给人看的README而是给Agent看的作业须知。2.2 一份能用的上下文文件应该写什么我试过很多版本最后稳定下来的结构大致是这几块项目定位与边界一句话说清这个仓库干什么以及明确不做什么。Agent很擅长顺手多做边界不写清楚它就会越界改无关模块。技术栈与版本约束框架、语言版本、包管理器、构建命令。版本一定要写死否则Agent会按训练数据里的旧版本写代码。目录结构与职责每个顶层目录负责什么新代码应该放哪里。编码与提交规范命名风格、错误处理约定、提交信息格式。验证方式怎么跑测试、怎么跑lint、怎么本地起服务。这是最容易被忽略但最关键的一块。禁区清单哪些文件、哪些配置、哪些依赖不允许Agent改动。# 项目上下文示例结构 ## 定位 订单服务负责下单、支付回调、订单状态流转。不处理用户账户逻辑。 ## 技术栈 - 语言Go 1.22 - 框架gin - 数据库PostgreSQL 15迁移用 golang-migrate - 测试go test ./...覆盖率要求新增代码 70% ## 目录职责 - internal/handler HTTP入口只做参数校验和调用service - internal/service 业务逻辑禁止直接操作DB - internal/repo 数据访问层 - internal/model 领域模型 ## 禁区 - 不要修改 go.mod 中的依赖版本 - 不要改动 migrations/ 下已存在的迁移文件 - 不要引入新的第三方库除非在PR描述中说明理由注意这份文件要跟着项目演进持续维护。我见过团队写完就放着不管三个月后Agent按过时的规范写代码反而制造了更多返工。2.3 上下文分层项目级、任务级、会话级只有项目级上下文还不够。一个需求进来还需要任务级上下文这个需求要改什么、验收标准是什么和会话级上下文当前这轮对话的临时信息。三层分开管理好处是项目级可以长期复用任务级随需求走会话级用完即弃。我的做法是项目级放仓库里任务级放issue或任务描述里会话级靠对话本身承载。Agent每次启动先读项目级再读任务级然后开始干活。这样即使换一个Agent实例接手上下文也不会丢。3. Plan Mode为什么先让Agent想清楚比直接让它写重要十倍3.1 直接生成的代价让Agent直接写代码最典型的问题是它会在没理解需求的情况下选一个看起来合理的方案然后一路写下去。等你发现方向错了已经生成几百行改起来比自己写还累。Plan Mode的思路很简单先让Agent输出一份执行计划人工确认后再动手。这一步看起来拖慢了速度实际上大幅降低了返工率。我统计过我们团队的数据加了计划确认环节后单个需求的平均返工次数从2.3次降到0.7次。3.2 一份合格的执行计划长什么样计划不是我要实现这个功能这种废话而是要具体到可验证的程度改动范围要动哪些文件新增哪些文件。实现步骤分几步每步做什么步与步之间的依赖关系。关键决策涉及方案选择的地方说明为什么选A不选B。验证方式每步做完怎么验证最终怎么验收。风险点哪些地方可能出问题需要人工重点看。需求订单支持部分退款 执行计划 1. 在 model 层新增 RefundRecord 结构记录退款金额、时间、操作人 - 决策不复用现有 Payment 结构因为退款和支付的生命周期不同 2. 在 repo 层新增退款记录的读写方法 3. 在 service 层实现部分退款逻辑 - 校验退款金额 订单可退金额 - 更新订单状态为 partial_refunded - 写入退款记录 4. 在 handler 层新增 POST /orders/:id/refund 接口 5. 补充单元测试覆盖正常退款、超额退款、重复退款 验证go test ./... 全绿手动调用接口验证三种场景 风险并发退款场景需要加锁计划中用数据库行锁处理3.3 计划确认环节的人工卡点计划确认不是走形式。我要求团队在确认计划时重点看三件事改动范围是否超出预期、关键决策是否合理、验证方式是否覆盖了边界情况。这三件事任何一件有问题都打回去重做计划。这个卡点花5分钟能省下后面半小时的返工。4. Agent编排单Agent、多Agent和Harness的边界在哪4.1 先搞清楚Harness和Agent的区别很多人把这两个概念混着用。简单说Agent是干活的Harness是管Agent怎么干活的。Harness负责调度、上下文注入、工具调用、结果校验、错误重试这些编排逻辑Agent负责在给定上下文下完成具体任务。打个比方Agent是工人Harness是工头加流水线。工人再强没有好的流水线也出不了活。很多团队一上来就追求更强的Agent其实瓶颈往往在Harness这一层。4.2 单Agent够用的场景不是所有任务都需要多Agent。以下场景单Agent完全够用任务边界清晰改动集中在一两个模块不需要跨领域知识比如既懂前端又懂数据库验证方式明确跑个测试就知道对不对单Agent的好处是上下文简单、调试容易、成本低。我建议默认从单Agent开始遇到明确的瓶颈再拆。4.3 什么时候需要多Agent多Agent的价值在于上下文隔离和并行。典型场景场景单Agent的问题多Agent的解法前后端联调上下文太长容易顾此失彼前端Agent和后端Agent各自维护上下文大规模重构一次改太多容易失控按模块拆分每个Agent负责一块需要多轮验证自己写自己验容易自洽一个写一个独立验证探索性任务单线程试错慢多个Agent并行探索不同方案但多Agent的代价是编排复杂度上升、上下文同步成本高、调试困难。我的经验是只有当单Agent的上下文确实装不下或者任务确实可以并行时才上多Agent。4.4 编排层要处理的核心问题不管单Agent还是多Agent编排层都要解决这几个问题上下文注入什么时候注入什么上下文注入多少。注入太多会稀释重点太少会缺信息。工具调用Agent能调哪些工具调用结果怎么回传。结果校验Agent的输出怎么验证验证失败怎么处理。错误重试失败了重试几次重试时要不要换策略。状态管理多步任务中间状态怎么存中断了怎么恢复。这些问题的处理质量直接决定了整套体系能不能稳定跑起来。5. 并发AI Agent怎么扛住真实团队的负载5.1 并发问题的本质Agent的并发不是简单的多开几个实例。真实团队里多个需求同时推进每个需求可能对应多个Agent任务这些任务共享仓库、共享CI资源、共享上下文文件。并发问题主要出在三个地方仓库冲突两个Agent同时改同一个文件合并时冲突。资源竞争CI流水线、测试环境、数据库被多个任务同时占用。上下文污染一个任务的中间状态影响了另一个任务。5.2 隔离策略我们的做法是按任务隔离工作区。每个Agent任务在独立的git worktree或独立分支上工作互不干扰。合并时按顺序来冲突在合并阶段解决而不是在生成阶段。# 为每个任务创建独立worktree git worktree add ../task-1234 -b feature/task-1234 # Agent在 ../task-1234 目录下工作 # 完成后合并回主分支资源层面CI流水线按任务排队测试环境用容器隔离每个任务起一套独立的依赖服务。这样即使某个任务把环境搞坏了也不影响其他任务。5.3 上下文隔离多任务并行时上下文文件不能共享可变状态。项目级上下文是只读的任务级上下文每个任务独立会话级上下文用完即弃。这样设计的好处是任何一个任务的上下文出问题都不会扩散到其他任务。5.4 并发下的成本控制Agent并发跑起来token消耗是线性增长的。我们设了几个闸单任务token上限超了就中断人工介入并发任务数上限根据团队实际吞吐量定简单任务用轻量模型复杂任务才用重模型定期清理无效的上下文注入这些闸门看起来限制了能力实际上是保证了整套体系不会因为成本失控而被迫停摆。6. 安全边界Agent能碰什么不能碰什么6.1 权限最小化Agent的权限要按最小必要原则给。能读的就不给写能写测试的就不给写生产配置。具体来说文件系统限制在项目目录内禁止访问系统目录和敏感路径网络限制可访问的域名禁止访问未知外部服务命令执行白名单机制只允许执行预定义的命令凭证Agent不直接持有生产凭证需要时通过受控通道获取6.2 敏感操作的人工卡点以下操作必须人工确认不能由Agent自主执行修改生产环境配置执行数据库迁移合并到主分支发布版本修改权限相关代码这些卡点不是不信任Agent而是风险不对称Agent做对了省几分钟做错了可能造成小时级的故障。卡点的成本远低于故障成本。6.3 审计与追溯每个Agent任务都要有完整的审计记录谁发起的、用了什么上下文、执行了哪些操作、产生了什么结果。出问题时能快速定位是哪一步出的错。我们的做法是把Agent的每一步操作都记到日志里和CI流水线的记录关联起来。6.4 代码审查不能省Agent生成的代码必须经过人工审查才能合入。审查的重点不是语法Agent语法一般没问题而是业务逻辑正确性和边界情况处理。我见过Agent写出语法完美但业务逻辑完全错误的代码这种错误只有懂业务的人才能发现。7. 落地路线从一个小场景开始别一上来就搞大平台7.1 选第一个场景的原则第一个落地场景要满足边界清晰、验证明确、失败成本低。比如补充单元测试修复明确的bug写文档和注释小范围的重构不要一上来就选核心业务逻辑失败成本太高一旦出问题整个团队对这套体系的信心就没了。7.2 逐步扩展的节奏我们的扩展节奏大致是第一阶段单Agent 项目级上下文跑通需求到代码的闭环第二阶段加入Plan Mode降低返工率第三阶段引入多Agent处理需要并行或上下文隔离的场景第四阶段完善编排层处理并发、安全、审计每个阶段跑稳了再进下一个不要跳步。7.3 团队协作方式的调整AI Native不只是工具变化团队协作方式也要跟着调需求描述要更精确Agent不会猜你的意图需求写得模糊产出就模糊验收标准要前置在需求阶段就定义清楚怎么算完成代码审查重点转移从写得对不对转向逻辑对不对知识沉淀方式变化项目知识要写成Agent能读的格式而不只是人读的文档7.4 常见误区最后列几个我见过或踩过的误区追求全自动以为Agent能端到端搞定一切结果发现关键环节还是得人工。正确做法是找到人机协作的最佳分工点。忽视上下文维护上下文文件写完就不管导致Agent按过时规范工作。过早多Agent单Agent还没跑稳就上多Agent编排复杂度直接压垮团队。安全后置先跑起来再说安全结果出了事故才补代价大得多。只看模型能力以为换个更强的模型就能解决所有问题忽视了编排和上下文的作用。这套体系我们跑了大半年最大的体会是AI Native的难点不在AI在Native。把AI嵌进现有流程很容易难的是重新设计流程让AI真正发挥作用。上下文怎么组织、编排怎么做、边界怎么画这些才是决定成败的地方。模型会一直变强但这些工程问题不会因为模型变强就消失。