做外包代码评审的那几年，我最怕接手的不是技术栈陌生的仓库，而是那种“每个人都有自己的编码规范”的仓库——同一个目录下三个文件三种缩进，工具函数命名从 camelCase 跳到 snake_case 再跳到拼音缩写，注释里写着“临时方案，勿动”，结果一放就是两年。这类仓库的维护成本，往往比技术债本身更贵。后来我开始系统性地研究 Coding-Standards 这一类开源规范项目：它们把散落在各种团队内部的编码约定，沉淀成一套公开、可讨论、可被工具执行的规范集合。这类项目本质上解决三件事——让代码风格不再靠口头约定、让评审焦点从“空格还是 Tab”回到“逻辑对不对”、让新人不用花两周时间去猜老代码的脾气。不管你是三五个人的小团队负责人，还是几十人协作的中间件维护者，甚至是刚入行、想提前养成好习惯的独立开发者，这套东西都值得认真过一遍。下面我按自己的实践路径，把一个编码规范项目从理解、拆解到真正跑起来的全过程拆开讲，包含配置、参数、踩坑和几处我至今仍在用的细节。
1. 项目整体设计与思路拆解
1.1 编码规范项目到底在解决什么问题
很多人第一次打开这类项目，看到一堆style-guide.md、rules/、configs/就以为它是一份“排版美观的说明书”。这个理解偏差会直接导致落地失败。文档类规范的通病是：写的时候很热闹，落地时没人看，三个月后它变成仓库深处一个没人更新的docs/目录。
我的判断标准很朴素——一个编码规范项目是否合格，看它能不能被机器执行。凡是只能靠人眼检查、靠评审人记忆的条目，长期看一定会失效。所以这类项目的真实结构通常是两条线并行：一条是自然语言写的约定（讲清“为什么这么定”），另一条是可直接安装的配置包、Lint 规则集、编辑器配置、钩子脚本。前者负责统一认知，后者负责统一结果。
再往深一层，它其实在解决协作中的三笔隐性成本。第一笔是沟通成本：两个人为了括号换行争十分钟，本质是缺少共同裁判。第二笔是切换成本：你在 A 项目写了半个月，回到 B 项目要重新加载一套完全不同的风格记忆，这个上下文切换是有代价的。第三笔是审查成本：评审者把注意力消耗在格式上，就必然会漏掉真正的逻辑缺陷和白名单之外的安全问题。规范项目的价值，就是把这三笔成本尽可能压到接近零。
理解了这一点，你就不会把规范当成“额外负担”，而是当成一种降低团队整体摩擦的基础设施。它的定位更像Dockerfile或者构建脚本，而不是 README 里的装饰。
1.2 为什么规范项目普遍采用“分层 + 分语言 + 分场景”的组织方式
成熟一点的规范项目，目录基本都长这样：顶层按语言或技术域分（前端、后端、移动端、脚本工具），中间层按“通用原则 / 语言特性 / 框架约定”分，底层落到具体可复制的配置文件。这种三层切法不是拍脑袋定的，而是对应了三种不同的变更频率。
通用的那部分极稳定：命名要能被读出语义、函数单一职责、避免魔法数字，这些十年不变。语言相关的部分中等稳定：某语言新版本引入了新的语法糖，规范可能要半年跟进一次。框架和工具相关的部分变化最快：构建工具换代、Lint 规则从旧配置格式迁到扁平配置，一年可能要动两三次。
把变更频率不同的内容放在同一层，会造成两种灾难：改一条工具规则要连带修改整篇通用文档，或者在通用原则里塞满了某个框架的细节，导致别的技术栈的人看了以为冒犯自己。分层之后，每层有各自的维护节奏和责任人，文档才不会腐坏。
我在实际复用这套结构时，还额外加了一个“场景”维度。同一个团队里，业务代码、SDK（对外提供的开发包）、脚本工具、（命令行接口）的规范性要求是完全不同的。业务代码看重可读性和可删改性，SDK 看重向后兼容和 API 稳定性，脚本工具看重短小直接、允许一定的“糙”。用一个标准套所有场景，结果一定是脚本被过度设计、SDK 被随意改动。分场景不是官僚主义，而是承认不同类型代码的优化目标本来就冲突。
1.3 文档是契约，工具是执行者：两者的映射关系必须显式
这是我认为最容易被忽略的一环。规范文档里写“禁止使用any”，配置文件里写的却是'@typescript-eslint/no-explicit-any': 'warn'——文档说禁止，工具只告警。这种不一致会迅速摧毁规范的可信度：第一次有人带着告警合并了代码，第二次所有人都会这么做。
我的做法是在规范项目里维护一张映射表，把每一条强约束和它对应的规则级别一一对上。级别只允许三档：error（阻断合并）、warn（允许合并但记入趋势）、off（明确不检查，且要在文档里写明理由）。凡是文档里写“禁止”的，工具必须是error；凡是工具设为warn的，文档里就不能写“禁止”，只能写“建议”。
注意：
warn级别在多数 Lint 工具里不会阻断构建，但会在输出里刷屏。一个常见的错误是“先用 warn 过渡一下”，结果过渡了两年。如果一条规则你打算长期保留，直接上error；如果你不确定，写进“讨论中”清单，别进配置。
映射表还有一个副产品：它天然是一份“规范覆盖率”清单。你可以清楚看到哪些条款有工具兜底、哪些还纯靠人。后者通常是架构层面的东西（模块边界、依赖方向），短期内无法自动化，那就老老实实交给评审清单，别硬造规则。
2. 核心细节解析：一份能落地的规范该写什么
2.1 命名规则要给出判定依据，而不是审美偏好
绝大多数失败的规范，都栽在命名这一章。因为它们写的是“变量名要有意义”“避免使用缩写”，这属于愿望，不是规则。有意义的判定标准是什么？谁来判？没人说得清。
我见过写得最好的一版是这样处理的：把命名拆成可机器判定的部分和可人工评审的部分，前者进配置，后者进清单。可机器判定的包括：常量全大写下划线分隔、类型/类用大驼峰、函数与变量用小驼峰、布尔值以is/has/can/should开头、私有成员加前缀、测试文件与源文件同名加后缀。这些规则不涉及审美，只涉及一致性，因此可以强制。
可人工评审的部分，规范里给的是“判定流程”而不是形容词：一个名字是否合格，先问“它描述的是值还是行为”，值用名词、行为用动词；再问“不看上下文能否猜出类型”，猜不出说明太抽象；最后问“换个新人来读，需不需要额外解释”，需要就说明名字承担了解释职责，应该补注释或改名。
这套流程看起来啰嗦，但它解决了一个核心争议：命名争执从“我觉得不好”变成“通不过第三问”。争议有了客观落点，讨论才能收敛。
另外强烈建议在规范里明确列出禁用词表。这类词不违法，但会稀释信息量：data、info、obj、temp、tmp、flag、res、val、handle（单独使用时）、util（作为文件名的兜底）、common、base、manager（滥用）。禁用词表的价值在于，它逼着你在写下getData()的那一刻停下来想一秒：这里到底是什么数据？这一秒往往就能省掉半年后的一次重构。
2.2 注释与文档注释：写“为什么”，不写“是什么”
规范项目里关于注释的章节，几乎都会引用那句老话：好代码自解释。但现实是，绝大多数业务代码做不到完全自解释，因为业务规则本身就带着历史包袱和外部约束。所以规范的重点应该从“要不要写注释”转向“写什么类型的注释”。
我采用的分类是三类，规则完全不同。第一类是意图注释：解释这段代码为什么这么写，尤其是那些看起来“绕”的地方。比如故意不用缓存、故意吞掉某个异常、故意做了两次校验。这类注释是刚需，规范应该要求写，并且要求写清“如果不这样会出什么问题”，否则半年后一定有人把它“优化”掉。第二类是接口文档注释：对外暴露的函数、组件属性、公共模块导出，必须写参数含义、返回值结构、可能的错误情况。这类可以也应该用工具生成文档，规则上强制要求覆盖率。第三类是过程注释：// 循环处理// 判断是否为空这种，规范里应该明确禁止，因为它复述代码，还会随代码变更而过期，过期的注释比没有注释更有害。
文档注释还有个实用细节：规范里要明确注释的“失效处理”。代码改了注释没改，是常态。我的做法是把文档注释的检查放进持续集成流水线，只检查导出符号是否“有”注释以及参数数量是否匹配，不检查语义是否准确——语义靠评审。这样既不会因为过度检查导致全员抵触，又能挡住“新增了三个参数但注释没更新”这类问题。
2.3 错误处理、日志与边界，是规范里最该较真的部分
风格类条款吵得最凶，但真正出事故的地方往往在错误处理和日志。这部分规范如果写得太软，等于没写。
错误处理我一般要求三条硬规则。其一，错误必须带上上下文再抛出或上报：只抛一个“请求失败”，等于什么都没说；至少要包含操作对象、关键参数、失败阶段。其二，禁止空捕获：catch块里什么都不做，或者只打印一行日志，是线上排障的最大敌人。如果确实要忽略，必须写明理由并加日志标记。其三，错误分层：底层错误不要直接穿透到用户可见层，中间必须有一层做转换和脱敏。这条在对外接口里尤其重要，原始错误堆栈可能带着内部路径甚至配置信息。
日志规范我坚持的几条是：禁止在循环体内无条件打日志（一条日志在循环里打一万次，等于把日志系统打挂）；日志必须包含可关联的标识（请求标识、任务标识），否则多个并发任务交错的日志根本没法拼；级别要克制，只保留错误、警告、信息、调试四档，不要自创业务级别；敏感字段必须脱敏，这条要写进规范的“红线”章节，并且要有对应的检查手段，比如在日志封装层做字段过滤，而不是靠每个调用方自觉。
边界条件也值得单列一条：规范里应明确要求对空值、空集合、超长输入、超时、并发重入这几类情况写出处理策略。很多线上问题不是逻辑写错，而是“没想到会传空”。
2.4 提交信息与分支命名，决定了三个月后你能不能查清历史
很多人把提交规范当成形式主义，直到某次线上故障需要定位“这个字段是哪次改的”，然后在git log里看到一连串update、fix bug、修改。这时候你就知道提交规范值多少钱了。
我采用的方案是约定式提交：类型 + 可选范围 + 简短描述，类型限定在固定枚举里（功能、修复、重构、性能、文档、测试、构建、流水线、杂务、回滚）。这套格式的好处不只是可读，而是它可以被工具解析，自动生成变更日志、自动判断版本号该升哪一位。规范里要写清枚举含义，尤其要界定“重构”和“修复”的边界——改了行为但对外表现不变算重构，对外表现有变化才算修复或功能。
分支命名同理。我的建议是“类型/工单标识-简短描述”，例如feat/order-split-01。规则不在于好看，而在于它能被流水线识别，自动决定这个分支要不要跑全量回归、合并后要不要触发特定发布流程。
提示：提交信息长度建议主体控制在 72 个字符内，这不是审美，而是多数终端和代码托管平台的列表视图在这个宽度内不会截断。超过之后标题被省略，等于白写。
3. 实操过程与核心环节实现
3.1 环境准备与依赖清单
我把落地拆成“基础设施层、检查层、门禁层”三块，按顺序装。不要一上来就全量铺开，先让本地跑起来，再谈流水线。
基础设施层只有两个东西：编辑器配置和格式化工具。编辑器配置负责最基础的字符集、换行符、缩进、行尾空格、文件末尾换行，它解决的问题是“不同操作系统保存出来的文件不一样”。格式化工具负责代码排版，它解决的问题是“排版不应该由人决定”。
检查层是 Lint 工具和对应的规则集。门禁层是提交前的钩子、暂存区校验，以及流水线上的校验脚本。依赖大致是：格式化工具、Lint 核心加语言插件加框架插件、样式检查工具、提交信息检查工具、钩子管理工具、暂存区过滤工具。版本上有个硬要求——钩子管理工具和 Lint 工具的大版本必须团队统一，否则会出现“我本地能过、你本地不过”的经典问题。我的做法是在项目里锁死版本号，并且在文档里写明升级流程，禁止个人自行升级。
# 依赖安装：以典型的 JS/TS 项目为例 npm i -D prettier eslint @eslint/js typescript-eslint \ eslint-config-prettier stylelint stylelint-config-standard \ @commitlint/cli @commitlint/config-conventional \ husky lint-staged这里有个容易踩的点：eslint-config-prettier必须放在配置数组的最后。它的唯一作用就是关掉所有与格式化冲突的规则，如果放在前面，后面的规则集又会把冲突规则打开，你会得到一堆莫名其妙的报错。
3.2 配置文件逐个落地
先写编辑器配置。它必须放在仓库根目录，文件名固定，多数编辑器会自动读取。
# .editorconfig root = true [*] charset = utf-8 end_of_line = lf insert_final_newline = true trim_trailing_whitespace = true indent_style = space indent_size = 2 [*.md] trim_trailing_whitespace = false [Makefile] indent_style = tabend_of_line = lf这条比想象中重要。如果团队里有成员在另一套操作系统上工作，不统一换行符会导致整个文件被标记为“全部修改”，代码评审时根本看不出真实改动。*.md关掉行尾空格裁剪，是因为 Markdown 里两个空格代表换行，裁掉会改变渲染结果。Makefile必须用 Tab，这是语法要求。
接着是格式化配置。参数不是随便填的，每条都对应一个取舍：
{ "semi": true, "singleQuote": true, "printWidth": 100, "tabWidth": 2, "trailingComma": "all", "arrowParens": "always", "endOfLine": "lf" }printWidth从默认的 80 调到 100，理由是现在的显示器普遍更宽，80 会导致大量不必要的折行，反而降低可读性；但也不建议超过 120，因为在分屏或并排对比时右侧会被截断。trailingComma: all的收益在于后续增删元素时，前一行不用改，代码差异更干净。arrowParens: always是为了统一，避免出现有的地方带括号有的不带。这些参数一旦定下来，就不要在项目中途改，改一次全库重排，代码历史会被污染一大截。
然后是 Lint 配置。现在主流的做法是扁平配置，一个数组，按顺序叠加：
// eslint.config.js import js from '@eslint/js'; import tseslint from 'typescript-eslint'; import prettier from 'eslint-config-prettier'; export default [ js.configs.recommended, ...tseslint.configs.recommended, prettier, { files: ['**/*.{ts,tsx}'], rules: { 'no-console': ['warn', { allow: ['warn', 'error'] }], 'no-unused-vars': 'off', '@typescript-eslint/no-unused-vars': [ 'error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' } ], '@typescript-eslint/no-explicit-any': 'error', complexity: ['warn', 12], 'max-lines-per-function': ['warn', { max: 80, skipComments: true }] } }, { files: ['**/*.test.{ts,tsx}', '**/scripts/**'], rules: { 'no-console': 'off', '@typescript-eslint/no-explicit-any': 'warn' } }, { ignores: ['dist/**', 'coverage/**', '**/generated/**', '**/*.min.js'] } ];几个参数值得解释。argsIgnorePattern: '^_'是给“故意不用的参数”留的出口，没有这个出口，团队就会用更糟的方式绕过（比如直接删掉参数破坏接口）。complexity: 12是圈复杂度阈值，超过 12 的函数建议拆，这个数字来自经验——超过 12 之后单元测试的分支组合会迅速爆炸。max-lines-per-function: 80配合skipComments: true，是为了不惩罚那些注释写得很足的函数。
按文件类型覆盖规则这一层很关键。测试代码和脚本工具应该有独立的宽松度，否则会出现“为了通过 Lint，把测试代码写得更难读”的荒谬结果。ignores里放构建产物和生成代码，生成代码永远不要纳入规范检查，它不是人写的，改了也会被下次生成覆盖。
样式文件用另一套工具，配置原则是“只留必要的”，把排版交给格式化工具：
{ "extends": ["stylelint-config-standard"], "rules": { "selector-class-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$", "no-descending-specificity": null, "custom-property-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$" } }selector-class-pattern是在强制一种类名风格（小写加连字符），如果不统一，同一个模块里会同时出现几种风格，后期改样式靠全文搜索都得搜三遍。no-descending-specificity关掉，是因为它误报率高，而且现代构建工具会处理优先级问题，收益不抵成本。这类“明确关闭并写明理由”的条目，一定要在规范文档里留痕，否则半年后新人会以为漏配了又给你加回去。
3.3 提交前拦截：钩子与暂存区校验
流水线跑得再快，也不如提交前拦一次。钩子的价值在于反馈延迟——本地拦截反馈是秒级，流水线拦截反馈是分钟级，后者会让人养成“先推上去看看”的坏习惯。
// commitlint.config.js export default { rules: { 'type-enum': [ 2, 'always', ['feat', 'fix', 'refactor', 'perf', 'docs', 'test', 'build', 'ci', 'chore', 'revert'] ], 'subject-max-length': [2, 'always', 72], 'subject-full-stop': [2, 'never', '.'], 'subject-empty': [2, 'never'], 'scope-case': [2, 'always', 'kebab-case'] } };subject-full-stop: never这条看着琐碎，实际有用：标题末尾加句号会导致自动生成的变更日志里出现奇怪的标点，而且团队里总有人加有人不加。
暂存区校验的配置如下：
{ "lint-staged": { "*.{js,jsx,ts,tsx}": ["eslint --fix --max-warnings=0", "prettier --write"], "*.{css,scss}": ["stylelint --fix", "prettier --write"], "*.{json,md,yml,yaml}": ["prettier --write"] } }--max-warnings=0是这套配置的核心。不加这个参数，警告不会导致失败，前面说的“warn 过渡两年”就会真实发生。加上之后，暂存区里的文件只要有一条警告就提交不了，逼着当场解决。这和全量检查的区别是：只检查你改的文件，所以不会因为别人的历史遗留问题卡住你。
钩子安装用工具提供的初始化命令，装完之后它会接管提交前和提交信息两个节点。这里有个常见坑：克隆仓库后必须执行一次安装命令，否则钩子不生效。解决方案是在项目初始化脚本里挂上这个命令，或者用包管理器的准备钩子自动触发。
3.4 流水线门禁与增量治理策略
本地能过的，流水线要做一次“绝不信赖本地”的复核。这一步不是为了抓人，而是为了避免本地环境差异（比如有人手动禁用了钩子）。同时流水线还承担一项本地做不了的事：统计与趋势。
# 通用流水线配置示意 stages: - verify lint-and-gate: stage: verify script: - npm ci - npx eslint . --format json --output-file reports/eslint.json || true - npx stylelint "**/*.css" --formatter json > reports/stylelint.json || true - node scripts/quality-gate.js artifacts: when: always paths: - reports/注意|| true这个写法：它让 Lint 命令本身不中断流水线，把结果写到文件，再由自定义的校验脚本决定是否失败。这样做的好处是，无论通过与否都会产出完整报告，方便定位和做趋势统计。如果直接让 Lint 中断，你只会拿到一个退出码，看不到全貌。
真正的策略体现在quality-gate.js里。这里我用增量治理的思路，而不是全量清零。原因是全量清零在存量大的项目里几乎不可能完成，强行要求只会让团队集体绕过。
具体做法是先建立基线，再卡增量。假设仓库有 12.6 万行业务代码，第一次全量跑出 8742 条告警。先分类：格式类（可自动修复）占约 61%，也就是大约 5330 条；剩下 3412 条需要人工判断。
第一步，跑一次--fix自动修复格式类问题，这一步在独立分支上做，提交时在描述里写明“仅格式变更，无逻辑修改”，并且加上跳过检查的标记，避免自动修复本身被规则拦住。
第二步，对剩余 3412 条按规则维度排序，找出 Top 5 高频规则。经验上通常是“禁止使用 any”“函数过长”“圈复杂度过高”“缺少返回类型”“未处理 Promise”。这几类先设warn，其余维持error。
第三步，设定门禁阈值。基线告警密度 = 8742 / 126000 ≈ 0.069 条每行。新增代码的门槛可以卡在 0.02 条每行，也就是不到基线的三分之一。这个数字的推导逻辑是：老代码的债务不要求新人背，但也不能让新代码继续加剧；取三分之一是留了一定操作余量，不至于让正常业务开发天天被卡。
第四步，设定清理节奏。3412 条人工告警，按每周 5 个工作日、单日可顺手处理 20 条估算，一个人需要约 34 周，明显过长；分摊到 3 个人并行，约 57 个工作日，也就是接近 3 个月。这个节奏是可执行的，因为它假设的是“顺手修”，而不是专门排期。
关于流水线耗时，这里也有个可以量化的优化。全量 Lint 在中等规模仓库里大约需要 3 分 20 秒，改成只检查变更文件加缓存后，稳定在 45 秒上下。变更文件的识别方式是对比目标分支的合并基点，拿到改动文件列表再传给 Lint。缓存则依赖工具自身的缓存目录，注意把缓存目录加入忽略清单，不要提交进仓库。
3.5 存量代码的迁移节奏与阈值设定
迁移最怕两种极端：一种是要求“本周全部清零”，结果是一堆人为了过检查加了大量跳过标记；另一种是“慢慢来”，结果永远不来。
我的节奏是三段式。第一段只做自动修复，不引入任何新的人工规则，目标是把格式类的 5330 条一次消掉，让团队的痛感从“到处是红”变成“偶有红”。这一段通常一周内能完成，收益立竿见影，也最容易建立信任。
第二段引入增量门禁，老代码不动，新代码从严。这一段的关键指标是“新增告警密度”，要每周看趋势，只要不上升就说明门禁有效。这段最容易出的问题是规则开得太猛，导致正常业务开发频繁被卡，然后有人去改配置。所以这一段建议只开 5 到 8 条规则，全部是error级别，宁少勿多。
第三段做定向清理，按模块而不是按规则推进。理由是按规则推进会导致同一个文件被反复修改十几次，每次都要重新评审；按模块推进则可以一次把某个目录清干净，然后把该目录加入严格白名单。这个技巧很实用：在配置里按目录覆盖规则，已经清理干净的目录用最严格规则，未清理的目录暂时放宽。白名单只增不减，进度就永远可见。
迁移过程中还有一个容易被忽略的参数：跳过标记的治理。规范里应该允许跳过（否则遇到确实无法修改的情况会走投无路），但必须要求写明原因和关联标识，并且定期统计数量。我的经验是，跳过标记数量应该控制在总文件数的 1% 以内，超过这个比例说明规则设计有问题，而不是代码有问题。
4. 常见问题与排查技巧实录
4.1 格式化工具与 Lint 工具打架
症状很典型：保存时格式化工具把代码改成 A 样子，提交时 Lint 又报错要求 B 样子，来回拉扯；或者两个人在不同编辑器里保存同一文件，产生完全相反的差异。
根因几乎都是配置继承顺序错了。格式化工具和 Lint 工具的规则集有重叠区，重叠部分必须由一方让位。正确顺序是：Lint 推荐规则集在前，冲突关闭配置在最后。如果中间还插了框架插件，那就得确保关闭配置永远在数组末位。
还有一种隐蔽情况是编辑器插件各自读取了不同的配置文件。比如项目根有配置，用户主目录也有一份个人配置，插件优先级不同就会打架。排查方法是让插件输出它实际使用的配置路径，确认指向项目根。团队里统一要求“项目配置优先于个人配置”，个人偏好只能通过项目配置覆盖，不能反向影响。
排查命令：让 Lint 输出最终生效的规则值。如果某个规则最终是
off，说明被后面的配置覆盖了；如果和预期不符，按数组顺序倒着找。
4.2 本地过、流水线不过
这是出现频率最高的问题，原因通常有三类。第一类是换行符，本地是另一套换行符，提交后整个文件被判定为修改，行尾空格和格式检查全部触发。解决办法是编辑器配置加版本库的行尾规范化配置双管齐下。第二类是版本不一致，本地装的是新版本，流水线锁的是旧版本，规则默认值不同。解决办法是锁死版本并禁止个人升级。第三类是缓存污染，本地缓存文件过期，读到了旧的检查结果。解决办法是提供清理命令，并在排查步骤里固定加上“先清缓存”。
我处理这类问题的固定流程是：先看流水线报告的第一个错误而不是最后一个，因为后面的错误往往是连锁反应；然后本地用同样的命令和同样的配置跑一遍；最后对比两边的版本号。三步之内基本能定位。
4.3 存量治理的三种翻车姿势
翻车一：一次开太多规则。第一天上线 40 条规则，全库爆出上万条问题，所有人第一反应是找绕过方法，规范项目当场失去权威。正确做法是分批，每次不超过 8 条，且优先选自动可修复的。
翻车二：把生成代码和第三方代码纳入检查。构建产物、自动生成的接口客户端、复制的第三方库，一旦纳入检查，告警数会瞬间翻倍，而且你根本不该改它们。忽略清单必须在第一天上齐。
翻车三：只用警告不用阻断。全员警告等于全员无视。规则定了就上阻断，实在要过渡就设一个明确的到期时间，写在配置注释里，到期必须处理。
还有一类不那么明显的问题：规则之间互相冲突导致无法同时满足。比如同时要求“函数不超过 80 行”和“禁止提前返回”，某些逻辑就只能写成超长函数。这类冲突要在规范项目里显式列出优先级：可读性高于函数长度，安全性高于简洁性。有了优先级，冲突时才有解。
4.4 常见问题速查表
| 现象 | 最可能原因 | 排查动作 | 处理方式 |
|---|---|---|---|
| 格式化与 Lint 结果反复互相覆盖 | 冲突关闭配置没有放在末位 | 查看配置数组顺序 | 把关闭配置移到最后一层 |
| 提交后整个文件显示全改 | 换行符或行尾空格不一致 | 检查编辑器配置是否生效 | 统一换行符并重新规范化一次 |
| 本地通过、流水线失败 | 工具版本或缓存不一致 | 对比两边版本号、清缓存 | 锁死版本、固化清理步骤 |
| 钩子完全不生效 | 未执行安装命令 | 查看钩子目录是否存在 | 补执行安装并加入初始化脚本 |
| 告警数量突然暴涨 | 忽略了生成代码或新增了规则 | 对比忽略清单与规则变更记录 | 补齐忽略、或回滚该规则 |
| 某个目录始终无法通过检查 | 存量债务集中，规则过严 | 按目录统计告警密度 | 该目录降级，其余目录保持严格 |
| 提交信息校验总是失败 | 枚举值不在白名单或标题过长 | 打印实际提交标题 | 补枚举、压缩标题长度 |
5. 规范项目自身的维护方式
5.1 版本化与变更评审
规范一旦被多个项目依赖，它就是一个有兼容性问题的产物。新增一条规则等于一次破坏性变更，因为所有下游项目都会突然报错。所以规范项目本身必须有版本策略：新增规则走大版本，调整规则参数走小版本，修正文档走补丁版本。
变更评审我建议加一道硬性要求：每条新规则必须附带“误报场景说明”和“自动修复可能性”两栏。没有这两栏，评审就无法判断这条规则会不会把团队拖进无休止的争论。实践下来，光是要求写误报场景这一条，就能过滤掉大约三分之一“看起来很美好”的规则提案。
还有一个流程细节值得坚持：规则讨论要留下决议记录，写清“为什么最终选了 A 不选 B”。半年后有人重新提议 B 时，直接翻记录，省掉一轮重复辩论。
5.2 用数据判断规范到底有没有生效
规范项目的成功不能靠“大家说好”，得有指标。我常看的四个数是：新增代码的告警密度趋势（应该持续下降）、代码评审中关于格式的评论占比（应该降到 5% 以下）、合并请求的平均停留时长（应该缩短）、新人首次提交通过检查所需的时间（应该在一周内）。
这几个数都不难拿到。告警密度从流水线报告里统计；评审评论占比可以靠关键词粗略分类；停留时长看流水线记录；新人上手时间靠问一句。关键是别做成一堆没人看的报表，而是每月花十分钟看一眼趋势，发现哪项恶化就去查原因。
我个人在实际操作中的体会是：规范项目真正的分水岭不在于规则写得多全，而在于第一次有人试图绕过它时，团队有没有坚持住。这条守住了，后面全是顺水推舟；这条没守住，再漂亮的文档也只是一份 README。另外分享一个我一直在用的小技巧——把最容易违反的三条规则做成编辑器里的实时提示，而不是等到提交时才报错。人在写代码的那一秒看到提示，改起来是零成本的；等到提交时被拦下来，情绪成本要高得多。
