go-practices
Go conventions for hexagonal architecture, project structure, error handling, testing, and observability. Use when writing Go services.
practices
SKILL.mddata/go-practices
GitHubGo Practices
How Go code is written in this repository: one root module
github.com/eser/stack (framework in pkg/ajan/, binary in
cmd/noskills-server/) plus the FFI bridge module github.com/eser/ajan in
pkg/@eserstack/ajan/.
Always
- Business packages under
pkg/ajan/api/business/import only the standard library; wiring happens inpkg/ajan/api/adapters/appcontext/appcontext.go. - Files are snake_case.
- Check every error and wrap with a context prefix:
fmt.Errorf("load session %q: %w", id, err). Lowercase messages,%qfor user input,errors.Isanderrors.AsType, handle each error once. - Log and trace through
logfxwith the*Contextmethods; neverfmt.Printlnorlog.Printf. ctx context.Contextfirst; pass the caller's context down and cancel every context you derive.- Pass by value unless the function mutates, nil means something, the type must
not be copied, or it is 80+ bytes (gocritic
hugeParam). - Dependencies arrive through constructors: no globals, no service locator, no
init(); functional options that validate; enums start at an Unknown. defer Close()on the line after a successful open;paniconly for bugs.- Use the standard library up to the
go 1.26directive, nothing newer. - Tests are table-driven with
t.Parallel()and run with-race. make okchecks only the root module.deno task cli okalso vets, builds and lints the bridge module, since./...never crosses a module boundary.
References
| File | Read when |
|---|---|
| architecture.md | Adding a package or domain, dependency injection, constructors |
| errors-and-logging.md | Returning or matching errors, logging, spans, metrics |
| context.md | Passing, deriving or detaching a context; handlers; outbound calls |
| language.md | Strings, types, generics, parameters, enums, iterators, JSON, regexp |
| testing.md | Writing Go tests, fakes for ports, or benchmarks |
| data-structures.md | Choosing slices, maps, containers, buffers or generic types |
| performance.md | Profiling, benchmarks, allocations, caching, I/O and batching |
| modernization.md | Replacing an old idiom, raising the go directive, Go tooling |
General rules (errors, logging, timeouts, config, interfaces) live in coding-practices and design-principles; commands in AGENTS.md.