1. 从“人肉流水线”到“AI Native 团队”为什么我要重写整个研发手册过去大半年我一直在带一个不到十人的小团队做产品迭代。说是“敏捷开发”实际上大部分时间都耗在了写文档、对齐接口、补测试、改注释这些重复劳动上。直到我把 Claude Code、Codex 这类工具真正嵌进日常流程才发现问题根本不是“AI 能不能写代码”而是整个软件开发生命周期SDLC的协作方式需要被重新设计。这份手册就是那段时间踩坑之后的产物。它不讲空泛的“AI 提效”而是回答一个具体问题当一个团队把 AI 当作正式成员而非玩具时项目该怎么组织、代码该怎么管、人该怎么配合。适合三类人看正在尝试把 AI 工具引入团队的技术负责人、想搞清楚 AI Native 研发到底怎么落地的一线工程师、以及被各种“Agent 框架”绕晕了不知道从哪下手的人。核心思路只有一句话把 AI 当成一个需要明确上下文、明确边界、明确验收标准的初级工程师来管理。听起来简单但真做起来光是“怎么让 AI 知道项目规范”这一件事就够折腾好几轮。2. AI Native 研发范式的核心设计逻辑2.1 传统 SDLC 在 AI 介入后到底哪里变了传统软件开发生命周期大致是需求 → 设计 → 编码 → 测试 → 部署 → 运维。每个环节由人主导工具只是辅助。AI 介入之后变化最大的不是“编码”这一步而是信息传递的方式。以前一个需求从产品经理传到开发手里中间要经过 PRD 文档、原型图、口头对齐、技术方案评审。信息在传递过程中不断损耗最后写出来的代码和最初的需求可能已经偏了十万八千里。AI 没有“悟性”你给它什么上下文它就产出什么结果。这意味着上下文的质量直接决定产出质量。我试过让 AI 直接根据一句话需求写代码结果它生成了一堆看起来合理但完全不符合项目架构的代码。后来我意识到问题不在 AI而在我没有把“项目规范”这个东西显式地告诉它。于是就有了CLAUDE.md这个文件。2.2 为什么是 CLAUDE.md 而不是别的CLAUDE.md本质上是一个放在项目根目录的 Markdown 文件用来告诉 AI 这个项目的技术栈、目录结构、编码规范、常用命令、禁止事项。它不是什么官方标准而是 Claude Code 这个工具约定俗成的入口文件。类似的还有.cursorrules、AGENTS.md逻辑都一样给 AI 一个稳定的、可版本控制的上下文锚点。为什么不用聊天记录因为聊天记录是临时的、碎片化的而且每次新开一个会话AI 就“失忆”了。CLAUDE.md跟着代码仓库走任何人 clone 下来都能看到AI 每次启动也会自动读取。这就把“项目知识”从人的脑子里、从聊天窗口里固化到了代码仓库里。我现在的做法是CLAUDE.md里至少包含这几块内容——项目一句话简介、技术栈和版本、目录结构说明、常用命令构建、测试、lint、编码规范命名、注释、错误处理、禁止事项比如不要动某个目录、不要引入新依赖。写的时候要具体不要写“遵循最佳实践”这种废话要写“函数名用 camelCase常量用 UPPER_SNAKE_CASE”。2.3 Plan Mode让 AI 先想清楚再动手Claude Code 有一个模式叫 Plan Mode开启之后 AI 不会直接改代码而是先输出一个执行计划等你确认了再动手。这个功能看起来不起眼但实际用下来它把 AI 从“自动补全”变成了“可审查的协作者”。我踩过的坑是有一次让 AI 重构一个模块它直接开始改文件改到一半我发现方向不对但已经改了好几个文件回滚都麻烦。后来我强制要求团队任何涉及超过两个文件的改动必须先走 Plan Mode。AI 输出的计划里会列出它打算改哪些文件、每个文件改什么、为什么这么改。我只需要扫一眼就能判断方向对不对不对就让它重新规划成本极低。这个习惯养成之后代码 review 的压力小了很多。因为方向性的错误在 Plan 阶段就被拦住了不会等到代码写完才发现。2.4 Agent 在团队里的角色定位很多人把 Agent 想得太玄乎觉得它能自主完成一切。实际用下来Agent 更像是一个执行力很强但缺乏判断力的实习生。你给它清晰的任务描述和上下文它能干得很好你给它模糊的指令它就自由发挥结果往往不是你想要的。所以在团队里我给 Agent 的定位是执行层。人负责拆解任务、定义验收标准、审查产出Agent 负责按照CLAUDE.md里的规范去实现。具体来说Agent 承担的工作包括根据 Plan 写代码、补单元测试、更新文档注释、跑 lint 和格式化、生成 commit message。人不应该让 Agent 去做架构决策、技术选型、需求优先级判断这些需要上下文和判断力的事情。3. 核心细节解析与实操要点3.1 CLAUDE.md 到底怎么写才有效我见过很多团队的CLAUDE.md写得像 README全是项目介绍没有一条可执行的规范。这种文件对 AI 来说等于没写。有效的CLAUDE.md应该像一份给新人的入职指南具体、可操作、有例子。我自己的模板大概长这样# 项目规范 ## 技术栈 - 语言TypeScript 5.x - 框架React 18 Vite - 状态管理Zustand - 测试Vitest Testing Library ## 目录结构 - src/components通用组件每个组件一个目录 - src/pages页面级组件 - src/lib工具函数 - src/types全局类型定义 ## 编码规范 - 组件文件用 PascalCase工具函数用 camelCase - 禁止使用 any必要时用 unknown 加类型守卫 - 所有导出函数必须有 JSDoc 注释 - 错误处理统一用 Result 类型不要 throw ## 常用命令 - 安装依赖pnpm install - 开发pnpm dev - 测试pnpm test - 构建pnpm build ## 禁止事项 - 不要修改 src/lib/legacy 目录下的文件 - 不要引入新的第三方依赖除非在 PR 描述里说明理由 - 不要删除现有的测试用例这份文件大概两百行覆盖了 AI 日常需要知道的所有信息。关键是每一条都是可验证的AI 看完之后知道什么能做、什么不能做、怎么做。注意CLAUDE.md不是写一次就完事的。每次发现 AI 犯了同样的错误就应该把对应的规范补进去。它应该是一个活的文档随着项目演进不断更新。3.2 Plan Mode 的正确打开方式Plan Mode 的核心价值在于把“执行”和“决策”分离。AI 在 Plan 阶段只输出计划不碰代码人审查计划确认后再让 AI 执行。这个流程听起来多了一步但实际上省掉了大量返工时间。我总结了一个 Plan 审查清单每次 AI 输出计划后我会快速过一遍检查项判断标准改动范围是否只涉及必要的文件有没有误伤方案合理性是否符合项目现有架构有没有引入不必要的复杂度遗漏风险有没有考虑边界情况、错误处理、测试更新规范符合度是否遵循 CLAUDE.md 里的编码规范如果计划有问题直接告诉 AI “第三点不对应该用 X 方案而不是 Y 方案重新规划”。AI 会基于反馈重新输出计划。这个过程通常一两轮就能收敛比写完代码再改快得多。3.3 Agent 任务拆解的粒度控制给 Agent 派任务粒度太粗它做不好粒度太细又失去了自动化的意义。我的经验是一个任务对应一个可独立验证的产出。比如“实现用户登录接口”这个粒度就太粗里面包含了路由、参数校验、数据库查询、token 生成、错误处理等多个子任务。拆成“实现登录路由和参数校验”“实现用户查询和密码比对”“实现 token 生成和返回”就合适得多。每个子任务应该满足有明确的输入输出、有可验证的验收标准、不依赖其他未完成的任务。这样 Agent 做完一个人可以快速验证没问题再继续下一个。如果一次性让 Agent 做太多中间某一步错了后面全错排查成本很高。3.4 上下文窗口管理别让 AI “失忆”AI 的上下文窗口是有限的。当一个会话聊得太长早期的信息会被挤出去AI 就开始“失忆”忘记之前定的规范。我遇到过好几次聊到后面AI 突然开始用any类型而CLAUDE.md里明明写了禁止使用。解决办法有两个一是定期开新会话把当前进度和关键决策写到一个临时文件里新会话开始时让 AI 先读这个文件二是把重要规范放在CLAUDE.md里因为它是每次会话都会自动加载的不受上下文窗口影响。我现在的习惯是每完成一个功能模块就开一个新会话。旧会话里如果有重要的讨论结论我会手动摘录到CLAUDE.md或一个NOTES.md里。这样既保持了上下文的干净又不会丢失关键信息。4. 实操过程与核心环节实现4.1 从零搭建一个 AI Native 项目的完整流程假设现在要启动一个新项目我会按这个顺序来第一步初始化项目骨架。用pnpm create vite之类的命令生成基础结构然后手动调整目录确保符合团队规范。这一步不涉及 AI因为项目结构是人的决策。第二步编写 CLAUDE.md。根据项目技术栈和团队规范写出第一版CLAUDE.md。不用追求完美先把已知的规范写进去后续再补。第三步让 AI 生成基础代码。比如让 AI 根据CLAUDE.md生成一个示例组件、一个工具函数、一个测试文件。这一步的目的是验证CLAUDE.md是否足够清晰——如果 AI 生成的代码符合预期说明规范写得到位如果不符合就补充规范。第四步建立 Plan Mode 工作流。从第一个真实需求开始强制走 Plan Mode。AI 输出计划 → 人审查 → AI 执行 → 人验证。这个流程跑通两三次之后团队就习惯了。第五步持续迭代 CLAUDE.md。每次发现 AI 犯错就追问是规范没写清楚还是 AI 没遵守如果是规范缺失补上如果是 AI 没遵守检查是不是上下文窗口的问题。4.2 一个真实需求的完整落地记录拿一个具体需求举例给现有项目加一个“用户头像上传”功能。Plan 阶段我让 AI 先读CLAUDE.md然后描述需求。AI 输出的计划是在src/components下新建AvatarUploader组件组件包含文件选择、预览、上传三个状态上传逻辑调用src/lib/api.ts里的uploadAvatar函数在src/lib/api.ts里新增uploadAvatar函数使用现有的request封装新增测试文件AvatarUploader.test.tsx更新src/types里的用户类型增加avatarUrl字段我审查后发现两个问题一是没有考虑文件大小限制和格式校验二是没有处理上传失败的情况。我把这两点反馈给 AI它重新输出了计划补充了校验逻辑和错误处理。执行阶段确认计划后AI 开始写代码。我盯着它改文件每改完一个文件我就快速扫一眼。组件写完后它自动跑了测试发现一个类型错误自己修了。整个过程大概十分钟产出了六个文件的改动。验证阶段我手动跑了一遍开发服务器上传了一张图片确认功能正常。然后检查了测试覆盖率发现错误处理的分支没覆盖到让 AI 补了一个测试用例。这个需求如果纯手写大概需要一两个小时。走 AI Native 流程从 Plan 到验证完成大概二十分钟。效率提升是明显的但前提是CLAUDE.md写得足够细Plan 审查足够认真。4.3 多 Agent 协作的尝试与教训我试过让多个 Agent 并行处理不同模块比如一个写前端组件一个写后端接口。结果发现并行 Agent 的协调成本很高。两个 Agent 各自按自己的理解去改代码最后合并的时候发现接口定义不一致、类型不匹配、甚至改了同一个文件。后来我放弃了并行 Agent改成串行 人工协调。一个 Agent 做完一个模块人确认后再启动下一个。如果确实需要并行就确保两个 Agent 的工作范围完全不重叠比如一个只改src/components一个只改src/lib并且提前把接口定义好写进CLAUDE.md。提示多 Agent 协作目前更适合探索性场景生产环境还是串行更稳。别为了“看起来高级”而引入不必要的复杂度。4.4 Agent 安全边界设置Agent 能改代码就意味着它也能删代码、改配置、甚至执行危险命令。我踩过一次坑让 AI 清理无用文件它把我一个还没提交的本地配置文件删了。虽然最后找回来了但那次之后我定了规矩禁止 Agent 执行rm、git reset --hard、git push --force等破坏性命令禁止 Agent 修改.env、package.json的scripts字段、CI 配置文件所有 Agent 的改动必须经过人 review 才能提交在CLAUDE.md里明确列出禁止修改的目录和文件这些规则写进CLAUDE.md之后AI 基本不会越界。但也不能完全依赖 AI 自觉关键操作还是得人盯着。5. 常见问题与排查技巧实录5.1 AI 不遵守 CLAUDE.md 里的规范怎么办这是最常见的问题。原因通常有三个一是规范写得太模糊AI 理解不了二是上下文窗口满了AI 忘了三是规范之间有冲突AI 不知道该听哪个。排查顺序先检查规范是否具体可执行比如“代码要整洁”就是废话“函数不超过 50 行”才是可执行的。然后看会话是不是太长了开个新会话试试。最后检查规范之间有没有矛盾比如一处说用interface另一处说用type。如果都排除了就在CLAUDE.md里把这条规范加粗、加例子甚至写上“这条很重要每次都要检查”。AI 对强调性的内容会更敏感。5.2 Agent 执行到一半报错终止怎么恢复Agent 执行过程中可能因为网络、超时、上下文溢出等原因中断。这时候不要慌先看它改到哪了。用git diff看当前改动判断是完整的还是半成品。如果是半成品有两个选择一是手动补完二是让 AI 基于当前状态继续。我通常会让 AI 先读一遍当前改动的文件然后告诉它“上次执行到 X 步骤中断了请检查当前状态并继续完成剩余部分”。AI 会重新规划通常能接着做。但要注意如果中断原因是上下文溢出继续之前最好开新会话把当前状态写进一个临时文件让 AI 读。5.3 常见问题速查表问题现象可能原因解决方法AI 生成的代码不符合项目规范CLAUDE.md 缺失或模糊补充具体规范加示例AI 忘记之前的约定上下文窗口溢出开新会话重要约定写入 CLAUDE.mdAgent 改了不该改的文件禁止事项未明确在 CLAUDE.md 里列出禁止修改的路径Plan 方向不对需求描述不清晰补充背景和约束条件重新规划多个 Agent 产出冲突工作范围重叠改为串行或明确划分文件边界Agent 执行中断网络/超时/上下文问题检查当前状态让 AI 继续或手动补完测试跑不过AI 没更新测试或类型让 AI 先跑测试再提交Plan 阶段包含测试更新5.4 几个让我少走弯路的实操心得心得一CLAUDE.md 要当代码一样维护。每次 AI 犯错都是一次改进规范的机会。我现在的CLAUDE.md已经迭代了十几版每一条规范背后都有一次踩坑经历。心得二Plan Mode 不是万能的但不用是万万不能的。小改动可以跳过 Plan但涉及多文件、架构调整、依赖变更的必须走 Plan。这个判断标准要写进团队规范里。心得三别让 AI 做它不擅长的事。AI 擅长的是模式化的、有明确规范的、可验证的任务。让它做架构设计、技术选型、需求判断纯属给自己找麻烦。心得四定期清理上下文。我现在的习惯是每天下班前把当天的重要决策和进度写到一个DAILY.md里第二天开新会话时让 AI 先读这个文件。这样既保持了上下文的干净又不会丢失关键信息。心得五Agent 的产出必须验证。AI 会犯错而且犯的错往往很隐蔽。我见过 AI 生成的代码逻辑看起来没问题但边界条件处理错了。所以每次 Agent 产出后我都会跑一遍测试手动验证关键路径。别偷这个懒。这套流程跑下来我们团队的交付速度大概提升了百分之三四十但更重要的是代码质量和一致性反而更好了。因为规范被固化到了CLAUDE.md里AI 每次产出都遵循同样的标准不会像人一样今天一个风格明天一个风格。当然这套东西还在不断迭代每次遇到新问题就补一条规范慢慢就形成了一套适合自己团队的 AI Native 研发手册。