AI Native 团队开发落地手册：CLAUDE.md、Plan Mode 与 Agent 实战-平芜编程栈

1. 从“AI Native 团队”说起：为什么传统 SDLC 到了必须重写的时候

“AI Native 团队完整开发落地手册”这个标题，第一次看到的时候我正带着一个六人小组做内部工具重构。当时我们刚把 CI 流水线跑通，结果发现一个尴尬的事实：代码是 AI 写的，测试是 AI 跑的，连 Code Review 的意见都是 AI 提的，但我们的开发流程还是三年前那套——需求评审、排期、编码、提测、上线，一步不少。流程没变，工具变了，结果就是 AI 带来的效率提升被流程本身吃掉了大半。

这就是我理解“AI Native”这个词的起点。它不是“用了 AI 工具的团队”，而是把 AI 当作团队的一等公民，围绕 AI 的能力边界重新设计整个软件开发生命周期（SDLC）。传统 SDLC 假设“人写代码、人做决策、人传递上下文”，而 AI Native SDLC 假设“Agent 承担大部分执行、人负责定义意图和验收标准、上下文通过文件而非会议传递”。

这个手册要解决的问题很具体：一个团队想真正落地 AI Native 研发范式，到底要改哪些东西？改到什么程度？哪些是必须的，哪些是锦上添花？我踩过的坑包括但不限于——Agent 在沙盒里跑着跑着上下文丢了、多个 Agent 并行改同一个文件互相覆盖、CLAUDE.md 写了一堆规则但 Agent 根本不遵守、Plan Mode 出来的计划看着很美执行起来全是幻觉。

适合读这篇的人：正在或准备把 AI Agent 引入研发流程的技术负责人、想搞清楚 AI Native 到底怎么落地的工程师、以及被“AI 提效”口号忽悠过一轮想看看真实操作细节的人。下面我按“设计思路—核心细节—实操过程—问题排查”四块展开，每一块都尽量给到可以直接抄的配置和步骤。

2. 整体设计与思路拆解：AI Native SDLC 到底长什么样

2.1 传统 SDLC 与 AI Native SDLC 的核心差异

先把差异摆清楚，不然后面所有讨论都是空中楼阁。我画不了图，但可以用一张表说清楚：

维度	传统 SDLC	AI Native SDLC
上下文载体	会议、文档、口头传递	仓库内的 Markdown 文件（CLAUDE.md 等）
执行主体	人	Agent 为主，人做编排和验收
计划方式	排期表、甘特图	Plan Mode 生成可执行计划，人审核
代码审查	人看 diff	Agent 自审 + 人抽检关键逻辑
测试	人写用例	Agent 根据意图生成用例，人补边界
失败模式	人漏了、人忘了	上下文丢失、幻觉、并发冲突

这张表里最关键的一行是“上下文载体”。传统 SDLC 里，上下文存在人脑和会议记录里，AI Native SDLC 里，上下文必须显式地写在仓库里，因为 Agent 没有“记忆”，它每次启动都是白纸一张。CLAUDE.md 这类文件就是给 Agent 的“入职手册”。

2.2 为什么是 CLAUDE.md + Plan Mode + Agent 这个组合

热词里出现了 CLAUDE.md、Plan Mode、Agent、SDLC，这几个词其实构成了一个最小闭环。我试过几种组合，最后稳定下来的原因是：

CLAUDE.md 解决“Agent 不知道规矩”的问题。它放在仓库根目录，Agent 每次启动先读它。里面写什么？不是写“你要好好写代码”这种废话，而是写具体的：项目用什么语言、目录结构什么样、提交信息格式、哪些文件不能动、测试怎么跑。我见过最有效的 CLAUDE.md 只有 40 行，但每一条都是可执行的约束。

Plan Mode 解决“Agent 上来就乱改”的问题。传统用法是让 Agent 直接改代码，结果它改了一堆不该改的。Plan Mode 强制它先输出计划，人确认后再执行。这个“先计划后执行”的分离，把 Agent 的幻觉挡在了执行之前。我实测下来，开启 Plan Mode 后，Agent 做无用功的比例从大概三成降到了一成以下。

Agent 解决“执行”的问题。但 Agent 不是越多越好。我一开始搞了五个 Agent 并行，结果它们互相覆盖文件，调试了两天才发现是并发写冲突。后来改成“一个主 Agent + 按需派生”，稳定多了。

2.3 方案选型的几个关键取舍

取舍一：Agent 跑在本地还是沙盒？热词里有“显示更新 agent 沙盒”，说明很多人遇到沙盒问题。我的经验是：涉及文件系统操作的，必须跑在沙盒里，否则 Agent 一个rm -rf就能让你哭。但沙盒的代价是上下文隔离，Agent 看不到沙盒外的文件。解决办法是把需要的上下文提前复制进沙盒，或者用挂载的方式只读挂载。

取舍二：用现成 Agent 框架还是自己搭？热词里 agent 框架、agent 架构、spring ai agent、adk.dev 的 kotlin 快速上手都出现了。我的建议是：如果团队没有特殊需求，用现成的（比如基于 Claude 的 Agent 能力）最快。自己搭框架的坑在于，你要处理上下文管理、工具调用、错误重试、并发控制，这些现成框架已经踩过一遍了。除非你有非常特殊的编排需求，否则不值得。

取舍三：Agent 记忆怎么存？热词里“agent 记忆”是个高频词。我的做法很简单：不用向量数据库，就用仓库里的 Markdown 文件。每次 Agent 完成一个任务，把关键决策和上下文追加到一个DECISIONS.md里。下次启动时让它先读这个文件。比向量检索简单，而且可审计。

3. 核心细节解析与实操要点：CLAUDE.md 怎么写、Plan Mode 怎么用、Agent 怎么配

3.1 CLAUDE.md 的写法：从“废话文档”到“可执行约束”

我见过太多 CLAUDE.md 写成这样：“请编写高质量的代码”“注意代码风格”“遵循最佳实践”。这种文档 Agent 读了等于没读，因为它不知道“高质量”具体指什么。

有效的 CLAUDE.md 应该像给新员工的 SOP，每一条都能被验证。我现在的模板大概长这样：

# 项目上下文 ## 技术栈 - 语言：TypeScript 5.x，严格模式 - 框架：Next.js 14 App Router - 测试：Vitest + Testing Library - 包管理：pnpm ## 目录约定 - `src/app/` 放路由和页面 - `src/components/` 放可复用组件 - `src/lib/` 放工具函数 - 不要动 `src/generated/`，那是自动生成的 ## 提交规范 - 格式：`type(scope): description` - type 只能是 feat/fix/refactor/test/docs/chore - 每次提交只做一件事 ## 禁止事项 - 不要引入新的依赖，除非在计划里说明理由 - 不要修改 `.env` 和 `next.config.js` - 不要写 `any` 类型 ## 测试要求 - 新功能必须有测试 - 跑测试用 `pnpm test` - 测试失败不要跳过，要修

这个文件的关键在于具体。“不要写 any 类型”比“注意类型安全”有用一百倍。另外，我建议把 CLAUDE.md 控制在 100 行以内，太长了 Agent 会忽略中间部分。

注意：CLAUDE.md 不是写一次就完事。每次 Agent 犯了新错误，就把对应的约束加进去。我现在的 CLAUDE.md 是迭代了十几版的结果，每一条背后都是一个踩过的坑。

3.2 Plan Mode 的正确打开方式

Plan Mode 的核心价值是把 Agent 的思考过程暴露出来。不开 Plan Mode 的时候，Agent 直接改代码，你只能看到 diff，不知道它为什么这么改。开了之后，它先输出一个计划，你能看到它的推理链条。

我的操作流程是这样的：

给 Agent 一个任务描述，比如“给用户列表页加一个按注册时间排序的功能”
Agent 输出计划：它会读哪些文件、改哪些文件、加什么测试
我审核计划，重点看三件事：有没有动不该动的文件、有没有漏掉测试、有没有引入新依赖
确认后让它执行
执行完我抽检关键 diff

这里有个技巧：计划里如果出现“重构”两个字，要特别警惕。Agent 经常借着加功能的名义顺手重构，结果改出一堆无关的 diff。我现在的做法是在 CLAUDE.md 里明确写“不要顺手重构，只做被要求的事”。

另一个技巧：让 Agent 在计划里列出它不确定的地方。比如“我不确定排序应该在前端做还是后端做”。这些不确定点就是你需要介入的地方。我试过让 Agent 自己决定，结果它选了前端排序，但数据量大了之后性能崩了。

3.3 Agent 配置：并发、沙盒、工具权限

热词里“ai agent 怎么扛并发”是个很实际的问题。我的经验是：不要试图让多个 Agent 同时改同一个仓库。并发冲突的调试成本远高于串行执行的时间成本。

如果确实需要并行，我的做法是：

每个 Agent 在独立的 git worktree 里工作
完成后由人合并
合并时重点看冲突文件

沙盒配置方面，热词里“显示更新 agent 沙盒”和“error occurred during initialization of vm agent library failed”都指向沙盒初始化问题。我遇到过的坑包括：沙盒里没有网络导致依赖装不上、沙盒路径映射错误导致文件找不到、沙盒资源限制导致大项目跑不动。

解决办法：

沙盒镜像里预装常用依赖
用只读挂载把仓库挂进去，输出写到单独目录
给沙盒至少 4GB 内存，大项目 8GB

工具权限方面，我建议默认最小权限。Agent 默认只能读文件、写指定目录、跑测试命令。需要执行其他命令时，在计划里说明理由，人批准后再开。我见过 Agent 自己git push --force的案例，虽然最后没出事，但想想后怕。

3.4 Agent Skill 的设计：让 Agent 学会“怎么做事”

热词里“agent skill 教程”“agent skills 测试”“claude agent skills: a first principles deep dive”出现频率很高。Skill 的本质是把一类任务的执行方法固化下来，让 Agent 不用每次重新摸索。

我现在的 Skill 大概分三类：

第一类是操作类 Skill，比如“如何添加一个新页面”。里面写清楚：在哪个目录建文件、用什么模板、需要改哪些配置文件、跑什么测试。Agent 遇到类似任务时直接调用这个 Skill，不用重新推理。

第二类是检查类 Skill，比如“提交前检查清单”。里面写：跑 lint、跑测试、检查有没有 console.log、检查有没有 TODO。Agent 在提交前自动跑一遍。

第三类是恢复类 Skill，比如“测试失败时怎么排查”。里面写：先看错误信息、再定位文件、再检查最近改动、最后尝试修复。这个 Skill 在 Agent 遇到测试失败时自动触发。

Skill 的写法跟 CLAUDE.md 类似，要具体、可执行。我见过有人把 Skill 写成一篇论文，Agent 根本读不完。我的经验是每个 Skill 不超过 50 行，只写关键步骤。

4. 实操过程与核心环节实现：从零搭一个 AI Native 工作流

4.1 环境准备与仓库初始化

假设你有一个现成的项目，想改造成 AI Native 工作流。第一步不是装工具，而是整理仓库。

我做的第一件事是清理仓库根目录。把散落的脚本、临时文件、过时的文档全部归档到archive/目录。根目录只留：src/、tests/、CLAUDE.md、README.md、package.json（或对应语言的配置文件）。为什么？因为 Agent 启动时会扫描根目录，文件太多它会抓不住重点。

第二步是写 CLAUDE.md。按 3.1 的模板来，先写技术栈和目录约定，禁止事项和测试要求可以后面慢慢加。

第三步是配置 Agent 的启动脚本。我用的是最简单的方案：一个 shell 脚本，做三件事——检查沙盒是否运行、把仓库挂载进去、启动 Agent 并传入任务描述。

#!/bin/bash # start-agent.sh TASK="$1" SANDBOX_NAME="agent-sandbox" # 检查沙盒 if ! docker ps | grep -q $SANDBOX_NAME; then echo "沙盒未运行，正在启动..." docker run -d --name $SANDBOX_NAME \ -v $(pwd):/workspace:ro \ -v $(pwd)/.agent-output:/output \ -m 4g \ agent-image:latest fi # 启动 Agent docker exec -it $SANDBOX_NAME \ agent-cli --task "$TASK" --context /workspace/CLAUDE.md

这个脚本的关键点是:ro只读挂载。Agent 不能直接改仓库，只能把改动写到/output，然后由人审核后合并。这个“人在环上”的设计，是我踩了无数次坑之后定下来的。

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

我拿一个真实任务来演示：给一个 Next.js 项目加“用户导出 CSV”功能。

任务描述：在用户列表页加一个“导出 CSV”按钮，点击后下载当前筛选条件下的用户数据。

第一步：Agent 读 CLAUDE.md 和 Plan Mode 输出计划。

Agent 的计划大概是：

读src/app/users/page.tsx了解现有结构
读src/lib/api.ts了解数据获取方式
在src/components/下新建ExportButton.tsx
在src/lib/下新建csv.ts处理 CSV 生成
修改page.tsx引入按钮
加测试ExportButton.test.tsx和csv.test.ts

第二步：我审核计划。

我发现两个问题：一是 Agent 没提“当前筛选条件”怎么获取，二是没提大数据量时的性能。我在计划上批注：“筛选条件从 URL query 取，大数据量时分批处理”。Agent 更新计划后重新提交。

第三步：Agent 执行。

执行过程中 Agent 遇到一个错误：csv.ts里用了Buffer，但项目是浏览器环境。它自己发现了，改成用Blob。这个自我纠错能力是 Plan Mode 带来的——它在计划里写了“用 Buffer 生成 CSV”，执行时发现不对，回头改了。

第四步：我审核 diff。

重点看三处：CSV 转义逻辑（有没有处理逗号和换行）、筛选条件传递（有没有漏参数）、测试覆盖（有没有测边界）。发现 CSV 转义漏了双引号，让 Agent 补上。

第五步：合并。

Agent 的改动在/output目录，我 review 后git apply到主仓库，跑一遍完整测试，提交。

这个流程走下来，一个中等复杂度的功能大概 20 分钟，其中我花在审核上的时间大概 5 分钟。比我自己写快，但快得有限。真正的效率提升在于批量任务——比如同时让 Agent 处理五个独立的 bug fix，我只需要审核五份 diff。

4.3 多 Agent 协作的实操配置

热词里“多 agent”和“agent 框架与编排”是很多人关心的。我试过几种编排方式，最后稳定下来的是“主从模式”：

主 Agent：负责任务分解和结果汇总。它不直接改代码，只做调度。
子 Agent：每个负责一个子任务，在独立 worktree 里工作。
人：审核主 Agent 的分解方案，审核子 Agent 的产出。

配置上，主 Agent 的 CLAUDE.md 里写清楚“你只做分解，不做执行”。子 Agent 的 CLAUDE.md 里写清楚“你只做被分配的子任务，不要越界”。

我遇到的最大坑是子 Agent 之间上下文不一致。比如子 Agent A 改了接口签名，子 Agent B 还在用旧签名。解决办法是：主 Agent 在分解任务时，先确定接口契约，把契约写进每个子 Agent 的上下文里。

注意：多 Agent 不是越多越好。我试过 8 个 Agent 并行，结果协调成本比收益还高。现在我的经验值是：3 个以内并行比较稳，超过 5 个就要考虑是不是任务分解本身有问题。

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

5.1 Agent 执行中断与错误排查速查表

现象	可能原因	排查步骤	解决办法
Agent 执行到一半停了	上下文超限	看日志里 token 数	拆分任务，减少单次上下文
沙盒初始化失败	镜像问题或资源不足	看 docker logs	重建沙盒，加内存
Agent 改了不该改的文件	CLAUDE.md 约束不够	看 diff	加禁止事项到 CLAUDE.md
测试跑不过但 Agent 说过了	Agent 跳过了测试	看测试日志	在 CLAUDE.md 里禁止跳过测试
多个 Agent 互相覆盖	并发写冲突	看 git status	改用 worktree 隔离
Agent 反复改同一个地方	陷入循环	看执行轮数	设最大轮数限制，超了人工介入
计划很美好执行全错	幻觉	对比计划和 diff	缩小任务粒度，加强审核

这张表里的每一条都是我实际遇到过的。最坑的是“Agent 反复改同一个地方”，有一次它在一个类型错误上循环了 20 多轮，烧了一堆 token 还没解决。后来我加了最大轮数限制，超过 10 轮就停下来让我看。

5.2 几个独家避坑技巧

技巧一：给 Agent 的上下文要“刚刚好”。太少了它不知道背景，太多了它抓不住重点。我的经验是：CLAUDE.md 控制在 100 行内，任务描述控制在 200 字内，相关文件不超过 5 个。如果任务需要更多上下文，说明任务该拆了。

技巧二：用“反向验证”代替“正向确认”。不要让 Agent 说“我做完了”，让它说“我改了哪些文件、跑了哪些测试、结果是什么”。前者是它的主观判断，后者是可验证的事实。我现在的流程里，Agent 必须输出一个结构化的完成报告，包含文件列表、测试结果、未解决的问题。

技巧三：把“不确定”当成一等公民。Agent 经常在不确定的时候硬编一个答案。我在 CLAUDE.md 里明确写：“遇到不确定的地方，停下来问，不要猜。” 这个约束加进去之后，Agent 的幻觉明显少了。

技巧四：定期清理 Agent 的“记忆”。如果用了 DECISIONS.md 这类记忆文件，要定期归档。我见过一个项目，DECISIONS.md 攒了 500 多行，Agent 每次启动读它要花好几秒，而且里面很多过时的决策反而干扰了它。现在我的做法是每月归档一次，只留最近一个月的决策。

技巧五：Agent 的产出必须过 CI。不管 Agent 说它跑过测试没有，合并前必须过一遍完整 CI。我遇到过 Agent 说“测试全过”，结果是因为它只跑了它改的那个文件的测试，没跑全量。CI 是最后一道防线，不能省。

5.3 关于“Agent 安全”的实操建议

热词里“agent 安全”是个绕不开的话题。我的安全原则很简单：Agent 不能做不可逆的操作。

具体来说：

不能直接 push 到主分支
不能删文件（只能移到 archive）
不能改 CI 配置
不能访问生产环境
不能装全局依赖

这些约束写在 CLAUDE.md 里，同时在沙盒层面做硬限制。比如沙盒里没有主分支的写权限，没有生产环境的凭证。我始终认为，Agent 的安全不能靠“它应该不会”，要靠“它就算想也做不到”。

6. 我个人的落地体会

这套工作流我跑了大概半年，最大的体会是：AI Native 不是让 AI 替人写代码，而是让 AI 替人做那些重复的、有明确规则的、不需要创造性决策的事。真正需要人做的——定义问题、设计架构、判断取舍、验收结果——一点没少，反而因为 Agent 产出多了，审核压力更大了。

另一个体会是：流程改造比工具引入难十倍。装个 Agent 工具一天就够了，但让团队接受“先写 CLAUDE.md 再写代码”“先出计划再执行”“Agent 的产出必须过 CI”这些规矩，花了两个月。中间有人觉得麻烦想回到老流程，直到有一次 Agent 在 Plan Mode 里拦下了一个会导致数据丢失的改动，大家才真正认可这套流程的价值。

最后分享一个我最近在用的技巧：让 Agent 写“变更日志”。每次任务完成后，Agent 在CHANGELOG.md里追加一条，写清楚改了什么、为什么改、影响范围。这个日志后来成了我们排查线上问题的重要线索——因为 Agent 写的比人写的详细多了，它会把每个决策的理由都记下来。