1. 从“人写代码”到“人管意图”AI Native 团队到底在改什么先说一个我观察到的现象。过去两年我参与过几个号称“全面拥抱 AI”的研发团队结果大多分成两派一派把 AI 当成高级自动补全写代码快了一点但流程没变另一派买了几套 Agent 平台演示时很惊艳真到项目里就卡在“谁来审、谁来兜、出错算谁的”上最后不了了之。这两派的共同问题是他们把 AI 塞进了旧流程而不是围绕 AI 重建流程。AI Native 团队的核心变化不是“用不用 AI”而是研发流程的默认执行者从人变成了 Agent人的角色从“生产者”上移到“意图定义者与验收者”。这句话听起来抽象落到日常就是以前你写一个需求是拆成任务分给人现在你写一个需求是先写成一份机器能读懂的规格文件让 Agent 去执行人只在关键节点做判断。这个转变对应的就是 SDLC软件开发生命周期的重构也就是热词里反复出现的 ai-native sdlc playbook。那这份“落地手册”到底解决什么问题它解决的是从“能跑通一个 Demo”到“团队每天稳定产出”之间的鸿沟。Demo 阶段你只需要一个 Agent 帮你改个函数生产阶段你要面对的是多个 Agent 并行、上下文怎么传、权限怎么收、失败了怎么回滚、成本怎么控、质量怎么保证。这些才是真正卡住绝大多数团队的地方。这篇文章适合三类人看一是正在推动团队 AI 化转型的技术负责人你需要一套可落地的流程而不是概念二是已经用过 Claude Code、Codex 这类工具但觉得“没想象中好用”的一线工程师你需要知道问题出在流程设计而不是工具本身三是刚开始接触 Agent 开发、想搞清楚 Agent 框架与编排到底怎么落地的人。我会尽量把每个环节的“为什么”讲透而不是只丢一堆配置。需要提前说明的是AI Native 不是一个可以“一键切换”的状态它更像是一个渐进式的成熟度模型。下面我会按一个团队从零搭建这套体系的真实顺序来展开中间会穿插我自己踩过的坑和实测有效的做法。2. 规格先行CLAUDE.md 这类文件为什么是整套体系的地基2.1 没有规格文件Agent 就只是个“猜你想干嘛”的机器很多人第一次用 Agent 写代码体验是这样的你给它一句话“帮我加个用户登录”它噼里啪啦生成一堆代码看起来挺像那么回事但跑起来各种问题——字段名对不上、错误处理缺失、和你项目里既有的鉴权体系完全不兼容。于是你得出结论“Agent 也就那样还是得自己写。”问题不在 Agent在于你没给它“项目上下文”。一个刚入职的工程师你不给他看代码规范、不给他说清楚项目架构直接让他改核心模块他也会写崩。Agent 同理而且它比人更依赖显式输入——它不会主动问你“咱们项目用的是什么 ORM”。这就是 CLAUDE.md 这类规格文件的价值。它本质上是一份写给机器看的项目说明书放在仓库根目录Agent 每次启动都会读取。它要回答几个核心问题这个项目是干什么的、技术栈是什么、目录结构怎么组织、代码风格有什么约定、哪些操作是禁止的、测试怎么跑、提交信息怎么写。我见过太多团队跳过这一步直接上 Agent然后抱怨效果差。这就像盖楼不打地基楼越高越危险。规格文件不是可选项它是整套 AI Native 流程的第一块砖。2.2 一份能用的规格文件该写什么我自己的模板通常包含这几块你可以直接拿去改# 项目规格说明 ## 项目概述 一句话说明项目定位以及当前处于什么阶段。 ## 技术栈 - 语言与版本 - 框架与关键依赖 - 数据库与缓存 - 部署方式 ## 目录结构 用树状结构列出核心目录并说明每个目录放什么。 ## 代码规范 - 命名约定 - 错误处理方式 - 日志规范 - 注释要求 ## 禁止事项 - 不允许直接改动的文件 - 不允许引入的依赖 - 不允许的操作如直接操作生产库 ## 常用命令 - 安装依赖 - 启动开发环境 - 跑测试 - 构建 ## 提交规范 提交信息格式、分支命名规则。这里有个关键经验规格文件要短而准不要写成百科全书。我一开始犯的错是把所有细节都塞进去结果文件几千行Agent 读取时反而抓不住重点还浪费上下文窗口。后来我改成“核心规范 按需引用的子文档”结构主文件控制在两百行以内细节放到docs/目录下需要时再让 Agent 去读。另一个坑是规格文件会过期。项目演进后技术栈变了、目录调整了但规格文件没更新Agent 就会按旧规则干活产出全是错的。我的做法是把它纳入代码评审任何影响项目结构的改动必须同步更新规格文件否则 PR 不通过。这条规则执行下来规格文件才真正“活”着。2.3 规格文件与 Agent Skill 的关系热词里有个概念叫 agent skill还有一篇流传很广的文章叫 claude agent skills: a first principles deep dive。简单说Skill 是比规格文件更细粒度的能力封装。规格文件告诉 Agent“这个项目是什么样”Skill 告诉 Agent“遇到某类任务该怎么做”。举个例子规格文件里写“本项目使用 PostgreSQL”而一个“数据库迁移 Skill”会详细说明迁移文件放哪、命名规则、怎么写回滚、怎么在测试环境验证。当 Agent 遇到迁移任务时它会加载这个 Skill按既定套路执行。我的建议是先有规格文件再逐步沉淀 Skill。不要一上来就设计一堆 Skill因为你还不清楚团队真正高频的任务是什么。等跑了一段时间你会发现某些任务反复出现、每次都要重新解释这时候把它固化成 Skill 最划算。这跟写代码时“三次重复再抽象”是一个道理。3. Plan Mode为什么“先让 Agent 说清楚要干嘛”能省掉一半返工3.1 直接执行 vs 先规划差距有多大我做过一个对比实验。同一个需求“给订单模块加一个超时自动取消功能”分别用两种方式让 Agent 执行。第一种直接下指令“给订单模块加超时自动取消功能。”Agent 立刻开始改代码生成了定时任务、修改了订单状态机、加了配置项。看起来很快但 review 时发现它选的定时方案和项目里既有的调度框架冲突状态机改动影响了另外两个业务流程配置项命名也不符合规范。返工成本极高。第二种先进入 Plan Mode“请先分析这个需求列出实现方案、涉及的文件、潜在影响不要动代码。”Agent 输出了一份计划它识别出项目已有调度框架、指出了状态机的三个调用方、建议了配置命名。我 review 这份计划改了两处然后让它执行。一次通过。差距就在这。Plan Mode 的本质是把“思考”和“执行”分离让人的判断力作用在最便宜的环节——改一份文字计划而不是改一堆已经写进代码库的东西。热词里 Plan Mode 被反复提及不是没有道理的。3.2 Plan Mode 的实操要点用 Plan Mode 有几个细节决定成败。第一计划要包含“影响面分析”。我要求 Agent 在计划里必须回答这个改动会影响哪些现有功能、哪些测试可能失败、有没有需要同步更新的文档。这一条能挡掉大量“改一处崩三处”的事故。第二计划要可评审、可修改。好的 Plan Mode 不是 Agent 自说自话而是输出一份你能直接编辑的文档。你可以在上面划掉不认可的方案、补充遗漏的约束然后让它按修改后的计划执行。这个过程很像技术方案评审只不过评审对象从人变成了 Agent。第三复杂任务要分层规划。一个涉及十几个文件的大需求不要指望一次规划到位。我的做法是先让它出“高层计划”分几个阶段、每阶段目标确认后再对每个阶段出“详细计划”。这跟人做项目拆解是一个逻辑。注意Plan Mode 不是万能的。对于改个错别字、调个日志级别这种小任务走规划流程反而拖慢节奏。我的经验是涉及三个以上文件、或者触及核心逻辑的改动才值得走 Plan Mode。3.3 计划评审时我重点看什么评审 Agent 的计划我通常盯这几个点方案是否复用了项目既有能力。Agent 很容易“重新造轮子”因为它不知道项目里已经有现成工具。计划里如果出现新的工具类、新的依赖我会追问为什么不用现有的。边界条件是否覆盖。超时取消要考虑订单已支付怎么办、正在退款怎么办、并发取消怎么处理。计划里没提的我会补上。回滚方案是否存在。任何涉及数据变更的改动计划里必须有回滚思路。没有的话直接打回。测试策略是否明确。改完怎么验证单元测试加在哪、要不要加集成测试、手动验证步骤是什么。这套评审标准用熟了之后你会发现 Agent 的计划质量也在提升——因为你的反馈本身就是在“训练”它理解你的标准。4. Agent 编排多 Agent 协作不是越多越好4.1 单 Agent 的天花板在哪单 Agent 能处理的任务是有上限的。当任务复杂度上升你会遇到几个瓶颈上下文窗口塞不下所有相关信息、一个 Agent 同时扮演多个角色容易混乱、串行执行效率低。我遇到的最典型场景是“全栈功能开发”既要改后端接口又要改前端页面还要写测试和文档。让一个 Agent 从头做到尾它会在前后端之间反复横跳上下文里塞满了不相关的信息最后哪块都做得不干净。这时候就需要多 Agent 编排。但这里有个巨大的误区很多人以为 Agent 越多越好搞出一堆角色结果协调成本爆炸。我见过一个团队设计了七个 Agent——需求分析、架构设计、后端、前端、测试、文档、评审结果每个 Agent 都要读一遍完整上下文token 成本翻了好几倍而且 Agent 之间的交接经常丢信息。4.2 我实际用的编排模式经过几轮迭代我稳定下来的模式是“一个主 Agent 按需派生的子 Agent”。主 Agent 负责理解整体需求、制定计划、协调子任务。当遇到可以独立完成的子任务时它派生一个子 Agent把最小必要的上下文传过去子 Agent 完成后把结果交回。这样每个子 Agent 的上下文都是干净的不会被无关信息污染。具体到全栈功能开发流程是这样的主 Agent 读需求产出整体计划。派生“后端 Agent”传入接口规格和数据库 schema让它实现后端。派生“前端 Agent”传入接口契约和 UI 规范让它实现前端。主 Agent 汇总派生“测试 Agent”做集成验证。关键在于接口契约要先定好。前后端 Agent 并行工作时如果接口没定清楚两边对不上返工比串行还慢。所以主 Agent 的第一件事是把契约敲定这跟人做前后端分离开发是一个道理。4.3 Agent 框架与编排工具怎么选热词里 agent框架、agent平台、agent scope、spring ai agent 这些词出现频率很高说明大家都在纠结选型。我的看法是先想清楚你要解决的是“编排”还是“能力”问题。如果你只是想让 Agent 按固定流程干活一个轻量的编排层就够了不需要引入重型框架。如果你需要复杂的多 Agent 协作、状态管理、可观测性那才考虑成熟框架。选型时我重点看几个维度维度关注点我的取舍上下文管理能否精细控制传给每个 Agent 的信息必须有否则成本失控可观测性能否看到每个 Agent 的输入输出和耗时必须有否则出问题没法排查失败处理Agent 执行失败后能否重试或降级必须有生产环境必然遇到学习成本团队上手要多久优先选团队已有技术栈的生态成熟度社区活跃度、文档质量参考但不迷信有个热词叫 agent execution terminated due to error这是很多人踩过的坑。Agent 执行到一半报错终止前面的工作全白费。所以失败处理机制是选型时的硬指标好的编排应该支持断点续跑而不是从头再来。4.4 并发场景下 Agent 怎么扛热词里有个很实际的问题ai agent 怎么扛并发。这确实是生产环境的痛点。Agent 扛并发和传统服务扛并发不一样。传统服务是无状态的加机器就行Agent 是有状态的每个任务都有自己的上下文而且很多操作比如改同一个文件不能并行。我的做法是按资源维度做隔离。不同任务如果操作的是不同文件、不同模块可以并行如果会碰同一块资源就串行或者加锁。这跟数据库的并发控制是一个思路。另外Agent 的并发瓶颈往往不在计算而在外部依赖调用大模型的 API 有速率限制、读写代码仓库有冲突风险、跑测试要抢环境。所以真正的并发设计是把这些外部依赖的瓶颈识别出来分别做限流和排队。提示不要一上来就追求高并发。先把单任务的稳定性和成功率做上去再逐步放开并发。我见过太多团队并发上去了但失败率也跟着上去了最后产出还不如串行。5. 记忆与上下文Agent 为什么总是“记不住”5.1 短期记忆、长期记忆与工作记忆Agent 的“记忆”问题是实际使用中最让人抓狂的。你跟它聊了半小时它突然忘了前面说过的约束你昨天让它做的事今天它完全不记得。要解决这个问题先得分清楚几种记忆。热词里提到的 agent 存储 working memory指的就是工作记忆——Agent 在当前任务中临时保存的信息。除此之外还有短期记忆当前会话和长期记忆跨会话持久化。我的实践是分层处理工作记忆放在上下文里任务结束就丢弃。比如当前正在改的文件内容、刚跑完的测试结果。短期记忆用会话摘要的方式保留。长会话定期压缩成摘要避免上下文爆炸。长期记忆落到外部存储。项目规范、历史决策、常见问题的解决方案这些写进规格文件或知识库需要时检索。很多团队的问题是把所有东西都往上下文里塞结果要么超限要么关键信息被淹没。记忆管理的核心不是“记住更多”而是“在对的时候取出对的信息”。5.2 上下文工程比提示词更重要的能力现在大家都很重视提示词工程但我认为上下文工程比提示词工程更重要。提示词决定 Agent“怎么想”上下文决定 Agent“知道什么”。知道得不对想得再好也白搭。上下文工程要解决三个问题放什么、放多少、什么时候放。放什么只放和当前任务相关的信息。改后端接口时不需要把前端代码塞进去。放多少控制在模型有效处理范围内。超长上下文不仅贵而且模型对中间部分的注意力会下降这是有研究支持的。什么时候放按需加载。Agent 需要查数据库 schema 时再去读而不是一开始就全塞进去。我常用的一个技巧是给上下文加“目录”。不直接把所有文件内容给 Agent而是先给它一份文件清单和每个文件的简要说明让它自己决定要读哪些。这样既省 token又让 Agent 有主动权。5.3 让 Agent 自己维护记忆一个进阶做法是让 Agent 自己维护一份“工作笔记”。每完成一个阶段让它把关键决策、遇到的问题、解决方案记下来存到指定文件。下次继续时先读这份笔记。这个做法我实测很有效尤其是在跨天的大任务上。Agent 第二天启动时读一遍笔记就能快速进入状态不用你重新解释一遍背景。而且这份笔记本身也是很好的项目文档人也能看。要注意的是笔记要结构化不能是流水账。我通常要求按“已完成 / 进行中 / 待办 / 关键决策 / 已知问题”几个板块组织。这样无论是 Agent 还是人扫一眼就能抓住重点。6. 安全与权限Agent 能碰什么不能碰什么6.1 最小权限原则在 Agent 场景的落地Agent 安全是绕不开的话题。热词里 agent安全 被单独列出来说明大家已经意识到风险。我见过最惊险的一次是 Agent 在执行“清理临时文件”任务时差点删掉了一个命名相似的源码目录。幸好当时做了权限限制。最小权限原则在这里必须严格执行。Agent 默认不应该有直接操作生产数据库的权限、删除文件的权限、推送代码到主分支的权限、访问敏感配置的权限。我的做法是给 Agent 划定一个“工作沙盒”它只能读写指定目录、只能操作测试环境、只能创建分支不能直接合并。需要更高权限的操作必须由人显式授权而且授权是单次的不是永久的。6.2 危险操作的拦截清单有些操作无论 Agent 多聪明都应该被硬性拦截。我维护了一份清单删除操作任何rm -rf类命令必须人工确认。数据库变更DDL 语句、批量 UPDATE/DELETE必须走评审。依赖变更新增或升级核心依赖必须人工审核。配置修改涉及环境变量、密钥的改动必须人工介入。对外请求Agent 不应该主动向外部服务发送数据。这份清单要写进规格文件的“禁止事项”并且在编排层做技术拦截不能只靠 Agent“自觉”。6.3 审计与可追溯Agent 干的每一件事都要能追溯。这不是为了监控而是为了出问题时能快速定位。我要求所有 Agent 操作都记录什么时间、哪个 Agent、执行了什么、输入是什么、输出是什么、结果如何。这些日志在排查问题时价值极高。有一次线上出了个诡异 bug最后就是靠 Agent 的操作日志定位到是某次自动重构引入的。审计日志还有个附带好处它是优化流程的依据。哪些任务 Agent 做得好、哪些经常失败、平均耗时多少这些数据能指导你决定下一步该把什么任务交给 Agent。7. 质量把关Agent 产出的代码凭什么能上线7.1 自动化验证是第一道防线Agent 写的代码第一道关卡必须是自动化验证。我的流水线里Agent 提交的代码会自动触发静态检查、单元测试、集成测试、构建。任何一项不过直接打回不进入人工评审。这一步能挡掉大部分低级问题语法错误、风格不符、测试失败。让 Agent 自己修修到全绿为止。这个过程通常不需要人介入Agent 根据报错信息自己就能改。关键是要把验证标准写清楚。规格文件里要说明测试覆盖率要求多少、静态检查用哪些规则、构建产物要满足什么条件。标准越明确Agent 自我修复的成功率越高。7.2 人工评审该看什么自动化验证过了不代表代码就能上线。人工评审要聚焦在自动化查不出来的地方设计合理性方案是不是最优的、有没有更好的复用方式。边界处理异常情况、并发情况、极端输入有没有考虑。可维护性命名是否清晰、逻辑是否好懂、有没有留下技术债。业务正确性代码逻辑是否真的符合业务需求这个只有懂业务的人能判断。我的经验是评审 Agent 代码和评审人写的代码关注点略有不同。Agent 代码通常“表面工整”但容易在业务语义上出偏差。所以我会特别关注业务逻辑部分而不是纠结代码风格——风格问题交给自动化工具。7.3 建立“Agent 产出质量”的度量要持续改进就得有度量。我跟踪几个指标一次通过率Agent 提交后无需返工的比例、平均返工次数、人工评审发现的问题类型分布。这些数据能告诉你很多信息。比如一次通过率低可能是规格文件不够清晰返工集中在某类问题说明那类任务的 Skill 需要完善评审总发现业务偏差说明需求描述环节要加强。我自己的团队跑下来一次通过率从最初的不到三成逐步提升到七成以上。提升主要来自三方面规格文件越来越完善、Skill 库越来越丰富、需求描述越来越规范。这是个正向循环。8. 成本控制Agent 跑起来之后账单怎么管8.1 成本都花在哪了Agent 的成本比想象中复杂。不只是模型调用费用还包括上下文重复读取的浪费、失败重试的消耗、并行任务的资源占用、人工介入的时间成本。我做过一次成本拆解发现最大的浪费来自上下文重复。同一个项目背景每个 Agent 启动都读一遍读了几十遍。后来我把公共上下文做成缓存只在必要时刷新成本直接降了一大截。另一个浪费是失败重试。Agent 执行失败后从头再来前面的 token 全白花。支持断点续跑之后这部分浪费也大幅减少。8.2 我的成本优化手段几个实测有效的做法模型分级简单任务用轻量模型复杂任务才用强模型。不是所有活都需要最强的模型。上下文缓存公共信息缓存起来避免重复读取。任务批处理把多个小任务合并成一批处理减少启动开销。结果复用相似任务的产出可以复用不必每次重来。预算告警设置成本阈值超了自动告警避免失控。提示成本控制不是一味省钱。有些地方该花就得花比如关键任务的验证环节。省了验证的钱出了事故的代价更大。关键是找到性价比的平衡点。8.3 成本与质量的平衡这里有个反直觉的结论有时候多花点钱反而更省。比如让 Agent 在 Plan Mode 多花点 token 做规划能省掉后面大量返工让它在提交前多做一轮自检能减少人工评审的负担。我判断的标准是这笔花费能不能减少下游的返工或人工介入。能就值得花不能就优化掉。单纯看 token 消耗数字做决策往往会做出错误的选择。9. 团队协作人和 Agent 怎么分工9.1 重新定义人的角色AI Native 团队里人的角色发生了根本变化。以前工程师大部分时间在写代码现在写代码的比重下降更多时间花在定义需求、评审计划、验收产出、处理异常。这不是说工程师不重要了而是重要的点变了。以前拼的是编码速度和熟练度现在拼的是判断力和架构能力。你能不能把一个模糊需求拆成清晰的规格你能不能看出 Agent 方案里的隐患你能不能设计出 Agent 友好又安全的流程——这些才是核心竞争力。我团队里的工程师现在花在“写”上的时间大概占三成剩下七成在“想”和“审”。一开始有人不适应觉得“不写代码还叫工程师吗”。但跑顺之后大家发现产出效率反而高了而且人有更多精力去思考真正有价值的问题。9.2 协作流程怎么设计人和 Agent 的协作流程我总结成一句话人定边界Agent 填内容人做验收。具体到日常需求进来人先把它翻译成规格可以是文档也可以是结构化的任务描述。Agent 读规格出计划人评审计划。计划通过Agent 执行人处理执行中的异常。执行完成自动化验证人做最终评审。上线后人负责监控和复盘。这个流程里人始终在关键节点上但不在每个细节上。这样既保证了质量又释放了效率。9.3 团队能力建设推动 AI Native 转型团队能力要跟上。我重点培养三方面规格写作能力能把需求写成 Agent 能懂的规格这是新基本功。计划评审能力能快速看出 Agent 方案的问题这需要扎实的技术功底。流程设计能力能设计出高效又安全的协作流程这需要系统思维。培训方式我倾向于“实战 复盘”。让每个人实际跑一遍完整流程然后一起复盘哪里卡了、怎么改进。比单纯讲课有效得多。10. 落地路线图从零到稳定产出的分阶段推进10.1 第一阶段单点验证不要一上来就全团队铺开。先选一两个愿意尝试的工程师选一个边界清晰的小项目跑通完整流程。目标是验证“这套方法在我们团队能不能work”。这个阶段重点解决规格文件怎么写、Plan Mode 怎么用、基本的验证流程怎么搭。不要追求效率追求的是把流程跑通、把坑踩出来。10.2 第二阶段流程固化单点验证成功后把有效的做法固化成团队规范。规格文件模板、Plan Mode 使用规范、评审清单、安全红线这些都沉淀下来。这个阶段会暴露很多协作问题不同人对规格的理解不一致、评审标准不统一、Agent 产出质量波动大。解决这些问题的过程就是流程成熟的过程。10.3 第三阶段规模化与优化流程稳定后逐步扩大范围同时做优化沉淀 Skill 库、优化上下文管理、完善成本控制、建立度量体系。这个阶段的关键是持续迭代。AI 工具和能力在快速演进流程也要跟着调整。我每个季度会做一次流程复盘看看哪些环节可以优化、哪些新能力可以引入。10.4 我踩过的几个大坑最后分享几个我实际踩过的坑帮你少走弯路。坑一过早追求自动化。一开始就想让 Agent 全自动干活结果质量失控。正确做法是先人机协作等流程稳定了再逐步提高自动化程度。坑二忽视规格文件维护。规格文件写完就不管了几个月后完全对不上项目现状Agent 按旧规则干活全是错的。必须把维护规格文件纳入日常流程。坑三Agent 数量失控。觉得 Agent 越多越厉害搞了一堆角色协调成本远超收益。记住编排的目标是解决问题不是炫技。坑四只看效率不看质量。短期内产出速度上去了但技术债堆积几个月后维护成本爆炸。质量和效率必须一起抓。坑五忽略人的适应过程。流程变了人的工作方式也要变但很多人会抵触。要给团队适应时间也要让大家看到新流程的好处。这套体系跑下来我最大的体会是AI Native 不是买几个工具就能实现的它是一次流程和思维的重构。工具会变模型会升级但“规格先行、计划评审、最小权限、持续验证”这些原则是稳定的。把这些原则吃透无论工具怎么变你都能快速适配。如果你正准备在团队里推这套东西我的建议是从一个小项目开始别贪大。跑通一个比规划十个更有价值。