上周看到 Anthropic 把内部使用的 AI 原生软件开发手册公开出来我第一时间把原文读完了。说实话这几年“用 AI 写代码”的内容我看过很多多数要么停留在提示词技巧要么是截几个对话炫一下看完还是不知道到底该怎么落地。这份手册不一样它回答了一个我一直想问的问题如果一支成熟团队真的把 AI 当成结对开发伙伴而不是高级自动补全他们日常工作流到底是什么样的。我按手册的方法在真实项目里跑了两三周把 CLAUDE.md 从三行写成三十行把一个模块从需求拆解到测试验收完整走了一遍确实能感受到“AI 辅助开发”和“AI 原生开发”之间的差别。这篇文章就把我对这份手册的理解、我的实操过程、以及踩过的坑一起整理出来给正在用或打算用 AI 编程的朋友做参考。内容不挑具体工具Claude Code、Cursor、其他支持 Agent 模式的工具都能用得上。1. 手册到底在讲什么AI 原生开发不是“用 AI 写代码”1.1 从“AI 辅助”到“AI 原生”换的不是工具是工作方式很多人觉得“用 AI 写代码”就是装个插件让 AI 自动补全函数、写个单元测试或者把报错信息丢给它让它修。这属于 AI 辅助开发人是司机AI 是副驾驶所有决策还是人做的。Anthropic 这份手册讲的不是这个它讲的是 AI 原生开发AI 是执行者人是指挥官和验收官。打个比方以前你用 Copilot 是让同事帮你想一个函数怎么实现而 AI 原生开发是你把一个功能模块的完整背景、约束条件、验收标准都讲清楚然后让同事自己去读代码、写实现、跑测试、修 bug最后把改完的代码交给你 review。中间那些“查文档”“找接口”“试错”的活AI 全包了。这个转变看起来只是“任务的颗粒度”变大了实际上整个工作模式都要跟着变。过去我们写代码主体是人代码是我们思考的产物。AI 原生开发里主体是模型加代码库加上下文人负责的是把需求拆到 AI 能理解的程度以及确认 AI 做出来的东西真的对。手册里反复强调的“上下文工程”“文档化”“小步迭代”“严格验收”本质都是在为这种新模式服务。1.2 手册的三大支柱上下文、文档、验收闭环这份手册的内容很多但核心骨架我认为是三件事。第一是上下文为王。AI 模型本身没有记忆力它每次工作都像一个刚入职、看过一些项目资料、但只记得你这次对话内容的程序员。你给它什么它就基于什么干活。给它看一个清晰的代码库、一份好的项目说明、一段准确的需求描述它能交出远超预期的代码。反过来让它在一个没文档、命名混乱、什么都要靠猜的仓库里干活它就会一本正经地写出一堆“看起来合理但跟项目实际脱节”的代码。第二是文档不再是可选项。这个结论很多人一开始不接受觉得写文档浪费时间。但在 AI 原生开发的模式下文档就是给“新同事”的入职培训材料。CLAUDE.md、README、架构说明、接口约定这些不是写给未来的人类看的是写给现在的 AI 看的。AI 每开一个新会话都会先去读这些文件来理解项目。文档质量直接决定 AI 的工作质量这是一笔很划算的投资。第三是验收闭环。AI 写得再快也是通过“生成代码”来工作它无法像人一样对“这个功能是否真的满足了业务需求”有感性认识。所以整个流程必须有硬性的校验机制测试、lint、类型检查、人工 review。手册里特别强调小步迭代——让 AI 每次只改一小块跑一遍验证再继续下一步。这和我们人类程序员写代码的节奏其实是一样的只不过 AI 的执行速度更快更需要我们主动控制节奏。2. 先做上下文工程决定 AI 上限的准备工作2.1 CLAUDE.md项目的“第二大脑”手册里有一个概念我觉得是所有内容里含金量最高的就是项目级说明文件。Claude Code 这个工具会默认加载项目根目录下的 CLAUDE.md 作为 AI 理解项目的入口。你可以把它理解成一个“给 AI 看的项目手册”。我第一次用的时候很不以为然随手写了几行就继续干活。结果 AI 在生成代码时频繁出现前后不一致前端说接口返回user_id后端实际生成userId说好错误码用统一格式结果每一处都是临时造的。后来我照着手册的建议把 CLAUDE.md 认真补全这些问题明显变少。我现在的 CLAUDE.md 大致长这样# 项目订单管理系统 ## 技术栈 - 后端Python 3.12 / FastAPI / SQLAlchemy 2.0 - 前端React 18 / TypeScript / Vite - 数据库PostgreSQL 16ORM 使用 async session ## 常用命令 - 本地启动make dev - 跑测试make test - 类型检查make typecheck ## 目录结构 - app/api路由层只做参数校验和响应包装 - app/services业务逻辑层禁止直接操作数据库 - app/repositories数据访问层所有 SQLAlchemy 操作都收在这里 - frontend/src/api前端接口封装统一走 axios 实例 ## 关键约定 1. 后端接口统一返回 { code, data, message } 结构 2. 所有时间字段使用 UTC返回前端时转 ISO 8601 3. 新增功能必须先写测试再写实现 4. 数据库迁移文件统一放在 alembic/versions 5. 禁止在 service 层直接操作数据库对象必须通过 repository 层这个文件不是一次写成的是随着项目演进不断补充的。每当我发现 AI 在某类问题上反复出错我就会想是不是说明文件里缺了一条约定然后补进去。几轮下来AI 的表现会越来越稳。2.2 一个“可读”的代码库比给 AI 喂提示词更管用手册里还有一个容易被忽略的点AI 在代码库里翻找信息的能力很强但前提是代码库本身结构清晰。如果文件名、函数名、目录结构都模棱两可AI 就会靠猜。比如一个仓库里同时有utils.py、helpers.py、common.pyAI 根本不知道应该把新工具函数放哪里最后大概率会新建一个utils2.py。所以我在接手项目用 AI 之前会先花一点时间做“代码库整理”。主要是三件事统一命名风格。目录名和文件名能反映职责比如services/order_service.py比services/order_operations.py更直观。把公共能力和业务能力分清楚lib/、core/只放通用逻辑业务代码不跨模块乱引用。每个关键模块有简短 README几句话说清它负责什么、被谁依赖。这些工作本质上不是给 AI 做的是给项目做的。只不过在 AI 原生开发模式下它的收益被放大了很多倍。2.3 会话开始前先“喂饱” Agent很多人用 AI 编程工具时习惯上来就一句“帮我写个登录接口”然后 AI 就问东问西或者直接给一个与项目风格完全不符的实现。这不是 AI 笨是它缺乏上下文。按手册的思路启动一个任务前应该先把上下文喂够。我在实际中练出一个开场模板效果非常好我的目标一句话说清要做什么。涉及范围涉及哪些模块、哪些文件不许动哪些文件。现有约定让 AI 先读 CLAUDE.md 和相关模块的 README。验收标准满足什么条件算做完比如“新增单测”“现有测试全绿”“不改变对外接口”。让 AI 先复述理解再开始干活别急着写代码。比如我会这样开头现在要新增一个订单取消接口。涉及 orders 模块的 service 和 repository 层路由写在 app/api/orders.py 里前端不用动。请先读 CLAUDE.md 和 app/services/order_service.py然后复述你对这个任务的理解包括接口参数、业务规则和测试方案确认无误后再开始实现。这个开头比直接甩一句“帮我写取消订单接口”多花 30 秒但在后续步骤里能节省大量来回纠偏的时间。2.4 上下文是会“过期”的维护上下文的方法AI 的上下文窗口再大也架不住一段超长对话持续堆积信息。我在实践中发现同一个会话里任务做多了以后AI 会出现一种“记性衰退”前面明明定好的接口字段后面它会搞混前面说好的命名风格后面又按默认风格来。这就是上下文窗口里的信息被冲掉了。应对办法有几个都是手册推荐思路的具体落地一个会话只做一个任务不要在一个会话里连续做五个功能阶段性把结论沉淀到文档里比如让 AI 把已确定的接口设计追加到docs/api.md而不是留在对话里上下文感觉混乱时果断开新会话在开场信息里给出“当前项目状态摘要”让 AI 重新读取文档。我踩过一次坑在一个超长会话里连续让 AI 做了三个模块到第三个时它开始把第一个模块里定的实体名字改掉了代码一测全是坏的。后来我养成了“一任务一会话”的习惯再没出过这种问题。说到底AI 的记忆力不在对话里在文档和代码里我们要做的就是把对话中的决策及时固化到仓库中。3. 实操工作流一次完整的 AI 原生开发迭代3.1 先计划后动手把 Plan 阶段当成“需求评审”手册明确建议不要一上来就让 AI 直接写代码而是先让它产出计划。这看起来是降低了效率实际上大幅减少了返工。AI 一次能把一个模块写个七七八八但如果方向错了返工成本远高于多花几轮对话确认计划。我现在的工作流是这样第一步给 AI 下任务要求它输出一份实现计划内容必须包含目标拆解、涉及文件清单、风险点、测试方案。第二步我 review 这份计划把不合理的地方指出来让 AI 改。第三步计划确认后才允许它进入实现阶段。举个具体的例子我给 AI 的任务是“为订单模块增加批量导出功能”。它给的计划里包括在app/services/order_service.py里新增export_orders方法在app/api/orders.py里新增POST /orders/export接口在前端新增导出按钮和下载逻辑用openpyxl生成 Excel补充测试。这个计划表面看没什么问题但我指出两个风险点导出功能不应该走 API 同步返回大文件应该用异步任务生成文件后返回下载链接。前端导出按钮涉及权限控制需要确认用户角色。AI 采纳建议修改了计划然后才开始实现。如果一开始就让它直接写这两个问题大概率会在代码写完之后才暴露改起来会非常痛苦。3.2 用测试定义“做完了”Agent 模式下的 TDD 闭环测试驱动开发在传统开发里是一门“知易行难”的功夫但在 AI 原生开发里变成了默认配置。原因很直接没有测试AI 就不知道自己做对了没有有了测试AI 就可以通过跑测试来自我验证、自我修复。相当于我们给它装了“眼睛”否则它只能“盲写”。我实操下来最顺的流程是让 AI 先写失败测试描述期望行为。让 AI 实现功能目标只有一个让测试变绿。跑完整测试集AI 自己修复失败用例。人工 review检查是否有测试覆盖不到的逻辑漏洞。最终提交代码。比如“订单取消接口”任务我先让 AI 写测试覆盖这几个场景取消已支付的订单状态改为已取消且库存回滚取消已取消的订单返回明确错误码非订单本人取消返回 403。这些测试写完后AI 才开始写 service 和 repository 层代码。过程中有一次测试失败它自己读日志、查逻辑、修复再跑直到全绿。这一步对质量提升是决定性的。我自己统计了一下没有测试引导时AI 生成的代码大概有 20% 左右的隐性 bug加了测试闭环后能堵住绝大部分。也不需要一开始就有多完备的测试基础设施从第一个功能开始补测试代码库测试覆盖会自然增长。3.3 Auto 模式什么时候可以放手给 AI 的自主权边界很多 AI 编程工具都有“自主模式”让 AI 连续执行多个操作直到任务完成。手册里对这个模式的态度很务实该放手时就放手但一定要设边界。我在实践中有几条判断标准。完全放手的情况改动范围单一的小任务比如修一个明确 bug、补充单元测试、重构一个函数内部实现有完整测试覆盖的模块AI 改坏任何行为测试立刻能发现不涉及用户数据、权限、支付等高风险逻辑的任务。必须人工把关的情况跨模块的大重构涉及数据库迁移和数据正确性的改动需要修改全局配置、第三方服务凭证、部署脚本的任务对外 API 契约的变更。理由很简单这类改动一旦出错影响面不是一次测试能覆盖的需要人做判断。用好 Auto 模式的关键还有权限设置。我会在工具配置里明确禁止 AI 访问生产环境禁止它执行一些危险命令比如直接操作线上数据库、推送代码到主分支。这些约束写在 CLAUDE.md 和工具的权限配置里比事后发现回滚要省心得多。3.4 提交与 Review把“人”放在关键节点上AI 干活很快但人不能因此就不看代码了。手册核心观点里有一条我一直很认同AI 写代码人管方向和质量。这个“质量门”最直接的承接点就是 Git 提交和 PR review。我定的流程是AI 每完成一个阶段就让它git diff自查一遍再提交提交信息要求清晰表达改了什么、为什么改提交后我本地看 diff用 Code Review 的眼光检查我不满意就直接在 review 里打回让 AI 根据意见修改。这个流程走下来AI 的提交越来越规范因为它从修改意见里“学到了”我的偏好。比如有一次 AI 提交里包含了一个调试用的console.log。我在 review 里指出并让它全局排查同类问题。它就学会了在自查阶段用正则搜console.log后续提交干净了很多。这跟带人很像你每次把关的标准就是 AI 下次的默认行为。3.5 让 AI 自己维护文档防止“文档烂尾”文档漂移是软件工程的老问题在 AI 原生开发模式下反而有一个解法把“更新文档”写进 AI 的任务完成定义里。也就是说AI 改变了一个模块的行为但这个模块的 README 没更新就算没做完。我在提示词模板里会固定加一句如果本次改动影响了对外接口、命令、配置方式或项目结构必须同步更新 CLAUDE.md 和对应模块的 README。然后 review 的时候我会专门检查 docs 目录是否有对应变更。真实效果是AI 不仅会更新上次对话中改动的文档还会主动发现旧文档里的错误并纠正。有一次我让它改接口返回字段它顺手把接口文档里的历史错误字段也修了。这种“顺手维护”靠人去做很难坚持但对 AI 来说就是一行指令的事情。4. 常见问题与排查实录我把手册里的坑都踩了一遍4.1 AI“一本正经地胡说八道”幻觉问题的排查思路AI 生成代码时最大的问题不是写不出来而是写出一堆看似合理、实则有问题的东西。我遇到过的典型情况是调用一个不存在的函数AI 还一本正经地给它加上了注释我体验过一次印象特别深刻。用了一个项目的工具函数后我一查那个函数从来就不存在。排查这类问题我的路径是固定的先检查上下文是否足够AI 有没有读过相关文件。它如果没看过代码库里的真实函数列表就会靠“猜”那出幻觉的概率极高。再看看任务范围是不是太大任务太复杂时 AI 会对细节失去控制容易在局部靠想象补齐最后看有没有硬性验证手段比如测试、类型检查、lint没有的话AI 的错误就没有“照妖镜”。解决方式对应也很简单任务下发时强制 AI 先读关键文件再动手把大任务拆成小步骤每一步都带验证先把测试写出来让实现必须满足测试才算完成。这三板斧下来幻觉出现的频率大幅下降。4.2 上下文太长导致“记性衰退”症状和处理办法我在 2.4 节提过这里展开讲一下具体表现。典型症状是AI 前面还说用snake_case后面生成的字段变成了camelCase之前确认过不在本次改动范围的模块它突然去改了写到第三个功能时它把第一个功能里定义的常量名改了导致测试崩溃。出现这些现象不要急着骂 AI 蠢本质是它的上下文窗口里信息太多、太杂早期信息被挤掉了。我的处理方法是新开会话把当前任务的背景、目标和项目约定重新写一遍把之前的阶段性结果固化成文档比如让 AI 把已经确认的接口设计写进docs/清理上下文删掉对话里无用的中间过程只保留结论。这个习惯需要刻意练习。一开始我总觉得“新开会话还要重新说一遍太麻烦”但算下来重新说一遍只要 20 秒省下的是来回纠偏几十分钟的时间非常划算。4.3 AI 乱改文件权限边界怎么设置才安全AI 在 Auto 模式下改动文件效率高但偶尔也会“手伸得太长”。我遇到过一次让它加个功能它顺手把package.json里一个依赖的版本升了理由是“这个版本有已知安全漏洞”然后把测试跑挂了。这里给所有人一个建议别把仓库的完整写权限交给 AI先在配置里划定边界。我现在的做法是在 CLAUDE.md 里明确写清楚哪些目录和文件是 AI 可以直接改的哪些是必须经过人工确认才能动的比如alembic/versions、.github/workflows、根目录配置文件用工具自带权限控制关闭 AI 的自动执行命令特别是 shell 命令所有命令执行前都弹确认审查时重点看 diff 中是不是有“计划外”的改动一旦发现就要求 AI 回退并在配置里补一条规则。有段时间我觉得这样太啰嗦把权限全放开结果一次 AI 误删了一个配置文件业务直接不可用。从那以后我还是老老实实设权限多一道确认少一次事故。4.4 代码改了文档没改把“更新文档”变成任务的完成条件文档漂移在 AI 原生开发里其实比传统开发更好解决只要你把它当成“任务的一部分”而不是“额外的事情”。具体做法在任务提示词里加一条固定要求如果改动影响了接口、行为、配置或依赖必须同步更新对应文档在验收清单里加一项“检查文档是否与代码一致”review 时发现文档没更新就作为问题打回让 AI 补上。我实际跑下来AI 修改文档的意愿和能力都比想象中强。它会读旧文档、对比代码改动、生成更新后的文档段落。这和人类开发者完全相反人类普遍最讨厌写文档AI 不会你只要提要求它就会执行。所以我们更应该把“文档同步”这个责任交给 AI。4.5 常见问题速查表症状可能原因建议处理生成的代码使用不存在的函数上下文不足AI 在猜测强制先读代码库再动手补测试写到后面忘了前面的约定上下文太长新开会话把结论写进文档改动范围超出任务描述权限边界不清晰在配置里限制可改目录review 时打回代码风格与项目不一致缺少风格约定在 CLAUDE.md 里写清命名、格式、目录规范测试一直跑不过任务太大/需求含糊拆小任务先写测试再实现文档与代码不同步没把文档任务列入验收条件在提示词里固定要求更新文档AI 自己“发明”业务规则业务上下文不够把业务规则、边界条件写进需求描述最后讲一点我的个人体会把这份手册的方法真正跑起来之后我最大的感受是AI 原生开发这事最大的瓶颈根本不是模型能力而是我们这些“人类开发者”敢不敢把任务完整地交出去同时认认真真地验收。交出去不是当甩手掌柜而是把需求讲清楚、把边界划明白、把验收标准定出来验收也不是走个过场而是真的去读 diff、跑测试、看文档。我刚开始用的时候总觉得 AI 写的代码不 debug 一遍不放心后来发现只要上下文给足了、测试写够了它生成的东西反而比某些平均水平的人类代码更稳定——它至少不会漏掉测试也不会忘记写文档。如果你也想试这套方法我的建议是别一上来就改造整个团队流程先挑一个小模块把 CLAUDE.md 写好把一个任务走完“计划-测试-实现-验收-文档”的闭环。一个模块成了自然就体会到这套打法的好处。这份手册写的不是什么高深理论就是一批每天在用 AI 写代码的人沉淀下来的好习惯。照着试一周你会回来感谢自己。