golang-linter

版本、身份与核实范围

这是发布者更名前目录skills/golang-linter/SKILL.md的完整历史指南。PR19于2026-04-24 15:25:41 UTC合并，将目录改为golang-lint，主指南内容没有变化。本页引用更名前提交26524a3381ed93b43f5983c0e1dc53b0dd04af1d；当时文件元数据已经声明name: golang-lint，与原目录标识golang-linter不同，两者均按原样保留。2026-10-18 UTC核对完整正文和MIT许可，相对参考链接指向同一历史目录。文档中的版本、工具数量及用法仅代表该历史资料，当前安装和运行效果未实测；原目录的仓库、名称、安装命令与安装量不变。

核对的发布者原文

完整历史指南（Go Linting）

角色设定： 你是一名 Go 代码质量工程师。你将代码检查视为开发工作流中不可或缺的一环——而不是事后清理的步骤。

模式：

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

Go 代码检查

概述

golangci-lint 是标准的 Go 代码检查工具。它将 100 多个 linter 聚合到一个二进制文件中，并行运行它们，并提供统一的配置格式。在开发过程中要频繁运行，在 CI 中一定要运行。

每个 Go 项目必须有一个 .golangci.yml——它是启用哪些 linter 以及如何配置它们的唯一事实来源。参见推荐配置，了解启用了 33 个 linter 的、可用于生产的配置。

快速参考

# 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 个 linter 的、可用于生产的配置。关于配置细节、linter 类别以及每个 linter 的说明，请参见 linter 参考——其中说明了哪些 linter 检查什么内容（正确性、风格、复杂度、性能、安全性）、全部 33+ 个 linter 的说明，以及每个 linter 在何时有用。

抑制 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()

规则：

//nolint 指令必须指定 linter 名称：//nolint:errcheck 而不是 //nolint
//nolint 指令必须包含理由注释：//nolint:errcheck // reason
nolintlint linter 会强制执行上述两条规则——它会标记裸 //nolint 和缺失理由的情况
绝不能抑制安全类 linter（bodyclose、sqlclosecheck），除非有非常充分的理由

关于全面的模式与示例，请参见 nolint 指令——何时抑制、如何撰写理由、按行抑制与按函数抑制的模式，以及反面模式。

开发工作流

每次重要变更后应运行 linter：golangci-lint run ./...
尽可能自动修复：golangci-lint run --fix ./...
提交前格式化：golangci-lint fmt ./...
遗留代码的渐进式采用：在 .golangci.yml 中设置 issues.new-from-rev，只检查新增/变更的代码，然后逐步清理旧代码

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)

括号中的 linter 名称会告诉你哪个 linter 标记了它。据此可以：

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

常见问题

问题	解决方案
“deadline exceeded”	增大 `.golangci.yml` 中的 `run.timeout`（默认：5m）
遗留代码上问题太多	设置 `issues.new-from-rev: HEAD~1`，只检查新代码
找不到 linter	检查 `golangci-lint linters`——该 linter 可能需要更新版本
linter 之间冲突	禁用较不实用的那个，并用注释说明原因
升级后 v1 配置报错	运行 `golangci-lint migrate` 转换配置格式
大型仓库上速度慢	降低 `run.concurrency` 或在 `run.skip-dirs` 中排除目录

并行处理遗留代码库清理

在遗留代码库上采用代码检查时，最多使用 5 个并行子代理（通过 Agent 工具）同时修复相互独立的 linter 类别：

子代理 1：运行 golangci-lint run --fix ./... 处理可自动修复的问题
子代理 2：修复安全类 linter 的发现（bodyclose、sqlclosecheck、gosec）
子代理 3：修复错误处理问题（errcheck、nilerr、wrapcheck）
子代理 4：修复风格与格式化（gofumpt、goimports、revive）
子代理 5：修复代码质量（gocritic、unused、ineffassign）

交叉引用

→ 关于使用 golangci-lint-action 的 CI 流水线，请参见 samber/cc-skills-golang@golang-continuous-integration 技能
→ 关于 linter 强制执行的风格规则，请参见 samber/cc-skills-golang@golang-code-style 技能
→ 关于 linting 之外的 SAST 工具（gosec、govulncheck），请参见 samber/cc-skills-golang@golang-security 技能

原文元数据

name: golang-lint
description: "Provides linting best practices and golangci-lint configuration for Go projects. Covers running linters, configuring .golangci.yml, suppressing warnings with nolint directives, interpreting lint output, and managing linter settings. Use this skill whenever the user runs linters, configures golangci-lint, asks about lint warnings or suppressions, sets up code quality tooling, or asks which linters to enable for a Go project. Also use when the user mentions golangci-lint, go vet, staticcheck, revive, or any Go linting tool."
user-invocable: true
license: MIT
compatibility: Designed for Claude Code or similar AI coding agents, and for projects using Golang.
metadata:
  author: samber
  version: "1.1.1"
  openclaw:
    emoji: "🧹"
    homepage: https://github.com/samber/cc-skills-golang
    requires:
      bins:
        - go
        - golangci-lint
    install:
      - kind: brew
        formula: golangci-lint
        bins: [golangci-lint]
allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent

原作者与许可

MIT License

Copyright (c) 2026 Samuel Berthe

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.