企业官网建设流程全解析

我把 Claude Code 从“玩具”推向“生产级工具”，是我过去半年里反复打磨的一件事。如果你也习惯开着终端写代码，大概率遇过这个场景：AI 给出一段看似完整的改动，本地跑得通，但一到合并请求评审就被打回——风格不统一、异常处理缺失、测试覆盖根本没到位。这篇内容是我整理的一份《Claude Code 最佳实践》中文版，重心不在几个花哨的命令上，而在怎么围绕 Claude Code 搭一套生产级代码规范。它适合所有在真实项目里使用 AI 编程助手的开发者，也适合想给团队引入统一 AI 开发准则的技术负责人。我会从项目定位、环境准备、上下文管理、编码规范落地、团队协作和避坑经验几个部分展开，每一部分都是实际项目里反复验证过的做法。

1. 项目定位与核心价值拆解：Claude Code 在生产环境里到底扮演谁

1.1 Claude Code 到底是什么

Claude Code 是一个终端里的 AI 编程代理。它和你在浏览器里跟大模型聊天的体验完全不一样：它直接运行在项目目录里，能读取代码库、查看 Git 状态、调用 shell 命令、修改文件，并且每一步操作都会先在终端里展示出来，等你批准后才真正执行。你可以把它理解为一个带权限控制的“AI 结对工程师”——它给出的不是口头建议，而是能落地的改动。

从工作方式看，Claude Code 和传统的代码补全插件有本质区别。代码补全插件是“你写一个单词，它猜下一个单词”，Claude Code 是“你下达一个任务，它规划任务拆解、定位相关文件、修改代码、运行测试、反馈结果”。这带来的变化是，它能把大量重复、机械、又特别容易出错的中间步骤给接手过去。比如批量把旧接口替换成新接口、给整个模块补充单测、把 A 设计模式下的代码迁移到 B 设计模式，这些活儿在过去要花半天甚至一天，现在规划得当的话，几轮对话就能出初稿。

它也有一些很实际的限制。最主要的限制是上下文窗口是有限的，不可能把整个巨大仓库一次性塞进去；其次是它的操作范围取决于你给的权限，权限给得宽就容易误伤，给得窄又效率不高。这些限制不是缺陷，而是需要我们在工程层面设计规则去管理的边界。后面第三部分我会专门讲上下文管理，第二部分先讲权限和基础接入。

1.2 为什么强调“生产级代码规范”

如果只是写个 Demo，AI 怎么发挥都没问题，能跑就行。但一旦进入生产仓库，代码要面对的东西就变了：它要在 CI 上经过 lint、类型检查、测试，要被人阅读和 review，下个季度还要继续维护。此时 AI 生成的代码如果没有规范约束，最容易出现“局部正确、整体失控”的情况——AI 会把你交给它的局部任务完成得很好，但它不会自动知道团队的命名规则、错误处理约定、架构边界。

我见过不少团队在刚引入 AI 编程工具时踩同一个坑：让 AI 帮忙加功能，功能确实加上了，但它的实现风格和团队现有代码格格不入。比如团队习惯用函数式组件，它给你写了个类组件；团队要求所有 API 错误统一抛业务异常，它直接在 catch 里console.log一下就结束了；更麻烦的是，它会为了“显得聪明”随手引入一个新的抽象，让后来维护的人一头雾水。

所以生产级代码规范的核心目的不是限制 AI，而是把团队的集体知识压缩成一个机器可读的项目规则文档，让 AI 在每次动手前都默认先读一遍。AI 越强，越需要给它划清楚边界。给它划边界这件事，本身就是生产级工程能力的一部分。

1.3 适合谁、能解决什么问题

这个实践的适用对象有两类。第一类是普通开发者，想把 AI 从“高级搜索框”变成真正的编码结对者，用它完成重构、补功能、补测试这类脏活累活，同时保住代码质量。第二类是技术负责人，需要为团队建立一套统一的 AI 开发细则，让每个工程师在使用 Claude Code 时都按同一套规矩办事，避免仓库被不同 AI 风格切割得支离破碎。

它能解决的核心问题有三个。一是把 AI 的产出质量从“看运气”变成“可预期”，通过规范文件、权限控制、检查命令把质量基线固定下来。二是把团队的隐性知识显性化，很多编码规范以前靠口头传递，写了 CLAUDE.md 之后新成员也能快速理解。三是把人和 AI 的分工理清楚：机器负责执行和验证，人负责定义目标和做最终判断。这套方法论不仅适用于 Claude Code，换到别的 AI 编程工具时思路也完全一致。

2. 环境准备与工程化接入：先立规矩再开工

2.1 安装、认证与第一份配置

安装方式很简单，在终端里执行一行命令：npm install -g @anthropic-ai/claude-code。前提是你已经装好了 Node.js，建议版本在 18 以上，太低的话部分功能会有兼容问题。装完后在项目根目录运行claude，就会进入交互界面。第一次启动要求完成认证，一般通过设置环境变量或者在登录流程里完成授权。认证完成后，剩下的使用体验就和本地工具没什么区别了。

第一次进入项目时，我建议不要急着让它干活，先做两件事：第一，跑一遍claude自带的帮助命令或/help，确认工具能正常读到当前目录；第二，在项目根目录创建一个CLAUDE.md文件，哪怕只写三行也行：“这个项目是什么技术栈、常用命令有哪些、代码风格要参考哪个目录的现有实现”。Claude Code 会把这个文件当作长期记忆和规则来源，每次会话自动加载。这是整个生产级规范的第一块基石，也是后面所有规则得以落地的根本设备。

2.2 权限模型：最小授权原则

Claude Code 的操作权限和用户体验高度相关。默认情况下，它执行写文件、运行命令这类高危操作前会停下来问你允许还是拒绝；你也可以手动调整权限模式。实际项目中，我建议遵守最小授权原则：先在计划模式下工作，让 AI 只读代码、分析问题、输出方案，完全不给它改文件的权限；确认方案没问题后，再切换成可编辑模式执行具体修改。

为了方便你选择，我把常见的权限模式做成一个对照表：

我常用的一个技巧是：用接受编辑模式时只打开要改的那几个文件，其他文件关闭，这样 AI 就算“溜号”也不会动到无关位置。不要贪图省事直接在全局开启全接受模式，代价是它哪天看错文件名就是一次灾难性误改。权限像水龙头，拧得越小越安全，工程上永远按最小需要给。

2.3 把规范写进 CLAUDE.md

生产级的第一块基石，是让 AI 在每次对话开始前都能读到项目规则。Claude Code 会固定加载项目根目录下的CLAUDE.md。我习惯在文件里写这么几类内容：项目技术栈和目录地图、惯用命令、编码规范、禁止事项、提交前的检查清单。下面是我某个项目里 CLAUDE.md 的简化片段：

# 项目规则 ## 技术栈 - React 18 + TypeScript + Vite - 状态管理使用 Redux Toolkit ## 常用命令 - 本地开发: npm run dev - lint: npm run lint - 类型检查: npm run typecheck - 测试: npm run test ## 编码规范 - 优先使用函数组件，不要写 class 组件 - 所有回调统一用 useCallback 包裹 - API 层错误必须抛出统一的 ApiError ## 禁止事项 - 不要直接修改 public/schema.json - 不要使用 any 类型 - 不要在 redux 里存放非序列化对象 ## 提交前检查清单 1. 运行 npm run lint 2. 运行 npm run typecheck 3. 运行 npm run test 4. 确认没有新增 any

这份文件会占一点上下文空间，但性价比很高。注意两点：第一，不要在 CLAUDE.md 里塞密钥或私密信息，因为它在团队仓库里可见；第二，不要写到所有细节都包进去，那样上下文窗口会被浪费，只写那些 AI 判断不了、必须人工告知的约定。好的 CLAUDE.md 应该像一份给外包工程师的交接文档，而不是一本百科。

2.4 团队级配置分发

CLAUDE.md 放进 Git 仓库后，团队所有人自动生效。个人习惯放在~/.claude/CLAUDE.md里，项目规则放在仓库根目录。如果某个子目录有自己的特殊规则，比如有些历史包袱很重的老模块，可以在子目录里放一个更局部的 CLAUDE.md，它的优先级会高于根目录。这三个层级逐级覆盖，能把“项目公共规范”和“局部特例”分开，避免一条规则套全仓导致误伤。

这里有个容易被忽略的操作：版本管理系统里的 CLAUDE.md 也是代码的一部分，修改它应该走正常的 review 流程。不要随意往里面加一条“为了过评审”的规则，规则要经过团队认可，要写清楚原因。遇到 AI 重复犯同一个错误时，可以把它记成规则，提交给团队讨论，通过后写入文件。这样 CLAUDE.md 会越来越像团队的技术决策记录，而不仅仅是一个给 AI 看的配置。

3. 代码库理解与上下文管理：让 AI 看对地方

3.1 上下文窗口的有效利用

上下文窗口是所有 AI 编程工具最现实的瓶颈。Claude Code 虽然能感知很多信息，但窗口总量是固定的，塞得太多反而会互相干扰。实际项目里我是这样管理的：

• 每次会话只围绕一个目标，做完就/clear，不要把所有需求混在同一个对话里。
• 历史信息丢得差不多了，用/compact压缩历史，保留关键结论，把中间过程丢掉。
• 引用文件时用@语法把路径加进去，只引“看代码时绕不开的关键文件”，不引大量风格雷同的样板文件。
• 需要看函数定义时，与其把整个文件丢进去，不如直接问“看一下 utils/format.ts 里 formatMoney 函数的实现”，让它按需读取。

上下文窗口就像工作台面积。你可以在台上铺开很多资料，但铺得太满，真正能操作的空间反而没了。AI 的“思考质量”和它看到的噪音信息量强相关。上下文管理得越好，越不容易出现“读错了文件导致改错函数”这种低级事故。我见过不少人在会话里同时塞三个不同模块的任务，结果 AI 把 A 模块的变量名带进了 B 模块，最后提交上去全是编译错误。

3.2 “任务书”式提示词

提示词的质量直接决定产出上限。与其随便说一句“帮我加个登录功能”，不如写一份任务书：背景、目标、约束、验证。举例来说明：

“这是我要你完成的任务：当前登录表单在用户输入非法邮箱时会闪一下错误但又消失，请定位src/components/LoginForm.tsx中相关逻辑，修复错误状态未持久化的问题。要求：保持现有函数签名不变，不要引入新的依赖；修改完成后运行npm run test -- LoginForm，并把测试结果贴出来。”

如果你不说约束，AI 很可能顺手帮你重构了整文件、改了两个你不认识的函数。任务书的关键在于告诉它“边界在哪里”。另外，一次只给一个任务。给三个任务，它往往会并行处理，结果就是 commit 里混进不属于本次需求的东西。把大需求切成小批次提交，这个原则在人工开发里成立，在 AI 驱动开发里更加成立。

3.3 长会话与状态管理

跨多文件的复杂任务，我建议把任务拆成几步写在 todo 文件里，一般用/todo命令管理。AI 会按顺序执行，并把每个步骤的状态回填给我们。如果做了一半被电脑重启、断网等意外打断，恢复会话时用/resume可以把之前的 todo 继续搬回来。这个能力在真实开发里非常救命，尤其是当你已经需要跨十几个文件改东西时。

需要注意的是：跨天的长任务最好拆开。AI 的“短期记忆”是用来追踪文件变化的，不是用来记业务逻辑的，重新开一个会话反而更清醒。你想让 AI 记住的长期信息，应该固化在 CLAUDE.md 里，而不是寄希望于上次对话的上下文。这条经验听起来简单，实际操作时最容易疏忽，因为人自己也会觉得“反正聊了这么久，它应该记得”。结果第二天一恢复，它就忘记当初的约束条件了。

4. 生产级编码规范落地：不让 AI 过分享特权

4.1 用本地检查当成“强制门槛”

AI 生成的代码能不能进仓库，本地检查是第一道关。我刚引入 Claude Code 的时候，最头疼的是它自己没跑检查就说“完成了”，然后 CI 一跑就红了。后来我改了策略：把 CLAUDE.md 里的提交前检查清单写得非常明确，每次让它改完代码，必须把 lint、typecheck、test 全都跑一遍，并且在回复里贴出结果。有报错就自己迭代，直到全绿才算完成。

这个循环一旦固定下来，AI 输出质量立刻上一个台阶。如果不强制，AI 会默认“完成任务就行”，它没有意愿去验证边界条件，更不会主动补齐缺失的模块。你的规则越明确，它的行为就越稳定。我还会额外要求它在更改涉及多个文件时，先贴出git diff的关键片段，人工扫一眼再继续，避免改动方向跑偏后还一路跑到底。

4.2 代码审查是防错环

把 AI 生成的代码完全跳过审查，等于埋雷。我的态度是：AI 产出的 PR 一定要走常规代码审查，而且审查者要带“AI 偏好”的视角去看。AI 特别容易犯几类问题：

• 把简单逻辑写成抽象工厂，为了“扩展性好”而过度设计；
• 边界条件（null、空串、0、超长字符）考虑不周；
• 测试只顺着实现写，没有真正验证行为；
• 复制粘贴式代码导致重复逻辑散布。

我在团队推行一个 30 秒检查清单：看异常处理、看边界输入、看是否引入新模式、看测试有没有断言真实结果。这四条过了，AI 代写的代码基本能放心合入。记住，AI 生成代码的速度快，只是让它更早进入评审，并不是让它免于评审。代码审查永远是人的责任，工具做得再好，也只是把人工检查的重点从“逐行读逻辑”转移到“判断边界和架构约束”上。

4.3 测试优先与测试同等对待

让 Claude Code 写测试是效率非常高的用法，但要注意它给测试“注水”。它写的测试通常全是 happy path，把正常路径跑一遍就是绿灯。比较有效的方式是采用“行为驱动”的描述：先写 Given/When/Then，让它按行为定义生成实现和测试，并要求补上边界用例和异常用例。

在实际项目里，我会让 AI 写完测试后，手工改一个实现细节让测试失败，看看它能不能抓到。抓不到，就说明测试写得不够狠，趁早重写。这个“反向验证”的方法很简单，却很能说明问题。很多 AI 生成的测试表面绿油油，实际上一改实现就崩，它们只是在镜像实现，而不是在验证契约。测试的价值不是数字，而是保护功能的行为边界。

4.4 处理“AI 风格代码”的漂移问题

AI 生成代码多了，仓库会越来越像“多人 AI 协作”的杂交地。每个人的指令习惯不同，就会产出五花八门的代码风格。要压住这种漂移，我推荐三管齐下：

• 项目里放自动格式化工具，比如 Prettier，统一所有文件的基础风格；
• 开启严格类型检查，从类型层面约束掉一批“差不多先生”式的代码；
• 在 CLAUDE.md 里写明“新代码必须遵循 src 下现有模块的风格，不能为了抽象去新建 pattern”。

定期做一次全仓库 diff，把风格不一致的文件挑出来统一清洗，也是好习惯。尤其是当一个新加入的工程师因为不熟悉项目习惯，让 AI 产出了完全不同于旧模块的代码布局时，这个问题会特别明显。生产级代码规范不是一份静态文件，它需要像除草一样时不时维护，才能保持整个仓库风格的连贯性。

5. 团队协作与可维护性：把规范做成系统

5.1 Git 提交与分支策略

Claude Code 可以直接操作 Git，也能帮你生成提交信息。但生成之前，要让它形成原子提交的意识：一个逻辑一个提交。如果你的 prompt 是“把两个功能都做掉”，它大概率会在一个 commit 里积压所有事。所以分支策略上我建议功能分支加 PR 保护模式：main 分支禁止直接 push，所有 AI 改动都走 PR。这样即使 AI 不小心踩了线，也能在合并前被拦下来。

提交信息生成后，我会把Claude生成的标题过一遍，改成符合团队规范的前缀，比如feat(login): 修复表单错误状态持久化。AI 喜欢用比较笼统的描述，比如“修复登录表单相关问题”，这种信息在维护几年后的 blame 视图里基本没用。提交信息的质量直接影响回溯成本，这种细节不能完全交给默认值。

5.2 文档自动化与知识沉淀

Claude Code 非常适合做文档类任务：补注释、更新 README、生成 changelog。但它这里有个坑，就是会把文档写得“看起来很努力但讲不到点”。我现在的规则是：注释只写 Why，不写 How；README 里的命令必须和 package.json 里的 scripts 一致。为了让规则可执行，可以在 CI 上挂一个简单的同步检查，专门扫描那些写着“待更新”的关键词，一旦出现就 Fail。

因为 AI 生成的文档对“一致性”的感知较弱，所以人需要在流程上兜底。另一个实用的做法是每次更新代码时，让 Claude Code 顺手标记出哪些注释或文档可能需要更新，而不是直接替你把文档全部重写。否则很容易出现一个情况：代码已经重构完毕，README 里还留着旧接口的用法，后来的人照着文档调接口，越调越怀疑人生。文档的“维护性”比“丰富度”重要得多。

5.3 团队的 CLAUDE.md 要持续演进

最好的规范文件是“长出来”的，不是写出来就完了。在使用过程中遇到 AI 犯的低级错误，我会立刻把它记到 CLAUDE.md 的修订记录里。比如有次团队发现 AI 自动给所有接口加了 try/catch，把错误吞掉了，我们就在 CLAUDE.md 里写了一行：“API 层禁止吞错，必须抛 ApiError”。一个月后回看，这份文件的每一条几乎都来自真实事故，比任何培训都管用。

持续演进意味着要建立“记录”的习惯。当你在 review AI 产生的 PR 时，发现一个值得注意的问题，不要只口头跟作者说一句就算了。顺手打开 CLAUDE.md，想一下这个问题是不是“未来还会再发生”的类型，如果是，就用一句话写进去。日积月累，这份文件会成为团队 AI 协作最重要的机器可读资产，也会成为新工程师了解项目约束的一手资料。

6. 常见问题、避坑技巧与经验总结：真实项目踩过的坑

6.1 AI 会“脑补”执行结果

这个问题发生频率比想象中高。你让 AI 统计代码行数或查看测试覆盖率，它有时会直接给出一个结论，而不是真正运行命令。越是接近自然语言的任务，越容易触发这种“过度自信”。解决办法是审查命令：确认它正在调用wc -l、npm test -- --coverage这类实际命令，而不是凭空给结果。再保险一点，让它在回复开头贴出命令原文，复查命令对不对。

我试过最典型的一次：让 AI 统计项目里还有多少处旧 API 调用，它贴了个“约 37 处”，但实际一查 git grep 的结果是 82 处。从那以后我凡是让它做统计类任务，都会明确要求“必须使用 grep 或 wc 之类的命令获得真实结果，禁止估算”。这种约束写进 CLAUDE.md 的“提交前检查清单”里，比现场核对要省心得多。

6.2 权限过宽导致误改文件

实际项目里踩过最疼的坑：有一次让它重构一个旧模块，结果它顺手把同目录下另一个模块也改了。原因是提示词里“相关文件”的表述太宽泛，AI 对范围的判断和我们不一致。从那以后我总结了几条纪律：

1. 先把要改的文件清单列出来，让它确认；
2. 任务开始前跑git status看一下基线；
3. 在 CLAUDE.md 里标注“禁止修改 src/legacy/ 下文件”之类的红线；
4. 涉及大范围重构时，先开一个新分支，让 AI 只能在该分支上操作，出问题随时删。

误改文件这件事，本质上是“提示词边界”和“权限边界”双重偏差叠加的结果。你能做的，不是让 AI 永远不犯错，而是让错误的影响范围被限制在一个很小的区域里。分支是新手的救生圈，清单是范围的止火带，这两个东西组合起来，就能把 AI 的莽撞变成可控的实验。

6.3 单测“全绿”但“没测到点上”

AI 生产的测试最典型的场景：接口返回的字段名写错了，但测试断言也写错了，两个错误对齐了，测试照样全绿。这种“错误对齐”最迷惑人。我验证测试有效性的土办法很简单：故意把一个实现改成错的值，再跑测试；如果测试没有红，说明测试没在真正验证行为。让 AI 补上这样的“反向测试”，比单纯加覆盖率数字有价值得多。

覆盖率这个指标本身没有太大意义，AI 很容易把覆盖率刷到 90% 以上，但关键的错误分支还是漏的。真正有效的手段是性能检查：把测试里最核心的那几条用例挑出来，手动破坏实现，看测试能不能报警。这比盯着覆盖率数字去买放心要好得多。我一再提醒团队不要为了“让 AI 显得成功”而放过这种测试假绿的情况，否则上线后爆出来的问题更痛。

6.4 写进 CLAUDE.md 的几条“保命规则”

最后分享几条我现在每个项目通用配置里都会写死的规则，它们几乎是用事故换来的经验：

• 所有对外导出的函数必须有类型定义，禁止any；
• 接口返回数据必须经过运行时校验，不能假定后端一定符合类型；
• 测试必须是独立可重复的，不能依赖执行顺序；
• 所有对外 API 的变化必须同步更新类型文件和文档。

这几条规则单独看都很朴素，但组合在一起，基本能把 AI 输出里最常见的“类型漂移”“假测试”“影子文档”三种问题堵住。我现在建立新项目时会直接复制一套 CLAUDE.md 模板过去，然后根据项目特性做加减。这套模板的每条规则都有真实事故背景，所以团队成员读起来也更容易接受，不会觉得是形式主义。

我个人在实际操作中的体会是：AI 辅助开发最大的价值不是替你把代码写完，而是替你把那些重复、机械、容易遗忘的检查工作做完。但它对“规范”的理解，非常取决于你怎么写、怎么配、怎么审。今天这些方法不一定每条都适合你的仓库，但有一点是通用的：如果你不给 AI 立规矩，它就会用自己的风格去写代码；生产级代码规范的意义，正是把这个“默认值”从人的身上，搬到一个可持续运行的工程系统里。希望这些经验能帮你把 Claude Code 调教成团队里最守规矩的那位新同事。