go-pr-quality-gate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Go PR Quality Gate Skill

Go PR质量门禁技能

Operator Context

技能运行背景

This skill operates as an operator for Go quality validation workflows, configuring Claude's behavior for automated code quality checking. It implements the Deterministic Execution pattern --

make check

is the single source of truth, the skill parses and categorizes output into actionable feedback.

本技能作为Go质量验证工作流的执行器，配置Claude的自动化代码质量检查行为。它实现了确定性执行模式——

make check

是唯一可信来源，技能会解析输出并分类为可执行的反馈。

Hardcoded Behaviors (Always Apply)

固定行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before execution
Over-Engineering Prevention: Only run the checks requested. No speculative analysis, no additional tooling beyond what
```
make check
```
provides
Deterministic Execution: Always use
```
make check
```
as the single source of truth. No custom check orchestration or tool selection logic
Exit Code Fidelity: Report exact exit codes and status from make. Never mask or modify build tool results
Validate First: Always validate repository prerequisites (go.mod, Makefile) before running checks
Incremental Fixes: Apply one category of fixes at a time, re-run checks after each

CLAUDE.md 合规性：执行前读取并遵循仓库的CLAUDE.md文件
避免过度设计：仅运行请求的检查。不进行推测性分析，不使用
```
make check
```
以外的额外工具
确定性执行：始终将
```
make check
```
作为唯一可信来源。不自定义检查编排或工具选择逻辑
退出码保真：准确报告make的退出码和状态。绝不掩盖或修改构建工具的结果
前置验证：运行检查前始终验证仓库前置条件（go.mod、Makefile）
增量修复：每次仅应用一类修复，修复后重新运行检查

Default Behaviors (ON unless disabled)

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

Communication Style: Report facts without self-congratulation. Show exact error messages and locations. Be concise but informative
Temporary File Cleanup: Remove temporary analysis files and debug logs at completion. Keep only files needed for user review
Error Categorization: Group errors by type (linting, tests, build) with actionable fix suggestions
Coverage Reporting: Extract and report test coverage percentage from check output
Progressive Output: Stream progress updates as checks run

沟通风格：只报告事实，不自我夸耀。显示精确的错误信息和位置。简洁且信息完整
临时文件清理：完成后删除临时分析文件和调试日志。仅保留用户评审所需的文件
错误分类：按类型（检查、测试、构建）分组错误，并提供可执行的修复建议
覆盖率报告：从检查输出中提取并报告测试覆盖率百分比
渐进式输出：检查运行时流式输出进度更新

Optional Behaviors (OFF unless enabled)

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

Verbose Debug Mode: Available via
```
--verbose
```
flag for troubleshooting
Custom Coverage Thresholds: Available via
```
--min-coverage
```
flag for stricter validation
JSON-Only Output: Available via
```
--format json
```
for automation pipelines

详细调试模式：通过
```
--verbose
```
标志启用，用于故障排查
自定义覆盖率阈值：通过
```
--min-coverage
```
标志启用，用于更严格的验证
仅JSON输出：通过
```
--format json
```
标志启用，适用于自动化流水线

What This Skill CAN Do

本技能可实现的功能

Run
```
make check
```
and parse results into categorized, actionable output
Categorize linting, test, and build errors by type and severity
Extract coverage percentages from test output
Suggest make targets for common fix patterns (goimports, tidy-deps, license-headers)
Validate repository prerequisites (go.mod, Makefile, git)
Generate structured JSON reports for automation

运行
```
make check
```
并将结果解析为分类后的可执行输出
按类型和严重程度分类检查、测试和构建错误
从测试输出中提取覆盖率百分比
针对常见修复模式建议make目标（goimports、tidy-deps、license-headers）
验证仓库前置条件（go.mod、Makefile、git）
为自动化流水线生成结构化JSON报告

What This Skill CANNOT Do

本技能无法实现的功能

Fix code automatically -- identifies issues and suggests make targets only
Run custom linters -- only works with linters configured in the repository's
```
make check
```
target
Modify Makefile -- requires an existing
```
make check
```
target
Run checks incrementally -- executes full
```
make check
```
suite, not individual file checks
Interpret business logic errors -- provides technical categorization, not domain debugging

自动修复代码——仅识别问题并建议make目标
运行自定义检查器——仅与仓库
```
make check
```
目标中配置的检查器配合工作
修改Makefile——要求仓库已存在
```
make check
```
目标
增量运行检查——执行完整的
```
make check
```
套件，而非单个文件检查
解释业务逻辑错误——仅提供技术分类，不进行领域调试

Instructions

使用说明

Prerequisites

前置条件

Go repository with
```
go.mod
```
at root
Repository has
```
Makefile
```
with
```
check
```
target
Works best with Makefile-based build workflow repositories

根目录下有
```
go.mod
```
的Go仓库
仓库包含带有
```
check
```
目标的Makefile
最适用于基于Makefile构建工作流的仓库

Step 1: Validate Repository Context

步骤1：验证仓库上下文

Run the validation script to check prerequisites:

bash

python3 ~/.claude/skills/go-pr-quality-gate/scripts/quality_checker.py --validate-only

Expected success output:

json

{
  "status": "valid",
  "repository": "/path/to/repo",
  "has_gomod": true,
  "has_makefile": true,
  "is_gomakefilemaker": true
}

If validation fails:

"Not a Go repository": Navigate to a directory with
```
go.mod
```
"Makefile not found": Repository may need a Makefile-based build workflow setup
"Not in git repository": Initialize git or navigate to repo root

Gate: Validation returns

"status": "valid"

. Proceed only when gate passes.

运行验证脚本检查前置条件：

bash

python3 ~/.claude/skills/go-pr-quality-gate/scripts/quality_checker.py --validate-only

预期成功输出：

json

{
  "status": "valid",
  "repository": "/path/to/repo",
  "has_gomod": true,
  "has_makefile": true,
  "is_gomakefilemaker": true
}

如果验证失败：

"Not a Go repository"：导航到包含
```
go.mod
```
的目录
"Makefile not found"：仓库可能需要配置基于Makefile的构建工作流
"Not in git repository"：初始化git或导航到仓库根目录

门禁要求：验证返回

"status": "valid"

。仅当门禁通过时才可继续。

Step 2: Run Quality Checks

步骤2：运行质量检查

Execute comprehensive quality gate:

bash

python3 ~/.claude/skills/go-pr-quality-gate/scripts/quality_checker.py

The script will:

Run
```
make check
```
(static analysis + tests)
Parse output for errors and coverage
Categorize any failures
Generate actionable report with fix suggestions

For verbose progress output:

bash

python3 ~/.claude/skills/go-pr-quality-gate/scripts/quality_checker.py --verbose

执行全面质量门禁检查：

bash

python3 ~/.claude/skills/go-pr-quality-gate/scripts/quality_checker.py

脚本将：

运行
```
make check
```
（静态分析+测试）
解析输出中的错误和覆盖率
分类所有失败项
生成包含修复建议的可执行报告

如需查看详细进度输出：

bash

python3 ~/.claude/skills/go-pr-quality-gate/scripts/quality_checker.py --verbose

Step 3: Interpret Results

步骤3：解读结果

Success Scenario

成功场景

Success output format:

json

{
  "status": "success",
  "coverage": "87.3%",
  "checks_passed": ["static-check", "test", "coverage"],
  "summary": "All quality checks passed"
}

When successful:

Acknowledge passing checks
Report coverage percentage
Suggest next steps: view detailed coverage (
```
open build/cover.html
```
), create commit, or run specific checks

成功输出格式：

json

{
  "status": "success",
  "coverage": "87.3%",
  "checks_passed": ["static-check", "test", "coverage"],
  "summary": "All quality checks passed"
}

成功时：

确认所有检查通过
报告覆盖率百分比
建议下一步操作：查看详细覆盖率报告（
```
open build/cover.html
```
）、提交代码或运行特定检查

Failure Scenario

失败场景

Failure output format:

json

{
  "status": "failed",
  "exit_code": 2,
  "errors": {
    "linting": [{"linter": "errcheck", "file": "pkg/api/handler.go", "line": 45, "message": "Error return value not checked", "severity": "high"}],
    "tests": [{"package": "github.com/example/pkg/service", "test": "TestProcessRequest", "error": "expected 200, got 500"}]
  },
  "fix_commands": ["make goimports", "make tidy-deps"]
}

When failures occur:

Categorize errors by type (linting, tests, build, license)
Group linting errors by linter name (errcheck, gosec, govet, etc.)
Show actionable fixes using the structured output:
- Import issues:
```
make goimports
```
- Dependency issues:
```
make tidy-deps
```
- License headers:
```
make license-headers
```
- Specific linter guidance: check
```
references/common-lint-errors.json
```
Provide context: file paths, line numbers, error descriptions
Suggest incremental fixes: one make target at a time

失败输出格式：

json

{
  "status": "failed",
  "exit_code": 2,
  "errors": {
    "linting": [{"linter": "errcheck", "file": "pkg/api/handler.go", "line": 45, "message": "Error return value not checked", "severity": "high"}],
    "tests": [{"package": "github.com/example/pkg/service", "test": "TestProcessRequest", "error": "expected 200, got 500"}]
  },
  "fix_commands": ["make goimports", "make tidy-deps"]
}

失败时：

分类错误：按类型（检查、测试、构建、许可证）分组
分组检查错误：按检查器名称（errcheck、gosec、govet等）分组
展示可执行修复方案：使用结构化输出：
- 导入问题：
```
make goimports
```
- 依赖问题：
```
make tidy-deps
```
- 许可证头：
```
make license-headers
```
- 特定检查器指南：查看
```
references/common-lint-errors.json
```
提供上下文：文件路径、行号、错误描述
建议增量修复：每次运行一个make目标

Step 4: Apply Suggested Fixes

步骤4：应用建议的修复方案

For common error patterns, run suggested make targets one at a time:

bash

undefined

针对常见错误模式，逐个运行建议的make目标：

bash

undefined

Fix import formatting

修复导入格式

make goimports

Fix dependency issues

修复依赖问题

make tidy-deps

Add/update license headers

添加/更新许可证头

make license-headers


After each fix, re-run quality checks (Step 2) to verify resolution.

**Gate**: All checks pass (exit code 0). Coverage meets baseline. No linting errors. All tests pass.

make license-headers


每次修复后，重新运行质量检查（步骤2）以验证问题已解决。

**门禁要求**：所有检查通过（退出码0）。覆盖率符合基线。无检查错误。所有测试通过。

Step 5: Detailed Investigation (Optional)

步骤5：详细排查（可选）

For complex failures, use specific make targets:

bash

undefined

针对复杂失败，使用特定的make目标：

bash

undefined

Run only static analysis

仅运行静态分析

make static-check

Run only tests

仅运行测试

make test

Run specific test with verbose output

运行特定测试并查看详细输出

go test -v -run TestSpecificTest ./pkg/service

View HTML coverage report

查看HTML覆盖率报告

open build/cover.html

undefined

open build/cover.html

undefined

Advanced Options

高级选项

Custom coverage threshold enforcement:

bash

python3 ~/.claude/skills/go-pr-quality-gate/scripts/quality_checker.py --min-coverage 80.0

JSON output for automation pipelines:

bash

python3 ~/.claude/skills/go-pr-quality-gate/scripts/quality_checker.py --format json

Combined options for thorough debugging:

bash

python3 ~/.claude/skills/go-pr-quality-gate/scripts/quality_checker.py --min-coverage 80.0 --verbose

自定义覆盖率阈值强制检查：

bash

python3 ~/.claude/skills/go-pr-quality-gate/scripts/quality_checker.py --min-coverage 80.0

为自动化流水线生成JSON输出：

bash

python3 ~/.claude/skills/go-pr-quality-gate/scripts/quality_checker.py --format json

组合选项进行全面调试：

bash

python3 ~/.claude/skills/go-pr-quality-gate/scripts/quality_checker.py --min-coverage 80.0 --verbose

Examples

示例

Example 1: Clean Quality Check

示例1：无问题的质量检查

User says: "Run quality checks before I create a PR" Actions:

Validate repository context (Step 1)
Run
```
make check
```
via quality_checker.py (Step 2)
Report all checks passed with coverage percentage (Step 3)
Suggest creating commit Result: Clean quality gate, ready for PR

用户说："提交PR前运行质量检查" 操作：

验证仓库上下文（步骤一）
通过quality_checker.py运行
```
make check
```
（步骤二）
报告所有检查通过及覆盖率百分比（步骤三）
建议提交代码结果：质量门禁检查通过，可提交PR

Example 2: Linting Failures with Auto-Fix

示例2：存在检查失败且可自动修复

User says: "Check code quality" Actions:

Validate, run checks -- import and license errors found
Report categorized errors with fix commands
Run
```
make goimports
```
then
```
make license-headers
```
Re-run checks to verify resolution Result: Issues fixed incrementally, all checks pass

用户说："检查代码质量" 操作：

验证并运行检查——发现导入和许可证错误
报告分类后的错误及修复命令
运行
```
make goimports
```
，再运行
```
make license-headers
```
重新运行检查以验证问题已解决结果：问题已逐步修复，所有检查通过

Example 3: Test Failures

示例3：测试失败

User says: "Why are the checks failing?" Actions:

Run quality checks -- test failures detected
Report failing test names and packages
Suggest running specific test with verbose output for details
After user fixes, re-run to verify Result: Test failures identified with actionable debug steps

用户说："为什么检查失败了？" 操作：

运行质量检查——检测到测试失败
报告失败的测试名称和包
建议运行特定测试并查看详细输出以排查问题
用户修复后，重新运行检查验证结果：已定位测试失败原因，并提供可执行的调试步骤

Error Handling

错误处理

Error: "make: *** [check] Error 2"

错误："make: *** [check] Error 2"

Cause: One or more quality checks failed (linting, tests, or build) Solution:

Review error categorization in JSON output
Apply suggested fixes from
```
fix_commands
```
array
Check
```
references/common-lint-errors.json
```
for specific linter guidance
Re-run checks after each fix

原因：一项或多项质量检查失败（检查、测试或构建）解决方案：

查看JSON输出中的错误分类
应用
```
fix_commands
```
数组中的建议修复方案
查看
```
references/common-lint-errors.json
```
获取特定检查器指南
每次修复后重新运行检查

Error: "golangci-lint: command not found"

错误："golangci-lint: command not found"

Cause: Static analysis tools not installed on the system Solution:

Install via package manager:
```
brew install golangci-lint
```
Or use project's install script if available
Verify with:
```
golangci-lint --version
```

原因：系统未安装静态分析工具解决方案：

通过包管理器安装：
```
brew install golangci-lint
```
或使用项目提供的安装脚本（若有）
验证安装：
```
golangci-lint --version
```

Error: "coverage: 0.0% of statements"

错误："coverage: 0.0% of statements"

Cause: No test files exist, or test packages have no executable tests Solution:

Verify test files exist: look for
```
*_test.go
```
files
Verify tests run independently:
```
make test
```
Check that test functions follow
```
Test
```
naming convention

原因：不存在测试文件，或测试包中无可执行测试解决方案：

验证测试文件存在：查找
```
*_test.go
```
文件
验证测试可独立运行：
```
make test
```
检查测试函数是否遵循
```
Test
```
命名规范

Error: Script Times Out

错误：脚本超时

Cause: Tests hang, infinite loops, or blocking external dependencies Solution:

Run individual targets to isolate:
```
make static-check
```
,
```
make test
```
Check for hanging tests or external service dependencies
Run specific test in isolation:
```
go test -v -run TestName ./pkg/...
```

原因：测试挂起、无限循环或依赖外部阻塞服务解决方案：

运行单个目标以隔离问题：
```
make static-check
```
、
```
make test
```
检查是否存在挂起测试或外部服务依赖
单独运行特定测试：
```
go test -v -run TestName ./pkg/...
```

Anti-Patterns

反模式

Anti-Pattern 1: Running Checks Without Validation

反模式1：未验证直接运行检查

What it looks like: Immediately running quality_checker.py without checking for go.mod and Makefile Why wrong: Fails with cryptic errors. Wastes time debugging environment instead of code quality. Do instead: Always run Step 1 validation first. The

--validate-only

flag exists for this purpose.

表现：未检查go.mod和Makefile就直接运行quality_checker.py 危害：会出现模糊的错误信息。浪费时间排查环境问题而非代码质量问题。 正确做法：始终先运行步骤一的验证。

--validate-only

标志就是为此设计的。

Anti-Pattern 2: Fixing All Errors Simultaneously

反模式2：同时修复所有错误

What it looks like: "I see 15 linting errors, let me fix them all at once across multiple files" Why wrong: Multiple concurrent changes are hard to review. If one fix is wrong, all changes need rollback. Cannot verify which fix resolved which error. Do instead: Apply one category of fixes at a time. Run

make goimports

, re-run checks, then fix next category.

表现："我看到15个检查错误，我要同时修改多个文件中的所有错误" 危害：同时进行多项变更难以评审。若其中一个修复错误，所有变更都需要回滚。无法验证哪个修复解决了哪个错误。 正确做法：每次只修复一类错误。先运行

make goimports

，重新运行检查，再修复下一类错误。

Anti-Pattern 3: Bypassing make check with Individual Tools

反模式3：绕过make check直接使用单个工具

What it looks like: Running golangci-lint, go test, go vet separately instead of

make check

Why wrong: Bypasses repository's configured quality gates. May miss checks the Makefile includes. Different projects have different configurations. Do instead: Always use

make check

as single source of truth. Only run individual make targets for focused investigation after a check fails.

表现：单独运行golangci-lint、go test、go vet而非

make check

危害：绕过了仓库配置的质量门禁。可能遗漏Makefile中包含的检查。不同项目有不同的配置。 正确做法：始终将

make check

作为唯一可信来源。仅在检查失败后，为了集中排查才运行单个make目标。

Anti-Pattern 4: Ignoring Coverage in Results

反模式4：忽略结果中的覆盖率

What it looks like: "All tests pass!" without mentioning that coverage dropped from 85% to 45% Why wrong: Coverage regression indicates untested code paths. New code without tests reduces overall quality. Do instead: Always report coverage percentage. Highlight changes if baseline is known. Use

--min-coverage

for threshold enforcement.

表现："所有测试通过！"但未提及覆盖率从85%降至45% 危害：覆盖率倒退意味着存在未测试的代码路径。无测试的新代码会降低整体质量。 正确做法：始终报告覆盖率百分比。若已知基线，需突出变化。使用

--min-coverage

强制检查阈值。

Anti-Pattern 5: Over-Explaining Linter Errors

反模式5：过度解释检查器错误

What it looks like: Writing paragraphs about Go error handling philosophy when errcheck reports an unchecked return Why wrong: User asked for quality check, not a tutorial. The script already provides fix suggestions. Delays actionable response. Do instead: Report the specific error with location, show the fix suggestion from script output, explain only if the user asks.

表现：当errcheck报告未检查返回值时，大段讲解Go错误处理理念危害：用户请求的是质量检查，而非教程。脚本已提供修复建议。会延迟可执行响应。 正确做法：报告具体错误及位置，显示脚本输出中的修复建议，仅在用户询问时才进行解释。

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks

本技能使用以下共享模式：

反合理化 - 避免找借口走捷径
验证清单 - 完成前检查

Domain-Specific Anti-Rationalization

领域特定反合理化

Rationalization	Why It's Wrong	Required Action
"make check is slow, I'll just run go vet"	Skips configured quality gates	Run full `make check`
"Coverage is fine, no need to report it"	Hides regression information	Always report coverage
"I know what the error is, skip validation"	Assumptions miss prerequisites	Validate repository first
"One big fix is faster than incremental"	Can't verify individual fixes	Fix one category at a time

合理化借口	危害	要求操作
"make check太慢了，我只运行go vet"	跳过了配置的质量门禁	运行完整的 `make check`
"覆盖率没问题，不用报告"	隐藏了倒退信息	始终报告覆盖率
"我知道错误是什么，跳过验证"	主观假设会遗漏前置条件	先验证仓库
"一次性修复比增量修复更快"	无法验证单个修复的有效性	每次修复一类错误

Reference Files

参考文件

${CLAUDE_SKILL_DIR}/references/common-lint-errors.json

: Linter descriptions, severities, and fix suggestions

${CLAUDE_SKILL_DIR}/references/makefile-targets.json

: Available make targets and when to use them

${CLAUDE_SKILL_DIR}/references/expert-review-patterns.md

: Manual review patterns beyond automated linting

```
${CLAUDE_SKILL_DIR}/references/examples.md
```
: Detailed usage examples with expected output

${CLAUDE_SKILL_DIR}/references/common-lint-errors.json

：检查器描述、严重程度和修复建议

${CLAUDE_SKILL_DIR}/references/makefile-targets.json

：可用的make目标及使用场景

${CLAUDE_SKILL_DIR}/references/expert-review-patterns.md

：自动化检查之外的手动评审模式

${CLAUDE_SKILL_DIR}/references/examples.md

：详细使用示例及预期输出