quality-enforcement

质量管控

概述

质量管控是自动化的，而非仅仅是目标。凡是机器能够检查的，都必须检查。

核心原则： 未在 CI 中强制执行的质量检查，就等于不存在。

没有例外。没有变通办法。没有捷径。

首要原则

NO CODE LANDS WITHOUT ALL QUALITY CHECKS PASSING

如果检查失败，就修复代码。绝不禁用检查。绝不绕过 CI。

适用时机

务必在以下操作之前：

• 提交代码
• 发起拉取请求
• 合并到主干
• 发布到生产环境

尤其是在以下情况：

• “这次就先抑制一下代码检查工具的提示吧”（绝不）
• “CI 太慢了，手动合并吧”（修复 CI，不要跳过它）
• “有类型错误，但运行时没问题”（修复类型）
• “覆盖率下降了，但关键路径都测过了”（恢复覆盖率）

执行流程

BEFORE any PR or merge:

1. LINT: Zero errors, zero warnings
2. TYPES: Zero type errors (strict mode)
3. TESTS: All passing, coverage meets threshold
4. BUILD: Clean build, no warnings
5. SIZE: Bundle/binary within budget (if applicable)
6. DEPS: No known vulnerabilities (critical/high)
7. COMPLEXITY: No functions exceeding complexity threshold

Any check fails = code is not ready. Fix before advancing.

质量检查参考

检查 1：代码检查

Standard: Zero errors AND zero warnings

设置	值	理由
错误	0	不容妥协
警告	0	警告会变成你习惯忽略的错误
提交配置	是	确保所有贡献者使用一致的配置
CI 强制执行	是	本地覆盖配置无关紧要

今天的警告就是明天的错误。 要么修复，要么调整规则。绝不容忍警告。

要禁用规则？ 只有团队明确同意该规则不适用于此项目时才可以。请在配置文件中记录理由。绝不要为了方便而在代码行内禁用规则。

检查 2：类型安全

Standard: Zero type errors, strict mode enabled

TypeScript：

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true
  }
}

Python： 使用严格模式的 mypy 或 pyright。

反模式	问题	修复方法
any 类型	禁用了类型检查	使用具体类型或泛型
// @ts-ignore	掩盖真实错误	修复类型错误
# type: ignore	同样的问题	修复类型错误
非严格模式	造成虚假的安全感	从第一天起就启用严格模式

any 是你选择不解决的类型错误。 每个 any 都会削弱它所影响的一切的类型系统。

检查 3：测试覆盖率

Standard: Coverage threshold that never decreases

指标	最低要求	目标
行覆盖率	80%	90%+
分支覆盖率	70%	85%+
新增代码覆盖率	90%	100%（努力达到）

覆盖率阈值只增不减。 它们只会提高，不会降低。配置 CI，在覆盖率低于当前水平时使其失败。

覆盖率是必要条件，但不是充分条件。断言质量差的 100% 覆盖率，不如断言严谨的 70% 覆盖率。覆盖率检查应与 TDD 纪律（godmode:test-first）结合使用。

检查 4：构建

Standard: Clean build, zero warnings

• 构建必须成功完成
• 编译器和构建警告为零
• 输出符合预期结构
• 构建时不得缺少依赖项

检查 5：包体积预算（前端）

Standard: Total bundle size within defined budget

目标	预算	工具
初始 JS（压缩后）	<200KB	webpack-bundle-analyzer
CSS	<50KB	PurgeCSS 检查
图片	已优化，WebP/AVIF	imagemin
页面总大小	<1MB	Lighthouse

设定预算，并在 CI 中强制执行。 超出预算时，分析包内容并删除或拆分内容。

检查 6：依赖项审计

Standard: Zero critical or high vulnerabilities

语言	命令	CI 集成
JavaScript	npm audit --audit-level=high	存在高危及以上问题时失败
Python	pip-audit 或 safety check	存在高危及以上问题时失败
Go	govulncheck ./...	存在任何问题时失败
Rust	cargo audit	存在任何问题时失败

还要确认：

• 没有不必要的依赖项（每个依赖项都确实在使用吗？）
• 没有重复的依赖项（同一软件包存在不同版本）
• 依赖项仍在维护（最近一次更新在 12 个月以内）

检查 7：复杂度指标

Standard: No function exceeds complexity threshold

指标	阈值	工具
圈复杂度	每个函数 <10	ESLint（complexity 规则）、radon、gocyclo
函数长度	<50 行	Linter 规则
文件长度	<400 行	Linter 规则
参数数量	每个函数 <5 个	Linter 规则

复杂度超出阈值时： 重构。提取函数。简化条件语句。绝不提高阈值。

检查 8：死代码

Standard: No unused exports, variables, or dependencies

内容	工具
未使用的导出	ts-prune、knip
未使用的依赖	depcheck、knip
未使用的变量	Linter（no-unused-vars）
不可达代码	Linter、类型检查器

死代码会误导人。它暗示有其他内容依赖它。删除它。

CI 流水线模板

# Minimum quality enforcement pipeline
quality-checks:
  steps:
    - name: Lint
      run: npm run lint
    - name: Type Check
      run: npm run typecheck
    - name: Test
      run: npm test -- --coverage
    - name: Coverage Check
      run: check-coverage --threshold 80
    - name: Build
      run: npm run build
    - name: Bundle Size
      run: bundlesize
    - name: Audit
      run: npm audit --audit-level=high

每个 PR 都会运行所有检查。合并前必须全部通过。

认知陷阱

合理化说辞	事实
“只是 lint 警告，不是错误”	被你忽视的警告，会变成你漏掉的错误。
“有类型错误，但运行时能正常工作”	类型能防止你尚未遇到的运行时错误。
“覆盖率下降了 1%，问题不大”	每个 PR 下降 1%，一年就会下降 50%。阈值只会越设越高。
“跳过 CI 吧，我在本地测试过了”	本地环境与 CI 不同。这正是 CI 存在的原因。
“因为我们添加了功能，所以打包体积变大了”	新功能应该替换或拆分现有内容，而不只是增加内容。
“漏洞在开发依赖里”	开发依赖会在 CI 中运行。CI 里有密钥。这仍然有风险。
“函数虽然复杂，但可读”	复杂度限制之所以存在，是因为可读性是主观的。
“以后可能会用到这段死代码”	Git 会记住。删除它。需要时从历史记录中恢复。

护栏——立即停止并修复

• 未提供文档化理由就内联禁用 lint 规则
• 使用 @ts-ignore 或 # type: ignore，但没有附带相关 issue
• 配置中的覆盖率阈值被降低
• 为了合并而跳过或覆盖 CI
• any 类型在整个代码库中蔓延
• 打包体积增大却未进行调查
• 将警告视为可以接受
• 因为“这是开发依赖”而忽略审计失败

以上任何一种情况都意味着：检查机制已失效。继续编写代码之前，先修复检查机制。

集成

互补关系：

• godmode:test-first — 测试只是众多检查之一
• godmode:completion-gate — 质量检查是验证证据
• godmode:project-bootstrap — 在项目初始化时配置检查
• godmode:security-protocol — 依赖审计是一项安全检查
• godmode:performance-tuning — 打包体积是一项性能检查

总结

Every quality check automated in CI. Every check passing before merge. No exceptions.

如果检查可以绕过，就一定会被绕过。让绕过检查变得不可能。