1. 从“人肉流水线”到“AI Native 团队”为什么我要重写整个开发手册过去大半年我一直在带一个不到十人的小团队做产品迭代。说实话最初听到“AI Native”这个词的时候我跟很多人的反应一样——觉得又是一个包装概念。直到有一次我们为了赶一个版本连续加班两周结果复盘时发现真正花在“写代码”上的时间不到三成剩下七成全耗在了需求对齐、文档同步、环境配置、代码审查和跨模块联调上。那一刻我才意识到问题不在于我们不够努力而在于整个软件开发生命周期SDLC还是“人肉流水线”的模式AI 只是被当成一个高级补全工具塞在编辑器角落里。后来我花了大概三个月时间把团队的工作流从“人驱动、AI辅助”硬生生掰成了“AI Native 驱动、人把关”的模式。具体来说就是把 CLAUDE.md 作为项目级上下文锚点把 Plan Mode 作为需求拆解的第一入口把 Agent 作为执行单元嵌入到 SDLC 的每个环节。效果怎么说呢——同样一个中等复杂度的功能模块从需求到可合并的 PR过去平均要 3 到 5 天现在压缩到了 1 天以内而且代码审查时发现的低级问题反而更少了。这篇手册就是这三个月踩坑、调参、推翻重来的完整记录。它不是什么官方文档也不是理论综述而是一个一线小团队在真实项目里跑通的一套可复现流程。如果你正在带团队、或者自己一个人维护项目想搞清楚 AI Native 到底怎么落地、Agent 怎么编排、CLAUDE.md 和 Plan Mode 到底该怎么用那这篇内容应该能帮你省下不少试错时间。下面我按“设计思路—核心细节—实操过程—问题排查”四个板块来展开每个板块都会给出具体的配置、参数和踩坑记录。2. 整体设计与思路拆解为什么是 CLAUDE.md Plan Mode Agent 这三件套2.1 传统 SDLC 的断点在哪里在聊 AI Native 之前得先把传统 SDLC 的痛点说清楚。我们团队之前的工作流大概是这样的产品经理写 PRD开发看 PRD 写技术方案然后拆任务、估时、写代码、自测、提 PR、等 review、改 comment、合并。这个链条里信息损耗最大的环节有三个第一PRD 到技术方案之间的“翻译”全靠人脑不同人理解偏差很大第二任务拆分粒度依赖个人经验拆得太粗容易漏拆得太细管理成本高第三代码审查时reviewer 需要重新建立上下文效率极低。AI 工具最早介入的时候我们只是让它在编辑器里做代码补全。这解决的是“写”的问题但“想”和“对齐”的问题一点没动。后来我意识到AI Native 的核心不是让 AI 写更多代码而是让 AI 参与到“想”和“对齐”的环节里把人的角色从“执行者”上移到“决策者和把关者”。2.2 为什么选 CLAUDE.md 作为上下文锚点市面上做 AI 编程辅助的工具不少我们最终选择以 CLAUDE.md 为核心来组织项目上下文原因有几个。第一它是纯文本、项目内嵌、版本可控的不像某些工具把上下文存在云端或者私有格式里迁移和审计都很麻烦。第二它的结构足够灵活可以写项目概述、目录结构、编码规范、常用命令、架构决策记录甚至可以把“这个模块为什么这么设计”的来龙去脉写进去。第三也是最重要的一点——它天然适合作为 Agent 的“系统提示词”来源。每次 Agent 启动时先读 CLAUDE.md就等于把项目的“世界观”注入进去了。我们团队现在的 CLAUDE.md 大概控制在 800 到 1200 行之间分几个固定区块项目定位与核心领域模型、目录结构与模块职责、编码规范与命名约定、构建与测试命令、架构决策记录ADR、常见陷阱与历史包袱。每个区块都有明确的维护责任人变更走 PR 流程。这里有个经验CLAUDE.md 不是写一次就完事的它应该随着项目演进持续更新而且更新频率最好和代码变更频率挂钩。2.3 Plan Mode 为什么是需求拆解的第一入口Plan Mode 的本质是“先想清楚再动手”。在 AI Native 工作流里我要求团队所有非 trivial 的需求都必须先进入 Plan Mode由人来主导、AI 来辅助产出一份结构化的执行计划。这份计划至少包含目标描述、影响范围、涉及模块、任务拆分、每项任务的验收标准、风险点与回滚方案。为什么这一步不能省因为 Agent 执行的质量高度依赖于输入计划的质量。你给 Agent 一个模糊的指令它就会给你一个模糊的结果。你给它一个结构清晰、边界明确的计划它就能稳定输出可用的代码。我们内部有个说法Plan Mode 产出的计划就是 Agent 的“施工图纸”。图纸画得越细施工返工越少。2.4 Agent 在 SDLC 中的定位与编排逻辑Agent 在我们团队不是“一个万能助手”而是“一组有明确职责的执行单元”。我们目前把 Agent 分成几类需求分析 Agent、代码生成 Agent、测试生成 Agent、代码审查 Agent、文档同步 Agent。每类 Agent 都有自己的系统提示词、工具权限和输出格式约束。编排逻辑上我们采用“串行为主、局部并行”的方式。需求分析 Agent 先跑产出结构化需求然后代码生成 Agent 按模块并行执行测试生成 Agent 紧随其后代码审查 Agent 在 PR 创建后触发文档同步 Agent 在合并后触发。每个 Agent 的输出都会写入项目内的指定目录形成可追溯的执行记录。这里的关键是Agent 之间不直接通信而是通过文件系统这个“共享黑板”来传递状态。这样做的好处是解耦、可审计、可重放。3. 核心细节解析与实操要点CLAUDE.md、Plan Mode、Agent 配置的硬核细节3.1 CLAUDE.md 的区块设计与维护规范先看一个我们实际在用的 CLAUDE.md 骨架示例# 项目名称XXX 平台 ## 1. 项目定位与核心领域模型 - 业务目标... - 核心实体User, Order, Payment, ... - 关键流程下单 - 支付 - 履约 - 结算 ## 2. 目录结构与模块职责 - src/modules/user用户域负责认证、授权、profile - src/modules/order订单域负责创建、状态机、查询 - ... ## 3. 编码规范与命名约定 - 语言TypeScript strict mode - 命名文件名 kebab-case类型 PascalCase函数 camelCase - 错误处理统一使用 Result 类型禁止 throw 裸异常 ## 4. 构建与测试命令 - 安装pnpm install - 开发pnpm dev - 测试pnpm test -- --coverage - 类型检查pnpm typecheck ## 5. 架构决策记录ADR - ADR-001为什么选择事件驱动而非请求响应 - ADR-002为什么订单状态机不用第三方库 ## 6. 常见陷阱与历史包袱 - 支付模块的金额单位是分不是元 - 用户模块的软删除标记是 deleted_at不是 is_deleted这个骨架看起来简单但每一条都是踩过坑之后补上去的。比如“金额单位是分”这条就是因为早期 Agent 生成代码时默认用了元导致测试数据对不上排查了半天。再比如“禁止 throw 裸异常”这条是因为 Agent 生成的代码里经常出现未捕获的异常导致服务崩溃。维护规范上我们要求任何新增模块、修改核心接口、调整构建命令的 PR都必须同步更新 CLAUDE.md 对应区块。reviewer 在审查代码时也会检查 CLAUDE.md 是否同步。这条规则执行了两个月之后CLAUDE.md 的准确率明显提升Agent 生成代码的首次通过率也从最初的不到 40% 提升到了 70% 以上。3.2 Plan Mode 的执行流程与输出模板Plan Mode 在我们团队不是一个工具按钮而是一个强制流程。具体操作是需求提出后由负责人通常是 tech lead发起一个 Plan SessionAI 作为辅助人作为主导。Session 的目标是产出一份 Markdown 格式的执行计划存放在plans/目录下命名规则是YYYY-MM-DD-需求简称.md。计划模板如下# 执行计划XXX 功能 ## 1. 目标描述 一句话说明这个需求要解决什么问题验收标准是什么。 ## 2. 影响范围 - 涉及模块... - 涉及接口... - 数据库变更有/无如有则附 migration 说明 ## 3. 任务拆分 | 任务编号 | 任务描述 | 负责 Agent | 预估工时 | 依赖 | |---------|---------|-----------|---------|------| | T1 | 新增 Order 状态枚举 | code-gen | 0.5h | 无 | | T2 | 实现状态流转逻辑 | code-gen | 2h | T1 | | T3 | 补充单元测试 | test-gen | 1h | T2 | ## 4. 风险点与回滚方案 - 风险1状态机变更可能影响历史数据回滚方案是保留旧字段双写一周。 ## 5. 验收清单 - [ ] 单元测试覆盖率不低于 80% - [ ] 集成测试通过 - [ ] 文档已更新这个模板的关键在于“任务拆分”和“验收清单”。任务拆分要细到单个 Agent 能独立执行的程度验收清单要可量化、可自动检查。我们内部有个经验如果一个任务无法用一句话描述清楚验收标准那说明它拆得还不够细。3.3 Agent 的系统提示词设计与工具权限控制每个 Agent 的系统提示词都存放在.agents/目录下命名规则是agent-name.system.md。以代码生成 Agent 为例它的系统提示词大概长这样你是本项目的代码生成 Agent。你的职责是根据执行计划中的任务描述生成符合项目规范的代码。 你必须遵守以下规则 1. 每次执行前先读取 CLAUDE.md 和对应的执行计划文件。 2. 只修改任务描述中明确指定的文件不得擅自改动其他文件。 3. 生成的代码必须通过 pnpm typecheck 和 pnpm lint。 4. 如果任务描述不清晰停止执行并输出疑问不得猜测。 5. 输出格式先输出变更文件列表再输出每个文件的完整内容。 你的工具权限 - 可读整个项目目录 - 可写仅限任务描述中指定的文件路径 - 可执行pnpm typecheck, pnpm lint, pnpm test这里有几个细节值得展开。第一“只修改指定文件”这条规则非常重要早期没有这条约束时Agent 经常“顺手”重构其他模块导致 PR 范围失控。第二“停止执行并输出疑问”这条是为了避免 Agent 在信息不足时瞎猜。第三工具权限要显式声明尤其是写权限必须收窄到最小范围。3.4 多 Agent 协作的共享黑板机制Agent 之间不直接通信而是通过文件系统传递状态。具体来说每个 Agent 执行完后会在.agents/artifacts/目录下生成一个结构化输出文件命名规则是任务编号-agent名称.json。下一个 Agent 启动时先读取上游的 artifact 文件再开始执行。这种设计的好处是第一解耦任何一个 Agent 挂掉不影响其他 Agent 的已有产出第二可审计所有中间状态都有文件记录第三可重放只要 artifact 文件还在就能重新跑某个环节。我们内部把这套机制叫“共享黑板”灵感来自多智能体系统里的 blackboard architecture。4. 实操过程与核心环节实现从需求到合并的完整跑通记录4.1 环境准备与基础配置先列一下我们团队的基础环境配置方便你对照复现项目配置操作系统macOS 14 / Ubuntu 22.04运行时Node.js 20 LTS包管理pnpm 9.x代码托管自建 Git 服务CIGitHub Actions 兼容的 runnerAgent 运行环境本地 CLI 容器化沙盒Agent 运行环境这块要特别说一下。我们早期直接在本地跑 Agent结果出现过 Agent 误删文件、误改配置的情况。后来改成容器化沙盒每个 Agent 在独立容器里运行只挂载必要的项目目录网络权限也做了限制。这样即使 Agent 行为异常也不会影响宿主机。4.2 需求分析 Agent 的完整执行记录以一个真实需求为例给订单模块增加“部分退款”功能。需求分析 Agent 的输入是产品经理的原始描述输出是结构化的需求文档。执行过程如下第一步Agent 读取 CLAUDE.md建立项目上下文。第二步Agent 读取原始需求描述识别出关键实体和流程。第三步Agent 扫描现有订单模块代码识别出需要变更的接口和数据结构。第四步Agent 输出结构化需求文档包含功能描述、影响范围、边界条件、验收标准。这里有个实操细节我们在 Agent 的系统提示词里加了一条“必须列出至少三个边界条件”。这条规则逼着 Agent 去思考异常场景比如“退款金额超过已支付金额怎么办”“部分退款后再次退款怎么处理”。实测下来这条规则让需求文档的完整度提升了不少。4.3 代码生成 Agent 的任务执行与参数选择代码生成 Agent 执行时有几个关键参数需要配置参数说明我们的取值temperature生成随机性0.2max_tokens单次输出上限8000top_p核采样阈值0.95重试次数失败后重试3超时时间单任务超时300stemperature 设 0.2 是因为代码生成需要稳定性不需要创意。max_tokens 设 8000 是因为我们单个任务的文件变更量一般不超过这个范围。重试次数设 3 是因为偶尔会遇到网络抖动或模型输出截断。超时时间设 300s 是因为复杂任务可能需要多轮推理。执行流程上Agent 先读取执行计划和上游 artifact然后按任务编号逐个执行。每个任务执行完后Agent 会运行pnpm typecheck和pnpm lint只有通过才会写入文件。如果失败Agent 会尝试自动修复最多重试 3 次。3 次都失败就停止输出错误日志等待人工介入。4.4 测试生成 Agent 与代码审查 Agent 的联动测试生成 Agent 在代码生成 Agent 完成后触发。它的输入是代码变更 diff 和执行计划中的验收标准。输出是对应的单元测试和集成测试。这里有个经验测试生成 Agent 的系统提示词里要明确要求“每个验收标准至少对应一个测试用例”否则 Agent 容易漏测。代码审查 Agent 在 PR 创建后触发。它的输入是 PR diff、CLAUDE.md 和执行计划。输出是一份审查报告包含规范符合性检查、潜在 bug 识别、性能风险提示、安全风险提示。审查报告会作为 PR comment 自动发布。我们设置了一个规则如果审查报告里有“严重”级别的问题PR 会被自动标记为“需要人工复核”不允许直接合并。4.5 文档同步 Agent 与合并后收尾文档同步 Agent 在 PR 合并后触发。它的职责是更新 CLAUDE.md 中受影响的区块、更新 API 文档、更新 CHANGELOG。这个 Agent 的存在解决了“代码改了文档没改”的老大难问题。执行完后Agent 会输出一份变更摘要发到团队频道。整个流程跑下来从需求提出到 PR 合并平均耗时从原来的 3 到 5 天压缩到了 1 天以内。当然这个数字因需求复杂度而异简单需求可能几小时复杂需求可能两天。但整体效率提升是肉眼可见的。5. 常见问题与排查技巧实录那些文档里不会写的坑5.1 Agent 执行中断与沙盒初始化失败这是最常见的问题之一。典型报错是“agent execution terminated due to error”或者“error occurred during initialization of vm agent library failed”。我们排查下来原因主要有几类第一容器资源不足内存或 CPU 被耗尽第二挂载目录权限不对Agent 无法读写第三网络策略过严Agent 无法访问必要的依赖源。排查步骤我整理成了一个速查表现象可能原因排查方法解决方案启动即失败容器资源不足查看容器日志和资源监控提高内存/CPU 限额读写报错挂载权限不对检查目录权限和挂载配置调整权限或挂载方式依赖拉取失败网络策略过严检查网络策略和 DNS 配置放行必要域名或使用本地缓存执行中途中断超时或 OOM查看 Agent 日志和系统日志调整超时时间或拆分任务这里有个经验Agent 的日志一定要持久化不能只输出到控制台。我们后来把 Agent 日志统一写到.agents/logs/目录下按日期和任务编号归档排查问题时方便很多。5.2 Agent 输出不稳定与幻觉问题Agent 输出不稳定主要表现为生成的代码不符合规范、遗漏任务、或者“幻觉”出不存在的方法和接口。我们的应对策略有几个。第一在系统提示词里明确要求“只使用 CLAUDE.md 中列出的接口和方法”减少幻觉空间。第二在 Agent 执行前先让它输出一份“执行前检查清单”确认自己理解了任务。第三在 Agent 执行后用自动化脚本做一轮静态检查不通过就打回重做。实测下来这三条组合拳能把 Agent 输出的首次通过率从 40% 左右提升到 70% 以上。剩下的 30% 里大部分是任务描述本身不够清晰导致的需要人工介入调整计划。5.3 多 Agent 协作时的状态冲突多 Agent 并行执行时偶尔会出现状态冲突。比如两个 Agent 同时修改了同一个文件或者下游 Agent 读取到了过期的 artifact。我们的解决方案是第一任务拆分时确保文件级隔离不同 Agent 不碰同一个文件第二artifact 文件带版本号和时间戳下游 Agent 读取时校验版本第三引入一个轻量的协调 Agent负责在并行任务开始前做一次冲突检测。这里有个坑要提醒不要试图用复杂的锁机制来解决冲突那样会把系统搞得很重。我们的经验是与其事后加锁不如事前把任务拆到文件级隔离。拆得够细冲突自然就少了。5.4 安全边界与权限收窄的实操建议Agent 安全是我们非常重视的一块。除了前面提到的容器化沙盒和最小权限原则还有几条实操建议。第一Agent 的写权限必须显式声明默认无写权限。第二Agent 执行的命令要白名单化只允许运行预定义的安全命令。第三Agent 的输出要经过一轮敏感信息扫描防止把密钥、token 之类的信息写进代码或日志。第四定期审计 Agent 的执行记录发现异常行为及时调整策略。我们内部有个“三不原则”Agent 不直接访问生产环境、Agent 不持有长期凭证、Agent 不执行未经审查的脚本。这三条原则执行下来基本能覆盖大部分安全风险场景。5.5 团队协作与心智模型转变的软性经验最后聊点软性的。AI Native 落地最大的阻力往往不是技术而是人的心智模型。团队里总有人觉得“AI 生成的代码不靠谱”或者“让 AI 干活显得自己没价值”。我的经验是不要试图说服而是用结果说话。先找一个低风险模块做试点跑通流程把效率提升和 bug 率下降的数据摆出来自然就有人愿意跟进了。另外角色定位要重新梳理。在 AI Native 团队里人的核心价值不再是“写代码快”而是“定义问题准、拆解任务细、把关质量严”。我们团队现在的要求是每个人都要会写清晰的执行计划都要会审查 Agent 的输出都要对最终合并的代码负责。这个转变需要时间但一旦转过来整个团队的产出质量和速度都会有明显提升。6. 我个人的一些实操体会与后续扩展方向这套流程跑到现在最大的体会是AI Native 不是“用 AI 替代人”而是“重新划分人和 AI 的分工边界”。人负责定义问题、拆解任务、把关质量AI 负责执行、生成、检查。边界划清楚了效率自然就上来了。后续我打算在几个方向继续扩展。第一把 Agent 的执行记录做成可视化面板方便团队实时查看进度。第二引入更细粒度的成本核算追踪每个 Agent 的 token 消耗和执行耗时。第三探索把部分 Agent 的能力封装成可复用的 skill减少重复配置。第四在代码审查 Agent 里加入更多领域特定的检查规则比如针对我们业务特有的数据一致性约束。如果你也在带团队做 AI Native 转型我的建议是先从 CLAUDE.md 和 Plan Mode 这两个最基础的东西做起不要一上来就搞复杂的多 Agent 编排。基础打牢了后面的扩展会顺很多。踩坑是必然的但只要方向对每一步都算数。