/gen-linter

Generate golangci-lint Configuration Command

Instantly create a professional .golangci.yml configuration for Go projects with comprehensive linting coverage. This command converts the multi-step linter skill into a one-command solution.

Why This Command Exists

Problem: Setting up golangci-lint requires manually creating YAML configuration, understanding 90+ linter options, and balancing strict quality checks with pragmatic development - a 15-30 minute process prone to over-configuration.

Solution: One-command generation that:

• Creates battle-tested .golangci.yml (224 lines)
• Enables all linters by default with sensible exclusions
• Balances code quality with development velocity
• Works out-of-the-box for most Go projects
• Includes inline documentation for customization

Content Generation Rules

CRITICAL: When generating any content (configuration files, commit messages, or any other output):

• NEVER add Claude Code attribution or co-authorship
• NEVER include phrases like "Generated by Claude", "Created with Claude Code", or similar
• NEVER add "Co-Authored-By: Claude" in commit messages or documentation
• All generated content should appear as if written by a human developer
• Focus on technical accuracy and providing working templates

Process (6 Phases)

Phase 1: Prerequisites Validation

Critical checks before proceeding:

1. Validate Git repository:

   git rev-parse --git-dir
   

   • If fails: Exit with error "Not a git repository. Run 'git init' first."

2. Validate Go project:

   test -f go.mod
   

   • If fails: Exit with error "go.mod not found. This command is for Go projects only."

3. Check existing configuration:

   test -f .golangci.yml || test -f .golangci.yaml
   

   • If either exists: Store existingConfig = true and existingFile = <filename>
   • If not exists: Store existingConfig = false

4. Check for golangci-lint binary (non-blocking):

   command -v golangci-lint
   

   • If not found: Store linterNotInstalled = true (will show warning later)
   • If found: Check version with golangci-lint --version and store for report

5. Verify command assets directory:

   • Use Read tool to verify ${CLAUDE_PLUGIN_ROOT}/commands/assets/linter/.golangci.yml exists
   • If fails: Exit with error "Command assets directory not found at ${CLAUDE_PLUGIN_ROOT}/commands/assets/linter/. Plugin may be corrupted. Reinstall the go-specialist plugin."

Phase 2: Argument Parsing

Parse command arguments from $argument string:

Supported flags:

• --force: Skip confirmation if .golangci.yml already exists
• --dry-run: Show preview without writing file

Parsing logic:

arguments = split($argument by space)
for each arg in arguments:
  if arg == "--force": set forceMode = true
  if arg == "--dry-run": set dryRunMode = true

File Selection:

• Single file generation: .golangci.yml (224 lines)

Phase 3: Template Reading

Read template file from command assets directory:

Template location:

• Path: ${CLAUDE_PLUGIN_ROOT}/commands/assets/linter/.golangci.yml
• Expected size: ~6.5 KB (224 lines)
• Format: YAML with inline comments

Reading logic:

Use Read tool to read: ${CLAUDE_PLUGIN_ROOT}/commands/assets/linter/.golangci.yml
Store content as: templateContent
Verify: content is not empty and starts with "# golangci-lint"

Error handling:

• If file not found: Exit with error "Template file not found at ${CLAUDE_PLUGIN_ROOT}/commands/assets/linter/.golangci.yml"
• If file empty: Exit with error "Template file is empty or corrupted"

No variable substitution required - the template is copied as-is.

Phase 4: User Confirmation

Build preview message:

📋 golangci-lint Configuration Preview

Files to be created:
  .golangci.yml (224 lines, ~6.5 KB)

Configuration features:
  • Enables all linters by default (90+)
  • Disables overly strict linters (goerr113, wrapcheck, etc.)
  • 5-minute timeout for large projects
  • Fast mode with caching enabled
  • Parallel execution across all CPUs
  • Project-agnostic settings

Excluded linters (too opinionated):
  • depguard, exhaustruct, gci, gochecknoglobals
  • godox, goerr113, inamedparam, maintidx
  • nonamedreturns, testpackage, wrapcheck, wsl

Integration ready:
  ✓ GitHub Actions (via gen-github-dir)
  ✓ GitLab CI (via gen-gitlab-ci)
  ✓ Task runner (via gen-taskfiles)
  ✓ Pre-commit hooks
  ✓ VS Code, GoLand, Vim/Neovim

<CONDITIONAL WARNINGS>

Conditional warnings:

If existingConfig = true:

⚠️  WARNING: Existing configuration detected
    File: <existingFile>
    This will OVERWRITE your existing linter configuration.
    Consider backing up your current settings before proceeding.

If linterNotInstalled = true:

ℹ️  INFO: golangci-lint binary not found
    Configuration will be created, but you'll need to install golangci-lint to use it:
      • macOS: brew install golangci-lint
      • Other: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
    After installation, verify with: golangci-lint --version

Confirmation logic:

If dryRunMode = true:

[DRY RUN MODE - No files will be written]

Skip to Phase 6 (report preview only)

If forceMode = true:

[--force mode enabled, skipping confirmation]

Proceed to Phase 5

If existingConfig = true and forceMode = false:

Use AskUserQuestion:
  Question: "Overwrite existing .golangci.yml configuration?"
  Options:
    - "Yes, overwrite configuration" (proceed to Phase 5)
    - "No, cancel operation" (exit with message "Operation cancelled by user")

If existingConfig = false:

Use AskUserQuestion:
  Question: "Create .golangci.yml in project root?"
  Options:
    - "Yes, create configuration" (proceed to Phase 5)
    - "No, cancel operation" (exit with message "Operation cancelled by user")

Phase 5: File Creation

Write configuration file:

Use Write tool to create:

File: .golangci.yml (in project root, not in .github/)
Content: <templateContent from Phase 3>

Writing logic:

Use Write tool:
  file_path: ./.golangci.yml (absolute path to project root)
  content: templateContent (no modifications, copy as-is)

Error handling:

• If write fails: Report error to user with file path and error message
• If write succeeds: Proceed to Phase 6

Phase 6: Validation & Success Report

Verify file creation:

test -f .golangci.yml && wc -l .golangci.yml

Success report:

If dryRunMode = true:

✅ [DRY RUN] Preview completed successfully

Would create:
  • .golangci.yml (224 lines)

To create files, run without --dry-run flag.

If normal execution:

✅ golangci-lint configuration created successfully!

Created files:
  ✓ .golangci.yml (224 lines)

Next steps:

1. Run initial lint check:
   golangci-lint run ./...

2. Auto-fix issues where possible:
   golangci-lint run --fix ./...

3. See verbose output with active linters:
   golangci-lint run -v ./...

4. Test specific linter:
   golangci-lint run --disable-all --enable=govet ./...

5. Customize configuration:
   Edit .golangci.yml to adjust enabled linters, timeouts, or exclusions

6. Integrate with CI/CD:
   • GitHub Actions: Run /gen-github-dir (includes linter workflow)
   • GitLab CI: Run /gen-gitlab-ci (includes lint job)
   • Task runner: Run /gen-taskfiles (includes lint tasks)

7. Configure editor integration:
   • VS Code: Install Go extension, set "go.lintTool": "golangci-lint"
   • GoLand: Settings → Tools → File Watchers → Add golangci-lint
   • Vim/Neovim: Configure ale plugin with golangci-lint

Configuration features:
  ✓ 90+ linters enabled by default
  ✓ Balanced quality vs. pragmatism
  ✓ Fast execution with caching
  ✓ Parallel processing
  ✓ CI/CD ready

📚 Need help with advanced customization?
   Visit: https://golangci-lint.run/usage/configuration/

If linterNotInstalled = true, append:

⚠️  Remember to install golangci-lint:
   • macOS: brew install golangci-lint
   • Other: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
   Verify: golangci-lint --version

Integration with Other Commands

This command works seamlessly with other go-specialist commands:

Before gen-linter:

• None required (can be first command run)

After gen-linter:

• /gen-github-dir - Includes linter workflow using this configuration
• /gen-gitlab-ci - Includes lint job using this configuration
• /gen-taskfiles - Includes lint tasks for local development
• /verify-task - Validates task quality using linter output

Typical workflow:

# 1. Generate linter config
/gen-linter

# 2. Fix initial issues
golangci-lint run --fix ./...

# 3. Set up CI/CD
/gen-github-dir  # or /gen-gitlab-ci

# 4. Add task automation
/gen-taskfiles

Best Practices

Configuration maintenance:

• Review and update .golangci.yml when upgrading golangci-lint versions
• Adjust linter selection based on team preferences
• Document any custom exclusions in comments
• Test configuration changes with --fast flag first

CI/CD integration:

• Always run linter in CI before tests
• Use --timeout=5m for large projects
• Cache golangci-lint binary and build cache
• Block PRs with linting failures

Local development:

• Run linter before committing: golangci-lint run ./...
• Use auto-fix when possible: golangci-lint run --fix ./...
• Configure editor integration for real-time feedback
• Set up pre-commit hooks for automatic checks

Team adoption:

• Gradually enable stricter linters
• Document project-specific conventions
• Review linter output in code reviews
• Share configuration explanations with team

Limitations & Caveats

Golangci-lint installation:

• This command only creates configuration
• Binary must be installed separately
• Requires Go 1.21+ for full linter compatibility

Configuration style:

• Opinionated defaults (pragmatic over perfect)
• May need customization for specific projects
• Some linters may conflict with project conventions

Performance considerations:

• Initial run can be slow on large codebases
• Enable caching for faster subsequent runs
• Use --fast flag for quick checks during development

CI/CD requirements:

• Workflows expect golangci-lint v2.4.0+
• Docker images may need golangci-lint installation
• GitHub Actions uses dedicated golangci-lint action

Error Recovery

If linter fails after generation:

1. Check golangci-lint version: golangci-lint --version
2. Validate configuration: golangci-lint run --help
3. Test with minimal config: golangci-lint run --disable-all --enable=govet ./...
4. Check for syntax errors: yamllint .golangci.yml

If too many issues reported:

1. Start with auto-fix: golangci-lint run --fix ./...
2. Disable problematic linters temporarily
3. Use --exclude patterns for known issues
4. Gradually enable stricter linters

If conflicts with existing tooling:

1. Review .golangci.yml disable list
2. Adjust exclusions for project needs
3. Check for conflicting editor plugins
4. Verify Go version compatibility

Additional Resources

Official documentation:

• Configuration reference: https://golangci-lint.run/usage/configuration/
• Linters list: https://golangci-lint.run/usage/linters/
• Editor integrations: https://golangci-lint.run/usage/integrations/

Related commands:

• /gen-github-dir - GitHub Actions with linter workflow
• /gen-gitlab-ci - GitLab CI with lint jobs
• /gen-taskfiles - Task automation with lint tasks

Community resources:

• Example configurations: https://github.com/golangci/golangci-lint/tree/master/test
• Best practices: https://golangci-lint.run/usage/best-practices/
• GitHub repository: https://github.com/golangci/golangci-lint