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 的核心差异先把差异摆清楚不然后面所有讨论都是空中楼阁。我画不了图但可以用一张表说清楚维度传统 SDLCAI Native SDLC上下文载体会议、文档、口头传递仓库内的 Markdown 文件CLAUDE.md 等执行主体人Agent 为主人做编排和验收计划方式排期表、甘特图Plan Mode 生成可执行计划人审核代码审查人看 diffAgent 自审 人抽检关键逻辑测试人写用例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_NAMEagent-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 写的比人写的详细多了它会把每个决策的理由都记下来。 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 的核心差异先把差异摆清楚不然后面所有讨论都是空中楼阁。我画不了图但可以用一张表说清楚维度传统 SDLCAI Native SDLC上下文载体会议、文档、口头传递仓库内的 Markdown 文件CLAUDE.md 等执行主体人Agent 为主人做编排和验收计划方式排期表、甘特图Plan Mode 生成可执行计划人审核代码审查人看 diffAgent 自审 人抽检关键逻辑测试人写用例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_NAMEagent-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 写的比人写的详细多了它会把每个决策的理由都记下来。