Anthropic 把内部那套 AI 原生软件开发手册公开出来这消息在工程圈确实炸了一下。倒不是因为大家没见过 AI 编程指南而是这家公司本身就在用 Claude Code 重构自己的产品拿自家最核心的业务当试验田这本手册等于把“怎么让模型真正参与完整开发流程”的底层逻辑摊开给人看。过去一年我用 Claude Code 在真实团队里推过 AI 原生开发踩了不少坑看到手册里的思路之后很多原本模糊的判断都能对号入座了。这不是那种教你“10 个提示词写出高质量代码”的速成教程也不是让你把整个仓库丢给模型然后祈祷它别改坏东西的玄学。它解决的其实是一个工程管理问题当模型不再只是补全工具、而是像一个能连续工作的执行单元时项目的上下文怎么组织、文档怎么写、任务怎么拆、反馈怎么闭环、人要保留哪些决策权。这篇文章我就顺着这几个维度把手册的核心内容和我自己的落地经验放一起拆开讲。1. AI 原生的定义重构先分清“辅助”和“原生”1.1 AI 原生不是加一个 AI 对话框很多团队现在就觉得只要在 IDE 里装个 AI 插件偶尔让它生成一段工具函数、补全几个字段就算跟上 AI 原生开发了。这个理解差得有点远。AI 辅助编程和 AI 原生软件开发本质上是两套完全不同的工作模式。辅助模式下人承担了几乎全部的上下文理解工作。你告诉模型“帮我写一个把秒数转成 HH:MM:SS 的函数”它生成出来你检查一眼贴进去完事。这个场景里模型是个高级片段生成器它不需要知道你的代码库里有没有类似的工具函数不需要考虑调用方的风格也不需要关心测试。AI 原生软件开发的场景完全不同。模型要像团队里一个初级工程师那样进入真实仓库读代码理解需求动手改然后跑测试看到失败信息再回头修如此循环直到任务完成。整个过程中人做的是定义任务和审核结果而不是替模型把每一步都想好。这个区别决定了团队的组织方式、文档规范和审查机制的走向。1.2 手册反复强调的三个词上下文、约束、反馈闭环读完手册再对照自己的实践你会发现它的核心框架其实就是三个词的组合上下文、约束、反馈闭环。模型不是魔法它不会凭空知道你的业务逻辑也不会天然知道你的代码风格更不会在改完之后自我怀疑“我是不是改坏了”。这三个缺口全部要靠工程手段补上。上下文仓库结构、技术栈、业务背景、相关模块的既有实现。模型能看到的上下文越准确生成的代码越贴合实际。约束任务边界。哪些文件不能动、哪些接口必须保持兼容、加密逻辑必须走哪个库、配置必须走环境变量这些限制条件越明确模型“自由发挥”的空间越小。反馈闭环模型改完代码之后靠什么知道自己改对了。单测、lint、类型检查、编译命令、冒烟脚本这些自动验证手段就是模型的“眼睛”。三件套缺一不可。对比那些失败的 Agent 实践几乎都能归因到这三个环节的某一个上要么没给上下文让模型瞎猜要么没给约束让它顺手改了不该改的文件要么没给反馈闭环让它自信满满地输出坏代码。2. 文档工程先写给模型看再写给人看的代码2.1 CLAUDE.md 不是装饰是项目的“开机启动文件”在 Anthropic 的实践里项目根目录的CLAUDE.md地位非常高。它相当于模型的“项目认知起点”模型开始干活前会先读这个文件。很多团队没有这个文件或者只有一句“这是 XX 项目”那模型等于空着手进仓库它的所有判断只能靠猜。CLAUDE.md 和 README 最大的区别在于它不是写给人类看的项目介绍而是写给模型看的“操作手册”。它要告诉模型的是这个项目用什么包管理器、哪些目录是什么职责、代码风格有什么硬性要求、有什么特殊约定、常用命令是什么。我整理过一份实用的 CLAUDE.md 结构包含这几个板块# 项目概览 一句话说清楚项目是干什么的。 # 技术栈与命令 - 包管理器: pnpm禁止使用 npm/yarn - 测试命令: pnpm test - Lint 命令: pnpm lint - 类型检查: pnpm typecheck # 目录结构 - src/api: 所有对外接口 - src/services: 业务逻辑层 - src/components: UI 组件 # 代码规范 - API 返回格式统一为 { code, data, message } - 禁止直接操作 DB必须走 repository 层 - 时间统一使用 UTC 存储 # 本仓库特殊约定 - 数据库迁移脚本不允许自动生成必须人工 review - 不修改 src/api 的导出的函数签名没有这份文件的时候模型生成的代码经常出现风格突变用 npm、直接在组件里写业务请求、时间格式混用。补上 CLAUDE.md 之后这类低级问题几乎绝迹。2.2 需求描述要“写细”减少模型的自由发挥额度人和人协作时你给同事一句“把登录改成 JWT”他能靠行业常识补全大部分细节但模型没有行业常识它只有训练数据里的统计规律。你少写一个“token 有效期 10 分钟”它可能生成一套完全不同的配置你没说“token 不要存数据库”它可能就加了个 token 表。这里有个非常实用的经验需求文档里必须写验收标准、约束条件、反例。反例尤其重要。比如“不要在用户表新增 token 相关字段”“不要改动 api/auth.ts 的导出接口”“token 过期时间由环境变量 JWT_EXPIRES 注入不要写死”每一条反例都是给模型做一次边界校准这比写十条正面指令还有效。也有人觉得这样写文档成本太高但实际操作中这些明细你本来就要在代码评审时一条条看只是把时间提前到了任务描述阶段而已。2.3 文档必须持续维护它会直接影响代码质量AI 原生开发有一件反直觉的事情文档和代码脱节造成的影响比人看不懂文档还严重。为什么因为人是能感知到文档可疑的看到描述和代码不一致会去确认模型不会它会把文档当成“事实”基于错误信息生成错误代码。这种错误代码还往往很自信看起来逻辑完整实际一跑就崩。我们现在的做法是CLAUDE.md里加一条规则凡任务涉及目录结构调整、命令变更、依赖变化必须在提交前同步更新相关文档。这个维护成本并不高因为模型可以帮你写变更记录你只需要审核。等于用模型生成的文档来喂模型形成一个正循环。3. 代理式开发的任务设计把大需求拆成能闭环的小单元3.1 让模型“一口气完成整个项目”是最危险的想法我见过不少团队推 Agent 开发的时候第一反应就是把一个完整需求扔给它“帮我做一个用户系统。”结果模型写出来几千行代码风格混乱、模块内部依赖缠得乱七八糟一跑起来全是问题根本没法 review。Anthropic 手册里的思路刚好相反把大需求拆成边界清晰、能在短时间内完成并验证的小单元。比如“用户导出 CSV”这个需求不要一次性丢给 Agent拆成下面这几步实现导出模板生成逻辑写用户查询与数据组装逻辑实现导出接口并接入路由补对应的单元测试每一步都是一个独立的执行单元模型可以在有限的上下文窗口中集中精力处理当前任务。这背后的原理其实很直白模型的注意力资源是有限的任务边界越窄它在有限的上下文里能看到的相关信息占比就越高输出质量自然越好。3.2 任务描述怎么写模型执行率差很多同样是让 Agent 干活任务描述的写法直接影响结果。抽象描述和动作指令的差距非常大。举个例子你说“请确保登录功能安全”模型大概率会输出一个看起来很安全但实际上没有具体措施的实现。但你换成“登录接口必须校验密码哈希、必须检查用户是否存在、失败时统一返回 401禁止把具体错误信息返回给前端”模型的执行确定性立刻就不一样了。我整理过一个比较实用的任务描述模板包含五个要素目标一句话说明这次任务要交付什么涉及文件明确告诉模型哪些文件可以改哪些不能碰验证方式改完以后要跑哪条命令跑通过才算完成约束条件接口签名、代码风格、安全要求反例明确说明不要做什么这套模板看起来简单实际操作中能省掉大量无效对话。模型不再需要反复追问“我该用哪个包”也不再会越界改动无关文件。3.3 人的工作从“写代码”变成“做决策和审代码”AI 原生开发并没有取消工程师而是把工作重心从“手写每行代码”变成了“定义任务、设计边界、审核结果”。听起来轻松了实际上对人的要求反而高了你需要比以往更快地判断一段不是你写的代码是否正确。审核模型代码我的经验是抓三个核心点。第一看接口兼容性改动的函数签名会不会影响其他调用方第二看错误处理路径是不是只写了主流程、没写异常分支第三看安全边界比如 SQL 拼接、文件路径、用户输入有没有做防御。把这三层盯住了其他风格类问题都可以交给 linter 和格式化工具去兜底。这个“人机结对”的节奏一开始会有点别扭但跑顺之后体验其实不错。人不用把时间浪费在敲样板代码上而是把精力集中在真正需要判断力的地方。4. 反馈闭环的建设没有验证手段就不要交给 Agent4.1 没有测试和检查的任务模型就是在裸奔这是我在实际项目中踩过最大的坑。有一阵子让 Agent 去改一个老旧的 PHP 模块那个模块没有任何测试也没有 lint项目常年靠人肉验证。Agent 改完之后跑起来感觉没问题结果上线出故障。原因后来排查才知道它改动了一个函数的行为而那个函数在另一个不相关的流程里被调用因为没有测试它根本不知道自己破坏了什么。这个教训非常深刻。AI 原生开发里面反馈闭环不是可选优化而是必要条件。模型修改代码之后需要依靠自动验证手段来感知错误否则它就等于在黑暗里开车只能凭感觉往前走。一个任务如果连最基础的单测或 lint 都没有那就不应该直接交给 Agent除非任务描述里明确要求它“自己写一个最小验证脚本再动手”。4.2 建立分层的反馈机制在团队实践里我把反馈机制按照成本从低到高分成了几层层级工具/手段作用L1ESLint、Prettier、TypeScript拦截语法错误、格式问题、低级类型问题L2单元测试、集成测试验证业务逻辑是否正确L3端到端测试、API 冒烟测试验证关键链路是否通L4人工代码评审兜底处理自动化覆盖不到的边界每一层都能让 Agent 在更早阶段意识到自己的错误。L1 层的反馈最快几乎实时L2 层的反馈是核心能证明逻辑正确L3 层虽然慢但能拦住那些单元测试覆盖不到的问题。这里有个参数经验任务描述里不要写“请确保代码正确”这种抽象指标模型对抽象指标的执行率很低。要写具体动作“运行 pnpm lint修复所有暴露的错误”“运行相关单测如果现有测试受影响则一并更新”。模型对动作指令的响应质量比对抽象指标高得多。4.3 让模型提交“实现说明”把代码评审变成三段式审阅Anthropic 手册里还有一个很值得借鉴的做法让模型在交付时附上简明的实现说明解释自己做了什么决策、做了哪些假设、动了哪些边界。这不是形式主义而是为了让人在评审时快速对齐上下文。我们团队目前强制要求 Agent 的提交信息按三段式输出改动列表改了哪些文件每个文件的改动目的关键决策自己做了哪些技术取舍为什么遗留风险哪些地方不确定、需要人重点确认一开始你会觉得这是多了一道手续但实际用久了你就会发现这大概率成本最低的代码评审素材。review 的时候直接盯着这三段去看 diff效率能翻倍。有很多问题在 Agent 自己写“遗留风险”的时候就已经暴露出来了它觉得不确定的地方往往就是最需要人盯的地方。5. 团队落地建议从试点到内部沉淀5.1 先选低风险、高重复度、有测试覆盖的试点项目很多团队看完手册的第一反应是“好从下周开始我们所有项目都这么干”这几乎必然翻车。AI 原生开发的落地不是技术问题是组织问题。一上来就把核心业务模块丢给 Agent 改等于让新人第一天就上生产环境干重活出事的概率极大。我建议的路径是先选一个“低风险、高重复度、有测试覆盖”的内部服务做试点。比如报表生成、内部工具、配置管理这类模块。这类模块业务敏感度低就算 Agent 改出问题影响范围也有限而且因为有测试覆盖Agent 的反馈闭环最容易搭起来。试点阶段最重要的事情是建立基线。记录同样需求在人工模式下的完成耗时、代码缺陷率再对比 Agent 模式的耗时和缺陷率。没有这组数据你后面没办法说服团队这套流程到底值不值得推广。5.2 手册落地时最常见的三个冲突我推这套流程的时候踩到的坑基本集中在三个方面提前知道能省掉不少沟通成本。第一个冲突是“老员工觉得流程绕”。很多人习惯了“我写代码快得很”让他写 CLAUDE.md、写验证脚本他会觉得管理成本加重了。应对办法是强调这些成本大多是一次性的而且你可以让模型辅助生成初稿人只需要审核。第二个冲突是测试缺失的旧项目没法直接跑 Agent。这种情况不需要硬上可以先从“调研类任务”试点比如“梳理这个模块的所有对外依赖”“列出这个模块的入口函数和调用链”。这类任务不涉及代码修改不会产生破坏性风险同时能帮你把项目上下文整理清楚为后续改造打基础。第三个冲突是不同模型的表现差异很大别拿某个模型的失败案例全盘否定整套工作流。工具迭代非常快这周不行的方案下周可能就行关键是把你流程里可变的部分和不变的基础部分分开不要因为暂时的效果波动就推翻整套方法论。5.3 把积累的知识沉淀成团队的内部手册Anthropic 公开的那份手册可以当作参考框架但它毕竟是从 Anthropic 自己的业务场景里长出来的。每个团队的业务类型、代码库结构、风险偏好都不相同真正能指导你日常工作的一定是团队内部沉淀出来的那份手册。我们团队目前的内部手册包含这几大块内容任务描述模板统一所有人写 Agent 任务时的格式CLAUDE.md 维护规则明确哪些改动必须同步更新文档代码评审 checklist列出审核模型代码必须盯的几个点反馈回路配置说明不同项目用什么验证手段常见失败模式记录 Agent 出过的典型问题、修复方案、回滚预案这套东西跑顺之后一个新成员加入团队的适应速度会快很多因为很多隐性的工程判断都固化成文档了而不是存在某个老员工脑子里。另外有一个细节值得强调内部手册要动态维护至少每两周回顾一次。特别是“常见失败模式”这块每次 Agent 出诡异问题都要记录进去。时间长了它就是团队的避坑指南价值会越来越大。最后分享一点个人经验我自己落地这套流程跑了大半年最大的感受是AI 原生开发真正改变的并不是“怎么写代码”而是“怎么把工程管理的颗粒度变细”。以前一个需求从口头到上线要经过产品、开发、测试、运维各个环节的反复交接现在一个需求被拆成若干个明确的任务单元每个单元都有验证闭环和审核节点整个流程反而比以往更清楚。当然这套流程也远没有到“团队可以裁掉大部分工程师”的程度。人的价值在新的流程里被重新定义了不是看你写了多少行代码而是看你能不能把任务拆好、把边界定准、把风险看到。一个普通需求能在一次对话里完成测试和文档都随附交付这种效率提升是实实在在能感受到的。最后再给一条最直接的建议如果你的团队想推这套不用先研究复杂的工作流设计从写一份好的 CLAUDE.md 开始先把项目的上下文管好。上下文理顺了后面整个流程都会跟着顺起来别让模型在黑暗里替你写代码。