golang-lint

角色： 你是一名 Go 代码质量工程师。你将 lint 视为开发工作流中的重要环节，而不是事后清理步骤。

编排模式： 在旧代码库中采用 lint 时，启动“并行处理旧代码库清理”一节中介绍的五个子 Agent（自动修复、安全 lint、错误处理、风格/格式、代码质量），让不同类别的 lint 并行修复。在 Claude Code 中，使用 ultracode 显式启用多 Agent 编排。

模式：

• 设置模式 — 配置 .golangci.yml、选择 lint、启用 CI：依次遵循配置和工作流章节。
• 编码模式 — 编写新的 Go 代码：启动后台 Agent，仅对修改过的文件运行 golangci-lint run --fix，同时主 Agent 继续实现功能；运行完成后展示结果。
• 解读/修复模式 — 阅读 lint 输出、抑制警告、修复现有代码中的问题：从“解读输出”和“抑制 lint 警告”开始；大规模清理旧代码时使用并行子 Agent。

依赖项：

• golangci-lint：go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Go Lint

概述

golangci-lint 是标准的 Go lint 工具。它将 100 多个 lint 工具整合到一个二进制文件中，并行运行这些工具，并提供统一的配置格式。开发期间应频繁运行，并始终在 CI 中运行。

每个 Go 项目都必须有一个 .golangci.yml — 它是启用哪些 lint 工具及其配置方式的唯一事实来源。生产环境就绪的配置启用了 48 个 lint 工具，请参阅推荐配置。

快速参考

# Run all configured linters
golangci-lint run ./...

# Auto-fix issues where possible
golangci-lint run --fix ./...

# Format code (golangci-lint v2+)
golangci-lint fmt ./...

# Run a single linter only
golangci-lint run --enable-only govet ./...

# List all available linters
golangci-lint linters

# Verbose output with timing info
golangci-lint run --verbose ./...

配置

推荐的 .golangci.yml提供了生产环境就绪的配置，包含 33 个 lint 工具。有关配置详情、lint 分类和各 lint 工具的说明，请参阅**lint 参考** — 了解各 lint 工具检查的内容（正确性、风格、复杂度、性能、安全性）、全部 33 个以上 lint 工具的说明，以及每个工具的适用场景。

抑制 Lint 警告

谨慎使用 //nolint 指令 — 请先修复根本原因。

// Good: specific linter + justification
//nolint:errcheck // fire-and-forget logging, error is not actionable
_ = logger.Sync()

// Bad: blanket suppression without reason
//nolint
_ = logger.Sync()

规则：

1. //nolint 指令必须指定 lint 工具名称：//nolint:errcheck，而不是 //nolint
2. //nolint 指令必须附带说明注释：//nolint:errcheck // reason
3. nolintlint lint 工具会强制执行上述两条规则 — 它会标记未指定 lint 工具名称的 //nolint 和缺少说明的指令
4. 绝不要在没有充分理由的情况下抑制安全 lint 工具（gosec、bodyclose、sqlclosecheck）

有关完整的模式和示例，请参阅**nolint 指令** — 了解何时抑制、如何撰写说明、逐行与逐函数抑制模式，以及反模式。

开发工作流

1. 每次重要更改后都应运行 lint 工具：golangci-lint run ./...
2. 尽可能自动修复：golangci-lint run --fix ./...
3. 提交前格式化：golangci-lint fmt ./...
4. 在旧代码库中逐步采用：在 .golangci.yml 中设置 issues.new-from-rev，仅对新增或更改的代码运行 lint，然后逐步清理旧代码

推荐的 Makefile 目标：

lint:
	golangci-lint run ./...

lint-fix:
	golangci-lint run --fix ./...

fmt:
	golangci-lint fmt ./...

有关 CI 流水线设置（使用 golangci-lint-action 的 GitHub Actions），请参阅 samber/cc-skills-golang@golang-continuous-integration 技能。

解读输出

每个问题都遵循以下格式：

path/to/file.go:42:10: message describing the issue (linter-name)

括号中的 lint 工具名称表示是哪一个工具标记了该问题。请据此：

• 在参考文档中查找该 lint 工具，了解它会检查什么
• 如果是误报，请使用 //nolint:linter-name // reason 抑制
• 使用 golangci-lint run --verbose 获取更多上下文和耗时信息

常见问题

问题	解决方案
"deadline exceeded"	在 .golangci.yml 中设置或增加 run.timeout；golangci-lint v2 默认不设置超时（0）
旧代码中问题过多	设置 issues.new-from-rev: HEAD~1，仅检查新代码
未找到 Linter	检查 golangci-lint linters——Linter 可能需要更新的版本
Linter 之间存在冲突	禁用较不实用的 Linter，并添加注释说明原因
升级后出现 v1 配置错误	运行 golangci-lint migrate 转换配置格式
大型仓库中运行缓慢	降低 run.concurrency，或使用 linters.exclusions.paths / formatters.exclusions.paths 排除路径

并行清理旧代码库

在旧代码库中采用 Lint 时，可使用最多 5 个并行子 Agent 同时修复互不相关的 Linter 类别：

• 子 Agent 1：运行 golangci-lint run --fix ./...，修复可自动修复的问题
• 子 Agent 2：修复安全 Linter 检查结果（bodyclose、sqlclosecheck、gosec）
• 子 Agent 3：修复错误处理问题（errcheck、nilerr、wrapcheck）
• 子 Agent 4：修复风格和格式问题（gofumpt、goimports、revive）
• 子 Agent 5：修复代码质量问题（gocritic、unused、ineffassign）

交叉引用

• → CI 流水线（使用 golangci-lint-action）请参阅 samber/cc-skills-golang@golang-continuous-integration 技能
• → Linter 强制执行的风格规则请参阅 samber/cc-skills-golang@golang-code-style 技能
• → 除 Lint 外的 SAST 工具（gosec、govulncheck）请参阅 samber/cc-skills-golang@golang-security 技能
• → 使用这些指南在 CI 中进行自动化 AI 驱动代码审查，请参阅 samber/cc-skills-golang@golang-continuous-integration 技能