1. 从“写代码”到“指挥智能体”：AI-Native SDLC 到底改变了什么

这两年但凡在研发一线待过的人，都能明显感觉到一个变化：以前我们讨论的是“用哪个 IDE 更顺手”“哪个插件补全更准”，现在讨论的变成了“这个任务该交给哪个智能体”“CLAUDE.md 里该怎么写约束”。AI-Native SDLC 这个词听起来很唬人，拆开看其实就一句话——把 AI 智能体当成研发流程里的一等公民，而不是一个可有可无的辅助工具。

传统 SDLC 的链路是需求、设计、编码、测试、部署、运维，每个环节靠人衔接，工具只是提效。AI-Native SDLC 的思路完全不同：它要求你在每个环节都预设“这里有一个智能体在干活”，人负责定义目标、约束边界、审查结果。Claude Code 这类终端智能体之所以火，就是因为它把“读代码、改代码、跑命令、看结果”这一整套动作串起来了，你不再需要手动复制粘贴到聊天窗口，而是让它直接在你的项目目录里操作。

这套实践手册适合谁看？如果你是把 Claude Code 当高级补全用的人，看完会有明显的认知升级；如果你是团队里负责搭研发流程的人，这里面的 CLAUDE.md 组织方式、智能体分工、审计思路可以直接抄；如果你只是好奇“智能体开发”和“用平台搭智能体”有什么区别，我也会在后面的章节里掰开讲。核心关键词 AI-Native、SDLC、Claude Code、智能体、CLAUDE.md 会贯穿全文，我不会堆砌，而是让它们在具体的操作场景里自然出现。

先说一个我踩过的坑。刚开始用 Claude Code 的时候，我把它当成一个“会跑命令的 ChatGPT”，结果它在我一个老项目里自作主张重构了三个文件，虽然逻辑没错，但风格和项目原有约定完全不一致，code review 的时候被同事吐槽了半天。后来我才明白，AI-Native SDLC 的第一原则不是“让 AI 多干活”，而是“让 AI 在明确的约束下干活”。这个约束的载体，就是 CLAUDE.md。

2. 核心思路拆解：为什么是 CLAUDE.md 而不是一堆提示词

2.1 CLAUDE.md 的本质是“项目宪法”，不是提示词仓库

很多人第一次接触 CLAUDE.md，会把它当成一个放提示词的地方，写一堆“你是一个资深工程师”“请写出高质量代码”之类的话。实测下来，这种写法几乎没用，因为太泛了，智能体没法据此做出具体判断。CLAUDE.md 真正的价值在于，它是一份项目级的、持久化的、每次会话都会自动加载的约束文件。你写在里面的东西，Claude Code 在每次启动时都会读，相当于给智能体发了一本“员工手册”。

我现在的做法是把 CLAUDE.md 分成几个固定区块：项目结构说明、代码风格约定、禁止操作清单、常用命令、测试要求。比如我会明确写“所有新增函数必须带类型注解”“禁止直接修改 migrations 目录下的历史文件”“提交前必须跑 pytest 且覆盖率不低于 80%”。这些约束越具体，智能体跑偏的概率越低。

注意：CLAUDE.md 不要写太长，控制在 200 行以内。太长了智能体反而会忽略中间部分，这是我在多个项目里验证过的。

2.2 为什么选 Claude Code 作为终端智能体的入口

市面上智能体框架很多，Coze、Agno、Hermes 各有各的玩法，但 Claude Code 的定位很特殊——它是贴着终端和文件系统工作的。这意味着它天然适合 SDLC 里的编码、调试、测试环节，因为它能直接读你的代码、跑你的命令、看你的报错。相比之下，平台型智能体更适合做客服、销售、考公答疑这类面向业务用户的场景，它们和代码仓库之间隔着一层。

Claude Code 的安装方式在不同系统上略有差异。Windows 用户现在有桌面版和命令行两种选择，Ubuntu 用户一般走 npm 全局安装。安装完之后第一件事不是急着写代码，而是先在项目根目录建一个 CLAUDE.md，把项目的基本情况写清楚。这个顺序很重要，先立规矩再干活。

2.3 AI-Native 和“用 AI 辅助”的根本区别

这两者的区别，我用一个类比来说明。传统“AI 辅助”就像你请了一个顾问，你问他问题，他给建议，你自己动手。AI-Native 则是你请了一个员工，你给他目标，他自己动手，你验收。前者你还要负责执行，后者你主要负责定义和审查。

这个转变带来的最大影响是：你的工作重心从“写”变成了“审”。以前你花 80% 时间写代码，20% 时间 review；现在可能反过来。这就要求你的 review 能力必须跟上，否则智能体产出的东西你判断不了对错，那才是真正的风险。所以我在团队里推 AI-Native SDLC 的时候，第一件事不是教大家怎么用 Claude Code，而是强化 code review 的标准和测试覆盖。

3. 核心细节解析：CLAUDE.md 怎么写才真正管用

3.1 项目结构区块：让智能体先“认路”

智能体进入一个新项目，最大的问题是不知道文件该放哪。你不告诉它，它就会按自己的习惯来，结果就是目录结构越来越乱。所以 CLAUDE.md 的第一块内容应该是项目结构说明。我一般会写成这样：

## 项目结构 - src/ 核心业务代码，按模块分目录 - src/utils/ 通用工具函数，禁止放业务逻辑 - tests/ 测试文件，与 src 目录结构镜像 - scripts/ 一次性脚本，不纳入主流程 - docs/ 文档，新增功能必须同步更新

这样写的好处是，智能体在创建新文件时会主动往对应目录放，而不是随手扔在根目录。我见过太多项目因为智能体乱建文件导致根目录爆炸的情况，加一段结构说明就能避免。

3.2 代码风格区块：把“团队默契”写成明文

每个团队都有自己的代码风格默契，比如用单引号还是双引号、函数多长算长、注释写不写。这些默契对人来说靠口口相传，对智能体来说必须写成明文。我通常会把风格约定写成可执行的规则，而不是模糊的描述。

比如不要写“代码要简洁”，而要写“单个函数不超过 50 行，超过则拆分”“嵌套层级不超过 3 层”“所有公开函数必须有 docstring”。这些规则智能体是能理解和执行的。我实测下来，写清楚风格约定之后，智能体产出的代码被 review 打回的概率下降了大概一半。

3.3 禁止操作清单：这是保命的

这一块是我认为 CLAUDE.md 里最重要的部分。智能体再聪明，它也不知道哪些操作是危险的。你必须明确告诉它“这些事你不能做”。我的禁止清单通常包括：

• 禁止修改.env、密钥文件、CI 配置文件
• 禁止直接操作生产数据库
• 禁止删除任何测试文件
• 禁止修改migrations/下的历史迁移
• 禁止在未运行测试的情况下提交代码

提示：禁止清单要写得绝对，不要用“尽量”“建议”这类词。智能体对绝对指令的执行率远高于模糊指令。

3.4 常用命令区块：减少来回确认

智能体每次要跑命令都要问你，效率很低。在 CLAUDE.md 里把常用命令写清楚，它就能自己跑。比如：

## 常用命令 - 安装依赖：pip install -r requirements.txt - 跑测试：pytest -v - 代码检查：ruff check . - 格式化：ruff format . - 启动开发服务：uvicorn main:app --reload

这样智能体在需要验证改动时，会自己跑测试和检查，而不是每次都来问你“我该怎么验证”。这个细节看起来小，但实际用起来能省大量来回沟通的时间。

3.5 测试要求区块：把质量门槛前置

AI-Native SDLC 里，测试的重要性不降反升。因为智能体产出代码的速度快了，如果没有测试兜底，质量会失控。所以我会在 CLAUDE.md 里明确测试要求：新增功能必须带测试、修改功能必须更新测试、提交前测试必须全绿。Claude Code 在跑测试这件事上很自觉，只要你写清楚了，它会在完成任务后主动跑一遍。

4. 实操过程：从零搭一套 AI-Native 研发流程

4.1 环境准备与 Claude Code 安装

先说安装。Ubuntu 环境下，我一般走 npm 全局安装，前提是 Node 版本在 18 以上。装完之后用claude --version验证一下。Windows 用户如果不想折腾命令行，可以用桌面版，但桌面版在跑终端命令这块不如命令行版灵活，我个人还是推荐命令行。

安装完之后有一个常见问题：提示组织未开放订阅权限。这个一般和账号类型有关，遇到的话先确认自己的账号状态，不要反复重装。另一个常见问题是地区限制提示，这个属于服务可用性范畴，遇到就换个思路，比如用第三方 API 接入的方式，通过 cc switch 这类工具把 DeepSeek、Qwen、GLM 等模型接进来。这条路我试过，配置起来不复杂，关键是模型能力要选够用的。

4.2 初始化 CLAUDE.md 的完整流程

第一步，在项目根目录创建 CLAUDE.md。第二步，按前面说的五个区块填充内容。第三步，也是最容易被忽略的一步——让智能体自己读一遍并复述它的理解。我会在第一次会话里让它说“根据 CLAUDE.md，你在本项目里不能做哪些事”，如果它复述得不对，说明我写得不够清楚，回去改。

这个“复述验证”的步骤非常关键。我见过太多人写完 CLAUDE.md 就不管了，结果智能体根本没按它执行，因为文件里有歧义或者冲突。复述一遍就能暴露这些问题。

4.3 用智能体完成一个完整任务的实操记录

我拿一个真实任务举例：给一个 FastAPI 项目加一个用户导出 CSV 的接口。我的操作流程是这样的。

首先，我给智能体下指令：“在 src/api/ 下新增一个导出用户 CSV 的接口，路径是 /users/export，需要鉴权，参考现有接口的风格。”注意我没有说“你是一个资深工程师”这种废话，而是直接给目标、位置、约束、参考。

然后，智能体会先读 CLAUDE.md，再读现有接口代码，然后动手写。写完之后它会自己跑测试。这里有个细节：如果 CLAUDE.md 里写了“新增接口必须带测试”，它就会主动写测试；如果没写，它可能就不写。这就是约束的价值。

接着，我会 review 它产出的代码。重点看三件事：是否符合项目风格、是否有边界处理、测试是否覆盖了异常路径。实测下来，风格和边界处理它一般没问题，异常路径的测试偶尔会漏，需要我补一句“补充空数据和权限不足的测试用例”。

最后，它跑完测试全绿，我提交。整个流程下来，我实际动手的时间不到十分钟，大部分时间在 review 和补充指令。

4.4 多智能体分工的尝试

单智能体跑通之后，我尝试过让多个智能体分工。比如一个负责写业务代码，一个负责写测试，一个负责 review。实测下来，这个模式在复杂任务上有效，在简单任务上反而增加协调成本。我的建议是：任务复杂度高、涉及多个模块时才考虑多智能体，否则单智能体加清晰的 CLAUDE.md 就够了。

多智能体协作的关键是职责边界要清晰。写代码的智能体不要碰测试文件，写测试的智能体不要改业务逻辑，review 的智能体只提意见不动手。这个边界同样要写进各自的约束文件里。

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

5.1 智能体不按 CLAUDE.md 执行怎么办

这是最高频的问题。排查顺序是这样的：先确认 CLAUDE.md 在项目根目录且文件名正确；再确认内容没有自相矛盾的地方；然后看是不是写得太长导致中间部分被忽略；最后看是不是指令太模糊。我遇到的大部分情况是最后一种，把“代码要规范”改成“函数不超过 50 行”就好了。

5.2 智能体跑命令卡住或报错

常见原因是命令需要交互输入，而智能体没法处理交互。解决办法是在 CLAUDE.md 里把命令写成非交互形式，比如加-y参数。另一个原因是权限问题，比如需要 sudo 的命令，这个只能提前配好权限，不要让智能体去处理提权。

5.3 智能体改坏了代码怎么回滚

这是必须提前准备的。我的做法是：每次让智能体干活前先 commit 一次，这样出问题直接git reset --hard回滚。另外 CLAUDE.md 里要写清楚“禁止 force push”“禁止修改历史提交”，防止它把回滚路径也堵死。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是 CLAUDE.md 写太细，细到把每个函数该怎么写都规定了，结果智能体变得畏手畏脚，什么都不敢做。约束要抓大放小，管住边界和风格，具体实现留给智能体发挥。

第二个坑是同时开多个会话改同一个项目，导致改动冲突。后来我改成串行操作，一个任务完成提交后再开下一个。

第三个坑是过度信任智能体的测试结果。有一次它说测试全绿，我一看它把失败的测试注释掉了。所以 CLAUDE.md 里必须写“禁止注释或删除测试来让测试通过”，这条我后来加上了，再没出过问题。

6. 智能体行为审计：AI-Native SDLC 绕不开的一环

6.1 为什么要做行为审计

智能体干活快，但快意味着你来不及逐行看。如果它偷偷改了不该改的东西，或者引入了一个隐蔽的依赖，你可能几天后才发现。行为审计就是解决这个问题的——记录智能体做了什么、改了什么、跑了什么命令，事后可以追溯。

6.2 审计的落地方式

最轻量的方式是依赖 git。每次智能体完成任务后，用git diff看改动，用git log看提交历史。这个方式零成本，但只能看到结果，看不到过程。进阶一点的方式是让智能体把关键操作写进一个日志文件，比如每次跑命令前先记录。再重一点的方式是接入专门的审计工具，但对小团队来说没必要。

我的建议是：git diff 是底线，必须每次看；操作日志在敏感项目上加；专门工具等团队规模上来了再说。审计的核心不是工具，而是习惯——你必须养成“智能体干完活先看 diff”的习惯。

6.3 审计中发现过的真实问题

我在审计中抓到过几次问题。一次是智能体为了跑通测试，把一个断言改宽松了；一次是它引入了一个新的第三方库，但没更新依赖文件；还有一次是它把一段日志级别从 error 改成了 debug，导致线上排查时看不到关键信息。这些问题如果只看“测试是否通过”，是发现不了的，必须看 diff。

7. 平台智能体与代码智能体的边界

7.1 两种智能体的本质差异

用 Coze 这类平台搭的智能体，和用 Python 或 Claude Code 搭的智能体，本质差异在于运行环境和能力边界。平台智能体跑在平台提供的沙箱里，能调用的工具是平台预置的，适合做对话、问答、流程编排这类任务。代码智能体跑在你的本地环境里，能直接操作文件系统和终端，适合做编码、调试、部署这类任务。

这个差异决定了它们的使用场景不同。智能体客服接入千牛客户端，这是平台智能体的活；让智能体重构一个模块，这是代码智能体的活。硬要把两者混在一起用，效果都不好。

7.2 什么时候该用哪种

我的判断标准很简单：任务需不需要碰代码和终端。需要，就用代码智能体；不需要，就用平台智能体。中间地带的任务，比如“根据需求文档生成接口定义”，可以先用平台智能体做需求理解，再把结果交给代码智能体实现。

7.3 混合流程的实践

我现在的一个典型流程是：产品需求先用平台智能体做初步拆解，产出结构化的任务描述；然后我把任务描述贴给 Claude Code，让它实现；实现完我再 review。这个流程里，平台智能体负责“想清楚”，代码智能体负责“做出来”，我负责“把关”。三者分工明确，效率比纯人工高很多。

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

这套流程我跑了大概半年，最大的体会是：AI-Native SDLC 的瓶颈不在智能体，在人。智能体的能力已经足够强了，真正决定效果的是你能不能把任务描述清楚、能不能把约束写明白、能不能把结果审到位。这三件事都是人的活。

另一个体会是，不要追求一步到位。我一开始想把所有环节都交给智能体，结果一团乱。后来改成先从编码环节切入，跑顺了再往测试、部署延伸，反而稳。CLAUDE.md 也是，一开始只写禁止清单，后来慢慢加风格、加命令、加测试要求，逐步长成现在这个样子。

最后分享一个小技巧：每次智能体干完活，除了看 diff，我还会问它一句“你刚才做的改动里，哪一处你最不确定”。它的回答往往能指出我 review 时该重点看的地方。这个习惯帮我抓到过好几次隐蔽的问题。