Agent Skills: Go Tooling & Security

Go Tooling & Security

Agent Workflow (MANDATORY)

Before ANY tooling/security change, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Find existing go.mod/go.work, .golangci.yml, CI files
2. fuse-ai-pilot:research-expert - Verify latest golangci-lint v2 + govulncheck docs via Context7/Exa
3. mcp__context7__query-docs - Check current Go 1.27 go fix modernizer set

After changes, run fuse-ai-pilot:sniper for validation.

Overview

| Area | Description | |------|-------------| | Modules & Workspaces | go.mod directives, go.work for multi-module dev without replace | | golangci-lint v2 | Config version "2", formatters section, golangci-lint migrate | | govulncheck | Reachability-based scan of the call graph against vuln.go.dev | | go fix modernizers | Suite of fixers (rebuilt in 1.26, extended in 1.27), //go:fix inline for API migrations | | CI quality gate | fmt → vet → golangci-lint → govulncheck → test -race |

Critical Rules

1. Never invent flags or directives - Confirm every go/tool flag against official docs first
2. golangci-lint v2 config MUST start with version: "2" - v1 configs are rejected; migrate, don't hand-edit
3. govulncheck runs in source mode by default - Reachability filters noise; only reported findings matter
4. go.work is usually not committed - Commit only when modules are developed exclusively together
5. CI gate order is fail-fast - Formatting/vet before linters before vulnerability scan before tests

Architecture

repo/
├── go.work                 # optional: multi-module workspace
├── go.work.sum
├── module-a/
│   ├── go.mod              # module, go, require, toolchain
│   └── go.sum
├── module-b/
│   └── go.mod
├── .golangci.yml           # version: "2"
└── .github/workflows/ci.yml

→ See ci-workflow.md for the complete gate

Reference Guide

Concepts

| Topic | Reference | When to Consult | |-------|-----------|-----------------| | Modules & Workspaces | modules-workspaces.md | Editing go.mod/go.work, multi-module repos | | golangci-lint v2 | golangci-lint-v2.md | Config, v1→v2 migration, formatters | | govulncheck | govulncheck.md | Dependency vulnerability scanning | | go fix modernizers | go-fix-modernizers.md | Modernizing code, //go:fix inline, PGO |

Templates

| Template | When to Use | |----------|-------------| | golangci-v2-config.md | Dropping in a recommended .golangci.yml | | ci-workflow.md | Wiring the full CI quality gate |

Quick Reference

Workspace bootstrap

go work init ./module-a ./module-b   # create go.work
go work use ./module-c               # add a module
go work sync                         # sync build list to modules

→ See modules-workspaces.md

Migrate + run golangci-lint v2

golangci-lint migrate                # v1 config → v2 (backs up original)
golangci-lint run ./...

→ See golangci-v2-config.md

Scan for reachable vulnerabilities

go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...                    # source mode, call-graph reachability

→ See govulncheck.md

Modernize the codebase

go fix ./...                         # apply the modernizer suite (1.27 set)

→ See go-fix-modernizers.md

Best Practices

DO

• Pin toolchain with the toolchain directive for reproducible builds
• Gate CI on govulncheck ./... and treat reachable findings as failures
• Use go.work for local cross-module work instead of scattering replace directives
• Keep formatters (gofmt/goimports) separate from linters in the v2 config

DON'T

• Hand-write a v2 config from a v1 file — run golangci-lint migrate
• Commit go.work in repos whose modules are also developed with external modules
• Suppress govulncheck findings without confirming the vulnerable symbol is unreachable
• Assume go vet/gofmt changed in 1.26 — the 1.26 change is go fix, not those
• Forget that since 1.27 go test runs the stdversion vet check by default (reports stdlib symbols newer than the file's go version)