1. 从“堆人”到“造系统”AI Native 团队到底在变什么这两年带团队做研发最直观的感受就是以前一个需求从评审到上线中间要经过产品、设计、前端、后端、测试、运维至少六七个角色接力一个中等复杂度的功能排期两周起步。现在呢一个熟悉 AI Native 工作流的工程师配上几个靠谱的 Agent从写第一行代码到跑通端到端流程可能一个下午就搞定了。这不是夸张是我自己团队里反复验证过的节奏。AI Native 团队这个词听起来很唬人但拆开看其实就一句话把 AI 当成团队的一等公民而不是一个“辅助工具”。传统团队里 AI 是副驾驶帮你补全代码、写写注释AI Native 团队里 AI 是执行单元人负责定义目标、拆解任务、审查结果。这个转变带来的不是效率提升百分之几十而是整个SDLC软件开发生命周期的重构。我见过太多团队卡在中间态买了 Copilot 账号每个人装了个插件然后呢还是老一套流程还是人肉写 PRD、人肉写测试用例、人肉 review 每一行代码。工具升级了范式没升级效果自然出不来。这篇手册想聊的就是范式升级这件事——从CLAUDE.md这样的项目上下文约定到Plan Mode这样的任务规划机制再到多 Agent 编排和并发扛压把一套能落地的 AI Native 开发手册完整拆开讲。适合谁看如果你是小团队的技术负责人正在琢磨怎么用 AI 把交付速度拉起来如果你是独立开发者想搞清楚 Agent 到底怎么搭、怎么管、怎么不翻车或者你只是对 AI Native 这个词好奇想知道它跟“用 AI 写代码”到底差在哪——那这篇内容应该能给你一些直接能抄的作业。2. AI Native SDLC 的整体设计与思路拆解2.1 为什么传统 SDLC 在 AI 时代会失灵传统 SDLC 的核心假设是人是唯一的执行单元。需求分析、架构设计、编码、测试、部署每个环节都需要人投入时间所以流程设计的目的是“减少返工、提高协作效率”。瀑布模型、敏捷、Scrum本质上都是在优化人的协作方式。但 AI Native 的假设变了执行单元可以是 Agent。一个 Agent 可以同时读十个文件、写五个模块、跑三套测试而且不会累、不会抱怨、不会因为周五下午就摸鱼。这时候如果还用“人天”来估算工作量用“站会”来同步进度用“代码行数”来衡量产出整个管理体系就跟实际生产力脱节了。我踩过的一个典型坑早期让 Agent 帮忙写一个模块我按传统方式给它拆了任务每个任务写清楚输入输出然后等它交付。结果它十分钟就写完了但我花了两小时 review 和调试。问题出在哪我把 Agent 当成了一个“远程外包”而不是一个“需要上下文和约束的协作者”。后来我调整了方式先写CLAUDE.md把项目约定、代码风格、目录结构、常用命令全部固化下来再让 Agent 动手review 时间直接砍半。2.2 AI Native SDLC 的四层结构我把这套流程拆成四层从下往上分别是第一层上下文层。这是地基。包括项目级的CLAUDE.md、模块级的 README、接口文档、数据字典。Agent 不是人它不会“猜”你的意图你给它的上下文越完整它的输出越靠谱。这一层的核心原则是凡是人需要问的问题都提前写进上下文。第二层规划层。对应Plan Mode。Agent 接到任务后先不写代码而是输出一份执行计划要改哪些文件、新增哪些模块、依赖什么、风险点在哪。人审查计划确认后再进入执行。这一层解决的是“Agent 跑偏”的问题——与其等它写完再返工不如在计划阶段就拦住。第三层执行层。Agent 按计划动手包括写代码、跑测试、修 bug、提交 PR。这一层的关键是沙盒隔离和权限控制。Agent 不能直接往主分支推代码不能访问生产环境不能执行危险命令。我一般会给 Agent 一个独立的 worktree 或者容器环境让它随便折腾折腾完了再合并。第四层审查层。人 review Agent 的产出包括代码质量、测试覆盖、边界情况。这一层不是“逐行看”而是“看关键决策点”为什么选这个方案、为什么忽略那个边界、有没有引入新的依赖。审查通过后合并、部署、上线。这四层跑通之后一个典型的功能开发流程就变成了人写需求描述 → Agent 输出计划 → 人确认计划 → Agent 执行 → 人审查结果 → 合并。人的介入点从“全程参与”变成了“关键节点把关”时间投入大概能压缩到原来的三分之一甚至更少。2.3 方案选型的几个关键取舍在搭这套流程的时候有几个选择我反复权衡过这里直接说结论和理由。第一个取舍用现成 Agent 框架还是自己搭我的建议是团队规模小于十人、没有专职平台工程师的直接用成熟的 Agent 框架比如基于Claude Agent Skills或者Spring AI Agent的方案。自己搭框架听起来很酷但你要处理上下文管理、工具调用、错误重试、并发控制一大堆脏活投入产出比很低。等团队大了、有特殊需求了再考虑自研。第二个取舍单 Agent 还是多 Agent单 Agent 适合线性任务比如“把这个模块重构一下”。多 Agent 适合并行任务比如“前端后端同时开工”。但多 Agent 的协调成本很高我一般建议先从单 Agent 跑通确认流程没问题了再引入多 Agent 做并行。多 Agent 不是越多越好两个 Agent 能搞定的事别上五个。第三个取舍Agent 的权限给多大我的原则是最小权限 沙盒隔离。Agent 只能访问它需要的目录只能执行白名单里的命令所有写操作都在独立分支或容器里进行。这不是不信任 Agent而是工程上的基本纪律——人都会犯错何况 Agent。3. 核心细节解析与实操要点3.1 CLAUDE.md给 Agent 的“项目说明书”CLAUDE.md这个文件我把它叫做“Agent 的入职手册”。新员工入职你要告诉他项目怎么跑、代码风格是什么、有哪些坑不能踩Agent 也一样。这个文件放在项目根目录Agent 每次启动都会读相当于给它一个稳定的上下文基线。我自己的 CLAUDE.md 一般包含这几块内容# 项目概述 一句话说明这个项目是干什么的。 # 技术栈 - 语言TypeScript 5.x - 框架Next.js 14 - 数据库PostgreSQL 16 - 包管理pnpm # 常用命令 - 安装依赖pnpm install - 启动开发pnpm dev - 跑测试pnpm test - 构建pnpm build # 代码规范 - 组件用函数式不用 class - 样式用 Tailwind不写独立 CSS 文件 - API 路由统一放在 app/api 目录下 - 所有异步操作必须处理错误 # 目录结构 - app/页面和路由 - components/可复用组件 - lib/工具函数 - types/类型定义 # 禁止事项 - 不要修改 package.json 里的依赖版本 - 不要删除现有的测试用例 - 不要直接操作生产数据库这个文件看起来简单但效果非常明显。我做过对比同一个任务没有 CLAUDE.md 的时候Agent 输出的代码风格五花八门有的用 class 有的用函数有的把工具函数写在组件里review 起来很痛苦。有了 CLAUDE.md 之后输出的一致性大幅提升review 时间至少省了一半。提示CLAUDE.md 不要写太长控制在 200 行以内。太长了 Agent 读起来也费劲而且容易过时。核心原则是“写那些 Agent 容易搞错的地方”而不是把整个项目文档搬进来。3.2 Plan Mode先想清楚再动手Plan Mode是我认为 AI Native 工作流里最重要的一个机制。它的核心思想很简单Agent 接到任务后先输出计划人确认后再执行。为什么这个机制重要因为 Agent 的执行速度太快了。你给它一个模糊的需求它可能十分钟就写出五百行代码然后你一看方向完全错了。返工的成本比一开始就规划清楚要高得多。Plan Mode 相当于在“想”和“做”之间加了一个检查点。我一般这样用 Plan Mode第一步给 Agent 一个任务描述比如“给用户模块加一个邮箱验证功能”。第二步Agent 输出计划大概长这样执行计划 1. 在 types/user.ts 里新增 EmailVerification 类型 2. 在 lib/email.ts 里新增 sendVerificationEmail 函数 3. 在 app/api/user/verify-email/route.ts 里新增验证接口 4. 在 components/EmailVerificationForm.tsx 里新增前端表单 5. 在数据库里新增 email_verification_tokens 表 6. 补充对应的单元测试 风险点 - 邮件发送需要配置 SMTP需要确认环境变量 - token 过期时间需要确认默认建议 24 小时 - 需要处理重复发送的情况第三步我审查计划调整不合理的地方。比如我觉得 token 过期时间应该改成 1 小时或者我觉得前端表单应该拆成两个组件。调整完确认Agent 才开始执行。这个流程看起来多了一步但实际上省了大量返工时间。我统计过用 Plan Mode 之后Agent 产出的一次通过率从大概 40% 提升到了 75% 以上。3.3 Agent Skills把重复操作封装成“技能”Agent Skills这个概念简单说就是把一组相关的操作封装成一个可复用的技能包。比如“把网页保存成 Markdown”是一个技能“生成 API 文档”是一个技能“跑完整测试套件”是一个技能。为什么需要 Skills因为 Agent 每次执行任务都要重新理解一遍操作步骤效率低而且容易出错。把常用操作封装成 Skill 之后Agent 直接调用就行不用每次重新推理。我自己的项目里维护了大概十几个 Skill举几个例子Skill 名称功能使用场景save-webpage把网页内容保存为 Markdown收集资料、写文档run-tests跑完整测试套件并生成报告提交前检查gen-api-doc根据路由生成 API 文档接口变更后db-migrate生成并执行数据库迁移模型变更后lint-fix跑 lint 并自动修复代码提交前Skill 的定义一般是一个 Markdown 文件加一个可执行脚本Agent 读到 Skill 描述后就知道什么时候该调用它。这个机制的好处是把“怎么做”固化下来Agent 只需要判断“什么时候做”。3.4 沙盒与权限Agent 不能无法无天Agent 安全这块我踩过的坑最多。早期我给了 Agent 比较大的权限结果它有一次跑了一个rm -rf把测试数据删了还有一次直接往主分支推了代码。虽然没造成生产事故但吓出一身冷汗。后来我定了几条硬规矩第一Agent 的所有写操作都在独立分支或独立 worktree 里进行。主分支只接受人的合并操作Agent 不能直接推。第二Agent 的命令执行走白名单。只允许执行预定义的安全命令比如pnpm test、pnpm lint、git status这些。危险命令比如rm、curl、ssh一律禁止。第三Agent 不能访问生产环境的任何凭证。数据库连接串、API key、云服务凭证这些都不给 Agent。Agent 需要数据就用测试环境的 mock 数据。第四所有 Agent 的操作都有日志。谁在什么时候执行了什么命令、改了什么文件全部记录下来。出问题了可以追溯。这几条规矩看起来限制了 Agent 的能力但实际上反而让整个流程更顺畅——因为你知道它不会闯祸就敢放手让它干。4. 实操过程与核心环节实现4.1 环境准备从零搭一个 AI Native 工作区假设你现在要从零开始搭一套 AI Native 开发环境我按自己的实操顺序走一遍。第一步选一个 Agent 运行环境。我目前用的是基于 Claude 的方案配合Claude Agent Skills做技能扩展。如果你团队用 Java 技术栈Spring AI Agent也是个不错的选择。选哪个不是关键关键是这个环境要支持读项目文件、执行命令、调用工具、有沙盒隔离。第二步初始化项目结构。在项目根目录创建CLAUDE.md把项目概述、技术栈、常用命令、代码规范、目录结构、禁止事项全部写进去。这个文件是后面所有工作的基础值得花半小时认真写。第三步配置沙盒环境。我一般用 Docker 容器或者独立的 git worktree。容器方案的好处是隔离彻底坏处是文件同步麻烦一点。worktree 方案的好处是文件直接共享坏处是隔离性弱一些。小团队我推荐 worktree大团队我推荐容器。第四步定义 Skills。把团队里高频重复的操作整理出来每个操作写一个 Skill 定义。一开始不用多三五个就够后面按需增加。第五步跑一个端到端的小任务验证流程。比如“给现有项目加一个健康检查接口”。从写需求、出计划、执行、审查到合并完整走一遍。这一步的目的是发现流程里的问题比如 CLAUDE.md 写得不够清楚、Skill 定义有歧义、沙盒配置有问题等等。4.2 一个完整任务的执行记录我拿最近做的一个真实任务举例给一个 Next.js 项目加“用户头像上传”功能。任务描述我写给 Agent 的给用户设置页面加一个头像上传功能。 要求 - 支持 jpg/png 格式大小限制 2MB - 上传后裁剪成正方形输出 256x256 - 存储到 S3 兼容的对象存储 - 更新用户表的 avatar_url 字段 - 前端显示上传进度Agent 输出的计划执行计划 1. 安装依赖sharp图片处理、aws-sdk/client-s3对象存储 2. 新增 lib/image.ts图片校验和裁剪逻辑 3. 新增 lib/storage.tsS3 上传封装 4. 新增 app/api/user/avatar/route.ts上传接口 5. 修改 components/UserSettings.tsx添加上传组件 6. 新增数据库迁移user 表加 avatar_url 字段 7. 补充单元测试 风险点 - sharp 在部分环境需要额外编译依赖 - S3 凭证需要配置环境变量 - 需要处理并发上传同一用户的情况我的调整把“安装依赖”改成“先确认 sharp 在当前 Node 版本下能否正常安装”因为之前踩过 sharp 编译失败的坑。另外要求 Agent 在上传接口里加一个简单的限流防止恶意刷接口。执行过程Agent 按调整后的计划执行大概花了十五分钟完成所有代码和测试。中间有一次它想直接改 package.json 加依赖被沙盒拦住了因为我在白名单里没放pnpm add然后它改成先输出依赖变更建议我确认后才执行。审查结果代码质量整体不错但有两个问题。一是图片裁剪的边界处理不够严谨非正方形图片裁剪后可能变形二是上传进度前端没有真正实现只是显示了一个 loading。我让 Agent 修了第一个问题第二个问题我自己动手补了——因为涉及 UI 细节Agent 理解起来比较费劲。合并上线审查通过后合并到主分支部署到测试环境验证没问题后上线。整个流程从开始到上线大概两小时其中我实际投入的时间大概四十分钟。4.3 多 Agent 并行的实操要点单 Agent 跑顺之后可以尝试多 Agent 并行。我一般这样组织场景一前后端并行。一个 Agent 负责后端接口一个 Agent 负责前端页面两个 Agent 共享同一份 CLAUDE.md 和接口约定文档。关键是接口约定要提前定死不然两边对不上。场景二开发与测试并行。一个 Agent 写功能代码一个 Agent 写测试用例。测试 Agent 根据需求描述和接口文档写测试开发 Agent 根据测试反馈修 bug。这个模式有点像 TDD但执行单元换成了 Agent。场景三多模块并行。一个大功能拆成几个独立模块每个模块一个 Agent。这种场景下最关键的是模块边界要清晰不然 Agent 之间会互相踩脚。多 Agent 并行的坑主要有两个一是上下文同步两个 Agent 对同一个文件的理解可能不一致二是冲突处理两个 Agent 同时改一个文件会冲突。我的解决办法是给每个 Agent 分配独立的文件范围禁止跨范围修改所有共享的接口定义放在一个只读文件里Agent 只能读不能改。4.4 并发扛压Agent 多了怎么不崩Agent 一多并发问题就来了。我遇到过几种典型情况情况一多个 Agent 同时调用同一个 API。比如都去调 OpenAI 或者 Claude 的接口结果触发限流。解决办法是加一个请求队列控制并发数超出的排队等待。情况二多个 Agent 同时写同一个文件。这个前面说了靠文件范围隔离解决。情况三Agent 执行时间过长导致超时。有些任务比如跑完整测试套件可能要几分钟。解决办法是给 Agent 设置合理的超时时间超时后自动重试或者降级。情况四Agent 内存占用过高。多个 Agent 同时跑内存可能不够。解决办法是限制每个 Agent 的上下文大小定期清理不用的上下文。我自己的经验是并发数控制在 3 到 5 个比较合适。太少了效率上不去太多了管理成本太高。而且并发数不是固定的要根据任务复杂度和机器资源动态调整。5. 常见问题与排查技巧实录5.1 Agent 跑偏了怎么办Agent 跑偏是最常见的问题表现包括改了不该改的文件、用了不该用的依赖、忽略了关键约束。排查思路是从上下文找原因。先看 CLAUDE.md 里有没有写清楚相关约束。很多时候 Agent 跑偏是因为它根本不知道有这个约束。比如它改了 package.json可能是因为 CLAUDE.md 里没写“不要改依赖版本”。再看任务描述有没有歧义。比如你说“优化一下这个函数”Agent 可能理解成“重构”也可能理解成“加缓存”。任务描述要具体最好给出明确的输入输出和验收标准。最后看 Plan Mode 有没有生效。如果 Agent 直接执行没出计划那跑偏的概率会高很多。确保 Plan Mode 开启让 Agent 先想再做。5.2 Agent 执行报错怎么排查Agent 执行报错的常见原因和解决办法错误类型典型表现排查方向解决办法上下文超限提示 token 超限检查 CLAUDE.md 和任务描述长度精简上下文拆分任务工具调用失败提示命令不存在或无权限检查白名单配置添加命令到白名单依赖缺失提示模块找不到检查依赖是否安装先安装依赖再执行沙盒限制提示操作被拒绝检查沙盒权限配置调整权限或换执行方式网络超时提示请求超时检查网络和 API 限流加重试机制或降级我遇到最多的是上下文超限和沙盒限制。上下文超限的解决办法是把大任务拆成小任务每个任务只给必要的上下文。沙盒限制的解决办法是提前把需要的权限配好别等 Agent 报错了再临时加。5.3 Agent 输出质量不稳定的应对同一个任务Agent 两次执行可能输出质量不一样。这个问题的根源是大模型的随机性。应对办法有几个第一降低温度参数。如果 Agent 环境支持调温度把温度调低一点输出会更稳定。但温度太低也会导致输出死板需要权衡。第二提供更具体的示例。在 CLAUDE.md 或者任务描述里给一两个参考示例Agent 会照着示例的风格来。第三加验证步骤。Agent 输出后自动跑一遍 lint 和测试不通过就打回重做。这个机制能过滤掉大部分低质量输出。第四人工审查关键决策点。不要指望 Agent 一次就完美关键的地方人还是要看一眼。我的原则是“Agent 做初稿人做终审”。5.4 独家避坑技巧几个我从实践中总结的、文档里不会写的技巧技巧一给 Agent 起名字。听起来很傻但给 Agent 起个名字比如“小前”“小后”“小测”在日志和对话里更容易区分是哪个 Agent 在干活。多 Agent 场景下特别有用。技巧二任务描述用“验收标准”结尾。比如“完成后运行 pnpm test 应该全部通过运行 pnpm lint 应该没有警告”。这样 Agent 知道自己要做到什么程度。技巧三定期清理 Agent 的上下文。Agent 跑久了上下文会越来越长影响效率和准确性。我一般每完成三到五个任务就重启一次 Agent清空上下文。技巧四保留 Agent 的执行日志。Agent 出问题的时候日志是唯一的排查依据。我一般把日志按日期存起来保留至少一个月。技巧五不要让 Agent 做它不擅长的事。Agent 擅长写代码、跑测试、改 bug不擅长做产品决策、UI 设计、架构选型。这些事还是人来做Agent 打下手就行。6. 工具选型与团队落地建议6.1 Agent 框架怎么选市面上 Agent 框架很多我按自己的使用体验给个参考框架适合场景优势劣势Claude Agent Skills通用开发任务生态成熟Skill 机制灵活依赖 Claude 服务Spring AI AgentJava 技术栈与 Spring 生态集成好学习曲线较陡自研轻量框架特殊需求完全可控维护成本高选框架的核心原则是匹配团队技术栈。团队用 TypeScript就选 JS/TS 生态的框架团队用 Java就选 Spring AI。别为了追新而选一个团队不熟悉的框架后面维护起来很痛苦。6.2 团队推广的节奏AI Native 工作流在团队里推广不能一刀切。我的建议是分三步走第一步小范围试点。选一两个愿意折腾的工程师先跑通流程积累经验。这个阶段的目标是验证可行性不是追求效率。第二步沉淀最佳实践。试点跑通后把 CLAUDE.md 模板、Skill 定义、沙盒配置整理成文档形成团队规范。这个阶段的目标是让流程可复制。第三步全面推广。规范沉淀好之后逐步推广到全团队。推广过程中要持续收集反馈迭代规范。这个阶段的目标是让流程成为习惯。推广过程中最大的阻力往往不是技术而是习惯。很多工程师习惯了“自己写代码自己掌控”对 Agent 有天然的不信任。我的经验是先用实际效果说话——让试点的人展示他们的效率提升比讲一百遍道理都管用。6.3 成本控制Agent 跑起来是要花钱的主要是 API 调用费用。控制成本有几个办法第一合理设置上下文大小。上下文越长费用越高。CLAUDE.md 控制在 200 行以内任务描述尽量精简。第二缓存常用上下文。很多 Agent 框架支持上下文缓存重复的内容不用每次都重新计算。第三按任务复杂度选模型。简单任务用便宜的小模型复杂任务用贵的大模型。别所有任务都用最贵的。第四设置预算上限。给每个 Agent 或者每个项目设置月度预算超了就停。这个机制能防止意外的大额支出。我自己的经验是一个五人团队全面使用 AI Native 工作流月度 API 费用大概在几百到一千块之间相比节省的人力成本这个投入非常划算。6.4 安全与合规注意事项最后说几个安全方面的注意事项这些是我踩过坑之后总结的第一敏感信息不进上下文。API key、数据库密码、用户隐私数据这些绝对不能写进 CLAUDE.md 或者任务描述。Agent 的上下文可能被记录、被传输敏感信息一旦进去就有泄露风险。第二Agent 的操作要可审计。所有 Agent 执行过的命令、改过的文件、调过的接口都要有日志记录。出问题了能追溯这是底线。第三定期审查 Agent 的权限。Agent 的权限不是配一次就完事要定期检查。有些权限可能一开始需要后来不需要了要及时收回。第四建立应急机制。万一 Agent 闯祸了比如误删文件、误推代码要有快速回滚的方案。我一般用 git 分支隔离最坏情况就是丢弃分支重来。这套 AI Native 开发手册我自己团队跑了大概半年从最初的磕磕绊绊到现在基本顺畅中间踩了不少坑也总结了不少经验。核心体会就一句话Agent 不是魔法它需要好的上下文、清晰的约束、合理的流程。把这三点做好效率提升是实实在在的。后面我还会继续迭代这套流程有新经验再分享。