企业官网建设流程全解析

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，拆成下面这几步：

1. 实现导出模板生成逻辑
2. 写用户查询与数据组装逻辑
3. 实现导出接口并接入路由
4. 补对应的单元测试

每一步都是一个独立的执行单元，模型可以在有限的上下文窗口中集中精力处理当前任务。这背后的原理其实很直白：模型的注意力资源是有限的，任务边界越窄，它在有限的上下文里能看到的相关信息占比就越高，输出质量自然越好。

3.2 任务描述怎么写，模型执行率差很多

同样是让 Agent 干活，任务描述的写法直接影响结果。抽象描述和动作指令的差距非常大。

举个例子，你说“请确保登录功能安全”，模型大概率会输出一个看起来很安全但实际上没有具体措施的实现。但你换成“登录接口必须校验密码哈希、必须检查用户是否存在、失败时统一返回 401，禁止把具体错误信息返回给前端”，模型的执行确定性立刻就不一样了。

我整理过一个比较实用的任务描述模板，包含五个要素：

• 目标：一句话说明这次任务要交付什么
• 涉及文件：明确告诉模型哪些文件可以改，哪些不能碰
• 验证方式：改完以后要跑哪条命令，跑通过才算完成
• 约束条件：接口签名、代码风格、安全要求
• 反例：明确说明不要做什么

这套模板看起来简单，实际操作中能省掉大量无效对话。模型不再需要反复追问“我该用哪个包”，也不再会越界改动无关文件。

3.3 人的工作从“写代码”变成“做决策和审代码”

AI 原生开发并没有取消工程师，而是把工作重心从“手写每行代码”变成了“定义任务、设计边界、审核结果”。听起来轻松了，实际上对人的要求反而高了：你需要比以往更快地判断一段不是你写的代码是否正确。

审核模型代码，我的经验是抓三个核心点。第一看接口兼容性，改动的函数签名会不会影响其他调用方；第二看错误处理路径，是不是只写了主流程、没写异常分支；第三看安全边界，比如 SQL 拼接、文件路径、用户输入有没有做防御。把这三层盯住了，其他风格类问题都可以交给 linter 和格式化工具去兜底。

这个“人机结对”的节奏一开始会有点别扭，但跑顺之后体验其实不错。人不用把时间浪费在敲样板代码上，而是把精力集中在真正需要判断力的地方。

4. 反馈闭环的建设：没有验证手段，就不要交给 Agent

4.1 没有测试和检查的任务，模型就是在裸奔

这是我在实际项目中踩过最大的坑。有一阵子让 Agent 去改一个老旧的 PHP 模块，那个模块没有任何测试，也没有 lint，项目常年靠人肉验证。Agent 改完之后跑起来感觉没问题，结果上线出故障。原因后来排查才知道：它改动了一个函数的行为，而那个函数在另一个不相关的流程里被调用，因为没有测试，它根本不知道自己破坏了什么。

这个教训非常深刻。AI 原生开发里面，反馈闭环不是可选优化，而是必要条件。模型修改代码之后，需要依靠自动验证手段来感知错误，否则它就等于在黑暗里开车，只能凭感觉往前走。一个任务如果连最基础的单测或 lint 都没有，那就不应该直接交给 Agent，除非任务描述里明确要求它“自己写一个最小验证脚本再动手”。

4.2 建立分层的反馈机制

在团队实践里，我把反馈机制按照成本从低到高分成了几层：

每一层都能让 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 开始，先把项目的上下文管好。上下文理顺了，后面整个流程都会跟着顺起来，别让模型在黑暗里替你写代码。