go-practices
Go conventions for hexagonal architecture, project structure, error handling, testing, and observability. Use when writing Go services.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for Go development, focusing on hexagonal architecture, standardized project structures, and robust error handling. It helps developers build scalable, maintainable Go services by enforcing clean code principles, decoupled business logic, and advanced testing patterns like race detection and parallel execution.
Use Cases
- Architecting New Go Services: Designing a decoupled project structure where business logic remains independent of external dependencies using hexagonal architecture principles.
- Standardizing Error Management: Implementing consistent error wrapping and sentinel error patterns to improve system-wide debugging and error tracking in production environments.
- Optimizing Testing Workflows: Establishing table-driven tests with race detection and parallel execution to ensure high-quality, thread-safe Go applications.
- Enhancing System Observability: Integrating OpenTelemetry and structured logging conventions to facilitate better monitoring and performance analysis of Go-based microservices.
| name | go-practices |
|---|---|
| description | Go conventions for hexagonal architecture, project structure, error handling, testing, and observability. Use when writing Go services. |
go-practices
Quick Start
- Follow hexagonal architecture: business logic in
pkg/api/business/, adapters inpkg/api/adapters/ - Use snake_case for all Go files
- Wrap errors:
fmt.Errorf("%w: %w", ErrSentinelError, err) - Run tests with race detection:
go test -race ./...
Key Principles
- Business logic has NO external dependencies
- All external interactions through interfaces
- Composition via AppContext (composition root)
- Table-driven tests with
t.Parallel() - OpenTelemetry for observability
References
See rules.md for complete conventions.