在claude code中配置lint规则来规范生成代码的质量

去年秋天，我在一个 Next.js 项目里让 Claude Code 帮我写一个用户权限中间件。它 30 秒就吐出了完整代码，逻辑通顺、类型齐全。我正准备夸它一句，Prettier 自动格式化了文件，紧跟着 ESLint 弹了 14 个 warning：no-param-reassign 触发了 3 次，import/order 乱得像意大利面，还有一个 no-magic-numbers 直接飘红，函数体里赫然写着 if (status === 3)，而这个“3”到底代表“已注销”还是“被封禁”，连写它的 AI 都没给我留注释。

这件事让我意识到一个被严重低估的问题：AI 编码工具在“能跑”这件事上已经很强了，但在“能被人类维护”这件事上，还差着一整套约束体系。 而那之后的三个月，我花了大量时间在 Claude Code 里反复调试 Lint 规则的配置方式，踩过规则冲突的坑，也试出了一些官方文档没明说但实测有效的模式。这篇文章，就是这段实践的全部复盘。

一、先把核心结论摆到台面上

我知道很多人点进来是想直接抄配置文件的，所以我不吊胃口，先把结论讲清楚。

Claude Code 本身没有内置 Lint 引擎。 它不会像 ESLint 或 Pylint 那样对你的代码做 AST 解析然后报错。但它有一种更底层的机制，通过 CLAUDE.md 文件注入的自然语言指令，可以模拟 Lint 规则的大部分效果，而且是在“生成时”就约束，不是“生成后”再检查。

这两种路径的差异，决定了配置 Lint 规则的整个思路都和传统方式不一样。我用三个月的测试数据来量化这个差异：

这是我统计了 4 个前端项目、共计约 2800 行 AI 生成代码后得出的数据。

核心结论就一句话：事后 Lint 是打补丁，生成时约束是改基因。 在 Claude Code 里配置 Lint 规则的本质，不是“装一个检查器”，而是“定义一套 AI 在写代码时就遵守的写作规范”。理解了这一点，后面所有的配置思路才不会跑偏。

二、回到真实场景：Claude Code 到底“听”什么

在开始配置之前，需要先搞清楚一个前置问题，Claude Code 在执行编码任务时，到底会遵循哪些指令源。我测试出来的优先级从高到低是这样的：

1. 当前对话中的显式指令（单次有效，优先级最高）
2. 项目根目录的 CLAUDE.md 文件（项目级，每次会话自动加载）
3. ~/.claude/CLAUDE.md 全局文件（跨项目，次优先级）
4. Claude 模型本身的训练数据中的编码惯例

这个优先级顺序是我通过设计对照实验验证的。我让 Claude Code 在不同的指令源里分别设置了互相矛盾的编码风格要求（比如一个要求用单引号，另一个要求用双引号），然后观察它最终服从哪个。

测试结果很明确：CLAUDE.md 项目级文件的指令可以被全局文件覆盖，但对话中的显式指令可以覆盖以上所有。 这意味着：

• 如果你只想在自己的机器上生效，改 ~/.claude/CLAUDE.md 就够了
• 如果你想和团队共享编码约束，必须把 CLAUDE.md 放进项目根目录并纳入 Git 管理
• 即便配了 Lint 规则，单次对话中仍然可以用“这次别管 Lint 规则，先写功能”来临时覆盖

这个机制比很多教程里写的“直接配个文件就好了”要复杂得多，因为它涉及到一个关键的认知：不弄懂 CLAUDE.md 的加载时机和优先级，就没办法确定规则到底生没生效。 我看到网上有些文章直接甩出来配置文件就说“这样配就行”，但那些人根本没告诉你，CLAUDE.md 里的东西太重，是会影响生成速度的。

我在一个 1800 行的 CLAUDE.md（是的，有人真敢写这么长）上做测试，发现每次对话启动时加载这个文件的耗时会额外增加 3-7 秒。对于那些习惯了 Claude Code 秒回的人来说，这个延迟在频繁开新会话时会非常烦人。所以我在后续的配置策略里专门讨论了“轻量级约束”和“深度约束”的取舍，这个后面详细讲。

三、拆解最常见的三个配置误区

在我自己踩坑以及和同行交流的过程中，有三个误区反复出现。这些误区如果不先讲清楚，后面的配置方法论你会带着错误的前提去阅读。

误区一：“直接把 .eslintrc.json 的内容粘贴进 CLAUDE.md 就行”

这是我见过最多的做法，而且我敢说这么做的人大概率没实际验证过效果。

我在 2024 年 11 月做过一次严谨的测试。我把一个包含 47 条规则的 .eslintrc.json 原封不动复制进了 CLAUDE.md，然后让 Claude Code 生成一个包含异步请求、条件判断和数据转换的工具函数。

结果是灾难性的。 Claude Code 在面对 47 条同时生效的自然语言规则时，出现了明显的“规则混淆”。具体表现为：

• 第 12 条要求“禁止使用 var”，第 33 条要求“优先使用 const”，这两条同时存在导致 Claude 在变量声明时过度保守，连 let 都不敢用，全部用 const，结果就是该重新赋值的地方直接报错
• 关于缩进和换行的 8 条规则互相打架，生成出来的代码格式不一致，同一段 JSX 里，有的属性换行了，有的没换
• 最严重的是，因为规则太长（整个 CLAUDE.md 超过了 3000 tokens），Claude Code 在生成代码时实际只遵守了其中约 60% 的规则，而且它不会告诉你它跳过了哪些

这个测试让我得出了一个重要的判断：CLAUDE.md 里的 Lint 规则不是越多越好，是需要做“规则蒸馏”的。 你必须从几十条 ESLint 规则里提炼出最核心的 8-15 条，用最清晰的表达方式写进 CLAUDE.md，剩下的交给真正的 Linter 在事后检查。

误区二：“配置一次就一劳永逸了”

那些说“配好之后就不用管了”的文章，我怀疑作者根本没在真实项目里用过这个方法。

我维护的一个中台项目，在 2024 年 10 月到 2025 年 1 月之间经历了三次技术栈调整（从 Pages Router 迁移到 App Router，数据库从 MySQL 换到 PostgreSQL，中间还插了一个 Prisma）。每一次技术栈变动，之前配好的 Lint 规则就会出现不适配的情况。

举个例子：迁到 App Router 之后，CLAUDE.md 里原来写的“所有数据查询写在 getServerSideProps 里”这条指令不仅没用了，还导致 Claude Code 在新架构下反复尝试生成一个不存在的函数。我花了 20 分钟才定位到是这个“过时指令”在作祟，而不是我的 prompt 写错了。

所以 CLAUDE.md 里的编码约束是需要跟着项目技术栈同步迭代的。 我自己现在的做法是，每次 package.json 或 tsconfig.json 有重大变化时，检查一次 CLAUDE.md 是否有需要更新的规则条目。这个习惯后来帮团队避免了好几次“AI 为什么老写旧架构代码”的困惑。

误区三：“CLAUDE.md 配了 Lint 规则，就不用再跑 ESLint 了”

这个误区最危险。它会让你产生一种“AI 已经帮我检查过了”的虚假安全感。

CLAUDE.md 里的规则本质上是提示性的，不是强制性的。 Claude Code 没有内置 Linter，它只是在“尽力理解你的规则并遵循”。这意味着：

• 它能理解“不要使用 any 类型”，但不会真的做类型推导来验证
• 它能理解“函数不超过 50 行”，但不会真的统计生成代码的行数
• 它在 95% 的情况下能遵守规则，但那 5% 的遗漏是没有任何报错提示的

我在实际使用中保持了一个原则：CLAUDE.md 负责“事前约束”，ESLint/Prettier 负责“事后兜底”。 两个机制叠加使用，违规代码出现的概率才是真正可控的。我的数据也验证了这一点：单独使用 CLAUDE.md 约束，违规率是 7.4%；加上 ESLint 的自动检测和修复后，最终可交付的代码违规率降到了 1.2% 以下。

四、专业判断：什么样的规则“适合”写进 CLAUDE.md

这个问题是整篇文章的精华，也是我花了最长时间做实验的部分。不是所有的 Lint 规则都适合用自然语言注入给 Claude Code。我根据几百次生成测试，把常见的编码规范分成了三个层级：

第一层：强烈建议写进 CLAUDE.md 的规则（高适配）

这类规则的特点是：语义明确，边界清楚，能被自然语言精确描述，且 Claude 对它们的理解一致性很高。

我在 CLAUDE.md 里关于这部分是这样写的：

## 代码风格硬约束（以下规则必须严格遵守）

变量声明：优先 const，允许 let（仅限需要重新赋值时），严禁 var
函数命名：事件处理函数以 handle 开头，回调函数以 on 开头
模块导出：全部使用命名导出，不写 export default
禁止项：永远不要生成 eval() 或未经过滤的 dangerouslySetInnerHTML
异步处理：任何 async 函数内部必须包含 try/catch，并在 catch 中执行 console.error

这个格式是我迭代了 4 个版本之后定下来的。核心经验是：用“必须”、“严禁”、“绝不”这种绝对化词汇，比“建议”、“尽量”、“最好”有效得多。 Claude 对强制性语言的反应明显更一致，我测试了两组表述，一组用“建议”，另一组用“必须”，前者规则遵循率是 71%，后者是 89%。

第二层：可以写但不建议过细的规则（中适配）

这类规则的特点是：Claude 能理解意图，但当规则数量太多或表述过于复杂时，遵循率会明显下降。 需要做“蒸馏处理”，提炼核心要点。

这一层的关键技巧是把 Linter 的检查逻辑“翻译”成人类写代码时会遵循的原则，而不是把 Lint 规则原文放进去。

举个例子，no-magic-numbers 这个 ESLint 规则，规范定义是“禁止在代码中使用未命名的数字常量”。如果你直接把这句话写进 CLAUDE.md，Claude Code 有时会过度执行（把 i + 1 里的 1 也提取成常量），有时又会漏掉真正的魔法数字。

我测试出来的最佳表述是：

代码中出现的数字字面量，如果其含义不直观（如状态码、业务阈值、配置参数），必须提取为有意义的命名常量。但通用的数学常量（如 0、1、2）和索引操作可以保留原样。

这种“带判断条件的自然语言表述”比“直接翻译 Lint 规则”效果好得多。我在 20 次生成测试里对比了两种写法，改进版的规则遵循率从 65% 提升到了 82%。

第三层：不建议写进 CLAUDE.md 的规则（低适配）

有些规则天然不适合用自然语言去约束一个 LLM，尤其是那些依赖 AST 精确解析、依赖上下文深度推理、或规则本身模棱两可的规范。

我在第一版 CLAUDE.md 里犯过的最大的错误，就是试图把所有 .eslintrc.json 里的规则全翻成自然语言塞进去。结果是 CLAUDE.md 膨胀到 2100 tokens，每次会话的规则加载消耗了大量上下文窗口，留给真正业务逻辑的空间反而被压缩了。更重要的是，那些格式化类的规则根本没有效果，白白浪费了宝贵的 token 配额。

五、从零开始的配置实操：一个完整的实战案例

讲完了理论和误区分层，接下来做一次从头到尾的实操演示。这不是“假设你在做某个项目”，而是我从自己去年 12 月接手的一个真实项目中提取出来的完整配置过程。

项目背景

• 类型： Next.js 14 App Router + TypeScript + Prisma + PostgreSQL 的后台管理系统
• 团队： 3 个前端，1 个全栈，其中 2 个人日常使用 Claude Code 辅助编码
• 痛点： Claude Code 生成的代码和团队沉淀的编码规范严重脱节，反复出现以下问题：
• 组件文件里混杂了服务端和客户端逻辑（没有 'use client' 指令）
• Prisma 查询直接写在组件里而不是抽成 service 层
• 错误处理缺失，半数以上的 fetch 没有 catch
• TypeScript 类型使用混乱，出现大量 as 断言和偶发的 any

步骤一：梳理“必须约束”的规则清单

我做的第一件事不是写 CLAUDE.md，而是拉上团队的 Tech Lead 一起 review 了过去三个月代码 Review 中反复出现的、与 Claude Code 生成相关的问题。我们从 40 多个高频 Review Comment 里筛出了 11 条最适合通过 CLAUDE.md 约束的规则：

1. 客户端组件必须在文件顶部声明 'use client'
2. 所有数据查询逻辑抽到 services/ 目录下的独立文件
3. async 函数必须有 try/catch，catch 中输出结构化错误日志
4. 禁止 any，限制 as 断言的使用场景
5. 组件 Props 必须定义 TypeScript 接口，不允许内联类型
6. 使用命名导出，禁止默认导出
7. 魔法数字必须提取为命名常量
8. 事件处理函数统一 handle 前缀
9. Prisma 查询结果必须做空值检查
10. 避免深层嵌套，优先使用早返回
11. Import 语句按第三方库 → 本地模块 → 类型导入的顺序分组

这 11 条规则全部经过“适配层级”评估，没有包含任何格式化要求（交给 Prettier），也没有包含需要编译器检查的类型约束（交给 tsconfig 的 strict）。

步骤二：撰写 CLAUDE.md 规则部分

这是最终定稿版的规则部分，我直接贴出来，你可以参考它的结构和措辞：

# CLAUDE.md - 编码规范
项目技术背景

Next.js 14 App Router，使用 Server Components 和 Client Components 混合模式

TypeScript 严格模式，Prisma ORM，PostgreSQL

状态管理使用 Zustand，UI 组件库使用 Shadcn/ui

编码硬约束（AI 生成代码时必须遵守）

架构分层

客户端/服务端分离： 任何使用 useState、useEffect、事件处理、浏览器 API 的组件，必须在文件第一行声明 'use client'
数据访问层分离： 所有直接调用 Prisma 的查询或变更逻辑，必须抽到 src/services/ 目录下，以 getXxx、createXxx、updateXxx、deleteXxx 命名。组件文件内禁止直接 import { prisma }
类型定义分离： 组件 Props 的接口定义优先放在 src/types/ 目录下；如果仅当前文件使用，允许定义在文件顶部

代码风格

变量声明： 优先 const，需要重新赋值时使用 let。严禁出现 var
函数命名： 事件处理函数以 handle 开头（如 handleSubmit），异步数据获取函数以 fetch 或 get 开头
导入/导出： 所有模块使用命名导出 export const/function，禁止 export default
常量提取： 代码中出现的数字字面量（状态码如 403、404；业务阈值如 MAX_RETRY），必须提取为有意义的命名常量并放在文件顶部。0、1、2 等通用索引值除外

健壮性

错误处理： 任何包含异步操作（fetch、Prisma 查询、数据库操作）的函数，内部必须包含 try/catch 块。catch 中必须使用 console.error 输出包含函数名的错误描述，而非静默吞掉错误
空值检查： Prisma 查询、API 响应、数组索引访问的结果，在使用前必须做 null/undefined 检查
类型安全： 严禁使用 any 类型。as 类型断言仅在处理第三方库类型不完善或 DOM 事件目标时允许使用，使用前需添加简短注释说明原因

可读性

早返回模式： 避免超过 3 层的嵌套 if/else 或 switch。优先使用早返回（guard clauses）处理边界条件
函数规模： 单个函数应保持短小，专注于单一职责。如果函数超过约 40-50 行，说明需要拆分
Import 组织： 导入语句按以下顺序分组，组间空一行：React/Next.js 核心库 → 第三方 UI 库 → Prisma/数据层 → 本地模块 → 类型导入

步骤三：验证规则有效性

配完不验证等于白配。我设计了一套标准化的验证流程，每次修改 CLAUDE.md 之后都会跑一轮：

验证流程（每次约 15 分钟）：

1. 新建一个对话会话（确保没有历史上下文的干扰）
2. 发出 3 个固定的测试 prompt：

• “帮我在 src/components/UserTable.tsx 里写一个展示用户列表的客户端组件，支持搜索和分页”
• “写一个 Prisma 查询，根据用户角色筛选出所有管理员，并按注册日期倒序排序”
• “写一个处理表单提交的工具函数，包含输入验证、API 请求和错误处理”

1. 检查生成结果是否符合 CLAUDE.md 中列出的所有规则
2. 记录违规项，分析是规则表述不清还是 Claude 理解偏差
3. 调整 CLAUDE.md 的措辞，重新测试

我在这轮验证中发现的典型问题：

• 第 8 条（错误处理）最初写成“async 函数必须包含错误处理”，Claude 理解为只要有个 .catch() 就算，哪怕 .catch(() => {}) 这种空处理也认为合规。 改成了“catch 中必须使用 console.error 输出包含函数名的错误描述”之后，问题基本消失。

• 第 9 条（非空检查）最初写成“Prisma 查询结果必须检查 null”，Claude 生成了很多冗余检查，比如 const user = await prisma.user.findUnique(...); if (!user) return null;，这在很多场景下是合理的，但对于 findMany 返回空数组也做同样的处理就很多余。 我后来把表述改成了“在使用 Prisma 查询、API 响应、数组索引访问的结果前，必须做 null/undefined 检查”，加上了“使用前”这个条件，减少了过度防御。

• 第 13 条（Import 组织）Claude 的遵循率最低，因为它需要知道哪些包是“第三方”哪些是“本地模块”，而它并不真正了解项目结构。 我最终把这条降权为“尽力遵循”，不再作为硬约束。

步骤四：设立“规则版本号”并纳入 Git

这是团队协作中极其关键的一步。我在 CLAUDE.md 的顶部加了一行版本标识：

# CLAUDE.md - 编码规范 v1.2.1 (更新于 2024-12-18)
同时把这个文件纳入 Git 管理，在 PR 模板里加了一条 Checklist：“如果本次 PR 涉及技术栈或架构变更，请检查 CLAUDE.md 是否需要同步更新。”

这个做法的效果立竿见影。之前团队成员各自在自己的 ~/.claude/CLAUDE.md 里写规则，规则内容和优先级不一致，导致同一个 AI 在不同人的机器上生成出风格差异巨大的代码。统一了项目级 CLAUDE.md 之后，这种“同样的需求，不同人跑出不同结果”的问题减少了大约 80%。




六、不同项目阶段的配置策略差异

很多文章会给出一套“万能配置模板”，但我在实践中发现，项目所处的阶段不同，CLAUDE.md 里 Lint 规则的配置策略应该完全不同。

阶段一：原型/ MVP 阶段（0 到 1）

这个阶段的核心目标是验证想法，快速试错。代码今天写的明天可能就删了。

配置原则：只保留安全底线，不要设风格门槛。

在这个阶段，我的 CLAUDE.md 通常只有 3 条规则：

1. 永远不要生成 `eval()` 或不安全的动态执行代码

涉及用户输入的场景，必须包含基本的 XSS/注入防护
所有异步操作必须有基础的错误处理（至少一个 try/catch）

至于缩进用几个空格、文件命名用 kebab-case 还是 camelCase，这些在原型阶段完全不应该成为约束。我见过一个创业团队在还没验证 PMF 的情况下，花了整整两天配置 CLAUDE.md 和 ESLint 规则集，结果项目一周后就转向了。

在这个阶段，约束越少，AI 生成速度越快（CLAUDE.md 的 token 消耗少），而且你不会因为“规则过细导致 AI 过度保守”而拖慢开发节奏。

阶段二：项目稳定迭代阶段（1 到 N）

这个阶段项目已经确立，团队成员增多，代码的可持续维护性变得重要。

配置原则：分层配置，核心规则硬约束 + 风格规则软建议。

我在这个阶段采用的策略是“规则分层”：

## 硬约束（AI 必须遵守，违反则生成结果不可用）

[架构类规则：文件分层、客户端/服务端分离]

[安全类规则：禁止危险 API、输入校验]

[类型安全规则：禁止 any、限制 as]

软建议（AI 应该遵守，但不强制，违规可接受）

[命名惯例]

[函数长度建议]

[注释风格]

格式化（AI 无需关心，生成后自动处理）

[所有缩进、换行、引号等格式化要求]

这样分层的好处是：AI 把注意力集中在真正重要的架构和安全规则上，不会因为“引号用单还是双”这种琐碎规则消耗大量 tokens。 风格类规则作为“软建议”，Claude 在生成代码时会有意识地参考，但不会因为必须遵守而牺牲生成速度和代码结构的灵活性。

阶段三：成熟项目/多团队协作阶段

当项目有多个团队同时维护，代码标准的一致性成为刚需。

配置原则：规则完成度最高，加上明确的“豁免场景”说明。

在这个阶段，CLAUDE.md 里的规则会增加到 15-20 条（但不应该超过这个数量），同时需要加入“豁免场景”：

## 豁免场景
以下情况允许偏离上述规则，但需要添加注释说明原因：

第三方库的类型定义不完善，导致必须使用 as 断言 → 注释注明库名和版本

性能关键路径需要内联优化 → 注释注明 profiler 数据

遗留代码迁移中暂时无法完全规范化 → 注释标注 TODO 和计划修复日期

没有豁免场景的严格规则，在实践中是难以落地的。 我见过一份写得很漂亮的 CLAUDE.md，16 条规则滴水不漏，但没有任何豁免说明。结果团队成员在实际开发中遇到了必须使用 as 断言的场景，Claude Code 又严格遵循“禁止 as”的规则，导致代码生成陷入了僵局，AI 想尽各种办法绕开 as，写出来的代码又长又绕，反而降低了可读性。

七、规则冲突时，Claude Code 到底怎么决策

这个问题是我在配置实践中遇到的最棘手的 bug 来源。当 CLAUDE.md 里的规则和业务需求发生冲突时，Claude Code 的决策逻辑并不透明。

我通过设计冲突场景来逆向工程 Claude 的决策逻辑。以下是 4 个典型的冲突场景和 Claude 的实际行为：

场景一：CLA.md 规则 vs 当前 task 的显式需求

设定： CLAUDE.md 要求“所有组件 Props 必须定义独立的 TypeScript 接口”。但我这次的 prompt 是：“写一个简单的展示组件，不需要类型接口”。

Claude 的实际行为： 它在 10 次测试中，有 8 次仍然生成了接口定义，只有 2 次遵循了我的“不需要接口”的指令。这说明 CLAUDE.md 的约束权重在 Claude 的决策系统里非常高，甚至可以覆盖用户的显式指令。

结论：如果你明确需要突破某个规则，必须在 prompt 里明确说“本次生成忽略 CLAUDE.md 中的第 X 条规则”，而不是笼统地说“不需要”。

场景二：两条 CLAUDE.md 规则互相冲突

设定： 规则 A 要求“使用早返回模式避免深层嵌套”；规则 B 要求“每个函数最多 30 行”。当要处理一个包含多个边界条件的验证逻辑时，早返回确实减少了嵌套，但把函数拉到了 45 行。

Claude 的实际行为： 它在 10 次测试中，全部选择了优先遵守“早返回模式”，允许函数行数超标。这说明 Claude 对“结构清晰度”相关规则的优先级高于“长度限制”类的规则。

结论：CLAUDE.md 中的规则需要明确优先级，否则 Claude 会在冲突规则之间自行选择，而它的选择逻辑不一定符合你的预期。 我的做法是在规则前标注 [P0]、[P1]、[P2] 来明确优先级。

场景三：安全规则 vs 性能需求

设定： 规则要求“所有用户输入必须经过 XSS 过滤”。当前的场景是一个仅在管理员后台可见的内容输入框，团队判断可以跳过过滤以提升渲染性能。

Claude 的实际行为： Claude 对安全类规则有极强的遵循倾向。在 10 次测试中，0 次跳过 XSS 过滤，即使我在 prompt 里说明了“仅管理员可见、可跳过安全过滤”。

结论：安全类规则一旦写进 CLAUDE.md，非常难被覆盖。这类规则应该慎重写入，要么只写“默认要求”并明确指出可豁免的场景，否则会导致过度防御。

场景四：CLAUDE.md 规则和模型自身编码风格冲突

设定： CLAUDE.md 要求“所有导出使用命名导出”。Claude 的训练数据中有大量使用 export default 的代码示例。

Claude 的实际行为： 这是一个有趣的现象。在 20 次测试中，Claude 遵循“命名导出”规则的比例是 85%，但剩余的 15% 仍然会不自觉地生成 export default，尤其是当它在模仿一些经典 React 模式（比如 export default function App）时。

结论：模型训练数据中的强模式（idioms）会对抗 CLAUDE.md 的约束。对于这类“反惯例”的规则，需要在多个地方反复强调（比如在 task prompt 里也提一句），而不能只依赖 CLAUDE.md。

八、性能与体验的平衡：CLAUDE.md 不该超过多少行

这是一个在技术讨论中很少被提及但实践中极其重要的问题。

CLAUDE.md 的内容会在每次对话开始时作为系统指令加载进上下文窗口。Claude Code 的上下文窗口虽然很大（200K tokens），但前面的系统指令会持续占据窗口的一部分，压缩留给后续对话和代码生成的空间。

我做过一次不太严谨但很有参考价值的负载测试。在同一个 Next.js 项目中，我分别用 3 个版本的 CLAUDE.md 来做相同的 5 个编码任务：

结论很清晰：CLAUDE.md 应该控制在 1500 tokens 以内。 超过这个阈值，不仅首响应变慢，更重要的是长对话后期会出现明显的“规则遗忘”，Claude 在处理复杂的后续任务时，逐渐忽视了系统指令中的约束。

我现在的标准做法是：CLAUDE.md 的“编码约束”部分控制在 600-800 tokens，剩下的 tokens 留给项目背景、技术栈说明和常用命令。

另一个容易被忽略的性能问题是 CLAUDE.md 中的“废话”。我在 review 团队成员的配置文件时经常看到这样的内容：

# 这些是无效的，Claude 不会因此“更重视”
我们非常非常非常重视代码质量，请务必务必务必遵守以上规则...

请用最优雅、最高质量的方式来编写这段代码...

这种重复强调不仅浪费 tokens，而且在我的测试中没有提升规则遵循率。Claude 不通过“重复的次数”来判断指令的重要性，它通过措辞的明确性和结构性来判断。用 [P0]、[P1] 标注优先级，远比写三遍“非常非常重要”有效。

九、多文件项目中的规则传播困境

CLAUDE.md 的另一个隐藏问题是：Claude Code 在生成单个文件时，并不总是能访问到整个项目的上下文，这意味着某些需要跨文件感知的规则会失效。

我遇到的具体案例：CLAUDE.md 里有一条“所有 Prisma 查询必须抽到 services/ 目录”。当我在对话中让 Claude Code “在 UserTable 组件中加一个搜索功能，根据用户名模糊查询”时，Claude 在 UserTable.tsx 文件里直接写了 import { prisma } from '@/lib/prisma' 和一段 prisma.user.findMany(...)。

这意味着它没有遵守“数据访问层分离”的规则。不是因为 CLAUDE.md 没加载这条规则，而是因为在单文件生成的上下文中，Claude 没有看到 services/ 目录的存在，它的大脑倾向于“在当前文件中完成所有事情”。

解决方案不是改 CLAUDE.md，而是改变 prompt 的方式。 正确的 prompt 应该是：

在 UserTable 组件中加搜索功能。先在 services/user.ts 中新增一个 searchUsers 函数封装 Prisma 查询，然后在组件中调用这个函数。

也就是说，你需要把架构约束“具象化”到具体的 task 中。 仅仅在 CLAUDE.md 里写“数据访问层分离”是不够的，Claude 在执行具体任务时，需要你明确告诉它“去哪个文件写 Service 层”。这就像一个有经验的 Tech Lead 不会只甩给新人一份编码规范，然后说“照着写”，而是会具体到“你去 services/ 目录下新建一个文件，把查询逻辑放进去”。

这个发现很重要：CLAUDE.md 的规则是“防御层”，不是“执行层”。 真正让规则落地的，是你在每次 task prompt 中结合当前上下文给出的具体指令。

十、和 ESLint/Prettier 的“双轨制”协作

经过了这么多踩坑，我最终稳定的配置策略是“双轨制”：

轨道一：CLAUDE.md ， 编码意图层（生成时约束）

负责那些“需要 AI 理解语义”的规则：

• 架构分层
• 错误处理模式
• 类型安全偏好
• 命名约定
• 禁止特定危险 API

轨道二：ESLint + Prettier + TypeScript ， 代码检查层（生成后验证）

负责那些“需要精确解析和检查”的规则：

• 格式化（Prettier）
• 未使用变量/导入（ESLint）
• 导入排序（ESLint import/order）
• 精确的类型检查（TypeScript strict）
• 安全规则（eslint-plugin-security）

两个轨道在 CI/CD 流程中的位置也不同：

开发者通过 Claude Code + CLAUDE.md 生成代码
↓

代码提交到本地分支

↓

pre-commit hook: Prettier 自动格式化 + ESLint --fix 自动修复

↓

如果有 ESLint 无法自动修复的 error → 阻止提交，反馈给开发者

↓

提交成功 → 推送到远程

↓

CI 流程: TypeScript 编译检查 + ESLint 全量检查 + 测试

↓

全部通过 → 允许合并

这个流程在团队里跑了两个月，把 AI 生成代码导致的“代码风格类 Review Comment”从每周约 25 条降到了 3-4 条，节省下来的 Review 时间被重新分配到了逻辑正确性和架构合理性上。

值得一提的是 ESLint 的 --fix 和 CLAUDE.md 之间的协同效应。有些规则两者都在管，比如“命名导出 vs 默认导出”。当我配置中的 ESLint 规则 import/no-default-export 和 CLAUDE.md 的“禁止默认导出”重叠时，Claude Code 遵守的概率从单用 CLAUDE.md 时的 85% 提升到了约 97%。我推测这是因为 Claude 在训练数据中学到了“这个项目启用了禁止默认导出的 ESLint 规则”，而这条信息进一步增强了它的遵循意愿。 当然，这个推测还需要更多测试来验证。

十一、团队落地的实操建议：如何让其他人也愿意用

技术方案再完美，如果团队不用，等于零。我在推动这套配置落地的过程中，发现了几个非技术但极其关键的经验。

不要一开始就塞 15 条规则

我第一次在团队里推 CLAUDE.md 时，写了一份“完美版”，涵盖了 17 条规则。结果其他两个前端开发试用了一天就反馈：“Claude 写出来的代码太死板了，感觉像被绑住了手脚。”

后来我换了策略：先从 3 条最痛的规则开始。 我选的是：

1. 'use client' 指令（解决团队成员最频繁的报错）
2. 禁止 any（解决类型系统虚设的问题）
3. 异步函数必须有错误处理（解决线上反复出现的未捕获 Promise 错误）

就这 3 条，推行阻力几乎为零。跑了一周后，大家都看到了效果（'use client' 相关的报错减少了 90%），然后我再逐步加规则，每次加 2-3 条，让大家先适应再迭代。

给规则写“为什么”而不只是“是什么”

CLAUDE.md 虽然是给 AI 看的，但给人看的部分同样重要，尤其是对不熟悉 Lint 文化的开发者。

我的 CLAUDE.md 现在每条规则后会跟一句“为什么”：

### 禁止默认导出

规则：所有模块使用命名导出，禁止 export default

为什么：命名导出让 IDE 的自动导入和重构工具能精确追踪引用，避免默认导出造成的“导入名称不一致”问题

这个“为什么”对 AI 有没有用我不敢确定，但对团队成员理解规则价值、愿意遵守规则，起到了关键作用。一个开发者在 review 这份文件后跟我说：“以前我觉得命名导出很麻烦，现在理解了，愿意遵守。”

允许“摘口罩”的场景

绝对化的规则会激起抵触。我在 CLAUDE.md 里明确写了：

以下情况允许关闭 ESLint 规则检查（使用 eslint-disable 注释），但需要说明原因：

• 必要的 any 类型断言，配合注释说明
• 第三方库缺陷导致的规则误报
• 性能关键路径的特殊处理

这种“给了出口”的设计，让那些担心被规则束缚的开发者更容易接受。实际统计下来，团队里 eslint-disable 的使用频率在引入 CLAUDE.md 后反而下降了，因为大部分问题在生成阶段就被解决了，不需要事后 disable。

十二、持续迭代：怎么知道你的配置在“老化”

配置不是写完就结案了。我在维护 CLAUDE.md 的过程中总结了一套“配置衰退信号”的识别方法。当出现以下迹象时，说明你的规则需要更新：

我在每个月的第一周会专门 review 一次 CLAUDE.md，对照上面这个检查表逐条过。平均下来，每个月会调整 1-2 条规则的表述或优先级。这种维护频率很低但持续，三个月下来，CLAUDE.md 从最初的 17 条臃肿规则，精简到了现在的 13 条精炼规则，整体 token 消耗反而下降了 40%。

十三、未来演进：当 AI 编码工具原生支持 Lint 时，这些规则还有用吗

我在写这篇文章的过程中，也一直在思考一个更长远的问题：如果 Anthropic 或 JetBrains 未来在 AI 编码工具中直接原生集成了 Lint 检查（比如生成代码后自动跑一遍 ESLint，然后根据结果自动修复），那我这篇文章里讲的这套“手动配 CLAUDE.md”的方法是不是就过时了？

我的判断是：不会过时，但角色会变。

原生 Lint 集成解决的是“事后检查”的效率问题，AI 生成代码后自己跑一遍 Linter，然后自己改。这件事即使是现在，优秀的开发者已经可以通过脚本自动化了（比如我在用的 pre-commit hook 方案）。

但 CLAUDE.md 的规则配置解决的是另一个问题：定义什么是“好代码”的标准。 这个标准不是 ESLint 的哪一个规则配置能完全表达的，它包含了架构偏好、团队的工程哲学、特定领域的编码惯例。

举个例子：一个金融系统的编码规范里可能有“所有金额计算必须使用 decimal 类型，禁止使用浮点数”。这是 ESLint 永远不可能检查出来的，这是一个业务约束，不是语法约束。但把它写进 CLAUDE.md，Claude Code 就能在生成代码时遵守。

所以 CLAUDE.md 里的规则会从“代码风格约束”逐步进化为“工程哲学和业务约束的声明”。 格式化、命名、导入排序这些交给工具解决；架构分层、错误处理策略、领域建模偏好这些，永远需要人类定义并注入给 AI。

十四、总结：不止是配置，是一套和 AI 协作的语言

写到这里，我想回到文章开头那个“if (status === 3)”的故事。

我在后来的 CLAUDE.md 里加了一条规则：“代码中出现的数字字面量，如果其含义不直观（如状态码、业务阈值、配置参数），必须提取为有意义的命名常量。”

Claude Code 之后生成的代码变成了：

const USER_STATUS_BANNED = 3;
if (status === USER_STATUS_BANNED) {

// ...

}

这行代码对人的意义不需要多说了。但更让我触动的是，当我把这条规则从 CLAUDE.md 里删掉（做个测试），Claude Code 在接下来的任务中，依然保持了“提取魔法数字为常量”的习惯，尽管它不再是一条硬约束。

这说明那段时间的约束不只是改变了 AI 的单次输出，而是在一定程度上“训练”了它的编码直觉。

这件事让我重新理解了“在 Claude Code 中配置 Lint 规则”这件事的本质。它不是在安装一个插件，不是在运行一个检查器。它是在用一种结构化的语言，持续地向你的 AI 搭档传递“在我们这个项目里，什么样的代码是好的”。

这份语言，就是 CLAUDE.md。它会随着项目演进、随着团队的成熟度提升而不断迭代。它不是一成不变的配置文件，它是一份活的、关于代码价值观的文档。

现在就去你的项目根目录，创建一个 CLAUDE.md。先从 3 条最让你抓狂的规则开始。一周后，加上另外 3 条。你会发现，你花在 Code Review 上的时间开始变少，花在真正的技术决策上的时间开始变多。而你每一次看到 AI 自动生成出符合你们团队标准的高质量代码时，都会感谢自己花在配置这份“代码宪法”上的那几个小时。