Skip to content
golang-lint logo

Go Linting

golang-lint

Linting best practices and golangci-lint configuration for Golang projects — running linters, configuring .golangci.yml, suppressing warnings with nolint directives, interpreting lint output, and selecting linters. Use when configuring golangci-lint, asking about lint warnings or nolint suppressions, setting up code quality tooling, or choosing linters. Also use when the user mentions golangci-lint, go vet, staticcheck, or revive.

SKILL.md

Full skill instructions

Persona: You are a Go code quality engineer. You treat linting as a first-class part of the development workflow — not a post-hoc cleanup step.

Orchestration mode: Use ultracode when adopting linting on a legacy codebase — orchestrate the five sub-agents described in the "Parallelizing Legacy Codebase Cleanup" section (auto-fix, security linters, error handling, style/​formatting, code quality) so independent linter categories are fixed concurrently.

Modes:

  • Setup mode — configuring .golangci.yml, choosing linters, enabling CI: follow the configuration and workflow sections sequentially.
  • Coding mode — writing new Go code: launch a background agent running golangci-lint run --fix on the modified files only while the main agent continues implementing the feature; surface results when it completes.
  • Interpret/​fix mode — reading lint output, suppressing warnings, fixing issues on existing code: start from "Interpreting Output" and "Suppressing Lint Warnings"; use parallel sub-agents for large-scale legacy cleanup.

Dependencies:

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

Go Linting

Overview

golangci-lint is the standard Go linting tool. It aggregates 100+ linters into a single binary, runs them in parallel, and provides a unified configuration format. Run it frequently during development and always in CI.

Every Go project MUST have a .golangci.yml — it is the source of truth for which linters are enabled and how they are configured. See the recommended configuration for a production-ready setup with 48 linters enabled.

Quick Reference

# 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 ./​...

Configuration

The recommended .golangci.yml provides a production-ready setup with 33 linters. For configuration details, linter categories, and per-linter descriptions, see the linter reference — which linters check for what (correctness, style, complexity, performance, security), descriptions of all 33+ linters, and when each one is useful.

Suppressing Lint Warnings

Use //nolint directives sparingly — fix the root cause first.

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

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

Rules:

  1. //nolint directives MUST specify the linter name: //nolint:errcheck not //nolint
  2. //nolint directives MUST include a justification comment: //nolint:errcheck // reason
  3. The nolintlint linter enforces both rules above — it flags bare //nolint and missing reasons
  4. NEVER suppress security linters (gosec, bodyclose, sqlclosecheck) without a very strong reason

For comprehensive patterns and examples, see nolint directives — when to suppress, how to write justifications, patterns for per-line vs per-function suppression, and anti-patterns.

Development Workflow

  1. Linters SHOULD be run after every significant change: golangci-lint run ./​...
  2. Auto-fix what you can: golangci-lint run --fix ./​...
  3. Format before committing: golangci-lint fmt ./​...
  4. Incremental adoption on legacy code: set issues.new-from-rev in .golangci.yml to only lint new/​changed code, then gradually clean up old code

Makefile targets (recommended):

lint:
	golangci-lint run ./​...

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

fmt:
	golangci-lint fmt ./​...

For CI pipeline setup (GitHub Actions with golangci-lint-action), see the samber/​cc-skills-golang@golang-continuous-integration skill.

Interpreting Output

Each issue follows this format:

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

The linter name in parentheses tells you which linter flagged it. Use this to:

  • Look up the linter in the reference to understand what it checks
  • Suppress with //nolint:linter-name // reason if it's a false positive
  • Use golangci-lint run --verbose for additional context and timing

Common Issues

ProblemSolution
"deadline exceeded"Set or increase run.timeout in .golangci.yml; golangci-lint v2 defaults to no timeout (0)
Too many issues on legacy codeSet issues.new-from-rev: HEAD~1 to lint only new code
Linter not foundCheck golangci-lint linters — linter may need a newer version
Conflicts between lintersDisable the less useful one with a comment explaining why
v1 config errors after upgradeRun golangci-lint migrate to convert config format
Slow on large reposReduce run.concurrency or exclude paths with linters.exclusions.paths / formatters.exclusions.paths

Parallelizing Legacy Codebase Cleanup

When adopting linting on a legacy codebase, use up to 5 parallel sub-agents (via the Agent tool) to fix independent linter categories simultaneously:

  • Sub-agent 1: Run golangci-lint run --fix ./​... for auto-fixable issues
  • Sub-agent 2: Fix security linter findings (bodyclose, sqlclosecheck, gosec)
  • Sub-agent 3: Fix error handling issues (errcheck, nilerr, wrapcheck)
  • Sub-agent 4: Fix style and formatting (gofumpt, goimports, revive)
  • Sub-agent 5: Fix code quality (gocritic, unused, ineffassign)

Cross-References

  • → See samber/​cc-skills-golang@golang-continuous-integration skill for CI pipeline with golangci-lint-action
  • → See samber/​cc-skills-golang@golang-code-style skill for style rules that linters enforce
  • → See samber/​cc-skills-golang@golang-security skill for SAST tools beyond linting (gosec, govulncheck)
  • → See samber/​cc-skills-golang@golang-continuous-integration skill for automated AI-driven code review in CI using these guidelines

More Code Review & Quality skills

azure-enterprise-infra-planner logo
Code Review & Quality

azure-enterprise-infra-planner

Enterprise Azure infrastructure architect generating Bicep or Terraform from workload descriptions.

1.5K 454.3K
View
caveman-review logo
Code Review & Quality

caveman-review

Ultra-compressed code review comments: location, problem, fix on one line each.

109.9K 388.8K
View
requesting-code-review logo
Code Review & Quality

requesting-code-review

Dispatch code review subagents with focused context to catch issues before they compound.

295.4K 245.8K
View
executing-plans logo
Code Review & Quality

executing-plans

Execute a written implementation plan with critical review and task checkpoints.

295.4K 229.1K
View
subagent-driven-development logo
Code Review & Quality

subagent-driven-development

Dispatch fresh subagents per task with two-stage review (spec compliance, then code quality) in the current session.

295.4K 221.7K
View
seo-audit logo
Code Review & Quality

seo-audit

Comprehensive SEO auditing framework covering crawlability, indexation, speed, on-page optimization, and content quality.

53.3K 220.8K
View
receiving-code-review logo
Code Review & Quality

receiving-code-review

Evaluate code review feedback with technical rigor before implementing, avoiding performative agreement and blind implementation.

295.4K 208.8K
View
gpt-image-2 logo
Code Review & Quality

gpt-image-2

Generate images via your ChatGPT subscription using text-to-image, image editing, and style transfer.

16 169.5K
View
mcp-builder logo
Code Review & Quality

mcp-builder

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

179.7K 122.7K
View
elevenlabs-music-generation logo
Code Review & Quality

elevenlabs-music-generation

Generate studio-quality songs and instrumentals from text descriptions, 5 seconds to 5 minutes, with section-level structure control.

52 116.9K
View
site-architecture logo
Code Review & Quality

site-architecture

Plan and optimize your website's page hierarchy, navigation, URL structure, and internal linking.

53.3K 112.8K
View
workers-best-practices logo
Code Review & Quality

workers-best-practices

Cloudflare Workers code review and authoring against production best practices.

3K 100.4K
View

Coding & apps AI tools

Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View
Imagica logo
Coding & apps

Imagica

Build a no-code AI app in minutes.

Freemium
View
E
Coding & apps

Emergent.sh

An IDE for code migration from legacy to modern frameworks through coding agents.

Freemium
View
Wonder Dynamics logo
Coding & apps

Wonder Dynamics

Automate CGI animation in live-action scenes

Paid
View
M
Coding & apps

Mixo

Launch a website in seconds with AI.

Paid
View
AI Code Convert logo
Coding & apps

AI Code Convert

Streamline Your Coding Experience with AI Code Helper

Free
View