企业官网建设流程全解析

去年年中，我接手了一个内部工具链的改造任务，为了赶进度，我把大半的编码工作交给了 Claude Code。前半小时效率确实高，它飞快地生成了一堆接口代码，但等我切到终端看 diff 的时候，发现它顺手把我半年前写的一个配置模块整个重构了，还改了依赖版本，CI 直接在构建阶段挂了。那一刻我就意识到：工具越强，越不能在毫无约束的情况下放手用。Claude Code 的能力本身不是问题，问题是没有一套生产级代码规范来圈定它的工作边界。

这篇博文就是我为 Claude Code 整理的那套“最佳实践”中文版。它不是介绍 Claude Code 怎么安装、怎么聊天，而是一份从项目记忆、任务提交、代码审查到权限安全都覆盖的生产级代码规范。我测了差不多两个多月，踩了不少坑，最后沉淀成下面这些规则。无论你是个人开发者，还是正在把 AI 编程引入团队的技术负责人，这份规范里的东西都应该能直接抄作业。

1. 先说我为什么给 Claude Code 单独立了一本“军规”

1.1 没有规范时，它到底能闯多大祸

很多人用 Claude Code 的姿势是“直接说需求”，然后把它的输出原样合进仓库。短期看着很爽，长期却要付出高昂的修复成本。我见过最夸张的一次，是它为了实现一个排序功能，把项目里负责鉴权的公共函数也改掉了，理由是“顺便统一了错误处理”。单独看每一处改动都合理，组合在一起就变成了一个无法 review 的巨型 diff，最后只能全部回滚。

这类问题的根源并不在于模型不够聪明，而在于它缺少对“哪些事是这次任务该做的，哪些事绝对别碰”的认知。人带新人还要给一本员工手册，AI 进场干活，自然也需要一份项目级的规则说明。这份规则说明，我称之为 Claude Code 的“军规”。

1.2 为什么强调“生产级”而不是“能用就行”

如果你只是拿 Claude Code 写点一次性脚本，那怎么折腾都无所谓。但只要代码要合入主干、要上生产、要被人维护，就必须有一套硬性约定。生产级意味着三件事：第一，每次改动是可审查的，出了问题能快速定位责任人；第二，测试不是摆设，AI 生成的代码必须经过自动化验证；第三，任何对依赖、配置、底层公共模块的改动都要有显式确认，不能神不知鬼不觉地发生。

我见过太多“AI 生成一时爽，上线两周火葬场”的例子。代码能跑只是起点，能被人看懂、能被自动化流程校验、能在一段时间后依然安全维护，这才是生产级。

1.3 这份规范适合谁参考

如果你只是偶尔让 Claude Code 改个正则、写个 SQL，那看前三章就够了。如果你负责一个持续迭代的代码仓库，或者团队里有多个人同时用 AI 编程，那整份规范都值得认真过一遍。尤其是后面关于权限、禁区、复盘的部分，几乎是为团队协作场景量身定的。

2. 项目记忆层：CLAUDE.md 到底该怎么写

2.1 CLAUDE.md 就是项目给 AI 看的“入职手册”

Claude Code 的上下文窗口再大也有限，它需要在短时间内了解项目背景。CLAUDE.md 这个文件就是用来承载这类信息的。很多人的用法是往里面随便扔几句话，比如“这是一个电商项目，技术栈是 Java”。这远远不够。

我推荐的 CLAUDE.md 至少包含六个区块：项目简介、技术栈、目录结构、编码规范、常用命令、禁区。不需要写得像运维手册一样全，但核心约定必须钉死。下面是我在其中一个模拟订单系统里用的结构：

# 项目定位 - 这是一个订单管理系统，负责订单创建、支付回调、售后流程 ## 技术栈 - 后端：Go 1.22 + Gin + PostgreSQL - 前端：React 18 + TypeScript + Vite - 队列：Redis + Asynq ## 目录结构 - cmd/ 入口与启动逻辑 - internal/ 业务代码 - service/ 核心业务逻辑 - repository/ 数据访问层 - api/ HTTP 处理器 - migrations/ 数据库迁移文件 ## 编码规范 - 所有导出函数必须携带注释 - 禁止使用全局变量 - 错误必须向上抛出，禁止在业务层吞掉 - 新增依赖必须单独说明原因 ## 常用命令 - 本地启动: make dev - 运行测试: make test - 构建镜像: make build ## 禁区 - 禁止修改 migrations 目录中已提交的迁移文件 - 禁止重命名已有公开函数 - 禁止升级 go.mod 中与任务无关的依赖版本 - 禁止改动 cmd/ 下的启动流程

这段文件实际跑下来效果很明显。AI 不再自作主张地重构公共模块，因为它知道哪些目录是禁区；也不会写完代码不写注释，因为编码规范里写明了。

2.2 记忆文件的增量维护机制

CLAUDE.md 不是写一次就完事的。项目结构一变，它就得跟着变。我曾经吃过大亏：项目里新增了一个缓存层目录，我没更新 CLAUDE.md，结果 Claude Code 反复在 service 层里直接写 Redis 调用，生成的代码风格跟团队整体架构完全不一致。

后来我给自己定了几条维护规则。每次新开任务前，先花两分钟检查 CLAUDE.md 是否还反映当前仓库真实状态。新增了目录、更换了框架、调整了代码风格，都要立刻补进去。我自己更习惯的做法是，在每一个重要的 pull request 合并后，顺手把 diff 里涉及架构变化的部分同步到 CLAUDE.md。这个过程看起来琐碎，但长期收益极大。

2.3 上下文不是越大越好，要按优先级排布

Claude Code 能读取的上下文有限，CLAUDE.md 如果写了一两千行，它反而抓不住重点。我实测过一个很有意思的现象：当我把某个项目的 CLAUDE.md 从 1200 行压到 180 行之后，任务成功率明显上升，代码风格也更稳定。原因是信息多了之后，模型难以判断哪条规则优先级更高。

所以我的建议是按“优先级从上到下”排布。最顶上是无论何时都不能违反的禁区，其次是技术栈与架构约束，再次是风格与偏好。把不重要的历史决定、讨论记录全部扔出 CLAUDE.md。它应该是一份高密度、当前有效的规则集合，而不是项目流水账。

3. 任务提交规范：一句话需求是如何变成可执行规格的

3.1 五段式任务卡模板

直接对 Claude Code 说“帮我把登录接口改成 JWT”，这种用法在小 demo 里没问题，但在生产仓库里就是在赌运气。模型会自行脑补完成定义，而它脑补出来的“完成”往往和你的预期有偏差。我用的方案是五段式任务卡。

【任务目标】 用一句话说明要做什么，必须包含明确的业务动作。 【完成定义】 列出可验证的验收标准，一般 1 到 3 条。满足这些标准才算完成。 【输入与约束】 说明基于哪些现有文件、哪些数据结构，以及需要遵守的技术约束。 【禁区】 明确写出本次任务不碰什么。没有写“不要动”的区域，默认可以动，但强烈建议补全。 【验证方式】 写清楚执行哪个命令、通过哪一组用例，让 AI 自己跑测试并汇报结果。

看起来有点繁琐，但这是成本最低的纠错手段。任务卡写清楚之后，AI 生成第一版代码的正确率会比我随意描述高得多。我自己的体感是，随意描述的正确率大概五成，五段式任务卡能拉到八成以上。

3.2 每条规则背后的理由

任务目标必须用业务动作而非技术动作描述。因为“把登录改成 JWT”是一种方案描述，而“让登录状态可以安全跨服务校验”才是目标。方案会过时，目标不容易过时。

完成定义是任务卡里最重要的一环。没有验收标准，AI 会在代码写完自测通过后直接告诉你“完成”，哪怕你其实还要求补充单元测试和更新接口文档。我遇到过太多次它把“代码写完”和“任务完成”画等号的案例。

禁区是一条反向保险。AI 的训练数据里充满了“最佳实践”，它天然倾向于顺手重构、顺手升级依赖。你不写禁区，它就会按自己的偏好行事。实测下来，禁区字段写得越明确，diff 的噪音越小，review 需要的时间也越短。

3.3 一个真实需求从口述到任务卡的改写过程

举个例子。有一次我实际要处理的需求是“订单超时之后自动取消库存”。如果直接甩给 Claude Code，它会自由发挥。改成任务卡之后变成了这样：

【任务目标】 订单超过 30 分钟未支付时，自动取消订单并回补库存。 【完成定义】 1. 新增后台定时任务，每 5 分钟扫描一次超时订单； 2. 取消操作完成后，通过库存服务接口回补库存； 3. 增加 task 级别单元测试，覆盖订单状态、库存回补两个路径。 【输入与约束】 - 订单表结构见 internal/repository/order.go； - 库存接口使用 internal/service/inventory.go 中的 ReleaseStock 方法； - 任务调度基于 Asynq，新增任务类型遵循 internal/task 目录现有模式。 【禁区】 - 禁止修改支付回调流程； - 禁止改动 orders 表的 schema； - 禁止引入新的定时任务框架。 【验证方式】 - 执行 make test 全部通过； - 手动创建一个超时订单，运行任务后确认订单状态变为 canceled，库存数量恢复。

这份任务卡看着长，但 Claude Code 只需要几分钟就能按它执行，而且执行边界非常清楚。整个过程中我不需要盯着一行行代码去猜它有没有跑偏。

4. 代码生成与变更控制：合入主干前必须过的关卡

4.1 把编码风格锁进 CLAUDE.md，别靠模型自觉

每一个代码仓库都有自己的代码风格，而 Claude Code 的风格默认来自训练数据里的“主流写法”。如果不显式约束，它会把 Python 的味道写进 Go 代码里，或是在 Java 项目里引入一堆函数式链式调用。

我之前在 CLAUDE.md 里只写了“遵循项目现有风格”，效果很差，因为太抽象。后来改成具体规则，比如：方法必须写注释、禁止全局变量、错误必须向上抛出、函数长度不建议超过 50 行。规则一旦具体，生成的代码就稳定下来了。AI 编程不需要你给它讲道理，只需要给它足够明确的约束。

4.2 一次任务只做一类改动，diff 才有人敢 review

生产级代码规范的另一个核心是“变更范围控制”。我见过最难以接受的生成结果，是 Claude Code 在一次任务里同时完成了功能开发、代码格式调整、旧接口废弃和依赖升级。单看每一项都没毛病，合在一起却让代码审查形同虚设。

现在我强制要求每次任务只处理一个类型的改动。功能开发就只写业务代码；格式化就只做格式化；依赖升级必须单独提任务。这个规则最初是给人工协作定的，后来我发现它对 Claude Code 同样适用。因为模型更倾向于在一个上下文里把能做的都做了，你不拦住它，它就会制造出不可审查的巨型 diff。

4.3 生成后的 AI 自检与人工 review 清单

Claude Code 生成完代码之后，我会要求它先做一轮自检，包括跑静态检查、过一遍冲突风险、列出改动文件清单。但这只是辅助，最终审查人还是我。我在 review 时有一张固定清单，每次都会对着过一遍：

• 改动文件数量是否超出任务卡范围；
• 是否有与本次任务无关的重命名、注释删除、格式调整；
• 依赖变化是否在任务卡里明确说明过；
• 错误处理是否完整，有没有吞异常或忽略返回错误的情况；
• 是否引入了硬编码配置或敏感信息；
• 是否有遗留的调试输出、临时代码。

这张清单我打印出来贴在工位旁边。凡是没通过的项目，一律打回重改，不让 Claude Code 再通过追加对话的方式把同一份代码“调”到通过为止。因为反复追加对话修出来的代码，往往比推倒重写更难维护。

5. 测试与验收：AI 写的代码不能只“看起来能跑”

5.1 在任务卡里强制约定测试金字塔

我在团队里推过一种很简单的测试比例：对于 AI 生成的业务代码，单元测试要覆盖核心函数应覆盖主要分支；关联外部服务的交互要走集成测试路径；端到端用例减少但必须保留一条核心链路。比例上，单元测试大约占七成，集成测试占两成，端到端一成。

这不是说每个需求都必须按这个比例机械执行，而是它给了 Claude Code 一个默认的测试策略。如果你不指定，它会倾向于只写几个用例让测试变绿就算交差。我在任务卡里会把“测试要求”写进完成定义，比如“新增逻辑必须包含正常路径和超时路径的用例”，这样它生成的测试才更有针对性。

5.2 边界用例与回归校验：最容易翻车的地方

AI 写测试最大的弱点是喜欢走 happy path。它会把主流程测得很顺，但挂在网络超时、空列表、异常状态码这些边界场景上。我在任务卡的“验证方式”字段里加了一条硬性约定：每个新增功能必须列出至少三个边界用例，包括空数据、非法输入、依赖服务异常。

另外一条经验非常重要：不要只看测试是否通过，还要看 diff。测试是绿的，不代表业务逻辑是对的。我遇到过一次很典型的案例，Claude Code 把功能写错了，但它补的测试断言也跟着写错了，两边错到一起，测试自然全绿。从那以后，我在 review 清单里加了“测试断言是否与业务预期一致”这一项，要求每一条断言都能在业务层面解释得通。

5.3 从“测试过了”到“可上线”的最终验收标准

单纯测试通过，我不认为任务完成了。我还有一个最终验收清单，通常包含四件事：代码已经过人工审查；所有新增用例在本地和 CI 上均通过；相关文档和 API 注释已同步更新；提交信息写清了改动内容和影响范围。

如果 Claude Code 完成了前三件但没更新文档，我不会放宽要求。文档和代码不一致的债，最后都是人肉还。为了让这一点可执行，我在仓库里放了一个小的 check 脚本，会检查本次改动涉及的文件是否都有对应的注释或者 README 更新。这个机制不能保证 AI 的文档完全正确，但至少能逼着它把文档变更放进本次提交里。

6. 权限与安全：AI 在终端里能做什么、不能做什么

6.1 权限档位化：只读、可编辑、可执行

Claude Code 的能力范围不只是改代码，它还能跑命令、读文件、查日志。能力越大，风险越大。我习惯把它的工作权限分成三个档位，根据任务类型切换。

大多数时候让它编辑文件就足够，不需要它能执行任意命令。只有当它明确要跑测试或构建的时候，才临时放开到可执行档位。这个档位切换本身，就是对 AI 行为的约束，也是给开发者留出的确认窗口。

6.2 危险操作名单与逃生窗口

除了权限档位，我还维护了一个“未确认不执行”的危险操作名单。名单上的动作，不管是模型主动提出还是开发者要求，都必须经过额外确认：删除文件或目录、覆盖已有迁移文件、强制推送、批量修改依赖版本、修改 CI 配置文件。

实际操作上，我会在任务卡里把这些动作直接写进禁区，并且不允许 AI 在任务中途“顺便”执行它们。万一 Claude Code 真的开始做这些动作，我还有一个逃生窗口：在任何修改执行前，先查看完整的 diff，再决定是否放行。这个工具也好，人的习惯也好，退路永远要留一条。

6.3 敏感信息与密钥防泄漏的几条死规矩

AI 编程场景下，敏感信息泄漏的路径比人更容易被忽略。Claude Code 会读取仓库和上下文，如果开发者把生产环境的密钥、数据库连接串粘贴到对话里，这些信息可能被模型记住，也可能被输出到日志、测试报告或提交信息里。

我给自己订了几条死规矩：绝对不把真实密钥粘贴进 Claude Code 的对话上下文；所有敏感配置只通过环境变量引用；提交信息里不写任何连接串；在 CI 流程里加一层密钥扫描，如果检测出疑似凭证格式的内容，直接阻断合并。这些措施单独看都很基础，但组合在一起，才能把“AI 帮你写代码”这件事控制在一个安全边界之内。

7. 复盘：我最常遇到的六种翻车场景与对应修法

7.1 现象一：它悄悄升级了依赖

某次任务里，Claude Code 为了实现一个小功能，顺手运行了依赖安装命令，把两个间接依赖升到了新版本。构建虽然没挂，但兼容性风险被引入了生产分支。后续我做了两个调整：在任务卡禁区里明确列出依赖锁定文件，禁止未授权的版本变更；同时把权限档位在“常规任务”阶段锁在可编辑层级，不允许它自己跑安装命令。

7.2 现象二：测试全绿，但业务逻辑错了

这是最隐蔽的一类坑。AI 写出的实现逻辑与需求本意不符，但它自建的测试断言也跟着写偏了，两边一起错，CI 照样通过。后来我在任务卡里多了一个字段“验收标准中的关键业务场景”，要求把真实业务场景写成可执行的用例，而不是让 AI 自己定义断言。

7.3 现象三：文档和代码不一致

Claude Code 改完代码后，README 和接口注释还停留在旧版本。下一个接手的人照着文档操作，直接踩坑。现在我每次 review 都会对照 diff 检查文档，并且在最终验收清单里把“文档更新”设为硬性条件。如果它漏了，我会打回任务，要求补齐再合入。

7.4 现象四：为了修一个问题，引入两个新问题

有过一次连续三轮的修 bug 过程，每一轮修复都让前一轮的测试通过，但引入了新的边界漏洞。问题出在没有把“避免影响范围扩散”写进任务定义。后来我要求它在每次修复前先输出根因分析，再列出改动方案，确认完才允许动手。这个“先分析再改”的顺序，让这类问题的出现频率大幅下降。

7.5 现象五：过度设计

有一个配置导出功能，本来十行代码能搞定，Claude Code 却生成了一套带抽象接口、工厂模式和插件的框架。它确实按“最佳实践”写了，但跟项目当前规模完全不匹配。我在 CLAUDE.md 里加了明确要求：新代码必须遵循“最小可工作实现”原则，不引入额外抽象层，除非任务卡里明确要求。生产级不是堆设计模式，而是控制复杂度。

7.6 现象六：多轮对话后遗忘早期约束

长对话里，Claude Code 会逐渐淡化最初任务卡里的边界，越改越偏。我验证下来，最有效的办法是“一事一议”：一个大需求拆成多个小任务，每个任务独立启动新对话，并把任务卡完整粘贴进去。不要试图在同一个上下文里连续完成多个目标，那既损耗上下文深度，又会让边界逐渐模糊。

8. 团队落地：把个人规范变成团队公约的几条建议

8.1 从一份模板开始，先小范围试点

我个人规范跑通之后，把它整理成了一份团队模板，先在一个项目组里试了一个月。这一个月里我们不追求覆盖率，只看两条指标：一是 AI 生成的代码被直接合入的比例，二是代码 review 时被要求修改的次数。前者代表效率，后者代表质量风险。一个月后我们发现，使用了任务卡和 CLAUDE.md 的改动，review 打回率比之前的随手生成低了将近一半。

8.2 在仓库和 CI 里挂上规范检查

规范只有被工具强制执行，才不会变成纸面文章。我在仓库里做了三件事：把 CLAUDE.md 模板放入每个新项目初始化流程；在 PR 模板里要求提交人填写“Claude Code 生成范围”和“改动文件清单”；在 CI 里增加一个检查步骤，如果 diff 涉及禁区文件，就会在评论里自动提醒。人到提醒这一步还要再看一眼，但至少没有漏网的大改动。

8.3 团队执行时的争议规则怎么定

有一条争议最常出现：既然 Claude Code 效率这么高，为什么还要强制写任务卡？我的答案很简单，任务卡不是给 AI 看的流程负担，而是给自己看的纠错成本。写任务卡花五分钟，后续 review 可以省下半小时。AI 生成代码越自由，人的审查成本就越高。任务卡就是把自由限制在可控范围内，同时也成了代码 review 的对照依据。

8.4 一些我后来才想明白的体会

回过头看这两个多月的实践，最有价值的不是某条具体规则，而是态度的转变。以前我把 Claude Code 当成一个“能写代码的队友”，现在我会把它当成一个“需要明确指令的协作工具”。队友有自己的判断力，工具则需要把边界写清楚。你用控制工具的方式控制它，效率和安全性会同时上升。

我现在接到需求，第一件事不是打开 Claude Code，而是先写任务卡。这件事坚持了两个月之后，我发现不仅 AI 生成的代码质量稳了，连我自己的思路也变得更清晰了。凡是让我觉得“得让 AI 来写”的任务，往往是我还没想清楚怎么拆分的任务。规范最大的收益，可能就是在动手前逼着我把每一步想明白。