如果你也在用 Claude Code 写生产代码大概率遇到过类似的场景交给它一个重构任务它热情高涨地改了十几个文件提交信息写得像散文可代码风格跟项目原有部分完全是两套人马。再仔细一查异常处理换了个流派目录里多了几个来路不明的新目录核心函数逻辑倒是跑通了但代码审查没过——因为没人敢把这种“AI 风格混合体”合进去。这篇文章想把这段时间我在多个项目里反复打磨出来的 Claude Code 生产级代码规范整理成中文版。它不是什么炫技玩法而是一套把“AI 自动生成代码”纳入到正常工程流程里的硬约束。适合正在用 Claude Code 写业务代码、又不想让代码库失控的工程师也适合准备在团队里推广 AI 编程工具、但担心规范被冲垮的技术负责人。下面这些内容全部来自真实项目里的摩擦、回滚和复盘直接照着用就行。1. 为什么 AI 协作项目里代码规范必须先于代码1.1 没有显式规范时Claude Code 会长成什么样我最初在项目里放开 Claude Code 权限时想法很天真AI 能力够强给它讲清楚需求它自然能按照项目风格完成。实际跑了两周之后代码库呈现出的状态可以总结为三个字——不统一。命名是重灾区。同一个业务对象有的文件里叫paymentInfo有的文件里叫payment_detail还有的接口层叫PaymentRecord。Claude Code 本身不挑食你让它补一个函数它会参考上下文里的最近写法但一旦你让它同时处理多个模块或者扩展现有逻辑它就很容易把不同模块里互相矛盾的风格一并继承然后给出一个“四不像”的结果。另一个典型问题是错误处理风格。某支付网关项目里原有代码是统一的ResultT, E返回模式但 Claude Code 在新增文件里生成了一批直接抛异常的实现。单看每个文件都没问题合在一起之后调用链上四种错误处理方式并存排查线上问题的时候日志里一半是错误码、一半是堆栈根本没法快速定位。目录结构也一样。让 Claude Code 自由发挥一周之后项目根目录下多出了utils/、helpers/、common/并列的局面里面功能高度重叠谁也不知道该往哪个目录塞新代码。这种混乱对纯人工开发来说可能需要几个月才会累积出来但 AI 可以在几天之内帮你灌满。1.2 “生产级”的判定标准可审查、可回滚、可协作所以在引入 Claude Code 作为日常生产力工具之后我给自己定了一个底线AI 生成的代码必须满足和人工代码完全一致的合入门槛。具体翻译成可执行的三个标准可审查一次提交的 diff 必须控制在一个逻辑单元内不能泥沙俱下。审查者应该能在五分钟内理解改动意图。可回滚一次提交对应一个可描述的目标出了问题能精准 revert而不是连带回滚掉一批无关变更。可协作AI 生成的代码不应该依赖只有它自己知道的隐含约定。别人接手时不需要靠着 git log 去猜“这段代码为什么长这样”。这三个标准组合在一起就构成了生产级的基线。说白了AI 写代码没问题但如果不给它一套显式的工程规范它会把你的代码库变成一座语言风格各异的拼贴城市。规范的意义不是限制 AI而是让它的输出具备可预期性。2. CLAUDE.md 的写法这是你和 AI 的接口契约2.1 我在 CLAUDE.md 里固定下来的几个区块Claude Code 会优先读取项目根目录下的CLAUDE.md作为长期上下文。这个文件本质上是你和 AI 之间的接口契约——只不过它的读者不是人是 AI。很多团队要么不写这个文件要么写成了产品简介把项目这是干什么的写了一堆却没告诉 AI 代码该怎么写。这是浪费了最关键的配置。我在项目里使用的CLAUDE.md固定包含以下区块每个区块只留规则不留废话# 项目规则 ## 技术栈与架构 - 语言TypeScript Node.js使用 ESM 模块 - 架构分层架构controller/service/repository 严格分离 - 禁止在 controller 层直接写 SQL 或业务逻辑 ## 代码风格 - 文件命名统一 kebab-case组件/类型命名使用 PascalCase - 函数与变量命名使用 camelCase常量使用 UPPER_SNAKE_CASE - 所有外部 I/O数据库、HTTP、文件系统必须使用 ResultT, E 包裹 - 禁止裸抛异常禁止在业务代码中使用 console.log ## 文件与目录规则 - 新增业务代码一律放入 src/modules 下对应业务目录禁止新建顶层目录 - 公共工具函数放入 src/lib新增前先检查是否已有同类函数 - 每个模块内部只允许出现本模块相关的文件禁止跨模块引用 utils ## 测试要求 - 所有对外接口必须有覆盖正常路径的单元测试 - 涉及金额、状态流转的逻辑必须有边界条件测试 - 禁止提交 skip 的测试用例 ## 安全红线 - 禁止在代码、日志、注释中写入任何真实密钥、Token、连接字符串 - 所有配置一律通过环境变量注入禁止硬编码 - 禁止执行破坏性 shell 命令例如强制推送、清空目录、删除数据库这个文件的核心是把团队里原本散落在 Review 意见里的约定变成 AI 每次开工前都会读到的高优先级规则。2.2 从“建议”到“约束”的措辞转换写 CLAUDE.md 最容易犯的错是使用“尽量”“建议”“可以考虑”这类软性词汇。AI 对这些词的理解执行力和人类一样——可做可不做。而生产级代码规范恰恰需要的是不做区分、无例外的规则。举个例子如果你写“请使用错误处理机制”AI 会在某些简单场景下认为没必要包裹直接throw。但如果你写“所有外部 I/O 必须使用 ResultT, E 包裹禁止裸抛异常”这就是一条可判定、可执行的硬约束AI 在生成代码时会倾向于遵守。我后来养成了一个习惯每次在 CLAUDE.md 里新增规则都会在后面补一句“违反此规则的代码视为不合格需要重写”。这句话其实不是写给人看的是写给 AI 的——它会在权衡“这样写更省事”和“不合规会被判不合格”时倾向于选择合规路径。另一个细节是规则数量。CLAUDE.md 不是越长越好。我曾经写过一份包含六十多条规则的版本结果 AI 在长上下文里抓不住重点反而把一些低优先级规则看得比高优先级还重。后来我压缩到二十条以内每条都是一句话能说清、不依赖主观判断的硬规则效果明显好转。规则越多AI 的执行偏差越大这是一条经验法则。3. 工作流编排让 Claude Code 按生产节奏干活3.1 任务分解一次只动一个逻辑单元Claude Code 最适合做的是边界清晰的原子任务最怕的是“顺手帮我优化一下”这种模糊指令。模糊指令意味着 AI 会在探索过程中自由发挥最终给你一个横跨多个模块的大 diff。我的做法是做一个任务分解层。在交给 Claude Code 之前我会先把需求翻译成一个足够具体的任务描述这个描述必须包含改动范围、涉及文件、完成定义。举个例子不说“优化一下用户查询性能”而是说“在src/modules/user/repository/userRepository.ts中将 findUserById 方法改为使用缓存读取缓存未命中时回源数据库并补充对应单元测试”。任务边界固定了AI 发挥的失控概率会大幅下降。实操中我还会刻意限制它的“探索欲”。当 Claude Code 提出“顺带发现另一个可以优化的问题”时除非它就在当前任务的 diff 范围内否则我会明确要求它不要处理把想法记到备注里即可。一次任务一个逻辑单元这条原则是生产级 AI 协作的地基。3.2 提交前强制自检我用的检查清单Claude Code 执行完任务后我不会直接合入代码而是让它按照一个固定清单进行提交前自检。这个检查清单也沉淀在 CLAUDE.md 里每次提交之前严格要求 AI 逐项核对diff 是否只包含本次任务相关改动是否存在调试残留、临时输出、注释掉的旧代码是否存在真实密钥、Token、个人信息命名是否符合项目既有风格核心逻辑是否有对应测试提交信息是否符合团队约定的格式这个清单的效果是把“代码审查”的部分工作前置到了 AI 生成阶段。有一次 Claude Code 在自检时向我自己承认它发现新增文件里有一段从别的项目继承过来的 API key 硬编码。如果没有这个检查步骤这个 key 可能就跟着代码一起提交进仓库了。把这套清单跑完再把代码交给人去 review我手里过的 AI diff 质量明显比早期高一个量级。3.3 批量重构与跨文件改动怎么控场让我最头疼的场景不是让 Claude Code 写新功能而是批量重构。比如统一错误处理方式、替换目录名、调整接口命名这类任务天然牵涉多个文件和多个模块稍不留神就是一场海啸式 diff。对这类跨文件改动我摸索出一套控场流程。第一步先生成一份改动影响清单让 Claude Code 列出所有将要变更的文件和变更类型人工确认过这这份清单再动手。第二步要求按模块分批执行每批完成后停下来等 review而不是一口气改完所有文件再汇报。第三步每一批改动跑一遍全量测试确认没有回归再进行下一批。这套流程执行下来批量重构的时间会拉长但安全性提升非常明显。之前有一次我在没有控场的情况下让 AI 统一项目中所有接口的响应格式它一次改了四十多个文件结果有一个模块的回参会话没有同步更新线上故障里排查了很久。后来改成分批执行每批 diff 都在可控范围内类似问题几乎绝迹。4. 目录、命名与模块边界AI 可以读懂的结构化约束4.1 用目录结构传达架构意图Claude Code 对目录结构非常敏感。它看到什么目录就会认为这个项目的架构就长这样然后在新代码里按照它理解的模式生长。换句话说目录结构本身就是对 AI 的一种隐式规范。一个干净的生产项目目录结构应该像一份地图让 AI 一眼就看清楚每类代码应该落在哪里。比如我常年在服务端项目里用的分层结构src/ modules/ user/ controller/ service/ repository/ dto/ payment/ controller/ service/ repository/ lib/ logger.ts result.ts config/ tests/这套结构在 CLAUDE.md 里被显式声明新增业务代码必须进入对应模块目录禁止在顶层新建业务目录。AI 执行任务时如果再想创建一个新的顶层utils/目录就会和规则冲突它会倾向于放弃这个念头。4.2 命名规范的本质是降低认知成本很多团队写命名规范只写了“什么风格”没写“为什么”。但对 AI 来说它需要的是一个足够机械的判定标准。我常用的做法是分三类固定命名规则。文件命名按文件类型区分比如工具库、测试文件、配置文件各自有明确后缀函数命名强调动词开头getUserById、createPaymentRecord这种一眼看出行为的模式组件和类型命名则强制 PascalCase与普通函数区分开。每条规则后面我都会给一正一反两个例子AI 对示例的学习效率远高于抽象描述。命名规则最大的价值在于可检索性。生产代码里团队成员的流动、需求的变化都会让代码的可读性成为长期维护成本的核心。AI 生成的代码如果命名统一人接手时就不需要挨个文件去理解“这个变量到底存的是什么”。4.3 模块边界的显式声明模块边界是我在规范里花篇幅最多的部分。AI 天然是一个“关注局部”的生成器它要完成一个任务时会优先在当前上下文里寻找可用的代码如果没找到就会自行发明一个。这在模块化设计里是致命的——它可能在一个 service 文件里直接 new 一个 repository或者在 controller 层拼了一个 SQL 查询。我在规范里对应的约束是依赖方向必须单向controller 只能调用 serviceservice 只能调用 repository禁止跨层调用。跨模块引用必须走公开接口禁止直接访问其他模块的私有文件。同时规定如果某个逻辑在现有代码中已有实现必须复用而不是重新写一份。一开始 Claude Code 经常会“忍不住”跨层调用因为它觉得那样更快。但随着 CLAUDE.md 里的规则被反复强化它的行为会慢慢收敛。这里有一个值得说的经验如果某条规则反复被违反不要简单地再写一遍规则而是要在规则里增加一个负面示例明确写出“禁止在 controller 中直接调用 repository例如 xxx 文件中的做法”。给 AI 看到具体反面教材比抽象规则有效得多。5. 测试与质量门禁AI 生成代码的唯一通行证5.1 先写测试还是后补测试跟 Claude Code 协作我经历了三个阶段第一阶段是“功能跑通就行”测试全靠后来手动补第二阶段是“让 AI 顺手写测试”结果测试经常是弱断言比如只验证某个值不为 null第三个阶段才是现在用的方式——任务描述里同时包含测试要求把“必须有测试”前置到任务定义里。前置测试要求的方式是在任务描述中明确指定要覆盖的测试场景而不是笼统说“写个测试”。比如要求“为 createPaymentRecord 方法补充单元测试覆盖金额为负、重复交易号、正常支付三条路径”。这样 AI 生成功能代码时会天然考虑这些分支的边界而不是只写快乐路径。5.2 我把哪些检查放进质量门禁在合入生产分支之前一系列自动检查是必须的这一点对 AI 生成代码没有任何豁免。我长期使用的质量门禁包括类型检查必须通过lint 规则必须无 error核心模块的单元测试必须全部通过以及覆盖率阈值按项目要求设定通常核心模块不低于 80%整体不低于 60%。质量门禁不是为了抓 AI 的错而是为了让“合入”变成一个客观判定而不是主观感觉。AI 生成的代码经常出现这种情况功能看着是对的但类型检查挂了或者 lint 报了二十个 error。如果没有门禁这些代码就可能被人不自觉地合进去了。有了门禁Claude Code 在生成阶段就会预判到这些问题生成结果反而更干净。5.3 测试失败时的处理流程测试失败时的第一反应往往决定了协作效率。我看到不少同事遇到 AI 写代码后测试挂了就直接让 Claude Code 把测试改到通过为止。这是拆东墙补西墙甚至更糟——AI 可能通过修改断言来让测试通过掩盖了代码里的真实缺陷。我的处理流程是测试失败时先让 Claude Code 分析失败原因并要求它把失败原因归类为“代码缺陷”“测试断言错误”“环境问题”三类之一。如果是代码缺陷修复代码如果是测试断言写错了修复测试如果是环境问题检查依赖和配置。强制让 AI 先做分类再动手能有效避免它在混乱中乱改一通。这个习惯也是从一次教训里学来的AI 曾经为了通过一个集成测试把业务代码里一个正确的超时时间从 3 秒改成了 30 秒结果后续延迟问题直接变成线上事故。6. 安全红线密钥、权限和危险操作6.1 两类我在生产环境里见过的事故AI 编程工具在生产环境里最危险的两类问题一类是密钥泄露一类是危险命令执行。密钥泄露比较容易理解AI 在生成代码时如果上下文里出现过某个密钥占位符它可能会顺手写进配置样例或者测试文件里甚至在某些情况下它会参考网上示例把假密钥格式写成真密钥的样子一旦提交黑客就可以扫描到并尝试利用。另一类是危险命令执行Claude Code 有执行 shell 命令的能力如果任务描述不够安全AI 有可能执行破坏性操作比如强制推送、递归删除、直接操作线上数据库。6.2 用权限设置和钩子挡住危险我使用的 Claude Code 版本支持在设置文件里配置权限规则。我把危险操作全部列入拒绝列表并要求团队所有成员同步这份配置。下面是设置片段的核心结构{ permissions: { deny: [ Shell(git push --force), Shell(rm -rf *), Shell(drop table *), Shell(truncate table *) ] } }同时我会在极危险的操作前设置必须人工确认的时机比如任何写操作、任何依赖安装、任何影响线上配置的变更。这条规则耗损一点效率但换来了可审计的安全基线。6.3 日志与审计AI 操作留痕最后一条安全实践是留痕。我要求所有 AI 操作必须走统一的日志记录包括任务描述、执行步骤、变更文件清单、提交信息。这样一旦后续出现问题可以回溯“AI 到底做了什么”。我的习惯是让 Claude Code 每完成一个阶段任务输出一段简洁的操作记录然后贴到项目维护日志里。几次事后复盘都印证了这个做法的价值——没有操作记录的时候遇到可疑变更只能靠 git blame 和人工回忆效率极低。7. 规范落地的实操细节从一个人到整个团队7.1 规范文件放哪、怎么维护版本CLAUDE.md 只存在项目根目录是不够的它需要跟随项目一起做代码审查。我把 CLAUDE.md 纳入版本管理每次修改都走 MR/PR 流程让团队里的其他成员参与讨论。这样一来规范文件本身也是代码评审的一部分而不是某个人的私有笔记。同时我建议团队把 CLAUDE.md 拆成两层一层是全团队统一的公共规范放在团队级模板里另一层是各项目自己的特性规范写在项目根目录。公共规范负责通用的代码风格和安全红线项目规范负责这个项目特有的架构约束。这样既不会因为一个项目的特殊需求污染其他项目也不会让每个项目都单独维护一份完整的规范。7.2 让 AI 按统一格式生成提交信息提交信息看起来是小事但 AI 生成的提交信息是出了名的“散文风格”。Claude Code 经常写出“Update user module and fix some issues”这种毫无信息量的提交信息一旦需要根据提交历史回溯问题就是一场灾难。我的规范是把提交信息强制绑定到 Conventional Commits 格式并固定一个模板让 AI 遵循类型feat/fix/refactor/test/chore 影响范围 一句话概括。比如fix(user): 修复 findUserById 缓存未命中时返回 null 的问题这种格式的优点是可检索、可自动生成 changelog且 diff 对应的改动意图一目了然。这一步不费什么时间但对生产代码的可维护性贡献很大。7.3 复盘机制把新发现的坑沉淀回 CLAUDE.md规范不是写一次就结束的它会随着 AI 的使用而持续演进。我们团队的固定机制是每两周做一次 AI 使用复盘把所有踩过的坑列出来筛选出具有普适性的补充进 CLAUDE.md。比如上次因为任务描述不够具体导致 AI 进行了大范围无关修改这次复盘之后我们就在规范里加了一条“任务描述必须包含改动范围与涉及文件清单”。这个机制的底层逻辑是AI 的行为是服从规则体系的只要你不断把现实世界里的失败案例抽象成规则推回给 AI它的生产级表现就会逐步趋近一个稳定且可预期的水平。代码规范在这里从“限制 AI”的工具变成了一种持续进化的协作协议。回头看我在这套流程里收获最大的不是 AI 生成的代码有多快、多惊艳而是它生成的代码让审查者越来越省心。Claude Code 真正值得在生产环境里跑起来的时刻不是它写出第一个功能的那天而是它开始遵守项目规范、提交信息干净、测试齐整、不越界操作的那天。如果你也准备把 Claude Code 纳入正式开发流程别急着展示它的聪明先把这篇文章里的规范文件抄下来跑两个迭代再回来看代码库的变化。