在 Go 项目配置/运行 golangci-lint…

适用于 Go 项目采用 golangci-lint 做代码质量检查、配置 linter、处理告警与增量清理遗留代码。

适用场景

解决思路

1. 将 linting 作为开发工作流的一等公民，不要留到事后清理；频繁运行 `golangci-lint run ./...`，并在 CI 中始终运行。
2. 使用 `golangci-lint` 作为标准 Go linting 工具：它把 100+ 个 linter 聚合成单个二进制，并行运行，并提供统一配置格式。
3. 安装依赖：`go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest`。
4. 每个 Go 项目必须包含 `.golangci.yml`，它是启用哪些 linter 以及如何配置的 source of truth；参考推荐配置 `assets/.golangci.yml`（原文提到 production-ready 配置启用 48/33 个 linter）。
5. 运行所有已配置 linter：`golangci-lint run ./...`。
6. 自动修复：`golangci-lint run --fix ./...`。
7. 格式化代码（golangci-lint v2+）：`golangci-lint fmt ./...`。
8. 只运行单个 linter：`golangci-lint run --enable-only govet ./...`。
9. 列出所有可用 linter：`golangci-lint linters`。
10. 带耗时信息的 verbose 输出：`golangci-lint run --verbose ./...`。
11. 配置时参考 linter reference，了解配置细节、linter 类别（correctness、style、complexity、performance、security）、所有 33+ linter 的描述及各自适用场景。
12. Setup mode：配置 `.golangci.yml`、选择 linters、启用 CI 时，按 configuration 和 workflow 部分顺序执行。
13. Coding mode：编写新 Go 代码时，启动后台 agent 只对修改过的文件运行 `golangci-lint run --fix`，主 agent 继续实现功能；完成后展示结果。
14. Interpret/fix mode：阅读 lint 输出、抑制告警、修复已有代码问题时，从 Interpreting Output 和 Suppressing Lint Warnings 开始；大规模遗留清理使用并行 sub-agents。
15. 在遗留代码库采用 linting 时，分派最多 5 个并行 sub-agents 同时修复独立的 linter 类别；在 Claude Code 中用 `ultracode` 显式启用多 agent 编排。
16. 抑制 `//nolint` 要谨慎，先修根因。
17. 好的抑制写法：指定 linter + 理由，例如在 `_ = logger.Sync()` 前写 `//nolint:errcheck // fire-and-forget logging, error is not actionable`。
18. 坏的抑制写法：没有理由的全量抑制，例如在 `_ = logger.Sync()` 前写 `//nolint`。
19. 规则：`//nolint` 指令必须指定 linter 名，例如 `//nolint:errcheck`，不能写裸 `//nolint`。
20. 规则：`//nolint` 指令必须包含理由注释，例如 `//nolint:errcheck // reason`。
21. 规则：`nolintlint` linter 会强制检查上述两条规则，标记裸 `//nolint` 和缺少理由的情况。
22. 规则：绝不要在没有非常强理由时抑制安全 linter（`gosec`、`bodyclose`、`sqlclosecheck`）。
23. 参考 nolint directives reference，了解何时抑制、如何写理由、按行与按函数抑制的模式以及反模式。
24. 每次重要变更后都应该运行 linter：`golangci-lint run ./...`。
25. 尽可能自动修复：`golangci-lint run --fix ./...`。
26. 提交前格式化：`golangci-lint fmt ./...`。
27. 遗留代码增量采用时，在 `.golangci.yml` 设置 `issues.new-from-rev`，只 lint 新增/变更代码，再逐步清理旧代码。
28. 建议的 Makefile 目标： lint: golangci-lint run ./... lint-fix: golangci-lint run --fix ./... fmt: golangci-lint fmt ./...
29. 解释输出：每条 issue 格式为 `path/to/file.go:42:10: message describing the issue (linter-name)`。
30. 使用括号中的 linter 名：在 reference 中查该 linter 检查什么。
31. 使用括号中的 linter 名：若是误报，用 `//nolint:linter-name // reason` 抑制。
32. 使用括号中的 linter 名：需要额外上下文和耗时时，用 `golangci-lint run --verbose`。
33. 出现「deadline exceeded」时，在 `.golangci.yml` 设置或增大 `run.timeout`；golangci-lint v2 默认无超时（`0`）。
34. 遗留代码 issue 太多时，设置 `issues.new-from-rev: HEAD~1`，只 lint 新代码。
35. 出现「linter not found」时，检查 `golangci-lint linters`，可能需要更新版本。
36. linter 之间冲突时，禁用较不有用的那个，并用注释解释原因。
37. 升级后 v1 配置报错时，运行 `golangci-lint migrate` 转换配置格式。
38. 大仓库太慢时，降低 `run.concurrency` 或用 `linters.exclusions.paths` / `formatters.exclusions.paths` 排除路径。
39. 并行清理遗留代码库：Sub-agent 1：运行 `golangci-lint run --fix ./...` 处理可自动修复的问题。
40. Sub-agent 2：修复安全 linter 发现（`bodyclose`、`sqlclosecheck`、`gosec`）。
41. Sub-agent 3：修复错误处理问题（`errcheck`、`nilerr`、`wrapcheck`）。
42. Sub-agent 4：修复风格与格式化（`gofumpt`、`goimports`、`revive`）。
43. Sub-agent 5：修复代码质量（`gocritic`、`unused`、`ineffassign`）。

适用边界 · 注意事项

• 不适用于把 lint 步骤接入 GitHub Actions 流水线；应改用 `samber/cc-skills-golang@golang-continuous-integration` skill。
• 不适用于非 Go 项目，或没有安装 `go` / `golangci-lint` 的环境；需先安装依赖。
• 不适用于需要超出 linting 的 SAST（如 `govulncheck`）或仅需代码风格规范的情况；应结合安全或代码风格 skill。