AI Native 团队实战手册：从 CLAUDE.md 到 Agent 编排的 SDLC 改造

1. 从“人写代码”到“人管 Agent”：AI Native 团队到底在做什么

这两年“AI Native”这个词被喊得震天响，但真正落到研发团队日常里，它其实不是一句口号，而是一整套工作方式的重新洗牌。我所在的团队从去年开始尝试把 SDLC（软件开发生命周期）往 AI Native 方向改造，踩了无数坑，也攒了一些能直接抄作业的经验。这篇手册就是把这套东西完整摊开讲清楚：AI Native 团队怎么组织、CLAUDE.md 这类上下文文件怎么写、Plan Mode 和 Agent 怎么配合、并发和安全怎么兜底。适合正在做 AI 应用开发、或者想把现有研发流程往 Agent 方向迁移的团队参考，不管你是刚接触 Agent 的新手，还是已经在搭多 Agent 架构的老手，都能从里面找到能直接用的东西。

先说清楚一个核心认知：AI Native 不是“用 AI 辅助写代码”，那是 AI-Assisted，本质还是人在主导。AI Native 是反过来——人负责定义目标和验收标准，Agent 负责执行和迭代。这个转变听起来简单，实际落地时对团队结构、工具链、协作方式的要求完全是另一套逻辑。我见过太多团队买了 Copilot 就觉得完成了 AI Native 转型，结果半年过去效率没涨多少，问题就出在没搞明白这个根本区别。

传统 SDLC 里，需求、设计、编码、测试、部署是一条线性流水线，每个环节由人交接。AI Native 的 SDLC 更像一个“人设定约束、Agent 自主循环”的闭环系统。Agent 在里面不是工具，而是有记忆、有技能、能调用外部资源的执行单元。你要做的不是教它每一步怎么做，而是把上下文、边界、验收标准喂给它，让它自己跑。这中间的差别，决定了你整个团队的工作重心要从“写”转移到“定义和审查”。

2. AI Native SDLC 的整体设计与思路拆解

2.1 为什么传统 SDLC 在 Agent 时代会失灵

传统 SDLC 的假设是：执行者是人，人的上下文加载慢、沟通成本高，所以需要把流程切得很细，每个环节产出明确文档，靠文档传递信息。但 Agent 的上下文加载几乎是瞬时的，你给它一个 CLAUDE.md 加几个 skill 文件，它就能理解整个项目的约定。这时候如果还按老流程走，反而是在给 Agent 制造信息断层——它拿到的永远是上一个环节的“摘要”，而不是完整上下文。

我踩过最典型的坑：一开始我们让 Agent 只负责写单元测试，需求文档、接口定义都靠人转述。结果 Agent 写出来的测试跟实际业务逻辑对不上，因为它根本不知道业务背景。后来我们把整个仓库的上下文、历史决策记录、甚至 issue 讨论都整理成结构化文件喂给它，测试质量立刻上了一个台阶。这说明 AI Native SDLC 的核心不是“把任务拆给 Agent”，而是“把上下文完整地交给 Agent”。

2.2 人机分工的重新划分：谁定目标，谁做执行

AI Native 团队里，人的角色收敛到三件事：定义目标、设定约束、验收结果。Agent 承担的是：方案探索、代码实现、测试验证、迭代修复。这个划分的关键在于，人不再介入“怎么做”的细节，只关心“做成什么样”。

具体到岗位，我们团队现在的配置是：一个产品负责人（定义需求和验收标准）、一个架构师（维护 CLAUDE.md 和 skill 库）、若干 Agent 操作员（负责跑 Plan Mode、审查 Agent 产出、处理异常）。注意这里没有传统意义上的“初级开发”了，因为写代码这件事基本被 Agent 接管，人的价值体现在判断力和上下文维护上。

2.3 方案选型：为什么是 CLAUDE.md + Plan Mode + Agent 这套组合

市面上 Agent 框架很多，我们最终选了以 CLAUDE.md 为核心上下文文件、Plan Mode 做任务规划、Agent 做执行的组合，原因有三。第一，CLAUDE.md 是纯文本、可版本控制的，团队每个人都能改、能 review，不像某些框架把上下文藏在数据库里，出了问题根本查不到。第二，Plan Mode 强制 Agent 先出方案再执行，这个“先想后做”的机制极大降低了跑偏概率。第三，Agent 作为执行单元可以灵活替换，今天用这个框架明天换那个，只要 CLAUDE.md 和 skill 定义不变，迁移成本很低。

提示：不要一上来就追求多 Agent 协作。我们最开始搞了五个 Agent 互相调用，结果调试成本高到离谱。后来退回单 Agent + 清晰 skill 划分，效率反而更高。多 Agent 是规模化之后才需要考虑的事。

3. 核心细节解析与实操要点

3.1 CLAUDE.md 到底该写什么：上下文文件的结构化写法

CLAUDE.md 不是 README，它的读者是 Agent，所以写法要围绕“让 Agent 快速理解项目约定”来组织。我们团队的标准结构是这样的：项目概述（一段话说清楚这个项目干什么）、技术栈与版本约束、目录结构说明、编码规范（命名、注释、错误处理）、关键业务规则、禁止事项、常用命令。每一块都要具体到 Agent 能直接执行的程度。

举个例子，编码规范里不要写“代码要清晰”，要写“函数名用动词开头，超过 30 行的函数必须拆分，所有外部调用必须包 try-catch 并记录日志”。禁止事项里要明确写“不要修改 migrations 目录下的历史文件”“不要引入新的第三方依赖，除非在 CLAUDE.md 里登记”。这些约束越具体，Agent 跑偏的概率越低。

我实测下来，一份好的 CLAUDE.md 大概在 800 到 1500 字之间。太短了约束不够，太长了 Agent 加载慢而且容易忽略重点。维护频率大概是每周 review 一次，把本周 Agent 犯的错补进禁止事项里。

3.2 Plan Mode 的正确打开方式：先规划再执行

Plan Mode 是这套流程里最容易被低估的环节。很多人觉得让 Agent 先出方案是浪费时间，直接让它写代码更快。但我们的数据是：用 Plan Mode 的任务，返工率比不用低 60% 以上。原因很简单，Agent 在规划阶段会把任务拆解、识别依赖、暴露不确定点，这些如果等到写代码时才发现，改起来成本高得多。

实操上，Plan Mode 的产出应该包含：任务拆解清单、每步的输入输出、依赖关系、风险点、验收标准。人 review 这个 plan 的时候，重点看两件事：拆解是否合理、验收标准是否可量化。如果 plan 里出现“优化性能”这种模糊表述，直接打回重写，要求改成“接口 P99 延迟从 200ms 降到 100ms 以下”。

3.3 Agent Skill 的设计原则：可复用、可测试、可组合

Agent Skill 是把常见任务封装成可复用单元的方式。我们团队的 skill 库现在有 40 多个，覆盖了从“生成数据库 migration”到“把网页保存成 markdown”的各种场景。设计 skill 的核心原则是：单一职责、输入输出明确、有测试用例。

一个合格的 skill 定义包含：名称、描述、输入参数、输出格式、依赖、示例。比如“把网页保存成 markdown”这个 skill，输入是 URL，输出是 markdown 文件路径，依赖是某个解析库，示例里要给出一个真实 URL 和预期输出。skill 写完必须跑测试，我们要求每个 skill 至少有三个测试用例：正常输入、边界输入、异常输入。

注意：skill 不要设计得太“聪明”。我见过有人把整个业务流程塞进一个 skill，结果调试时根本不知道哪一步出错。skill 要像乐高积木，小块、标准接口、能自由组合。

3.4 Agent 记忆机制：短期上下文与长期知识库的配合

Agent 记忆分两层：短期记忆是当前会话的上下文，长期记忆是跨会话的知识库。短期记忆靠 CLAUDE.md 和会话历史维持，长期记忆需要单独设计。我们用的是“结构化文件 + 向量检索”的方案：把项目决策、历史 bug 修复、业务规则写成 markdown 文件，用向量库索引，Agent 需要时检索相关片段注入上下文。

这里的关键是写入策略。不是所有东西都值得记，我们只记三类：影响后续决策的（比如“为什么选了这个方案”）、容易重复犯错的（比如“这个 API 有坑”）、业务规则类的（比如“退款必须走审批流”）。每次 Agent 完成任务后，由人判断是否要沉淀记忆，避免知识库被垃圾信息污染。

4. 实操过程与核心环节实现

4.1 从零搭建一个 AI Native 项目的完整流程

假设你要新起一个项目，完整流程是这样的。第一步，初始化仓库，创建 CLAUDE.md，把项目概述、技术栈、目录结构、编码规范写进去。第二步，搭建 skill 库目录，先放三五个基础 skill（比如代码生成、测试生成、文档生成）。第三步，配置 Plan Mode，定义 plan 的输出模板和 review 标准。第四步，跑第一个任务，从最简单的开始，比如“实现一个用户查询接口”，全程用 Plan Mode + Agent 执行。第五步，review 产出，把问题补进 CLAUDE.md 和 skill 库。

这个流程我们跑了十几个项目，平均一个新项目从初始化到能稳定产出可用代码，大概需要两到三天的磨合期。磨合期的核心工作就是不断往 CLAUDE.md 里补约束，往 skill 库里补能力。

4.2 一个真实任务的完整执行记录

拿我们最近做的一个“订单导出功能”举例。需求是：支持按时间范围导出订单为 CSV，超过 10 万条要分片。第一步，人写需求描述和验收标准，扔给 Plan Mode。Plan Mode 产出的方案是：定义导出接口、实现查询逻辑、实现 CSV 生成、实现分片、写测试。人 review 后补充了一条约束：“分片大小可配置，默认 5 万条”。

第二步，Agent 按 plan 执行，每完成一步自动跑测试。中间遇到一个问题：CSV 生成时中文乱码。Agent 自己检索了长期记忆库，发现之前有个类似问题的记录，自动应用了解决方案。第三步，人验收，发现分片逻辑在边界情况下（正好 10 万条）有 off-by-one 错误，打回让 Agent 修复。第四步，修复后重新验收通过，把“分片边界要写测试”这条补进 CLAUDE.md。

整个任务从开始到完成大概 40 分钟，其中人介入两次，每次不超过 5 分钟。对比传统方式，同样任务大概需要半天。

4.3 并发场景下的 Agent 调度：怎么扛住高并发

Agent 扛并发是个真问题。我们早期试过让多个 Agent 同时跑任务，结果上下文互相污染，产出质量暴跌。后来总结出一套调度策略：按资源隔离，按依赖排序。具体做法是，每个 Agent 实例有独立的上下文空间，共享的只有只读的 CLAUDE.md 和 skill 库。任务之间如果有依赖，必须串行；无依赖的可以并行，但并行数不超过 CPU 核数的一半。

参数上，我们实测下来，单机跑 4 个 Agent 实例是比较稳的配置。再多的话，上下文切换开销和内存占用会拖慢整体速度。如果任务量确实大，建议横向扩展机器，而不是在一台机器上堆 Agent 数量。

4.4 Agent 安全边界：权限、审计与回滚

Agent 能执行代码、能调外部接口，安全边界必须提前划好。我们的做法是三层防护：第一层，Agent 运行在沙箱环境里，文件系统、网络访问都有白名单。第二层，所有 Agent 操作记审计日志，包括读了哪些文件、调了哪些接口、改了什么代码。第三层，关键操作（比如数据库 migration、生产部署）必须人工确认，Agent 只能生成待执行的脚本。

回滚机制也很重要。我们要求 Agent 每次修改代码前先打 git tag，出问题一键回滚。数据库操作必须走 migration 工具，禁止直接改表结构。这些约束都写在 CLAUDE.md 的禁止事项里，Agent 执行时会自动遵守。

5. 常见问题与排查技巧实录

5.1 Agent 跑偏了怎么办：上下文污染的排查思路

Agent 跑偏最常见的原因是上下文污染。表现是：Agent 突然开始用错误的命名规范、引用了不存在的依赖、或者逻辑跟需求对不上。排查思路是：先看 CLAUDE.md 是不是被误改了，再看会话历史里是不是混入了无关信息，最后看 skill 库有没有冲突的定义。

我们遇到过一次典型情况：Agent 突然开始用 Python 2 的语法写代码。查了半天发现是某个 skill 的示例代码里用了旧语法，Agent 把它当成了项目规范。解决办法是在 CLAUDE.md 里明确写“本项目使用 Python 3.11，禁止使用任何 Python 2 语法”，并在 skill 示例里全部更新。

5.2 Agent 执行报错“execution terminated due to error”的常见原因

这个报错信息很泛，实际原因可能有很多。我们整理了一张速查表：

排查时建议先看审计日志，定位到具体哪一步出错，再针对性解决。不要盲目重跑，重跑大概率还是同样的错。

5.3 多 Agent 协作的坑：什么时候该拆，什么时候该合

多 Agent 协作听起来很美，实际坑很多。我们试过的失败案例：让一个 Agent 写代码、一个 Agent 写测试、一个 Agent 做 review，结果三个 Agent 对需求的理解不一致，产出互相矛盾。后来改成单 Agent 串行执行，质量反而稳定。

我的经验是：只有当任务可以完全独立、且通信成本低于协作收益时，才拆多 Agent。比如批量处理 100 个独立的数据清洗任务，拆多 Agent 是合理的。但如果是同一个功能的不同环节，老老实实单 Agent 串行，别折腾。

5.4 实操避坑清单：我们踩过的 8 个坑

• 坑一：CLAUDE.md 写得太抽象，Agent 理解不了。解决：所有约束具体到可执行。
• 坑二：skill 粒度太粗，调试困难。解决：拆到单一职责。
• 坑三：不做 Plan Mode 直接执行，返工率高。解决：强制先规划。
• 坑四：长期记忆库不清理，检索出无关信息。解决：定期 review 记忆库。
• 坑五：并发数设太高，上下文互相污染。解决：按资源隔离，控制并发数。
• 坑六：安全边界没划清，Agent 误操作生产环境。解决：沙箱 + 审计 + 人工确认。
• 坑七：skill 没有测试用例，上线后才发现问题。解决：每个 skill 至少三个测试。
• 坑八：人 review 太粗，放过模糊验收标准。解决：验收标准必须可量化。

6. Agent 学习路线与团队能力建设

6.1 个人从零到能上手 Agent 开发的学习路径

如果你刚开始接触 Agent 开发，我建议的路线是：第一周，搞懂 Agent 是什么、跟传统程序的区别，动手跑通一个最简单的 Agent demo。第二周，学习 skill 的定义和编写，给自己常用的任务写三五个 skill。第三周，学习 Plan Mode 和上下文管理，理解 CLAUDE.md 的作用。第四周，做一个完整的小项目，从需求到验收全程用 Agent 跑一遍。

这个路线我们团队新人实测下来，四周能到独立操作的水平。关键是要动手，光看文档没用。Agent 开发很多坑是文档里不会写的，必须自己踩一遍。

6.2 团队协作规范：怎么让多个人维护同一套 Agent 配置

多人维护同一套 Agent 配置，最大的问题是冲突。我们的做法是：CLAUDE.md 和 skill 库都走 git 管理，修改必须提 PR，review 通过才能合并。每周固定时间做一次配置 review，把本周遇到的问题补进去。另外，每个人本地可以有自己的实验性配置，但合并到主分支前必须经过测试。

还有一个经验：指定一个“配置负责人”，专门维护 CLAUDE.md 和 skill 库的质量。这个人不一定是技术最强的，但必须是最细心的，因为配置里一个小错误可能导致所有 Agent 跑偏。

6.3 面试 Agent 开发岗位时，我会问什么

如果你在准备 Agent 开发相关的面试，我作为面试官会关注这几点：第一，你是否理解 Agent 和传统程序的区别，能不能说清楚上下文管理的重要性。第二，你有没有实际写过 skill，能不能讲清楚设计原则。第三，遇到 Agent 跑偏你怎么排查，有没有系统性的思路。第四，你对并发和安全边界有没有概念。

这些问题的答案不在教科书里，都在实操经验里。所以我的建议是，面试前一定要自己动手做过完整项目，哪怕很小，也比只看理论强。

7. 工具链选型与生态观察

7.1 Agent 框架怎么选：从需求反推工具

选 Agent 框架不要看哪个火，要看你的需求。如果你只是做单 Agent 任务自动化，轻量级框架就够了，别上重型编排系统。如果你要做多 Agent 协作，那要考虑框架的通信机制、状态管理、错误恢复能力。如果你要跟现有系统集成，那要看框架的扩展性和 API 设计。

我们团队评估过市面上主流的几个框架，最终选了一个扩展性好、社区活跃、文档清晰的。选型时重点看三点：能不能自定义 skill、上下文管理是否灵活、出错时调试信息是否充分。这三点决定了你后续的开发效率。

7.2 从单 Agent 到多 Agent 的演进时机判断

什么时候该从单 Agent 升级到多 Agent？我的判断标准是：当单 Agent 的任务队列排期超过一天，且任务之间确实独立时，才考虑多 Agent。如果任务之间有依赖，多 Agent 只会增加协调成本。另外，多 Agent 对团队的技术能力要求更高，如果团队还没把单 Agent 跑顺，别急着上多 Agent。

7.3 Agent 生态的下一步：我观察到的三个趋势

第一个趋势是 skill 的标准化。现在每个团队都在自己写 skill，未来可能会出现跨团队复用的 skill 市场。第二个趋势是上下文管理的工具化，现在靠手写 CLAUDE.md，未来可能会有专门的上下文管理工具。第三个趋势是 Agent 的可观测性，现在调试 Agent 主要靠日志，未来会有更专业的监控和追踪工具。

这些趋势对我们做技术选型的启示是：尽量选那些接口开放、数据可导出的工具，避免被锁定。上下文文件和 skill 定义尽量用纯文本，方便迁移。

8. 一些实操后的个人体会

这套 AI Native 的玩法我们跑了大半年，最大的体会是：Agent 的上限取决于你给它的上下文质量，而不是 Agent 本身有多强。同样的 Agent，喂给它一份结构清晰的 CLAUDE.md 和一堆模糊的需求描述，产出质量天差地别。所以团队在 AI Native 转型上投入的精力，应该大部分花在上下文建设和 skill 沉淀上，而不是追新框架。

另一个体会是，人的角色转变比想象中难。很多开发同学习惯了写代码，突然让他只做 review 和定义，会有失落感。这个转变需要时间，也需要团队在考核方式上做调整，不能再用代码行数衡量产出，要看 Agent 任务的完成质量和效率。

最后分享一个小技巧：每次 Agent 任务完成后，花两分钟想想“这次哪里可以更好”，把答案补进 CLAUDE.md 或 skill 库。坚持一个月，你会发现 Agent 的产出质量有肉眼可见的提升。这个习惯比任何工具升级都管用。