go-stack

Go Stack Harness

The Go side of the harness. Tools here are all native Go, so they're fast by default.

Tool choices

Role	Tool	Notes
Format	gofumpt	Stricter superset of gofmt. Opinionated, no config.
Imports	goimports	Organize imports, remove unused
Lint aggregator	golangci-lint v2	Parallel runner for 100+ linters
Dependency rules	depguard (inside golangci-lint)	Block forbidden package imports
Architecture	go-arch-lint	YAML-declared layer rules
Security	gosec	CWE-mapped static analysis
Complexity	cyclop (inside golangci-lint)	Cyclomatic complexity gate

golangci-lint v2 recommended config

The default .golangci.yml installed by /harness:init enables these linters:

# NOTE: protected by pre-config-protect hook
version: "2"
linters:
  enable:
    - errcheck
    - govet
    - ineffassign
    - staticcheck
    - unused
    - gosimple
    - depguard        # forbidden imports
    - cyclop          # complexity gate
    - iface           # interface bloat detection
    - exhaustive      # enum exhaustiveness
    - containedctx    # context in struct = smell
    - decorder        # declaration order
    - errorlint       # error wrapping correctness
    - gosec           # security

Run mode: --fast in PostToolUse hook (file-scoped, ~200ms), full run in CI.

go-arch-lint for Clean Architecture

A minimal Clean Architecture .go-arch-lint.yml:

version: 3
workdir: .

components:
  domain:         { in: domain/** }
  usecase:        { in: usecase/** }
  infrastructure: { in: infrastructure/** }
  interfaces:     { in: interfaces/** }

deps:
  domain:         { allow: [] }                  # pure
  usecase:        { allow: [domain] }
  infrastructure: { allow: [domain, usecase] }
  interfaces:     { allow: [domain, usecase, infrastructure] }

excludeFiles:
  - "**/*_test.go"
  - "**/*.pb.go"
  - "**/mock/**"

The template at ${CLAUDE_PLUGIN_ROOT}/templates/.go-arch-lint.clean-arch.yml has a more complete version.

How the hook runs these

On every .go file Write/Edit, post-edit-lint.js:

1. gofumpt -w <file> (or gofmt -w fallback)
2. goimports -w <file>
3. golangci-lint run --fast --out-format line-number <file>
4. go-arch-lint check (project-wide; only report if violation mentions this file)
5. Feedback collected → additionalContext

Generated files (*.pb.go, *_gen.go, files with Code generated ... DO NOT EDIT header) are skipped automatically.

Key learnings

• Context must be the first parameter in all exported functions. containedctx catches context stored in structs, which is always wrong.
• Error wrapping: use fmt.Errorf("...: %w", err), not %v. errorlint catches this.
• sql.Rows.Close(): always defer rows.Close() immediately after a successful query. This is easy to forget and hard to catch without a linter.
• Table-driven tests: standard Go idiom, enforced via review-profile.go.yaml watch_for rules.

Related Skills

• architecture-enforcement — go-arch-lint deep dive
• edit-lint-feedback-loop — hook mechanics
• harness-setup — initial setup

Gotchas

See gotchas.md.