golang-lint

ペルソナ： Go コード品質エンジニアです。Lint は後から行うクリーンアップ作業ではなく、開発ワークフローの中核として扱います。

オーケストレーションモード： レガシーコードベースに Lint を導入する際は、「レガシーコードベースのクリーンアップの並列化」セクションで説明している 5 つのサブエージェント（自動修正、セキュリティリンター、エラー処理、スタイル／フォーマット、コード品質）に作業を振り分け、独立したリンターのカテゴリを並行して修正します。Claude Code では、ultracode を使用してマルチエージェントのオーケストレーションを明示的に有効にします。

モード：

• セットアップモード — .golangci.yml の設定、リンターの選定、CI の有効化：設定とワークフローの各セクションに順番に従います。
• コーディングモード — 新しい Go コードの作成：バックグラウンドエージェントを起動して、変更したファイルだけに対して golangci-lint run --fix を実行し、その間、メインエージェントは機能の実装を続けます。完了したら結果を提示します。
• 解釈／修正モード — Lint の出力の確認、警告の抑制、既存コードの問題の修正：「出力の解釈」と「Lint 警告の抑制」から始めます。大規模なレガシーコードのクリーンアップには、並列のサブエージェントを使用します。

依存関係：

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

Go の Lint

概要

golangci-lint は標準的な Go の Lint ツールです。100 以上のリンターを単一のバイナリに集約し、並列で実行するとともに、統一された設定形式を提供します。開発中は頻繁に実行し、CI では必ず実行してください。

すべての Go プロジェクトには .golangci.yml が必須です。どのリンターを有効にし、どう設定するかを決める信頼できる唯一の情報源になります。本番環境向けの 48 個のリンターを有効にした設定については、推奨設定を参照してください。

クイックリファレンス

# 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 個のリンターを含む本番環境向けの設定です。設定の詳細、リンターのカテゴリ、各リンターの説明については、**リンターリファレンス**を参照してください。ここでは、各リンターが何を検査するか（正確性、スタイル、複雑さ、パフォーマンス、セキュリティ）、33 個以上のリンターの説明、各リンターが役立つ場面を紹介しています。

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 ディレクティブには、必ずリンター名を指定してください：//nolint ではなく //nolint:errcheck とします
2. //nolint ディレクティブには、必ず理由をコメントで記載してください：//nolint:errcheck // 理由
3. nolintlint リンターは上記の両方のルールを適用します — //nolint だけの指定や、理由の欠落を検出します
4. 非常に強い理由がない限り、セキュリティリンター（gosec、bodyclose、sqlclosecheck）を絶対に抑制しないでください

詳細なパターンと例については、**nolint ディレクティブ**を参照してください。抑制すべき場面、理由の書き方、行単位／関数単位で抑制するパターン、アンチパターンを説明しています。

開発ワークフロー

1. 重要な変更を行うたびに、リンターを実行することを推奨します：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)

かっこ内のリンター名は、どのリンターが指摘したかを示します。次の目的で使用してください。

• リファレンスでリンターを調べ、検査内容を理解する
• 誤検知の場合は、//nolint:linter-name // 理由 で抑制する
• 詳しい情報や実行時間を確認するには、golangci-lint run --verbose を使用する

よくある問題

問題	解決策
"deadline exceeded"	.golangci.yml の run.timeout を設定または増やします。golangci-lint v2 のデフォルトはタイムアウトなし（0）です
レガシーコードで問題が多すぎる	issues.new-from-rev: HEAD~1 を設定し、新しいコードのみを lint します
Linter が見つからない	golangci-lint linters を確認します。Linter には新しいバージョンが必要な場合があります
Linter 間の競合	あまり有用でない方を、理由を説明するコメントを添えて無効にします
アップグレード後に v1 の設定エラーが発生する	golangci-lint migrate を実行して設定形式を変換します
大規模なリポジトリで遅い	run.concurrency を減らすか、linters.exclusions.paths / formatters.exclusions.paths でパスを除外します

レガシーコードベースのクリーンアップを並列化する

レガシーコードベースで lint を導入する場合は、最大 5 つの並列サブエージェントを使って、独立した Linter カテゴリーを同時に修正します。

• サブエージェント 1：golangci-lint run --fix ./... を実行して、自動修正可能な問題を修正します
• サブエージェント 2：セキュリティ Linter の指摘事項を修正します（bodyclose、sqlclosecheck、gosec）
• サブエージェント 3：エラー処理の問題を修正します（errcheck、nilerr、wrapcheck）
• サブエージェント 4：スタイルとフォーマットを修正します（gofumpt、goimports、revive）
• サブエージェント 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 スキルを参照してください