AI原生开发实战：从Anthropic手册到上下文工程与验收闭环

上周看到 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 16，ORM 使用 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.py，AI 根本不知道应该把新工具函数放哪里，最后大概率会新建一个utils2.py。

所以我在接手项目用 AI 之前，会先花一点时间做“代码库整理”。主要是三件事：统一命名风格。目录名和文件名能反映职责，比如services/order_service.py比services/order_operations.py更直观。把公共能力和业务能力分清楚，lib/、core/只放通用逻辑，业务代码不跨模块乱引用。每个关键模块有简短 README，几句话说清它负责什么、被谁依赖。这些工作本质上不是给 AI 做的，是给项目做的。只不过在 AI 原生开发模式下，它的收益被放大了很多倍。

2.3 会话开始前，先“喂饱” Agent

很多人用 AI 编程工具时习惯上来就一句“帮我写个登录接口”，然后 AI 就问东问西，或者直接给一个与项目风格完全不符的实现。这不是 AI 笨，是它缺乏上下文。

按手册的思路，启动一个任务前应该先把上下文喂够。我在实际中练出一个开场模板，效果非常好：

1. 我的目标：一句话说清要做什么。
2. 涉及范围：涉及哪些模块、哪些文件，不许动哪些文件。
3. 现有约定：让 AI 先读 CLAUDE.md 和相关模块的 README。
4. 验收标准：满足什么条件算做完，比如“新增单测”“现有测试全绿”“不改变对外接口”。
5. 让 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 就可以通过跑测试来自我验证、自我修复。相当于我们给它装了“眼睛”，否则它只能“盲写”。

我实操下来，最顺的流程是：

1. 让 AI 先写失败测试，描述期望行为。
2. 让 AI 实现功能，目标只有一个：让测试变绿。
3. 跑完整测试集，AI 自己修复失败用例。
4. 人工 review，检查是否有测试覆盖不到的逻辑漏洞。
5. 最终提交代码。

比如“订单取消接口”任务，我先让 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 原生开发这事，最大的瓶颈根本不是模型能力，而是我们这些“人类开发者”敢不敢把任务完整地交出去，同时认认真真地验收。交出去不是当甩手掌柜，而是把需求讲清楚、把边界划明白、把验收标准定出来；验收也不是走个过场，而是真的去读 diff、跑测试、看文档。我刚开始用的时候，总觉得 AI 写的代码不 debug 一遍不放心，后来发现，只要上下文给足了、测试写够了，它生成的东西反而比某些平均水平的人类代码更稳定——它至少不会漏掉测试，也不会忘记写文档。

如果你也想试这套方法，我的建议是别一上来就改造整个团队流程，先挑一个小模块，把 CLAUDE.md 写好，把一个任务走完“计划-测试-实现-验收-文档”的闭环。一个模块成了，自然就体会到这套打法的好处。这份手册写的不是什么高深理论，就是一批每天在用 AI 写代码的人沉淀下来的好习惯。照着试一周，你会回来感谢自己。