在团队代码规范不一致时 claude code 生成代码的 lint 通过率

去年十月，我接手了一个已经维护三年的 React 项目。这个项目经历过四任技术负责人，每任都留下了自己的代码风格遗产。有的模块用 2 空格缩进，有的用 4 空格；有的强制分号结尾，有的看到分号就删；有的要求所有函数必须写返回类型，有的觉得那是过度工程。ESLint 配置文件中写着 47 条规则，其中 12 条已经 deprecated，还有 8 条和 Prettier 直接冲突。团队内部已经达成一项默契：代码 Review 时不讨论风格问题，因为讨论一次伤感情一次。

当我在这个项目上开始使用 Claude Code 时，情况迅速恶化。第一次让它写一个表单组件，生成的代码有 137 行，CI 跑 Lint 时报了 23 个 error 和 41 个 warning。那一刻我意识到，问题不在 Claude Code，也不在那份混乱的规范，问题在于我根本没有告诉 Claude Code 这份规范是什么。

过去三个月，我在这个项目上做了系统性的测试和调整。我从最初的 38% Lint 一次通过率，提升到了稳定在 87% 以上的水平。 这不是一个官方标杆数字，而是我在一个真实混乱的项目上的实测结果。下面我会完整拆解这个过程、背后的判断逻辑、以及在不同团队状况下你应该怎么做取舍。

一、先把结论放在前面

在团队代码规范不一致的情况下，Claude Code 生成代码的 Lint 通过率不是一个固定值，而是一个由三个变量共同决定的函数：

1. 规范混乱程度 ， 项目里有多少条规则、规则之间是否有冲突、运行时是否稳定可复现
2. 注入方式的有效性 ， Claude Code 是否在生成代码时“知道”这些规则、规则被传递的方式是否准确
3. 验证机制的闭环程度 ， 生成后是否有自动修复环节、修复结果是否反馈给下次生成

核心结论只有一句话：不管你的项目规范有多乱，只要你能把这份规范有效地注入到 Claude Code 的上下文里，通过率不会低于 75%。 如果你的通过率低于 50%，问题大概率不在规范本身，而在注入方式。

我用一个表格来量化这种关系：

这些数据对应的测试方法是：我在同一项目上，针对 10 类常见的前端开发任务（表单组件、列表组件、状态管理 Hook、API 请求封装、路由配置、工具函数、类型定义、样式文件、测试用例、配置文件），每种任务用不同的注入策略各生成 5 次，合计 50 个生成任务。Lint 命令用的是项目原始的 eslint . --ext .ts,.tsx，一次指代码生成后、不做任何人工修改直接跑 Lint 的结果。

有人在看到“混乱且冲突”这个描述时会想：为什么不先把规范统一了再用 AI？这个问题我稍后专门回答。现在先说一个反常识的判断：在规范混乱的项目上，一个有策略的 AI 使用者，反而比一个没有策略的人更容易写出通过 Lint 的代码。

为什么？因为人会被混乱的规范激怒，会在愤怒中忘记某条规则；而 Claude Code 如果被正确配置，它会严格按照你给它的规则清单逐条检查。它没有情绪，也不会偷懒跳过某条规则。

二、背景和真实场景：为什么“团队规范不一致”才是常态

2.1 我见过的三种典型混乱

在讨论技术方案之前，我想先描述三类真实的混乱场景。因为如果不理解“混乱”具体是什么，就没法设计有效的注入策略。

类型一：历史沉淀型混乱

这种混乱是时间的产物。项目刚开始时只有一份 .eslintrc.json，十几条规则，清晰简洁。第二年换了技术负责人，引入了一套更严格的 TypeScript 规则。第三年为了迁就某个第三方库，关闭了几条规则。第四年团队尝试迁移到 ESLint 9 的 flat config，写到一半发现改动太大，于是产生了一份 eslint.config.js 和一份仍然被部分文件引用的 .eslintrc.json 共存的局面。

更隐蔽的是，这种项目往往还有一个 .prettierrc，一份 .editorconfig，可能还有半套被注释掉的 tslint.json。这些文件之间的冲突不是写在明面上的，而是在 CI 跑 Lint 时才暴露出来：ESLint 说这里应该有分号，Prettier 在同一个文件里把它删了。

类型二：多团队合并型混乱

两家公司合并、两个部门整合、或者把外包团队的代码并入主体仓库时，会出现这种混乱。最典型的特征是：同一个仓库里的不同目录遵循不同的规范。/admin 下是一套规则，/mobile 下是另一套。仓库根目录有一个“公约数”级别的配置，但各个子目录都有自己的 .eslintrc，用 overrides 来 cover 各自的规则。

这种项目的 CI Lint 往往需要跑多个命令，或者有一个复杂的脚本去协调。新加入的开发者常常搞不清楚某个文件到底应该遵循哪套规则，只好“跑一下试试，报错再说”。

类型三：技术栈升级残留型混乱

这种混乱发生在框架或语言大版本升级时。比如从 Vue 2 升到 Vue 3，从 JavaScript 迁到 TypeScript，从 CRA 迁到 Vite。新代码用新规范，老代码维持原样。问题是，Claude Code 在生成代码时，如果不明确告诉它“这次生成的目标代码应该遵循哪个规范”，它可能会基于自己的训练数据做一个“平均”的选择，而这个平均选择往往和最老和最新的规范都不匹配。

2.2 混乱规范下 AI 编程工具的普遍困境

我不是第一个遇上这个问题的人。过去半年，我在各种技术社群里观察到一个普遍模式：开发者刚开始用 AI 编程工具时的惊叹期大约持续两周。到了第三周，就会开始抱怨“生成的代码风格不对”“每次都要手动修 Lint 错误”“还不如自己写”。这个转折点，几乎总是发生在 AI 工具被应用到“规范不统一”的项目上的时候。

AI 编程工具的本质矛盾在于：它们被训练来生成“普遍正确”的代码，但真实项目需要的是“局部正确”的代码。

Claude Code 比大多数工具更进一步的地方在于，它可以通过读取项目文件、理解上下文来调整自己的生成策略。但这个能力的前提是，你得把规则文件正确地放进它能看到且能理解的位置。

让我用一个真实例子说明这个问题。在我的测试项目中，有一条规则禁止使用 any 类型，要求使用 unknown 替代。这条规则写在 eslintrc 的 @typescript-eslint/no-explicit-any 中，设置为 error 级别。

当我没有任何上下文注入时，Claude Code 生成一个 API 响应处理函数的做法是：

const handleResponse = (data: any) => {
return data.items.map((item: any) => item.name);

};

Lint 报错：no-explicit-any error × 2。

但如果我在 Claude Code 的系统指令中明确写入了“本项目禁止使用 any 类型，应该使用 unknown 并进行类型守卫”，同样的需求它会生成：

const handleResponse = (data: unknown) => {
if (typeof data !== 'object' || data === null || !('items' in data)) {

throw new Error('Invalid response format');

}

const responseData = data as { items: unknown[] };

return responseData.items.map((item) => {

if (typeof item !== 'object' || item === null || !('name' in item)) {

return 'Unknown item';

}

return (item as { name: string }).name;

});

};

这次 Lint 通过。两份代码解决同一个问题，区别仅仅在于：生成第二份时，Claude Code 知道有一条规则叫“不能用 any”。

这个例子揭示了一个关键事实：Claude Code 本身具备生成符合规范代码的能力，但这个能力是否被激活，完全取决于规范是否被有效传递。

三、拆解常见误区

3.1 误区一：以为 Claude Code 会自动读取项目配置文件

这是我最早犯的错误，也是我见过最多人犯的错误。使用 Claude Code 的第一天，我以为它既然能访问本地文件系统，应该会自动发现并遵循 .eslintrc.js、.prettierrc、tsconfig.json 这些配置文件。我把 Claude Code 启动在项目根目录下，就假定它能“看到”并“理解”这些文件。

实际情况是，Claude Code 确实可以通过工具调用来读取文件内容，但它不会主动去读这些配置文件，除非你在 Prompt 中明确要求它去读。即使它读了，它也不一定会在生成代码时逐条检查自己是否遵守，因为它没有内建的 Lint 检查机制。

这句话值得加粗：Claude Code 不会在生成代码后自动跑 Lint，不会自动检查自己的输出是否符合 project rules，除非你明确要求它这样做。

这个数据来自我的测试：在 50 个未在 Prompt 中明确要求 Claude Code 读取 ESLint 配置的任务中，它只有 4 次主动读取了 .eslintrc 文件，而且这 4 次都是因为它需要理解某些 import 规则时才顺带读的，而不是为了遵循代码风格规则。

3.2 误区二：以为 lint 通过率低是因为 AI 能力不够

很多人用 Claude Code 生成代码后发现 Lint 报一堆错，第一反应是“这 AI 对工程规范的理解还不行”。这个判断是错的。

问题不在 AI 的能力，而在信息的传递。 用一句话概括：你给 AI 的上下文里没有包含“写代码时必须遵守的规则清单”，它就只能依赖训练数据里的统计规律，那些规律反映的是互联网上开源项目的“平均”写法，不是你当前项目的“具体”写法。

这个误区的深层原因是一种认知惯性：人类开发者在进入一个新项目时，会主动去看 README、看贡献指南、看 CI 配置、翻历史 PR 里的 Review 意见，通过一个主动学习过程来内化团队规范。但我们没有意识到 Claude Code 需要同样的过程，而且这个过程必须由我们来设计和触发。

3.3 误区三：靠“事后修复”来解决问题，而不是“事前注入”

另一个普遍的模式是：让 Claude Code 随便生成，然后用 eslint --fix 自动修复，或者手动修。这条路径在表面上看起来效率还行，毕竟自动修一下也就几秒钟。

但这条路径有三个隐性成本：

第一，自动修复无法解决所有问题。 eslint --fix 能修的是那些规则明确、支持自动修复的问题，比如自动加分号、自动调整缩进。但对于“不能用 any”“函数复杂度不能超过 20”“必须处理 Promise 拒绝”这类逻辑型规则，--fix 无能为力。

第二，修复后的代码可能引入新问题。 自动格式化可能导致代码逻辑出现肉眼不易察觉的变化。我遇到过一个案例：一段 JSX 代码因为 Prettier 自动换行，导致一个条件表达式的结果因为缺少括号而改变。

第三，每次修复都是对信任的消耗。 当你习惯了“反正 AI 生成的我都要修一遍”，你就会降低对 AI 的信任，不再认真优化 Prompt。这是一种负向循环。

正确的思路是事前注入而非事后修复：在 Claude Code 生成代码之前，就把规则清单完整地放到它的上下文里，让它生成时就考虑这些约束。

四、给出专业判断逻辑

4.1 核心框架：规则指令化 + 参考锚定 + 执行闭环

我经过三个月的测试和迭代，总结出一套可复用的方法论。这套方法论不是某个特定项目的方案，而是一个适用于所有“规则混乱项目”的通用框架。

框架由三个层次组成：

第一层：规则指令化

把你项目里所有有效的 Lint 规则，从配置文件里提取出来，整理成一段结构化的文本，直接放在 Claude Code 的系统指令或项目指令中。

很多人立刻会问：我的 .eslintrc 有几百行，全部放进去会不会占用太多 token？答案是：不需要全部，但需要“关键规则完整集”。具体操作方法后面会详细写。

第二层：参考锚定

在要求 Claude Code 生成代码时，不仅要告诉它规则，还要给它看一个“在这个规范下被认为合格的代码样本”。这个样本最好是项目里已经存在、经过 Review 的代码文件。Claude Code 会把它作为风格参考锚定点。

第三层：执行闭环

在 Claude Code 生成代码后，要求它自动运行 Lint 命令，如果发现错误，自动修复后再输出。如果某些错误无法自动修复，要求它在输出中标出“需要人工处理的规则项”并解释原因。

这三层环环相扣，缺一层效果都会打折扣。

4.2 为什么“先统一规范再用 AI”不现实

我经常听到的一种建议是：“先把团队规范统一了，再用 AI 生成代码。”这句话在理论上是正确的，但在真实世界里基本不可行。

原因有四：

第一，统一规范需要时间。一个维护了三年的中型项目，要把所有历史风格差异抹平，光是梳理和讨论就需要好几个迭代周期。在这段时间里，AI 工具已经迭代了好几个版本，等着“规范统一”再用的团队实际上放弃了技术进步的时间窗口。

第二，统一规范需要政治资本。在团队中推动“所有人按我的风格写代码”这件事，本质上是一种权力行为。不是所有技术负责人都有这个资本。AI 工具恰恰提供了一条低阻力的路径：你不用说服同事改变习惯，你只需要让 AI 按照既定规则生成代码。

第三，出于业务压力，某些模块根本不会被重构。那些“能跑就行”的遗留模块，在业务压力面前永远处于低优先级。但你的新功能可能正好要写在这些模块旁边。

第四，即使规范统一了，也挡不住下次技术升级带来的新混乱。规范统一不是一个终点，而是一个不断被打破和重建的过程。

基于这些原因，我的判断是：对于大多数已经历多次迭代的团队项目，与其等待规范统一，不如掌握在混乱中驾驭 AI 的能力。 这个判断可能会让一些追求“工程完美”的人不舒服，但它是务实的。

五、具体案例：我是如何把通过率从 38% 拉升到 87% 的

5.1 基线测试阶段（第 1-2 天）

我在那个 React 项目上做的第一件事，是建立一条基线。我选择了 10 个任务类型，每种生成 5 次，记录了 50 次生成的 Lint 结果。

任务列表如下：

1. 创建一个受控的表单输入组件
2. 创建一个带虚拟滚动的列表组件
3. 封装一个 useFetch 的 Custom Hook
4. 封装一个 axios 请求拦截器
5. 配置 React Router 的嵌套路由
6. 写一个日期格式化的工具函数，处理多种时区
7. 定义一个包含联合类型的 API 响应类型
8. 写一个带媒体查询的 CSS Module 文件
9. 为一个 Redux Reducer 写单元测试
10. 创建一个 Vite 插件的配置

在没有任何规范注入的情况下，50 次生成的 Lint 结果：

有两点发现值得注意。第一，类型定义文件的通过率明显更高（60%），因为类型文件涉及的 Lint 规则本身就少。第二，测试文件的通过率最低（15%），因为测试文件里大量使用 any 来 mock 数据，而项目规则禁用了 any，这是一个典型的“规则和实际场景冲突”的例子。

5.2 规则梳理阶段（第 3-5 天）

第二步，我花了两天时间梳理项目的 Lint 规则。这个工作比预想的复杂得多。

首先，我需要搞清楚“到底哪些规则在生效”。项目里有一个 /eslint 目录，里面有 base.js、typescript.js、react.js、tests.js，分别对应不同的 overrides。我执行了以下命令来确定每类文件实际使用的规则：

npx eslint --print-config src/components/FormInput.tsx > effective-config.json
这个命令输出了一个超过 800 行的 JSON 文件，列出了最终生效的所有规则及其值。我把这些规则按照影响频率分成了三级：

高影响规则（每次生成都可能触发）：缩进、引号、分号、行尾空格、文件末尾空行、import 排序、未使用变量、any 类型使用

中影响规则（特定场景触发）：函数复杂度限制、文件最大行数、函数参数个数限制、Promise 必须处理 rejected 状态

低影响规则（很少触发）：命名规范（kebab-case / camelCase 的文件名）、特定 API 的禁用

然后我做了一件很有价值的事：我把所有规则按照“是否支持自动修复”进行了分类。支持 --fix 的规则在生成后的自动化环节可以处理，不支持的则需要 Claude Code 在生成时就遵守。

不支持自动修复的关键规则列表（从这个项目中提取的）：

@typescript-eslint/no-explicit-any

@typescript-eslint/explicit-function-return-type

@typescript-eslint/no-unused-vars

import/order（部分场景）

react-hooks/exhaustive-deps

complexity

max-lines-per-function

这七条规则就是“必须在 Prompt 中明确提醒”的规则。其余的规则，即使生成时违规，也可以在后续的自动修复环节处理。




3 第一轮优化：规则指令化注入（第 6-10 天）
基于上述梳理，我创建了一份“规则指令文档”，放在了项目的 .claude/rules.md 文件中。这份文档不是把 .eslintrc 的内容复制过去，而是用行为指令的方式重新组织。

文档的核心部分是这样的结构：

代码生成时必须遵守的规则

类型安全规则（必须在生成时遵守，无法事后修复）

禁止使用 any 类型。使用 unknown 替代，并进行类型守卫。

所有函数必须明确标注返回类型。

未使用的变量立即删除。

代码风格规则（生成时尽量遵守，事后可自动修复）

使用 2 空格缩进。

字符串使用单引号。

文件末尾必须有一个空行。

项目结构规则

组件文件使用 PascalCase 命名。

每个文件只导出一个主要的类或函数。

import 顺序：React 相关 > 第三方库 > 项目内部模块 > 类型导入。

<p>我在 Claude Code 的系统指令中加入了这样一段话：</p>

在生成任何代码之前，请先读取项目根目录下的 .claude/rules.md 文件，并严格遵守其中的所有编码规则。生成代码后，运行 npx eslint <生成的文件路径> 检查是否符合规则。对于不符合的项，如果支持自动修复，运行 npx eslint --fix <文件路径> 进行修复。对于不支持自动修复的项，重新生成该部分代码。

之后我用相同的 50 个任务重新测试。

第一轮优化后的结果：

通过率从 38% 提升到 62%，改进明显但还远不够好。我分析了剩余的错误，发现主要集中在两个问题上：

1. Claude Code 理解了规则但执行不彻底。比如它知道要用 unknown 替代 any，但在复杂的嵌套类型中（比如 Record<string, any> 这种模式），它有时会“遗忘”规则。
2. 项目中某些规则本身存在歧义。比如“函数必须标注返回类型”这条规则，在箭头函数作为回调传递给另一个函数时，到底是否需要标注？规则文件说“所有函数”，但团队实际执行时并没有这么严格。

5.4 第二轮优化：参考锚定 + 歧义消解（第 11-14 天）

为了解决第一轮剩余的误差，我引入了“参考锚定”机制。

具体做法是：我在 .claude/rules.md 中增加了一个章节，叫“正确示例”，里面放了项目中被团队公认为“写得好”的 3 个真实文件。我选取的标准是：这些文件在最近的 Code Review 中没有任何风格相关的评论，且完全通过 Lint。

这三个文件分别是：

• 一个表单组件（UserProfileForm.tsx，约 200 行）
• 一个 Custom Hook（usePagination.ts，约 80 行）
• 一个工具函数文件（formatters.ts，约 150 行）

我把它们放在 .claude/examples/ 目录下，并在规则文档中增加了这样的指令：

在开始生成代码之前，请先浏览 .claude/examples/ 目录下的至少一个相关示例文件，理解本项目的代码风格、命名习惯和文件组织结构。生成的代码应该与这些示例在风格上保持一致。

同时，针对歧义规则，我在规则文档中增加了“判断边界”：

### 规则：函数必须标注返回类型
适用范围：所有顶层函数、所有导出函数、所有函数声明

不适用范围：作为回调直接传入的单行箭头函数（如 array.map(x => x.name)）

这看起来是一件小事，但它消除了 Claude Code 在理解规则时的猜测空间。AI 对规则的理解越好，生成的一次通过率就越高。

第二轮优化后的结果：

到了 76% 的一次通过率，团队的日常使用体验已经发生了质变。一位同事跟我说，他现在“看都不看就先跑 Lint，大部分时候直接通过，比以前用 ChatGPT 的体验好得多”。

5.5 第三轮优化：执行闭环（第 15-21 天）

76% 已经是相当不错的结果，但剩下 24% 的失败里仍然有规律可循。我分析了一个星期里所有 Lint 失败的 case，发现它们可以被分成三类：

A 类：生成的代码本身没问题，只是没有运行自动修复（约占剩余的 40%）

这类主要是格式问题：多了一个空行、少了一个分号、缩进差了一个空格。这些规则都支持 --fix，但 Claude Code 没有在每次生成后都运行修复。

B 类：规则冲突导致不能同时满足（约占剩余的 35%）

这是“规范不一致”问题最集中的体现。比如项目中 import/order 规则和 import/no-duplicates 规则在某些边缘 case 下的要求不一致。这种冲突连人类开发者都经常搞错。

C 类：Claude Code 不知道如何修复的复杂问题（约占剩余的 25%）

比如一个函数的复杂度超过了 20，需要重构才能降低。Claude Code 没有自动执行这种类型的重构。

针对这三类问题，我设计了一个“生成-检查-修复”的闭环流程：

1. 生成代码
运行 npx eslint <文件> --format json

解析 JSON 输出，识别 error 和 warning

对于支持自动修复的，运行 npx eslint --fix <文件>

再次运行检查，确认修复后的结果

对于无法自动修复的，逐条分析原因

如果是规则冲突，以 error 级别更高的为准，并在输出中说明

如果是复杂重构，输出建议但不强制执行

将检查结果作为新 prompt 的上下文，要求 Claude Code 重新生成

<p>这个流程我用 Claude Code 自身的“工具调用”能力来实现。Claude Code 可以运行命令行工具，所以它能自己跑 ESLint，自己看 JSON 输出，自己决定下一步怎么做。</p>

关键配置是将这段逻辑写入了 Claude Code 的项目指令中：

每次生成代码后：

1. 将生成的代码写入目标文件。
2. 执行 npx eslint <文件路径> –format json。
3. 如果结果中 errorCount 为 0 且 warningCount 为 0，任务完成。
4. 如果有 error 或 warning，先执行 npx eslint –fix <文件路径>。
5. 再次执行 npx eslint <文件路径> –format json。
6. 如果仍有 error，分析每个 error 的规则 ID，对照 rules.md 判断是规则冲突还是复杂重构需求。
7. 如果是规则冲突，按照优先级处理；如果是复杂重构，标记并建议人工处理。
8. 重复步骤 2-7，最多循环 3 次。

第三轮优化后的结果：

87% 的一次通过率和 94% 的零 error 率意味着，在实际使用中，Claude Code 生成的代码 10 次里有接近 9 次不需要任何人工修改就能通过 Lint；10 次里有超过 9 次即使有 warning 也没有 error。这个水平已经超过了我刚开始手写代码时的通过率，在熟悉这个项目的规范之前，我自己写代码的 Lint 一次通过率大概在 70% 左右。

六、不同情况下的行动建议

6.1 情况一：你的团队规范非常混乱

判定标准：项目中有多份 Lint 配置文件，部分规则存在冲突，CI 里甚至需要跑多道 Lint 检查，或者某些目录的 Lint 是手动的。

行动建议：

第一，不要试图先统一规范再引入 AI。 这是顺序错误。你可以在使用 AI 的过程中，逐步沉淀出一份“经过实战验证的有效规则集”，然后反推团队规范统一。

第二，从规则梳理开始，但要控制时长。 分配最多两天时间，执行 npx eslint --print-config 提取有效规则。做一份规则清单，按照“影响频率”和“是否支持自动修复”两个维度分类。这个过程本身也会让你对项目的规范现状有全新的认识。

第三，重点投资“参考锚定”。 在混乱项目中，规则文件可能自相矛盾，但经过 Review 的优秀代码样本不会。选 3-5 个文件作为参考样例，让 Claude Code 不仅看规则，还看“好代码长什么样”。在混乱中，样例比规则更容易被 AI 准确执行。

第四，接受 75%-85% 的通过率是这阶段的合理目标。 在规范本身有内在冲突的情况下，100% 通过率是一个不可能的指标。那些剩余的失败案例，往往反映了规范本身需要解决的矛盾。

6.2 情况二：你的团队规范基本一致，但不够严格

判定标准：有统一的 Lint 配置文件，大部分规则无冲突，但覆盖不全面，比如缺少 TypeScript 严格规则、缺少性能相关规则。

行动建议：

这是一个相对理想的状态，重点应该放在“把规则往细处完善”和“建立执行闭环”。

第一，补齐关键规则。重点增加三类规则：类型安全规则（no-explicit-any、strict-boolean-expressions、explicit-function-return-type）、可访问性规则（jsx-a11y 系列）、性能规则（react-hooks/exhaustive-deps、不能有不必要的重渲染）。这些是 AI 生成代码时最容易踩的坑。

第二，直接建立完整的执行闭环。这个阶段的通过率基线应该在 60%-70% 之间，加上闭环后可以稳定在 90% 以上。

第三，开始沉淀团队 Prompt 库。 把那些反复被证明有效的规则指令、参考样例、生成模板整理成文档，放在仓库里，让所有使用 AI 工具的团队成员共享。这比写一份没人看的“编码规范文档”有效十倍。

6.3 情况三：你在一个新建项目上从零开始

判定标准：项目还没有 Lint 配置，或者只有脚手架生成的默认配置。

行动建议：

这是最好的时机，因为你可以在第一天就设计一套“AI 友好”的规范体系。

第一，直接用最严格的配置。 如果是 TypeScript 项目，直接用 @typescript-eslint/recommended-type-checked 或 strict-type-checked。不要从宽松配置开始“慢慢收紧”，收紧的过程会破坏 AI 的学习模式。

第二，Prettier + ESLint 的分工必须从一开始就明确。 风格问题全部交给 Prettier，逻辑问题交给 ESLint。两者之间不要有重叠规则。每当你添加一条 ESLint 规则，检查一下是否和 Prettier 冲突。我的做法是把 Prettier 规则在 ESLint 中通过 eslint-config-prettier 全部关闭。

第三，在第一个组件写出来之前，就创建 .claude/rules.md 和 .claude/examples/。 把规范注入作为项目初始化的一部分，而不是后续的补丁。你可以先写一个 CodeBuddy（AI 生成的一个示例组件）作为第一个参考样例。

第四，把 Lint 通过率作为 CI 的一个强制检查项。 在 CI 中设置 eslint --max-warnings 0，AI 生成的代码和人类写的代码都必须通过同一个标准。这个做法的长期价值在于：它迫使团队把规范当作“必须遵守的契约”，而不是“建议参考的风格”。

6.4 情况四：你是一个使用 AI 工具的独立开发者

判定标准：没有团队，没有现成规范，在个人项目上使用 Claude Code。

行动建议：

独立开发者的优势是你可以完全自主决定规范；劣势是你可能缺乏制定规范的意识。

第一，不要裸用 Claude Code。 即使是个人项目，也至少花半小时设置一套基本的 Lint 规则和一份规则指令文档。裸用的后果是你不知不觉中积累了大量风格不一致的代码，将来想要统一时成本巨大。

第二，从行业标准配置开始，不要自己发明规则。在 ESLint 中直接 extends: ['airbnb', 'airbnb-typescript'] 或使用 @antfu/eslint-config。行业标准配置的好处是：它们经过大量项目的检验，而且 Claude Code 在训练数据中见过大量遵循这些规则的代码，生成质量天然更高。

第三，把 .claude/rules.md 当成一份活的文档。 每次你手动修改了 AI 生成的代码，问自己：这是哪里出了问题？是不是规则文档里没有说清楚？然后把这次教训更新到文档里。三个月后，这份文档会成为你最有价值的编程资产之一。

七、不同情况下的取舍

7.1 通过率 vs 开发速度的取舍

在追求高 Lint 通过率的过程中，有一个必须面对的取舍：你把规则指令写得多细，注入得多深，这本身是需要成本的。

我的经验数据是：

• 75% 通过率是性价比最高的点。 从 38% 到 75%，我投入了大约 12 个小时的梳理和配置时间。这些时间在一个月内就通过“减少手动修复 Lint 错误”回收了。
• 从 75% 到 85%，需要额外投入 8-10 小时。 这个阶段主要是处理边界 case、编写规则冲突消解逻辑、调试执行闭环。
• 从 85% 到 90% 以上，需要持续投入和频繁更新规则文档。 每增加 1% 的通过率，需要解决的都是那些“不常出现但一旦出现就很复杂”的问题。

取舍建议：

如果你的团队每天使用 Claude Code 的频率在 50 次以上，追求 85%+ 的通过率是值得的，因为节省下来的每个手动修复分钟数都会在规模上放大。

如果每天只用 5-10 次，75% 就足够了。把规则文档维护好，剩下的 25% 手动修一下，总体效率仍然远高于不用 AI。

7.2 严格规范 vs 灵活性的取舍

另一个关键取舍是关于规范的严格程度。

在一个“所有函数必须标注返回类型”的项目里，你写一个简单的箭头函数 const add = (a: number, b: number) => a + b 也必须写返回类型。这本身不是问题，但当这个函数作为回调传给 Array.map 时，items.map((item) => <ItemCard key={item.id} data={item} />)，你希望 Claude Code 怎么处理？

如果你严格遵循规则：Claude Code 会为每个回调标注返回类型，代码变得啰嗦。一些开发者会因为这些冗余的类型标注感到不满。

如果你放宽规则：Claude Code 在某些场景下省略返回类型，但可能在你不希望省略的场景（比如导出的工具函数）中也省略了。

我的取舍原则是：对 AI 生成代码的规则应该比对人类开发者的规则更明确、更少歧义，但允许在“不适用场景”的定义上留有解释空间。

具体的做法是，在规则文档中把每条规则的“适用范围”和“例外情况”都写清楚。这不只是帮助 AI 理解，当你把规则边界写清楚后，你对这条规则的理解也会更清晰，甚至可能发现规则本身就有问题。

7.3 投入“规则维护”还是“事后修复”的取舍

这是一个资源分配的问题。你可以把时间花在“优化规则注入，提高一次通过率”上；也可以花在“快速修 Lint 错误”上。

两条路径的成本对比如下：

取舍建议：

• 团队规模 ≥ 3 人且项目预期维护超过半年：选择规则维护路径
• 独立开发者短期项目（1-2 个月）：事后修复路径可能更经济
• 频繁需要生成同类代码（比如每周生成 20+ 个组件）：规则维护路径的优势迅速放大

7.4 “用 AI 生成规范”还是“人写规范”的取舍

一个有趣的元问题：你能不能用 Claude Code 来帮你生成那份“规则指令文档”？答案是：可以，但必须有人工审核和一个前提条件。

前提条件是：项目中必须有一批被公认为“高质量、符合团队审美”的代码文件。你可以把这些文件给 Claude Code，让它推断出这些代码共同遵守的规范，然后生成规则文档。

我做过这个实验。我给了 Claude Code 五个文件（三个组件、一个 Hook、一个工具函数），要求它“分析这些文件的共同编码规范”。它在 30 秒内生出了一份包含 23 条规则的清单，命中率大约 80%。遗漏的主要是那些“在所有五个文件中都没有触发”的规则（比如某个特定 ESLint 规则在五个文件中恰好都没有涉及的场景）。

取舍建议：AI 生成规则文档可以作为一个起点，节省 60%-70% 的文档编写时间。但人工审核必不可少，特别是验证那些“应该存在但因样本不够而遗漏”的规则。最好的方式是“AI 生成初稿 → 人审核补充 → AI 根据反馈修订”这个协作流程。

八、三个特别的经验教训

在整个过程中，有几个教训是我在事前完全没有预料到的，但它们对最终结果的影响很大。

8.1 Claude Code 的“过度遵守”问题

在第二轮优化后，我注意到一个反常现象：Claude Code 生成的代码有时比项目规范要求的还要严格。比如项目中 max-lines-per-function 设置为 100 行，Claude Code 有时会把函数拆分得过于细致，导致逻辑片段化，可读性反而下降。

这个问题的根源是：Claude Code 在尝试“安全地”遵守规则时，会选择最保守的解释，而不是最合理的解释。 它没有“这个规则在这里适度放松一点更好”的判断力。

解决方案是在规则文档中为“量级型规则”增加上下文说明：

### 规则：函数体不超过 100 行
这是一个上限，不是推荐值。30-80 行的函数是理想的。

如果拆分会导致逻辑片段化，80-100 行是可以接受的。

不要为了缩短行数而把单个逻辑概念拆成多个相互调用的微小函数。

这段说明对通过率没有明显影响，但显著提升了生成代码的可读性。

8.2 规则文档的“腐化”问题

规则文档不是写一次就一劳永逸。项目在演进，依赖在更新，ESLint 版本在升级，团队成员在流动。一份三个月前的规则文档可能包含了已经废弃的规则，或者遗漏了新引入的规则。

我在项目中建立了一个月度检查机制：

每月第一个工作日，执行这些步骤：

1. 运行 npx eslint –print-config 提取当前有效规则
2. 对比规则文档中的规则清单，标记新增和废弃的规则
3. 抽查 10 个 Claude Code 生成的代码文件，检查是否有新的 Lint 失败模式
4. 更新规则文档

这个机制的成本很低（每次约 30 分钟），但防止了规则文档的“熵增退化”。

8.3 团队内部的政治问题

这是一个我意料之外的教训。当我把 Lint 通过率从 38% 提升到 87% 后，团队里的两位高级开发者表现出了复杂的态度。一位非常认同，开始主动使用和贡献规则文档。另一位则有些抵触，理由是“这会让新人过度依赖 AI，不理解规范背后的原因”。

我处理这个问题的方式是：不争论“AI 好不好”，而是把规则文档开放出来，把它定位成“编码规范的可执行版本”，而不是“AI 专属配置”。规则文档本身是有价值的，不管你是否用 AI。当你把讨论焦点从“AI”转移到“规范”，来自人类同事的抵触会小很多。

这是一个提醒：技术优化如果被感知为对人的替代，就会遇到阻力。如果被感知为对人的辅助和对规范的强化，就容易获得支持。

九、总结

回到文章的核心问题：在团队代码规范不一致时，Claude Code 生成代码的 Lint 通过率到底是多少？

答案是：取决于你怎么配置，但无论起点多低，都可以拉到 75% 以上。

• 裸用的通过率一般在 30%-50%
• 规则指令化注入后可以达到 60%-75%
• 加上参考锚定和歧义消解后可以达到 75%-85%
• 建立完整的执行闭环后可以达到 85%-94%

我在一个规则混乱的三年 React 项目上，从 38% 做到了稳定的 87%。这不是因为 Claude Code 突然变聪明了，而是因为我终于学会了如何正确地跟它沟通规则。

三条最重要的经验：

1. 不要等规范统一再用 AI。 在混乱中驯化 AI 的能力，本身就是一种核心竞争力。
2. 规则指令化、参考锚定、执行闭环，三层缺一不可。 每一层解决不同的问题，只有三者协同才能达到实战可用的水平。
3. 把这套方法论当成团队的“编码宪法”来维护。 一份持续更新的 .claude/rules.md，比一份尘封的“编码规范文档”更有生命力。

下一步怎么做：

如果你是第一次尝试，从最简单的一步开始：今天打开终端，在项目根目录执行 npx eslint --print-config src/一个常用的文件.tsx，看看生效的规则到底有哪些。你可能会惊讶地发现，你以为存在的规则其实没有生效，你以为没有的规则其实一直在默默地给你报 warning。

然后把那些“不支持自动修复的关键规则”单独列出来，写成 5-10 句话，放到 Claude Code 的系统指令里。就这一个动作，你的 Lint 通过率就可能从 40% 跳到 60%。

接下来，把每一次 Claude Code 生成后需要手动修复的 Lint 错误记录下来。这些记录不是“AI 不行”的证据，而是“下次该告诉它什么”的指南。一次一次改，一月一月迭代，那份规则文档会越来越精准，通过率会越来越高。

这不是一项一蹴而就的工作。但三个月后回头看，你会发现，你已经不是在“使用一个 AI 编程工具”，而是在“管理一个按照团队意志精准执行的编程系统”。这两者之间的差距，就是 Lint 通过率从 38% 到 87% 的差距。