universal-quality-gate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Universal Quality Gate Skill

通用代码质量门禁Skill

Language-agnostic code quality checking system. Automatically detects project languages via marker files and runs appropriate linters, formatters, and static analysis tools for each detected language.

独立于语言的代码质量检查系统。通过标记文件自动检测项目语言，并为每种检测到的语言运行相应的linter、格式化工具和静态分析工具。

Operator Context

运行上下文

This skill operates as an operator for multi-language code quality enforcement, configuring Claude's behavior to run comprehensive quality checks across any codebase. It implements a Detect, Check, Report pattern with graceful degradation for unavailable tools.

本Skill作为多语言代码质量强制执行的操作器，配置Claude的行为以对任何代码库进行全面的质量检查。它实现了检测、检查、报告模式，针对不可用的工具会优雅降级处理。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md files before execution. Project instructions override default skill behaviors.
Over-Engineering Prevention: Only run tools that are configured and available. Do not add new tools, languages, or checks unless explicitly requested. Keep quality checks focused on what is already defined in language_registry.json.
Auto-detect languages: Scan for marker files (go.mod, package.json, pyproject.toml, Cargo.toml, etc.)
Show complete output: Display full linter output, never summarize as "no issues"
Graceful degradation: Skip unavailable tools without failing the entire gate
Non-blocking for optional tools: Only fail on required tool failures

遵循CLAUDE.md规范：执行前读取并遵循仓库的CLAUDE.md文件。项目指令会覆盖Skill的默认行为。
防止过度设计：仅运行已配置且可用的工具。除非明确要求，否则不要添加新工具、语言或检查项。保持质量检查聚焦于language_registry.json中已定义的内容。
自动检测语言：扫描标记文件（go.mod、package.json、pyproject.toml、Cargo.toml等）
显示完整输出：展示linter的完整输出，绝不以“无问题”概括
优雅降级：跳过不可用的工具，不会导致整个门禁检查失败
可选工具不阻塞：仅在必需工具失败时才判定检查失败

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

Communication Style: Report facts without self-congratulation. Show command output rather than describing it.
Temporary File Cleanup: Remove any temporary files or cache files created during quality gate execution at task completion.
Check all detected languages: Run tools for every language found
Include pattern checks: Scan for anti-patterns (silent except, debug prints, TODOs)
Verbose output: Show file paths and line numbers for all issues
Exit with status code: Return non-zero if any required check fails

沟通风格：只报告事实，不自我夸赞。展示命令输出而非描述输出内容。
临时文件清理：任务完成后删除质量门禁执行过程中创建的所有临时文件或缓存文件。
检查所有检测到的语言：为每个找到的语言运行对应工具
包含模式检查：扫描反模式（静默异常处理、调试打印、TODO注释等）
详细输出：显示所有问题的文件路径和行号
返回状态码：如果任何必需检查失败，返回非零状态码

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，可开启）

Fix mode: Auto-fix issues instead of just reporting (
```
--fix
```
)
Staged only: Only check git staged files (
```
--staged
```
)
Single language: Focus on one language only (
```
--lang python
```
)
Skip patterns: Disable pattern matching (
```
--no-patterns
```
)

修复模式：自动修复问题而非仅报告（使用
```
--fix
```
参数）
仅检查暂存文件：仅检查git暂存的文件（使用
```
--staged
```
参数）
单一语言聚焦：仅关注一种语言（使用
```
--lang python
```
参数）
跳过模式检查：禁用模式匹配（使用
```
--no-patterns
```
参数）

What This Skill CAN Do

本Skill可实现的功能

Auto-detect project languages from marker files and run all configured linters
Run language-specific lint, format, type-check, and security tools
Auto-fix safe issues when
```
--fix
```
flag is used
Check only staged files for faster pre-commit validation
Report issues with file paths, line numbers, and severity
Gracefully skip unavailable tools while still running available ones

从标记文件自动检测项目语言，并运行所有已配置的linter
运行特定语言的lint检查、格式化、类型检查和安全工具
当使用
```
--fix
```
参数时，自动修复可安全修复的问题
仅检查暂存文件以加快提交前验证速度
报告包含文件路径、行号和严重程度的问题
优雅跳过不可用的工具，同时仍运行可用的工具

What This Skill CANNOT Do

本Skill无法实现的功能

Install missing linter tools (reports them as skipped)
Catch logic bugs, race conditions, or architectural problems (use tests and code review)
Replace comprehensive code review (use systematic-code-review)
Add new languages without registry configuration (use language_registry.json)
Override project-specific linter configurations

安装缺失的linter工具（会报告为已跳过）
捕获逻辑错误、竞态条件或架构问题（请使用测试和代码审查）
替代全面代码审查（请使用systematic-code-review）
在无注册表配置的情况下添加新语言（请使用language_registry.json）
覆盖项目特定的linter配置

Supported Languages

支持的语言

Language	Marker Files	Tools
Python	pyproject.toml, requirements.txt	ruff, mypy, bandit
Go	go.mod	gofmt, golangci-lint, go vet
JavaScript	package.json	eslint, biome
TypeScript	tsconfig.json	tsc, eslint, biome
Rust	Cargo.toml	clippy, cargo fmt
Ruby	Gemfile	rubocop
Java	pom.xml, build.gradle	PMD
Shell	.sh, .bash	shellcheck
YAML	.yml, .yaml	yamllint
Markdown	*.md	markdownlint

语言	标记文件	工具
Python	pyproject.toml, requirements.txt	ruff, mypy, bandit
Go	go.mod	gofmt, golangci-lint, go vet
JavaScript	package.json	eslint, biome
TypeScript	tsconfig.json	tsc, eslint, biome
Rust	Cargo.toml	clippy, cargo fmt
Ruby	Gemfile	rubocop
Java	pom.xml, build.gradle	PMD
Shell	.sh, .bash	shellcheck
YAML	.yml, .yaml	yamllint
Markdown	*.md	markdownlint

Instructions

使用说明

Step 1: Run Quality Gate

步骤1：运行质量门禁检查

Execute the quality gate check:

bash

python3 ~/.claude/skills/universal-quality-gate/scripts/run_quality_gate.py

Common options:

bash

undefined

执行质量门禁检查：

bash

python3 ~/.claude/skills/universal-quality-gate/scripts/run_quality_gate.py

常用选项：

bash

undefined

Fix issues automatically

自动修复问题

python3 ~/.claude/skills/universal-quality-gate/scripts/run_quality_gate.py --fix

Only check staged files

仅检查暂存文件

python3 ~/.claude/skills/universal-quality-gate/scripts/run_quality_gate.py --staged

Verbose output

详细输出

python3 ~/.claude/skills/universal-quality-gate/scripts/run_quality_gate.py -v

Check specific language only

仅检查特定语言

python3 ~/.claude/skills/universal-quality-gate/scripts/run_quality_gate.py --lang python

undefined

python3 ~/.claude/skills/universal-quality-gate/scripts/run_quality_gate.py --lang python

undefined

Step 2: Interpret Results

步骤2：解读结果

Success Output:

============================================================
 Quality Gate: PASSED
============================================================

Languages: python, javascript
Files: 15

Tool Results:
  [+] python/lint: passed
  [+] python/format: passed
  [-] python/typecheck: skipped (Optional tool not installed)
  [+] javascript/lint: passed
  [+] javascript/format: passed

Quality gate passed: 4/5 tools OK (1 skipped)

Failure Output:

============================================================
 Quality Gate: FAILED
============================================================

Languages: python, go
Files: 8

Tool Results:
  [X] python/lint: FAILED
      hooks/example.py:42:1: F841 local variable 'x' is assigned but never used
      hooks/example.py:56:1: F401 'os' imported but unused
  [+] python/format: passed
  [+] go/format: passed
  [X] go/lint: FAILED
      main.go:15:2: S1000: should use for range instead of for select

Pattern Matches:
  [WARNING] hooks/example.py:78: Silent exception handler - add explanatory comment

Quality gate failed: 2 tool(s) reported issues, 1 error pattern(s)

成功输出：

============================================================
 Quality Gate: PASSED
============================================================

Languages: python, javascript
Files: 15

Tool Results:
  [+] python/lint: passed
  [+] python/format: passed
  [-] python/typecheck: skipped (Optional tool not installed)
  [+] javascript/lint: passed
  [+] javascript/format: passed

Quality gate passed: 4/5 tools OK (1 skipped)

失败输出：

============================================================
 Quality Gate: FAILED
============================================================

Languages: python, go
Files: 8

Tool Results:
  [X] python/lint: FAILED
      hooks/example.py:42:1: F841 local variable 'x' is assigned but never used
      hooks/example.py:56:1: F401 'os' imported but unused
  [+] python/format: passed
  [+] go/format: passed
  [X] go/lint: FAILED
      main.go:15:2: S1000: should use for range instead of for select

Pattern Matches:
  [WARNING] hooks/example.py:78: Silent exception handler - add explanatory comment

Quality gate failed: 2 tool(s) reported issues, 1 error pattern(s)

Step 3: Fix Issues

步骤3：修复问题

Run with

--fix

to auto-correct fixable issues, then re-run to verify:

bash

undefined

使用

--fix

参数自动修复可修复的问题，然后重新运行检查以验证：

bash

undefined

Auto-fix

自动修复

python3 ~/.claude/skills/universal-quality-gate/scripts/run_quality_gate.py --fix

Verify fixes

验证修复结果

python3 ~/.claude/skills/universal-quality-gate/scripts/run_quality_gate.py

undefined

python3 ~/.claude/skills/universal-quality-gate/scripts/run_quality_gate.py

undefined

Step 4: Review and Commit

步骤4：审查并提交

After quality gate passes:

Review auto-fix changes with
```
git diff
```
Run project tests to catch logic regressions
Commit with descriptive message

Gate: Quality gate passes with zero required-tool failures. Proceed only when gate passes.

质量门禁检查通过后：

使用
```
git diff
```
审查自动修复的变更
运行项目测试以捕获逻辑回归问题
使用描述性信息提交代码

门禁要求：质量门禁在必需工具全部通过时才算通过。仅当门禁通过后才可继续后续操作。

Examples

添加新语言

Example 1: Pre-Commit Check

—

User says: "Check if this code is ready to commit" Actions:

Run quality gate with
```
--staged
```
to check only staged files
Review output for failures and warnings
Use
```
--fix
```
for auto-fixable issues, manually fix the rest
Re-run quality gate to confirm all checks pass Result: Clean quality gate, ready to commit

通过语言注册表添加支持，无需编辑脚本：

json

// hooks/lib/language_registry.json
{
  "new_language": {
    "extensions": [".ext"],
    "markers": ["config.file"],
    "tools": {
      "lint": {
        "cmd": "linter {files}",
        "fix_cmd": "linter --fix {files}",
        "description": "Language linter",
        "required": true
      }
    }
  }
}

脚本会自动从注册表中获取新添加的配置。

Example 2: Full Repo Audit

错误处理

—

错误：“No files to check”

User says: "Run quality checks on everything" Actions:

Run quality gate without flags to scan all detected languages
Review per-language tool results and pattern matches
Triage issues by severity: required-tool failures first, then warnings
Fix issues in batches by language, re-run after each batch Result: Full codebase quality report with actionable issues

原因：未检测到变更文件，或项目中未找到语言标记文件 解决方案：

确认你处于正确的项目目录中
检查标记文件是否存在（如go.mod、package.json等）
如果检查暂存文件，请确保已使用
```
git add
```
将文件加入暂存区

Adding New Languages

错误：“Tool not found”

Add support through the language registry, not by editing the script:

json

// hooks/lib/language_registry.json
{
  "new_language": {
    "extensions": [".ext"],
    "markers": ["config.file"],
    "tools": {
      "lint": {
        "cmd": "linter {files}",
        "fix_cmd": "linter --fix {files}",
        "description": "Language linter",
        "required": true
      }
    }
  }
}

The script automatically picks up new entries from the registry.

原因：系统中未安装必需的linter工具 解决方案：

从输出中查看缺失的工具

安装该工具（例如

pip install ruff

、

go install golangci-lint

）

或者在language_registry.json中将该工具标记为可选

Error Handling

错误：“Command timed out”

Error: "No files to check"

—

Cause: No changed files detected or no language markers found in project Solution:

Verify you are in the correct project directory
Check that marker files exist (go.mod, package.json, etc.)
If checking staged files, ensure files are staged with
```
git add
```

原因：工具执行时间超过60秒超时限制，通常是因为文件集过大 解决方案：

使用
```
--staged
```
仅检查变更文件
使用
```
--lang
```
一次仅检查一种语言
检查项目中是否存在无限循环或非常大的生成文件

Error: "Tool not found"

错误：“Configuration file conflict”

Cause: Required linter tool is not installed on the system Solution:

Check which tools are missing from the output

Install the tool (e.g.,

pip install ruff

go install golangci-lint

)

Or mark the tool as optional in language_registry.json

原因：存在冲突的linter配置（例如同时配置了eslint和biome） 解决方案：

检查项目实际使用的工具
在language_registry.json中禁用未使用的工具
确保项目的CLAUDE.md指定了首选工具

Error: "Command timed out"

反模式

—

反模式1：未验证先决条件就运行

Cause: Tool taking longer than 60-second timeout, often due to large file sets Solution:

Use
```
--staged
```
to check only changed files
Use
```
--lang
```
to check one language at a time
Check for infinite loops or very large generated files in the project

表现：运行质量门禁后，所有语言都提示“Tool not found” 危害：不完整的检查结果会带来虚假的安全感。跳过的检查意味着代码未被验证。 正确做法：在依赖结果前，先验证已安装检测到的语言所需的工具。

Error: "Configuration file conflict"

反模式2：忽略失败的检查

Cause: Conflicting linter configs (e.g., eslint and biome both configured) Solution:

Check which tools the project actually uses
Disable the unused tool in language_registry.json
Ensure project CLAUDE.md specifies preferred tools

表现：质量门禁报告失败，但用户未审查就提交代码危害：违背了质量门禁的初衷。会将已知问题引入代码库。 正确做法：审查所有报告的问题。使用

--fix

修复可自动修复的问题，手动修复其余问题。

Anti-Patterns

反模式3：小变更却执行全量扫描

Anti-Pattern 1: Running Without Verifying Prerequisites

—

What it looks like: Running quality gate and getting "Tool not found" for every language Why wrong: Incomplete results give false confidence. Skipped checks mean unchecked code. Do instead: Verify required tools are installed for detected languages before relying on results.

表现：仅修改了一个文件，却对包含1000多个文件的5种语言执行全量质量门禁检查危害：浪费时间，会暴露旧代码中的无关问题，拖慢开发速度。 正确做法：使用

--staged

仅检查变更文件，或使用

--lang

针对相关语言。

Anti-Pattern 2: Ignoring Failed Checks

反模式4：盲目自动修复而不审查

What it looks like: Quality gate reports failures, user commits anyway without review Why wrong: Defeats the purpose of quality gates. Introduces known issues into the codebase. Do instead: Review all reported issues. Use

--fix

for auto-fixable issues, then manually address remaining ones.

表现：运行

--fix

后立即提交，未使用

git diff

审查变更危害：自动修复可能会意外改变代码行为。没有人工验证变更的正确性。 正确做法：运行

--fix

，审查差异，验证变更正确后，再使用描述性信息提交。

Anti-Pattern 3: Full Scan for Small Changes

反模式5：将质量门禁视为完整验证

What it looks like: Changed one file, running full quality gate on 1,000+ files across 5 languages Why wrong: Wastes time, surfaces unrelated issues from old code, slows development. Do instead: Use

--staged

to check only changed files, or

--lang

to target the relevant language.

表现：质量门禁通过后，用户跳过测试和代码审查危害：质量门禁只能捕获语法和风格问题，无法发现逻辑错误、竞态条件或架构问题。 正确做法：将质量门禁作为验证的一层。同时运行测试、执行代码审查，并考虑领域特定的检查。

Anti-Pattern 4: Blind Auto-Fix Without Review

架构

What it looks like: Running

--fix

then immediately committing without

git diff

Why wrong: Auto-fix can change code behavior unexpectedly. No human verification of changes. Do instead: Run

--fix

, review the diff, verify changes are correct, then commit with a descriptive message.

hooks/lib/
  quality_gate.py        # 共享核心库
  language_registry.json # 语言配置文件

skills/universal-quality-gate/
  SKILL.md               # 本文件
  scripts/
    run_quality_gate.py  # Skill入口（轻量封装）

本Skill使用

hooks/lib/

中的共享质量门禁库实现按需代码质量检查。

Anti-Pattern 5: Treating Quality Gate as Complete Verification

参考资料

What it looks like: Quality gate passes, user skips tests and code review Why wrong: Quality gates catch syntax and style issues, not logic errors, race conditions, or architectural problems. Do instead: Use quality gate as one layer. Also run tests, perform code review, and consider domain-specific checks.

本Skill使用了以下共享模式：

反合理化 - 防止寻找捷径的合理化借口
验证清单 - 完成前的检查项
门禁强制执行 - 阶段门禁标准

Architecture

领域特定反合理化

hooks/lib/
  quality_gate.py        # Shared core library
  language_registry.json # Language configurations

skills/universal-quality-gate/
  SKILL.md               # This file
  scripts/
    run_quality_gate.py  # Skill entry point (thin wrapper)

This skill uses the shared quality gate library from

hooks/lib/

for on-demand code quality checking.

合理化借口	错误原因	必需操作
“所有工具都通过了，代码可以提交了”	Linter只能捕获风格问题，无法发现逻辑问题	同时运行测试并审查代码
“工具被跳过了，应该没问题”	跳过工具意味着对应类别未被检查	安装工具或明确接受该风险
“只是格式问题，不是真正的bug”	不一致的格式会导致合并冲突	提交前修复格式问题
“要检查的文件太多了，跳过吧”	部分检查会带来虚假的安全感	使用--staged进行聚焦检查

References

—

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks
Gate Enforcement - Phase gate standards

—

Domain-Specific Anti-Rationalization

—

Rationalization	Why It's Wrong	Required Action
"All tools passed, code is ready"	Linters catch style, not logic	Run tests and review code too
"Tool was skipped, probably fine"	Skipped tool = unchecked category	Install tool or accept the gap explicitly
"Just formatting issues, not real problems"	Inconsistent formatting causes merge conflicts	Fix formatting before commit
"Too many files to check, skip it"	Partial checks give false confidence	Use --staged for focused checking

—