go-quality-review
Review Go code for code quality, style, and modern Go practices including function length, nesting depth, naming, mutable globals, interface design, receiver consistency, modern Go idioms (slog, generics, typed atomics), and static analysis. Trigger when reviewing Go code structure, readability, or maintainability. Also runs golangci-lint for automated style checks.
johnqtcg · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add johnqtcg/awesome-skills --skill go-quality-review技能说明
name: go-quality-review description: Review Go code for code quality, style, and modern Go practices including function length, nesting depth, naming, mutable globals, interface design, receiver consistency, modern Go idioms (slog, generics, typed atomics), and static analysis. Trigger when reviewing Go code structure, readability, or maintainability. Also runs golangci-lint for automated style checks. allowed-tools: Read, Grep, Glob, Bash(go build*), Bash(go vet*), Bash(golangci-lint*), Bash(gofmt*), Bash(staticcheck*)
Go Quality Review
Purpose
Audit Go code for structural quality, style conformance, and modern Go practices. This skill is the designated lint-tool runner — other vertical review skills do NOT run golangci-lint/staticcheck/go vet, avoiding duplicate execution.
This skill does NOT cover: security, concurrency, performance, error handling, test quality, or business logic — those belong to sibling vertical skills.
When To Use
- Reviewing code structure and readability
- Checking Go naming conventions and package organization
- Evaluating use of modern Go features
- Need to run
golangci-lint/staticcheck/go vet
When NOT To Use
- Security vulnerabilities →
go-security-review - Concurrency safety →
go-concurrency-review - Error handling correctness →
go-error-review - Performance optimization →
go-performance-review - Business logic →
go-logic-review
Mandatory Gates
1) Go Version Gate
Read go.mod for go directive. Do NOT recommend features above project version.
| Feature | Minimum Go |
|---|---|
| Generics | 1.18 |
Typed atomics (atomic.Int64, atomic.Bool) | 1.19 |
slog, slices/maps packages, min/max builtins, sync.OnceValue/OnceFunc | 1.21 |
| Range-over-func, enhanced loop variable semantics | 1.22 |
iter.Seq, unique package | 1.23 |
2) Anti-Example Suppression Gate
MUST quote specific code evidence. Category match alone insufficient.
Embedded anti-examples:
- "Should use generics" — when only one concrete type used throughout codebase. Generics add complexity without benefit for single-type usage.
- "Should use slog" — when project targets Go < 1.21. Version-inappropriate recommendation.
- "Should use typed atomics" — when project targets Go < 1.19.
- "Exported function missing godoc" — when symbol is in
internal/package not intended for external consumers. - "Function too long (>50 lines)" — when body is a straightforward table-driven switch, sequential pipeline with no nesting, or single select/case block. These are long but simple.
- "interface{} should be any" — pure cosmetic alias rename. Report only as part of broader modernization effort, never as standalone finding.
- "Should extract helper function" — when the code would only be called from one place and extraction reduces readability by splitting context.
3) Static Analysis Execution Protocol
Run lint tools in this priority order:
- Check for
.golangci.yml/.golangci.yaml— respect project config golangci-lint run(config-aware)staticcheck ./...(if golangci-lint unavailable)go vet ./...(minimal fallback) Report tool output in Execution Status. If no tools available, stateNot available. Dedup rule: same location + same issue from multiple tools = report once.
4) Generated Code Exclusion Gate
Exclude: *.pb.go, *_gen.go, mock_*.go, *_string.go, *_enumer.go. Note excluded files in Execution Status.
Workflow
- Define scope — files/diff under review. Apply Generated Code Exclusion Gate.
- Check Go version from
go.mod— gate all modern Go recommendations. - Run static analysis — follow execution protocol above. Record output.
- Gather evidence — read changed files, identify quality/style patterns.
- Load references — always load
go-error-and-quality.md(quality sections); loadgo-modern-practices.mdwhen modern Go features relevant. - Evaluate ALL 13 checklist items → cross-reference with lint output → suppress anti-examples → format.
Grep-Gated Execution Protocol
This skill uses mechanical grep pre-scanning to guarantee zero missed checklist items. 8 of 13 items are grep-gated; 5 are semantic-only.
Execution Order
- Identify target files (from dispatch prompt, or write raw snippet to
$TMPDIR/review_snippet.go) - Run grep for all grep-gated checklist items against target files
- HIT → run semantic analysis to confirm or reject
- MISS → auto-mark NOT FOUND, skip semantic analysis
- For semantic-only items (items 1, 2, 5, 9, 13): full model reasoning — these require structural analysis
- Report only FOUND items
Grep Audit Line
Include in Execution Status: Grep pre-scan: X/8 items hit, Z confirmed as findings (5 semantic-only)
Quality Checklist (12 Items)
All Medium severity unless marked (Low).
| # | Item | Pattern | Grep Pattern |
|---|---|---|---|
| 1 | Function too long | > 50 lines → extract helper (see anti-example for flat switch exception) | Semantic-Only (function length requires counting lines — no grep pattern) |
| 2 | Excessive nesting | > 4 levels → early return pattern ("happy path left-aligned") | Semantic-Only (nesting depth requires counting indent levels) |
| 3 | Naked return | In functions > 5 lines → explicit returns for clarity | return$|return\s*$ (naked return — grep for return with nothing after) |
| 4 | Mutable global variable | Mutable var at package level → const, getter, or functional options | ^var\s+\w (package-level var declarations — grep at file scope) |
| 5 | Interface bloat | Interface > 3 methods or defined at implementation site → small interfaces at consumer site | Semantic-Only (interface bloat requires counting methods) |
| 6 | Type assertion without ok | x.(T) without comma-ok → x, ok := x.(T) — panics on wrong type | \.\(\w (type assertion without comma-ok |