AI Native 团队开发手册：从 CLAUDE.md 到多 Agent 编排的 SDLC 重构

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 的定义一般是一个 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.ts：S3 上传封装 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 执行报错的常见原因和解决办法：

我遇到最多的是上下文超限和沙盒限制。上下文超限的解决办法是把大任务拆成小任务，每个任务只给必要的上下文。沙盒限制的解决办法是提前把需要的权限配好，别等 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 框架很多，我按自己的使用体验给个参考：

选框架的核心原则是匹配团队技术栈。团队用 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 不是魔法，它需要好的上下文、清晰的约束、合理的流程。把这三点做好，效率提升是实实在在的。后面我还会继续迭代这套流程，有新经验再分享。