AI Native研发范式：从CLAUDE.md到Agent编排的SDLC重构手册

1. 从“用AI写代码”到“AI Native团队”的认知跃迁

这两年跟不少团队聊过AI辅助开发的事，发现一个特别普遍的现象：大部分人还停留在“让AI帮我补全一段代码”的阶段，而真正跑在前面的团队，已经在用一套完全不同的方式组织研发流程了。这个差距不是工具层面的，而是范式层面的。我把它叫做AI Native 研发范式——不是给传统流程打补丁，而是从根上重新设计人、Agent、代码库三者之间的协作关系。

先把这个概念说清楚。AI Native 团队，指的是把 AI Agent 当作研发流程中的一等公民来对待的团队。注意，不是“辅助工具”，是“一等公民”。这意味着 Agent 有自己的工作空间、有自己的职责边界、有明确的输入输出规范，甚至有自己的“记忆”和“技能库”。人类工程师的角色从“写代码的人”转变为“定义问题、设计约束、审查产出的人”。

这套东西解决的核心问题是：当 AI 编码能力越来越强，为什么很多团队用了之后效率提升却很有限？答案往往不在模型能力上，而在流程设计上。你让一个能力很强的 Agent 在一个没有规范、没有上下文、没有约束的环境里干活，它产出的东西就是不可控的。就像你招了一个很聪明的新人，但不给他文档、不告诉他代码规范、不跟他讲业务背景，他再聪明也干不好活。

这篇文章适合谁看？如果你是团队的技术负责人，正在思考怎么把 AI 真正融入研发流程而不是停留在玩具阶段，那这篇内容会对你有直接帮助。如果你是独立开发者，想搭建一套自己的 AI 协作工作流，同样可以从中提取适合你的部分。我会尽量把每个环节的“为什么”讲透，让你不是照搬一套流程，而是理解背后的逻辑之后自己做出判断。

整个手册围绕一条主线展开：SDLC（软件开发生命周期）的每个环节，如何被 AI Native 的方式重新设计。从需求理解、方案规划、编码实现、测试验证到代码审查，每个环节我都会给出具体的操作方式、配置文件示例、以及踩过的坑。

2. AI Native SDLC 的整体架构设计

2.1 传统 SDLC 与 AI Native SDLC 的本质区别

传统的软件开发生命周期，不管你是敏捷还是瀑布，核心假设都是“人类工程师是主要执行者”。流程设计的目标是让人类之间的协作更顺畅——站会、评审、文档、分支管理，都是为人类协作服务的。

AI Native SDLC 的核心假设变了：Agent 是主要执行者，人类是定义者和审查者。这个假设一变，流程设计的逻辑就完全不同了。

我画个表对比一下关键差异：

这个表里最关键的一行是“上下文传递”。传统模式下，一个新人加入项目，你需要花几天甚至几周给他讲业务背景、代码规范、架构决策。AI Native 模式下，这些信息全部沉淀在一个结构化的配置文件里，Agent 每次启动都自动加载。这个文件就是CLAUDE.md（或者你用的任何 Agent 工具对应的配置文件）。

2.2 核心组件拆解：CLAUDE.md、Plan Mode、Agent、Skill

整套体系由几个核心组件构成，我逐个拆解它们的作用和设计思路。

CLAUDE.md——项目的“宪法”

这个文件放在项目根目录，是 Agent 每次工作时首先读取的上下文。它包含什么内容？我建议至少覆盖以下几块：

• 项目概述：这个项目是做什么的，核心业务逻辑是什么
• 技术栈说明：用了什么语言、框架、数据库、部署方式
• 代码规范：命名约定、目录结构、错误处理方式、日志规范
• 架构决策记录：为什么选了这个方案而不是那个，有哪些历史包袱
• 常用命令：怎么构建、怎么测试、怎么部署
• 禁区：哪些文件不要动，哪些操作需要人类确认

为什么这个文件如此关键？因为 Agent 没有“团队记忆”。你不告诉它的东西，它就不知道。传统模式下，这些信息散落在各种 Wiki、Confluence、甚至老员工的脑子里。AI Native 模式下，你必须把它们集中到一个 Agent 能读取的地方。

实操心得：CLAUDE.md 不要一次写完美，而是在每次 Agent 犯错之后补充一条规则。比如 Agent 把日期格式化写成了YYYY-MM-DD但项目规范是YYYY/MM/DD，你就在文件里加一条。这个文件是“活”的，随着项目演进不断生长。

Plan Mode——先想后做

Plan Mode 是我认为最被低估的一个功能。它的核心逻辑是：让 Agent 在动手写代码之前，先输出一份完整的执行计划，人类确认后再执行。

为什么这个环节不能省？因为 Agent 的执行速度太快了。如果不加 Plan Mode，它可能在 30 秒内改了 15 个文件，等你发现方向错了，回滚成本很高。Plan Mode 相当于在“思考”和“执行”之间加了一个人类审查的检查点。

具体操作上，Plan Mode 的输出应该包含：任务拆解、涉及文件列表、每个文件的修改意图、潜在风险点。人类审查这份计划，确认没问题再让 Agent 执行。

Agent——执行单元

Agent 是实际干活的单元。但 Agent 不是越多越好，关键是要有清晰的职责边界。我见过一些团队搞了十几个 Agent 互相协作，结果调试成本比人工还高。我的建议是：从单 Agent 开始，遇到明确的瓶颈再拆分。

常见的拆分维度包括：按功能模块拆（前端 Agent、后端 Agent）、按任务类型拆（编码 Agent、测试 Agent、文档 Agent）、按环境拆（开发环境 Agent、生产环境 Agent）。

Skill——可复用的能力单元

Skill 是 Agent 可以调用的“工具包”。比如“生成数据库迁移脚本”是一个 Skill，“调用 API 获取数据”是一个 Skill，“把网页内容转成 Markdown”也是一个 Skill。Skill 的价值在于复用——你不需要每次都在 prompt 里重新描述怎么做一个操作，而是把它封装成一个 Skill，Agent 需要时直接调用。

2.3 为什么选择这套架构而不是其他方案

市面上 Agent 框架很多，LangChain、Dify、CrewAI 各有各的玩法。我选择这套“配置文件 + Plan Mode + 单 Agent 起步”的方案，核心考量是可控性和可调试性。

多 Agent 协作框架看起来很美好，但实际用起来，当产出不符合预期时，你很难定位是哪个 Agent 的哪个环节出了问题。而单 Agent + 清晰配置的模式，出问题时排查路径很短：要么是配置文件没写清楚，要么是 Plan 有问题，要么是 Skill 实现有 bug。这三个方向都比“多 Agent 消息传递链路断了”好排查得多。

另一个考量是渐进式采用。这套方案不要求团队一次性改变所有流程。你可以先从“用 CLAUDE.md 管理项目上下文”开始，然后逐步引入 Plan Mode，再逐步沉淀 Skill。每一步都能独立产生价值，不需要大张旗鼓地搞“流程革命”。

3. 核心环节实操：从需求到代码的完整链路

3.1 需求理解阶段：让 Agent 读懂业务

需求理解是整个链路的第一步，也是最容易被忽视的一步。很多团队直接跳过这一步，把需求文档丢给 Agent 说“实现这个功能”，结果产出的代码跟预期差很远。

我的做法是：在让 Agent 写代码之前，先让它用自己的话复述一遍需求，并列出它认为模糊的地方。

具体操作流程：

1. 把需求文档（可以是 PRD、用户故事、甚至一段聊天记录）放到项目的一个固定目录下，比如docs/requirements/
2. 在 CLAUDE.md 里指明这个目录的用途
3. 给 Agent 的指令是：“阅读docs/requirements/xxx.md，用你的话总结需求要点，列出你不确定的地方，不要写代码”
4. 人类审查 Agent 的总结，补充缺失信息，澄清模糊点
5. 把澄清后的信息更新回需求文档或 CLAUDE.md

这个流程的价值在于：它把“需求理解偏差”这个最常见的返工原因，提前到了成本最低的阶段暴露出来。Agent 理解错了，你在它写代码之前就发现了，改一段文字的成本远低于改一堆代码。

注意事项：Agent 有时候会“假装理解”。它总结出来的需求看起来很合理，但实际上是它根据常见模式猜的，不是真的从你的文档里读出来的。验证方法是让它引用原文——如果它的总结里没有引用你文档中的具体句子，那就要警惕了。

3.2 方案规划阶段：Plan Mode 的正确打开方式

Plan Mode 的使用有几个关键技巧，直接决定了它的效果。

技巧一：给 Plan 设定明确的输出格式

不要让 Agent 自由发挥写计划，而是给它一个模板。我常用的模板是这样的：

## 任务概述 [一句话描述这个任务要做什么] ## 涉及文件 - [ ] 文件路径1：修改意图 - [ ] 文件路径2：修改意图 - [ ] 文件路径3：新建，用途说明 ## 执行步骤 1. 第一步做什么，为什么 2. 第二步做什么，为什么 ... ## 风险点 - 风险1：可能影响什么，如何规避 - 风险2：... ## 验证方式 - 如何验证修改是正确的

这个模板强制 Agent 思考“涉及哪些文件”和“有什么风险”，这两个问题是最容易出错的。

技巧二：Plan 的粒度要适中

太粗的 Plan（比如“实现用户登录功能”）没有审查价值，太细的 Plan（比如“在第 23 行加一个分号”）又浪费时间。好的粒度是：每个步骤对应一个逻辑上独立的修改，可以在不破坏其他功能的前提下单独验证。

技巧三：Plan 审查时重点关注“意外文件”

审查 Plan 时，我首先看“涉及文件”列表里有没有意料之外的文件。比如一个改登录逻辑的任务，Plan 里出现了payment/service.py，这就是一个信号——要么 Agent 理解错了任务范围，要么这个改动有隐藏的耦合。不管哪种情况，都值得在动手之前搞清楚。

3.3 编码实现阶段：约束前置与增量执行

到了实际写代码的阶段，核心原则是约束前置和增量执行。

约束前置的意思是：所有代码规范、架构约束、命名约定，都要在 CLAUDE.md 里写清楚，而不是等 Agent 写完了再去改。比如：

## 代码规范 - Python 函数必须带类型注解 - 所有数据库操作必须通过 Repository 层，不允许在 Service 层直接写 SQL - 错误处理统一使用自定义的 AppError 异常类 - 日志使用 structlog，不允许用 print - 新功能必须附带单元测试，测试文件放在 tests/ 对应目录下

这些约束写清楚之后，Agent 产出的代码质量会有一个明显的提升。你不写，它就按自己的“默认习惯”来，而那个默认习惯大概率跟你的项目不一致。

增量执行的意思是：不要一次性让 Agent 完成整个 Plan，而是分步骤执行，每步验证。比如 Plan 里有 5 个步骤，就让 Agent 先做第 1 步，你 review 通过后再做第 2 步。这样做的好处是，如果第 2 步方向错了，你只需要回滚第 2 步的改动，而不是整个任务的改动。

实操心得：我通常会让 Agent 在每一步完成之后，输出一个简短的“变更摘要”——改了什么文件、核心逻辑是什么、有没有偏离 Plan。这个摘要比直接看 diff 快得多，能帮我快速判断是否需要深入审查。

3.4 测试与验证阶段：Agent 自检清单

测试环节，我倾向于让 Agent 自己先跑一轮自检，人类再做最终验证。自检清单包括：

• 单元测试是否全部通过
• 新增代码的测试覆盖率是否达标
• 是否有明显的边界情况未处理
• 是否有硬编码的配置值应该提取
• 日志和错误处理是否符合规范

这个自检清单同样写在 CLAUDE.md 里，Agent 每次完成任务后自动执行。人类审查时，先看自检结果，如果自检都过了，再重点看核心逻辑；如果自检没过，直接打回让 Agent 修复。

这里有个细节：Agent 的自检结果要如实输出，不能只报喜不报忧。我遇到过 Agent 自检时发现测试没通过，但它“自作主张”改了测试用例让它通过。这种情况要在 CLAUDE.md 里明确禁止：“不允许修改测试用例来让测试通过，测试失败必须修复实现代码”。

3.5 代码审查阶段：人类审查的聚焦点

AI 生成的代码，人类审查的聚焦点跟审查人类代码有所不同。我总结下来，重点看这几个方面：

逻辑正确性——Agent 有时候会“自信地写错”。它生成的代码语法没问题、风格没问题，但业务逻辑是错的。比如把“大于等于”写成了“大于”，这种错误测试不一定能覆盖到。

边界处理——Agent 倾向于处理“正常路径”，对边界情况的考虑不够周全。空值、超长输入、并发冲突，这些需要人类重点检查。

架构一致性——Agent 可能引入跟项目现有架构不一致的模式。比如项目用的是事件驱动，它写了一个同步调用链。这种问题在单个文件里看不出来，需要结合项目整体架构来判断。

安全性——SQL 注入、XSS、权限校验缺失，这些安全问题在 AI 生成的代码里出现的概率不比人类低。审查时要特别留意。

4. Agent 编排与 Skill 体系的进阶玩法

4.1 单 Agent 的能力边界在哪里

在讨论多 Agent 之前，先要搞清楚单 Agent 的能力边界。根据我的实践，单 Agent 在以下场景下表现良好：

• 任务范围明确，涉及文件数量在 10 个以内
• 任务类型单一（纯编码、纯测试、纯文档）
• 上下文窗口能容纳所有相关文件

当任务超出这些边界时，单 Agent 开始出现问题：上下文溢出导致它“忘记”前面的约束、任务太复杂导致 Plan 质量下降、涉及多个技术栈时切换成本高。

这时候就需要考虑多 Agent 编排了。但我要强调：多 Agent 是解决方案，不是目标。不要为了用多 Agent 而用多 Agent。

4.2 多 Agent 编排的三种模式

我实践下来，多 Agent 编排有三种比较实用的模式：

模式一：流水线模式

Agent A 的输出是 Agent B 的输入，依次传递。比如：需求分析 Agent → 方案设计 Agent → 编码 Agent → 测试 Agent。这种模式适合流程清晰的场景，每个 Agent 的职责非常明确。

模式二：并行模式

多个 Agent 同时处理不同的子任务，最后汇总。比如前端 Agent 和后端 Agent 同时工作，各自完成自己的部分。这种模式适合任务可以清晰拆分的场景。

模式三：主从模式

一个“协调者 Agent”负责拆解任务、分配给“工作者 Agent”、汇总结果。这种模式最灵活，但也最难调试。协调者 Agent 的 prompt 设计直接决定了整个系统的效果。

我个人的建议是：从流水线模式开始。它的调试成本最低，每个环节的输入输出都是明确的，出问题容易定位。等流水线跑顺了，再考虑引入并行或主从模式。

4.3 Skill 体系的设计与沉淀

Skill 体系是 AI Native 团队的核心资产。一个好的 Skill 应该具备以下特征：

• 单一职责：一个 Skill 只做一件事
• 输入输出明确：调用者知道要传什么、会得到什么
• 可独立测试：不依赖其他 Skill 就能验证正确性
• 有文档：说明用途、参数、返回值、使用示例

Skill 的沉淀时机很重要。我的做法是：当一个操作被重复执行三次以上时，就把它封装成 Skill。比如“生成数据库迁移脚本”这个操作，如果每个 Sprint 都要做几次，那就值得封装。

Skill 的存放位置，我建议放在项目的.agent/skills/目录下，每个 Skill 一个文件，用 Markdown 描述。CLAUDE.md 里列出所有可用 Skill 的清单和简要说明，Agent 需要时读取对应的 Skill 文件。

注意事项：Skill 不是越多越好。Skill 太多会导致 Agent 在选择时犹豫，反而降低效率。我建议一个项目的 Skill 数量控制在 10-20 个之间，超过这个数量就要考虑合并或分层了。

4.4 Agent 记忆机制的设计

Agent 记忆是让 Agent 在多次会话之间保持上下文连续性的机制。没有记忆的 Agent，每次启动都是“失忆”状态，你需要重新告诉它所有背景信息。

记忆分两种：短期记忆和长期记忆。

短期记忆是当前会话内的上下文，由 Agent 工具自动管理。长期记忆需要你自己设计。我的做法是维护一个docs/agent-memory/目录，里面按主题存放 Agent 需要记住的信息：

• decisions.md：架构决策记录，为什么选 A 不选 B
• patterns.md：项目中常用的代码模式
• pitfalls.md：踩过的坑，避免重复犯错
• glossary.md：业务术语表

每次 Agent 启动时，CLAUDE.md 里指明这些文件的位置，Agent 按需读取。这样既保证了上下文的连续性，又不会把所有信息都塞进 prompt 导致上下文溢出。

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

5.1 Agent 产出质量不稳定的排查思路

这是最常见的问题。同一个任务，有时候 Agent 做得很好，有时候一塌糊涂。排查思路如下：

第一步：检查 CLAUDE.md 是否覆盖了相关约束。大部分质量问题源于约束缺失。Agent 不知道你的规范，自然按自己的习惯来。

第二步：检查 Plan 的质量。如果 Plan 本身就有问题，执行结果肯定有问题。Plan 太粗、涉及文件遗漏、风险点没识别，都会导致执行偏差。

第三步：检查上下文是否溢出。如果任务涉及的文件太多，Agent 的上下文窗口可能不够用，导致它“忘记”了前面的约束。这时候需要拆分任务。

第四步：检查 Skill 是否有 bug。如果任务调用了 Skill，Skill 的实现问题会直接体现在产出上。

5.2 Agent “自作主张”的预防与处理

Agent 自作主张的表现包括：修改了不该修改的文件、用了不该用的库、跳过了测试、改了测试用例来“通过”测试。

预防措施是在 CLAUDE.md 里明确写“禁区”：

## 禁区 - 不允许修改 tests/ 目录下的测试用例来让测试通过 - 不允许引入新的第三方依赖，除非在 Plan 中明确说明并获得确认 - 不允许修改 .env、config/production.yaml 等配置文件 - 不允许执行 git push、git rebase 等影响远程仓库的操作 - 不允许删除任何现有文件，只能新建或修改

处理方式：一旦发现 Agent 越界，立即回滚，然后在 CLAUDE.md 里补充对应的禁止规则。每一次越界都是一次完善约束的机会。

5.3 上下文窗口管理的实用技巧

上下文窗口是有限资源，管理好它能显著提升 Agent 的表现。几个实用技巧：

技巧一：分层加载。不是所有文件都需要一次性加载。CLAUDE.md 里指明“核心文件”和“参考文件”，Agent 先读核心文件，需要时再读参考文件。

技巧二：定期清理。docs/agent-memory/目录下的内容要定期清理，过时的决策记录、已经修复的坑，及时删除或归档。上下文里塞太多无关信息，会稀释关键信息的权重。

技巧三：用摘要代替全文。对于大型文件，不要让 Agent 读全文，而是维护一个摘要版本。比如一个 2000 行的配置文件，维护一个 50 行的摘要，说明每个配置块的作用。

5.4 常见问题速查表

6. 团队落地过程中的组织与协作调整

6.1 角色分工的重新定义

AI Native 团队里，角色分工跟传统团队有显著不同。我观察到的变化包括：

Tech Lead 的新职责：除了技术决策，还要负责 CLAUDE.md 的维护、Skill 体系的建设、Agent 编排方案的设计。这些工作占用的时间不少，需要纳入排期。

工程师的新职责：从“写代码”转向“审查代码”和“定义约束”。写代码的时间占比下降，但审查和定义的时间上升。这不是工作变轻松了，而是工作性质变了。

新增角色：Agent Ops。如果团队规模够大（10 人以上），可以考虑设置一个专门负责 Agent 基础设施的角色——维护配置文件、优化 Skill、排查 Agent 问题、沉淀最佳实践。

6.2 代码审查流程的调整

传统 Code Review 关注的是“代码写得对不对、好不好”。AI Native 模式下，Code Review 的关注点前移了：在 Plan 阶段就要审查“方案对不对”，代码审查更多是确认“实现是否符合 Plan”。

这意味着审查流程变成了两道关卡：Plan Review 和 Code Review。Plan Review 由 Tech Lead 或资深工程师负责，Code Review 可以由任何人执行，因为主要工作是确认实现与 Plan 的一致性。

这个调整带来的好处是：审查效率提升了。Plan Review 看的是几十行的计划，Code Review 看的是几百行的 diff，前者快得多。而且 Plan 阶段发现问题的修复成本远低于代码阶段。

6.3 知识沉淀方式的变革

传统团队的知识沉淀靠 Wiki、文档、口头传承。AI Native 团队的知识沉淀有三个新载体：

CLAUDE.md：项目级的规范和约束，是团队共识的集中体现。

Skill 库：可复用的操作能力，是团队经验的代码化封装。

Agent 记忆文件：决策记录、踩坑记录、模式总结，是团队历史的持续积累。

这三个载体的共同特点是：它们都是 Agent 可以直接读取和使用的。这意味着知识不再是“写给人看的”，而是“写给人和 Agent 共同使用的”。这个转变要求我们在写文档时更加结构化、更加精确，因为 Agent 不像人类那样能容忍模糊和歧义。

6.4 团队推广的渐进式路径

最后说说推广。我见过一些团队一上来就要求所有人用 AI Native 方式工作，结果阻力很大。我的建议是渐进式推广：

第一阶段：个人试点。选 1-2 个愿意尝试的工程师，让他们在自己的任务中使用这套方法，积累经验。

第二阶段：小范围推广。把试点经验整理成团队内部的实践指南，在 3-5 人的小组内推广，收集反馈。

第三阶段：全面推广。当小范围推广验证有效后，再向全团队推广。这时候 CLAUDE.md 和 Skill 库已经比较成熟了，新人的上手成本会低很多。

每个阶段的时间周期，根据团队规模和项目复杂度而定，我见过的最快是两个月走完三个阶段，慢的半年也正常。关键是不要跳过试点阶段直接全面推广，那样失败的概率很高。

实操心得：推广过程中，最重要的不是工具培训，而是心态调整。很多工程师一开始会抵触“让 AI 写代码”，觉得自己的价值被削弱了。这时候需要让他们看到：AI Native 模式下，工程师的价值不是降低了，而是转移了——从“写代码的速度”转移到“定义问题的能力”和“审查代码的判断力”。这两项能力，恰恰是资深工程师的核心竞争力。