Build Workflow
- Prefer straightforward code over abstraction. Make the happy path read down the page by handling errors early.
- Use the standard library idioms already present in the repo:
context,errors,fmt,io,testing,slog,net/http, and so on. - Keep names short but explanatory at their scope. Avoid package-name stutter in exported identifiers.
- Wrap errors with context using
%wwhen callers neederrors.Isorerrors.As. - Accept small interfaces and return concrete types. Avoid pointers to interfaces.
- Use type parameters for real type relationships; do not use generics to avoid writing clear domain code.
- Treat nil carefully: nil slices are usually fine for empty collections; maps must be made before writes.
- Document exported packages, types, functions, methods, and non-obvious behavior for users.
- Run
gofmt/goimportsafter edits and keep generated code separate.
Audit Workflow
- Inspect call sites before judging names, exported APIs, interfaces, or generic types.
- Flag error handling that loses classification, context, wrapping, cancellation, or caller actionability.
- Check context usage, nil handling, map writes, slices, pointer/interface choices, and generated-code boundaries.
- Treat style-only issues as low priority unless they obscure correctness or API intent.
- Report concise remediations that preserve the repo's existing style.
- Pair with
golang-code-auditwhen producing a full findings-first review.
Load References
- Read
references/idioms.mdwhen implementing APIs, error behavior, comments, interfaces, generics, or cleanup refactors. - Pair with the companion
golang-quality-lintingskill before claiming the implementation is complete.