Golang

Go Project Setup & Audit

Philosophy

Fast by default, comprehensive when needed.

Most Go projects start as a single main.go. That's fine. Add structure when you feel pain, not before. This skill offers two tiers:

Start with Quick Start. Graduate to Full Setup when:

• Multiple people contributing
• Codebase exceeds ~5k lines
• You're shipping to production users

When to Use

• "Create a new Go project"
• "Set up a Go CLI/API/library"
• "Audit this Go project"
• "Add linting to my Go project"

Quick Start (Recommended for New Projects)

5 steps, 2 minutes, ready to code:

1. Initialize

mkdir myproject && cd myproject
go mod init github.com/yourorg/myproject

2. Add Essential Tooling

go get -tool github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
go install github.com/air-verse/air@latest  # Hot reload

3. Copy Minimal Configs

Copy from assets/ to project root:

• .golangci.minimal.yml → .golangci.yml
• Makefile.minimal → Makefile
• .gitignore
• air.toml (optional, for hot reload)

Update local-prefixes in .golangci.yml to your module path.

4. Create Entry Point

// main.go
package main

import (
    "log/slog"
    "os"
)

func main() {
    if err := run(); err != nil {
        slog.Error("fatal", "error", err)
        os.Exit(1)
    }
}

func run() error {
    slog.Info("starting")
    // Your code here
    return nil
}

5. Verify

make lint  # Should pass
make test  # Should pass (no tests yet is fine)
make dev   # Hot reload running

Done. Start coding.

Full Setup (Growing Projects)

When Quick Start isn't enough, upgrade:

Structure Upgrade

mkdir -p cmd/myproject internal/{handler,service,config}
mv main.go cmd/myproject/

See references/structure.md for when each directory makes sense.

Linter Upgrade

Replace .golangci.yml with assets/.golangci.yml (full config).

Build Upgrade

Replace Makefile with assets/Makefile (or Taskfile.yml).

Audit Mode

For existing projects, check these in order:

Critical (Fix Now)

Important (Fix Soon)

Nice to Have

Quick Reference

Decision Shortcuts

Web framework?

• stdlib net/http + chi router (simple, idiomatic)
• Skip frameworks until you outgrow chi

Database?

• sqlc (type-safe, generates code from SQL)
• sqlx if you want more flexibility

Config?

• os.Getenv() + .env file for dev
• envconfig if you need struct binding

Logging?

• slog (stdlib, structured, fast enough)

Assets Summary

Anti-Patterns (Don't Do These)

The Only Rules

1. Don't ignore errors - Handle or explicitly _ = fn()
2. Wrap with context - fmt.Errorf("operation: %w", err)
3. Run the linter - make lint before commit
4. Write some tests - At least for the tricky parts

Everything else is optional until it isn't.

Containerization

Cross-Compilation (Recommended on Apple Silicon)

Go's built-in cross-compilation is simpler and more reliable than Docker multi-stage builds on Apple Silicon:

# Build for Linux from Mac
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -o app-linux-amd64 .

# Build for multiple platforms
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o app-amd64 .
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o app-arm64 .

Why native cross-compilation?

• Docker buildx QEMU emulation segfaults with Go 1.24+ on Apple Silicon
• Go's cross-compiler is fast and reliable
• No Docker needed for the compilation step

Dockerfile Pattern (Pre-Built Binary)

FROM alpine:latest
WORKDIR /app
COPY app-linux-amd64 ./app
RUN chmod +x ./app && addgroup -S app && adduser -S app -G app
USER app
CMD ["./app"]

Build and push:

docker buildx build --platform linux/amd64 -t myregistry/myapp:latest --push .

When to Use Multi-Stage Builds

Multi-stage Docker builds (compile inside Docker) still work for:

• CI/CD on Linux runners
• ARM64-to-ARM64 builds on Apple Silicon
• When you need reproducible builds without local Go installation

But avoid multi-stage with --platform linux/amd64 on Apple Silicon Macs.

Version Info

• Go: 1.25 (latest stable)
• golangci-lint: v2.8+ (uses formatters section for goimports)
• Skill Updated: January 2026