go-code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Go Code Review Skill

Go代码审查技能

Operator Context

技能运行上下文

This skill operates as an operator for Go code review workflows, configuring Claude's behavior for systematic, read-only analysis of Go codebases and pull requests. It implements the Sequential Analysis architectural pattern -- gather context, run automated checks, analyze quality, report findings -- with Go Domain Intelligence embedded in every phase.

本技能作为Go代码审查工作流的操作组件，配置Claude的行为，以对Go代码库和拉取请求（PR）进行系统化的只读分析。它实现了顺序分析架构模式——收集背景信息、运行自动化检查、分析质量、报告结果——且每个阶段都嵌入了Go领域智能。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before reviewing
Over-Engineering Prevention: Report issues only. Do not suggest speculative improvements or "while reviewing" refactors
Read-Only Mode: NEVER modify code during review. Analyze, identify, report -- do not fix
All Phases Required: Complete all 6 review phases. No skipping, no shortcuts
Evidence-Based Findings: Every issue must reference file, line, and concrete impact
Compilation First: Run
```
go build ./...
```
before any linting or analysis commands

遵循CLAUDE.md规范：审查前需阅读并遵循仓库中的CLAUDE.md文件
避免过度设计：仅报告问题，不建议推测性改进或“审查时顺带”的重构
只读模式：审查过程中绝对不能修改代码。仅分析、识别、报告问题——不修复
必须完成所有阶段：完成全部6个审查阶段，不得跳过或走捷径
基于证据的结论：每个问题都必须关联文件、行号及具体影响
先编译再分析：在运行任何 lint 或分析命令前，先执行
```
go build ./...
```

Default Behaviors (ON unless disabled)

默认行为（除非禁用否则启用）

Automated Checks: Run go build, go test -race, go vet, and coverage analysis
Gopls MCP Analysis: Use gopls MCP tools when available:
```
go_workspace
```
for structure,
```
go_file_context
```
for dependencies,
```
go_symbol_references
```
for impact analysis,
```
go_diagnostics
```
for build errors (fallback to grep/LSP)
Priority Classification: Tag every finding as CRITICAL, HIGH, MEDIUM, or LOW
Structured Output: Use the PR Review Output Template for all reports
Cross-Platform Build: Verify compilation on linux, darwin, and windows
Module Verification: Run go mod verify and check for tidy state

自动化检查：运行go build、go test -race、go vet及覆盖率分析
Gopls MCP分析：若可用则使用Gopls MCP工具：
```
go_workspace
```
用于结构分析，
```
go_file_context
```
用于依赖分析，
```
go_symbol_references
```
用于影响分析，
```
go_diagnostics
```
用于构建错误（无工具时回退到grep/LSP）
优先级分类：将每个问题标记为CRITICAL（严重）、HIGH（高）、MEDIUM（中）或LOW（低）
结构化输出：所有报告均使用PR审查输出模板
跨平台构建验证：验证代码在linux、darwin和windows平台均可编译
模块验证：执行go mod verify并检查是否处于tidy状态

Optional Behaviors (OFF unless enabled)

可选行为（除非启用否则禁用）

Security Audit: Run gosec and perform deep security analysis
Benchmark Review: Evaluate benchmark coverage for performance-critical code
API Compatibility Check: Verify exported API changes against semver expectations
Dependency Audit: Deep review of new or changed dependencies

安全审计：运行gosec并执行深度安全分析
基准测试审查：评估性能关键代码的基准测试覆盖率
API兼容性检查：验证导出的API变更是否符合语义化版本（semver）预期
依赖审计：对新增或变更的依赖进行深度审查

Available Scripts

可用脚本

scripts/check-interface-compliance.sh
— Find exported interfaces missing compile-time

var _ I = (*T)(nil)

checks. Run

bash scripts/check-interface-compliance.sh --help

for options.

scripts/check-interface-compliance.sh
—— 查找缺少编译时

var _ I = (*T)(nil)

检查的导出接口。执行

bash scripts/check-interface-compliance.sh --help

查看选项。

What This Skill CAN Do

本技能可完成的任务

Systematically review Go code across 6 structured phases
Run automated checks (build, test, vet, staticcheck, coverage)
Use gopls MCP for semantic analysis (implementations, references, symbols, diagnostics, vulnerability checks)
Classify findings by severity with actionable recommendations
Produce structured review reports with executive summary and detailed analysis

按照6个结构化阶段系统化审查Go代码
运行自动化检查（构建、测试、vet、staticcheck、覆盖率）
使用Gopls MCP进行语义分析（实现、引用、符号、诊断、漏洞检查）
按严重程度分类问题并提供可操作的建议
生成包含执行摘要和详细分析的结构化审查报告

What This Skill CANNOT Do

本技能不可完成的任务

Modify, edit, or fix any code (reviewers report, they do not fix)
Replace domain-specific skills (use go-concurrency for concurrency design, go-error-handling for error patterns)
Skip phases or approve without completing all analysis areas
Guarantee security (use dedicated security audit tools for compliance)

修改、编辑或修复任何代码（审查者仅报告问题，不修复）
替代领域特定技能（并发设计请使用go-concurrency，错误模式请使用go-error-handling）
跳过阶段或未完成所有分析就批准
保证安全性（合规性检查请使用专用安全审计工具）

Instructions

操作指南

Phase 1: Context Understanding

阶段1：背景理解

Goal: Understand what changed and why before analyzing code.

Step 1: Review scope analysis

markdown

undefined

目标：在分析代码前，理解变更内容及变更原因。

步骤1：审查范围分析

markdown

undefined

Review: [PR/Change Title]

Problem solved: [what]
Expected behavior change: [what]
Linked issues: [references]
Testing strategy: [approach]


**Step 2: Change overview**
- List all modified files and packages
- Identify core changes vs supporting changes
- Note deleted code and understand why
- Check for generated or vendored code

**Gate**: Scope understood. Proceed only when clear on intent.

Problem solved: [what]
Expected behavior change: [what]
Linked issues: [references]
Testing strategy: [approach]


**步骤2：变更概述**
- 列出所有修改的文件和包
- 区分核心变更与辅助变更
- 记录删除的代码并理解原因
- 检查是否包含生成代码或vendor代码

**准入条件**：已理解范围。仅当明确变更意图后才可进入下一阶段。

Phase 2: Automated Checks

阶段2：自动化检查

Goal: Run all automated tools and capture outputs.

Step 1: Compilation and tests

bash

undefined

目标：运行所有自动化工具并捕获输出。

步骤1：编译与测试

bash

undefined

Verify compilation across platforms

GOOS=linux go build ./... GOOS=darwin go build ./... GOOS=windows go build ./...

Run tests with race detector

go test -race -count=1 -v ./...

Run tests with coverage

go test -coverprofile=coverage.out ./... go tool cover -func=coverage.out | tail -10


**Step 2: Static analysis**

```bash

go test -coverprofile=coverage.out ./... go tool cover -func=coverage.out | tail -10


**步骤2：静态分析**
```bash

Static analysis

go vet ./... staticcheck ./... # if available golangci-lint run # if available

Module integrity

go mod verify go mod tidy && git diff go.mod go.sum


**Step 3: Gopls-enhanced analysis (MUST use when available)**

**Prefer gopls MCP tools** (available when `.mcp.json` configures gopls):

go mod verify go mod tidy && git diff go.mod go.sum


**步骤3：Gopls增强分析（可用时必须使用）**
**优先使用Gopls MCP工具**（当`.mcp.json`配置了gopls时可用）：

Detect workspace structure (MUST run first)

go_workspace

Understand file dependencies after reading .go files (MUST use)

go_file_context({"file": "/path/to/changed_file.go"})

Find all references before modifying any symbol (MUST use)

go_symbol_references({"file": "/path/to/interface.go", "symbol": "Handler.ServeHTTP"})

Fuzzy search for symbols

go_search({"query": "Server"})

Check for build/analysis errors after edits (MUST use)

go_diagnostics({"files": ["/path/to/changed_file.go"]})

Inspect package public API

go_package_api({"packagePaths": ["example.com/internal/storage"]})


**Fallback (when gopls MCP unavailable)** — use LSP tool or CLI:
```bash

go_package_api({"packagePaths": ["example.com/internal/storage"]})


**回退方案（当Gopls MCP不可用时）**——使用LSP工具或命令行：
```bash

LSP tool: goToDefinition, findReferences, hover, documentSymbol

CLI fallback:

command -v gopls >/dev/null && echo "gopls available" || echo "gopls not found" gopls implementation path/to/interface.go:42:10 gopls references path/to/changed_function.go:100:5 gopls symbols path/to/changed_file.go


When gopls adds value:
- Interface changes: find all implementations that need updating
- Function signature changes: find all callers that may break
- Renaming proposals: verify safe rename with `go_symbol_references` first
- Post-edit verification: `go_diagnostics` catches errors before running full test suite

Fallback: If neither gopls MCP nor CLI is available, use grep-based searches but warn about potential false positives.

**Step 4: Security checks (if optional behavior enabled)**

```bash
gosec ./...  # if available

Gate: All automated outputs captured. Proceed with analysis.


当Gopls能带来价值时：
- 接口变更：查找所有需要更新的实现
- 函数签名变更：查找所有可能受影响的调用方
- 重命名建议：先使用`go_symbol_references`验证重命名是否安全
- 编辑后验证：`go_diagnostics`可在运行完整测试套件前捕获错误

回退方案：若Gopls MCP和命令行工具均不可用，可使用基于grep的搜索，但需在报告中警告可能存在误报。

**步骤4：安全检查（若启用可选行为）**
```bash
gosec ./...  # if available

准入条件：已捕获所有自动化工具的输出。进入分析阶段。

Phase 3: Code Quality Analysis

阶段3：代码质量分析

Goal: Evaluate architecture, idioms, and performance.

Architecture and Design:

SOLID principles followed?
Appropriate abstraction levels?
Clear separation of concerns?
Dependency injection used properly?
Interfaces focused and minimal?

Go Idioms and Best Practices:

Using
```
any
```
instead of
```
interface{}
```
?
Proper error handling with context?
Appropriate use of pointers vs values?
Channels used correctly?
Context propagation proper?

Performance Considerations:

Unnecessary allocations in loops?
String concatenation in loops (use strings.Builder)?
Improper use of defer in loops?
Missing buffer pooling for high-frequency allocations?
Unbuffered channels in producer-consumer patterns?

Gate: Quality areas assessed. Proceed to specific analysis.

目标：评估架构、惯用写法及性能。

架构与设计：

是否遵循SOLID原则？
抽象层级是否合适？
关注点是否清晰分离？
依赖注入是否正确使用？
接口是否聚焦且精简？

Go惯用写法与最佳实践：

是否使用
```
any
```
而非
```
interface{}
```
？
是否结合context进行正确的错误处理？
指针与值的使用是否恰当？
通道的使用是否正确？
Context传播是否合理？

性能考量：

循环中是否存在不必要的内存分配？
循环中是否使用字符串拼接（应使用strings.Builder）？
循环中是否不当使用defer？
高频分配场景是否缺少缓冲池？
生产者-消费者模式中是否使用无缓冲通道？

准入条件：已评估所有质量维度进入专项分析阶段。

Phase 4: Specific Analysis Areas

阶段4：专项分析领域

Review each area relevant to the changed code.

Concurrency Review:

Data races possible?
Proper synchronization (mutex, channels)?
Goroutine leaks prevented?
Context cancellation handled?
Deadlock potential?

Error Handling Review:

All errors checked or explicitly ignored?
Error messages provide context?
Wrapped appropriately with %w?
Custom error types when needed?
Sentinel errors properly defined?

Testing Review:

Test coverage adequate (aim for >80%)?
Table-driven tests used?
Edge cases covered?
Error conditions tested?
Benchmarks for performance-critical code?
Test helpers marked with t.Helper()?
No test interdependencies?

Security Review:

Input validation present?
SQL injection prevented?
Path traversal prevented?
Sensitive data not logged?
Crypto/rand used for security-critical randomness?
Time-constant comparisons for secrets?

Gate: All relevant analysis areas complete.

审查与变更代码相关的每个领域。

并发审查：

是否存在数据竞争可能？
是否使用了正确的同步机制（互斥锁、通道）？
是否防止了Goroutine泄漏？
Context取消是否正确处理？
是否存在死锁风险？

错误处理审查：

是否所有错误都已检查或显式忽略？
错误消息是否提供了足够上下文？
是否使用%w正确包装错误？
是否在需要时使用自定义错误类型？
是否正确定义了哨兵错误？

测试审查：

测试覆盖率是否足够（目标>80%）？
是否使用表驱动测试？
是否覆盖了边缘情况？
是否测试了错误场景？
性能关键代码是否有基准测试？
测试辅助函数是否标记了t.Helper()？
测试之间是否不存在依赖？

安全审查：

是否存在输入验证？
是否防止了SQL注入？
是否防止了路径遍历？
敏感数据是否未被记录？
安全关键的随机数是否使用了crypto/rand？
密码等敏感数据的比较是否使用了时间恒定的比较方式？

准入条件：所有相关分析领域已完成。

Phase 5: Line-by-Line Review

阶段5：逐行审查

Goal: Inspect each significant change individually.

For each significant change, ask:

Is the change necessary?
Is the implementation correct?
Are there edge cases missed?
Could this be simpler?
Will this be maintainable?
Performance implications?
Security implications?

Gate: All significant changes inspected.

目标：逐一检查每个重要变更。

对于每个重要变更，需询问：

该变更是否必要？
实现是否正确？
是否遗漏了边缘情况？
是否有更简洁的实现方式？
该代码是否易于维护？
存在哪些性能影响？
存在哪些安全影响？

准入条件：所有重要变更已检查。

Phase 6: Documentation Review

阶段6：文档审查

Package comments present and helpful?
Public APIs documented?
Complex algorithms explained?
Examples provided for public APIs?
README updated if needed?

Gate: Documentation assessed. Review complete. Generate report.

是否存在包注释且内容有用？
公共API是否有文档？
复杂算法是否有解释？
公共API是否提供了示例？
README是否需要更新？

准入条件：已评估文档。审查完成，生成报告。

Review Output Template

审查输出模板

markdown

undefined

markdown

undefined

PR Review: [Title]

Executive Summary

Risk Level: [LOW/MEDIUM/HIGH]
Recommendation: [Approve/Request Changes/Comment]
Key Finding: [Most important discovery]

Critical Positives:

[What was done well]

Areas for Improvement:

[Issues that need attention]

Risk Level: [LOW/MEDIUM/HIGH]
Recommendation: [Approve/Request Changes/Comment]
Key Finding: [Most important discovery]

Critical Positives:

[What was done well]

Areas for Improvement:

[Issues that need attention]

Detailed Analysis

1. Architecture & Design

Score: [A/B/C/D/F]

[pass/fail] Modern Go patterns
[pass/fail] Proper package structure
[pass/fail] Interface design
[pass/fail] SOLID principles

Score: [A/B/C/D/F]

[pass/fail] Modern Go patterns
[pass/fail] Proper package structure
[pass/fail] Interface design
[pass/fail] SOLID principles

2. Code Quality

Score: [A/B/C/D/F] [Code snippets showing excellent patterns and improvements needed]

3. Testing Strategy

Score: [A/B/C/D/F] Coverage: X%, Target: 80%+, Gaps: [areas needing tests]

4. Security & Performance

Score: [A/B/C/D/F]

Specific Issues

[CRITICAL] Issue Title

File:
```
path/to/file.go:123
```
Problem: [Explanation]
Impact: [What could go wrong]
Fix: [How to fix]

[HIGH/MEDIUM/LOW] Issue Title

File:
```
path/to/file.go:456
```
Details: [Explanation]
Suggestion: [Improvement]

[CRITICAL] Issue Title

File:
```
path/to/file.go:123
```
Problem: [Explanation]
Impact: [What could go wrong]
Fix: [How to fix]

[HIGH/MEDIUM/LOW] Issue Title

File:
```
path/to/file.go:456
```
Details: [Explanation]
Suggestion: [Improvement]

Recommendations

Must Fix Before Merge: [Critical issues]
Should Address: [Important improvements]
Consider for Future: [Nice to have]

Must Fix Before Merge: [Critical issues]
Should Address: [Important improvements]
Consider for Future: [Nice to have]

Final Assessment

[Summary with actionable next steps]

---

[Summary with actionable next steps]

---

Review Priority Guidelines

审查优先级指南

CRITICAL (Block Merge): Security vulnerabilities, data corruption risks, race conditions, memory leaks, breaking API changes, missing critical tests.

HIGH (Should Fix): Performance regressions, error handling gaps, concurrency issues, missing error context, inadequate test coverage.

MEDIUM (Recommend): Code style inconsistencies, missing documentation, suboptimal patterns, minor performance improvements.

LOW (Suggest): Naming improvements, code organization, additional examples, future refactoring opportunities.

CRITICAL（阻止合并）：安全漏洞、数据损坏风险、竞争条件、内存泄漏、破坏性API变更、缺失关键测试。

HIGH（应修复）：性能退化、错误处理漏洞、并发问题、错误上下文缺失、测试覆盖率不足。

MEDIUM（建议修复）：代码风格不一致、文档缺失、次优模式、 minor性能改进。

LOW（建议优化）：命名改进、代码组织、补充示例、未来重构机会。

Death Loop Prevention

死循环预防

NEVER make changes that cause compilation failures during review:

Channel Direction Changes: NEVER change
```
chan Type
```
to
```
<-chan Type
```
without verifying the function does not send or close
Function Signature Changes: NEVER change return types without updating ALL call sites
Compilation Before Linting: Run
```
go build ./...
```
FIRST. If code does not compile, report compilation errors before linting issues

审查过程中绝对不能做出导致编译失败的变更：

通道方向变更：绝对不能在未验证函数是否发送或关闭通道的情况下，将
```
chan Type
```
改为
```
<-chan Type
```
函数签名变更：绝对不能在未更新所有调用方的情况下修改返回类型
先编译再 lint：先执行
```
go build ./...
```
。若代码无法编译，需先报告编译错误，再处理lint问题

Error Handling

错误处理

Error: "Automated Tool Not Available"

错误："Automated Tool Not Available"

Cause: staticcheck, golangci-lint, gosec, or gopls not installed Solution:

Check tool availability with
```
command -v
```
Proceed with available tools (go build, go test, go vet are always present)
Note in report which tools were unavailable
Use grep-based fallback for gopls queries (warn about false positives)

原因：staticcheck、golangci-lint、gosec或gopls未安装解决方案：

使用
```
command -v
```
检查工具是否可用
使用可用工具继续（go build、go test、go vet始终可用）
在报告中注明哪些工具不可用
对于gopls查询，使用基于grep的回退方案（需警告可能存在误报）

Error: "Tests Fail on Current Code"

错误："Tests Fail on Current Code"

Cause: Tests were already broken before the PR changes Solution:

Run tests on the base branch to confirm pre-existing failures
Distinguish between pre-existing failures and newly introduced ones
Report new failures as findings; note pre-existing as context

原因：PR变更前测试已失败解决方案：

在基础分支上运行测试以确认是否为预先存在的失败
区分预先存在的失败与新引入的失败
将新失败作为问题报告；预先存在的失败作为上下文记录

Error: "Cannot Determine Change Scope"

错误："Cannot Determine Change Scope"

Cause: No clear PR description, unclear commit messages, or large diff Solution:

Read all changed files to infer intent
Check commit messages for context
Ask the user to clarify the change scope before proceeding

原因：PR描述不清晰、提交信息模糊或差异过大解决方案：

阅读所有变更文件以推断变更意图
检查提交信息以获取上下文
要求用户澄清变更范围后再继续

Anti-Patterns

反模式

Anti-Pattern 1: Fixing Code During Review

反模式1：审查时修复代码

What it looks like: Opening Edit tool to "quickly fix" a found issue Why wrong: Reviewer role is read-only. Fixing bypasses author ownership and testing. Do instead: Report the issue with file, line, impact, and suggested fix in the report.

表现：打开编辑工具以“快速修复”发现的问题 错误原因：审查者的角色是只读的。修复会绕过作者的所有权和测试流程。 正确做法：在报告中记录问题，包含文件、行号、影响及建议修复方案。

Anti-Pattern 2: Skipping Automated Checks

反模式2：跳过自动化检查

What it looks like: "I can see the code is fine, no need to run tests" Why wrong: Visual inspection misses race conditions, compilation errors, and edge cases. Do instead: Run ALL Phase 2 checks regardless of how "simple" the change looks.

表现：“我看代码没问题，没必要运行测试” 错误原因：视觉检查会遗漏竞争条件、编译错误和边缘情况。 正确做法：无论变更看起来多么“简单”，都必须运行所有阶段2的检查。

Anti-Pattern 3: Severity Downgrading to Avoid Conflict

反模式3：为避免冲突降低问题严重程度

What it looks like: Marking a logic bug as LOW because "the author will be upset" Why wrong: Severity is objective, not social. Logic bugs are HIGH or CRITICAL. Do instead: Classify severity honestly based on impact, not author relationship.

表现：将逻辑Bug标记为LOW，因为“作者会不高兴” 错误原因：严重程度是客观的，而非社交性的。逻辑Bug属于HIGH或CRITICAL级别。 正确做法：根据影响如实分类严重程度，而非考虑与作者的关系。

Anti-Pattern 4: Approving Small PRs Without Full Review

反模式4：未完成完整审查就批准小型PR

What it looks like: "It's only 10 lines, LGTM" Why wrong: Small changes cause large bugs. Config changes affect runtime behavior. Do instead: Complete all 6 phases regardless of PR size.

表现：“只有10行代码，批准通过” 错误原因：小变更可能导致大Bug。配置变更会影响运行时行为。 正确做法：无论PR大小，都必须完成所有6个阶段。

Anti-Pattern 5: Reviewing Only Changed Lines

反模式5：仅审查变更的代码行

What it looks like: Ignoring surrounding context of the changed code Why wrong: Changes may break invariants or assumptions in adjacent code. Do instead: Read enough surrounding context to understand the full impact.

表现：忽略变更代码的周围上下文 错误原因：变更可能破坏相邻代码中的不变量或假设。 正确做法：阅读足够的周围上下文以理解完整影响。

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization: Review - Review-specific rationalization prevention
Anti-Rationalization: Core - Universal shortcut prevention
Verification Checklist - Pre-completion checks
Severity Classification - Issue severity standards

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

Anti-Rationalization: Review - 审查专用的反合理化模式
Anti-Rationalization: Core - 通用的反捷径模式
Verification Checklist - 完成前检查清单
Severity Classification - 问题严重程度标准

Domain-Specific Anti-Rationalization

领域特定反合理化

Rationalization	Why It's Wrong	Required Action
"Tests pass, must be fine"	Tests can be incomplete or wrong	Review test coverage and quality too
"Small PR, quick review"	Small changes cause big bugs	Full 6-phase review regardless of size
"Author explained the logic"	Explanation does not equal correctness	Verify the code itself
"Just a refactor"	Refactors change behavior subtly	Verify behavior preserved with tests
"Trusted author"	Everyone makes mistakes	Same rigor for all authors

合理化借口	错误原因	要求的行动
“测试通过了，肯定没问题”	测试可能不完整或本身存在错误	同时审查测试覆盖率和质量
“PR很小，快速审查就行”	小变更可能导致大Bug	无论大小，都需完成完整的6阶段审查
“作者已经解释了逻辑”	解释不等于正确性	直接验证代码本身
“只是重构而已”	重构会微妙地改变行为	通过测试验证行为是否保持不变
“作者是可信的”	每个人都会犯错	对所有作者采用相同的审查严谨度

Reference Files

参考文件

```
${CLAUDE_SKILL_DIR}/references/common-review-comments.md
```
: Go code patterns with good/bad examples for error handling, concurrency, and testing

```
${CLAUDE_SKILL_DIR}/references/common-review-comments.md
```
：包含错误处理、并发和测试等方面的Go代码模式示例（含正确/错误示例）