go-standards

Clean Architecture patterns for Go services, with explicit applicability criteria. Use when implementing features, creating new components, modifying existing code, or reviewing Go service structure. Read the applicability section first - four layer directories are for complex domains, not for every service.

Contract-first planning for Go microservices. Use when creating story files, planning features, or writing technical specifications. Stories capture scope, contracts, acceptance criteria and verification commands - not function bodies. Implementation writes code in the repo against compiler and test feedback.

Enforces proper error handling patterns in Go services. Use when creating error types, handling errors, wrapping errors with context, or implementing error boundaries between layers. Applies to any Go code that returns or processes errors.

Before writing any helper, util, wrapper, or 'glue' code in Go, check if a maintained library already solves it. Activates when about to implement: HTTP retry, backoff, config loading, validation, CLI parsing, scheduling, MQTT, Modbus, graceful shutdown, structured logging, metrics, ID generation, error wrapping, or any 'small thing'. Strongly prefer the curated library catalog below over hand-rolled code.

Enforces code quality and linting standards for Go services. Use after writing Go code, before completing implementation, or when fixing lint errors. Applies to all Go code modifications and must be verified before marking tasks complete.

Use modern Go idioms appropriate for the project's Go version (read from go.mod). Activates when generating new Go code, refactoring existing code, or reviewing Go for outdated patterns. Counters Claude's bias toward older idioms (interface{}, manual loops, manual cancellation) by mapping to current stdlib equivalents.

Enforces testing standards for Go microservices. Use when writing tests, reviewing test coverage, creating mocks, or implementing test patterns. Applies to unit tests, integration tests, and any test-related code in Go services.