CLAUDE.md

Project Context

Go HTTP API service. Router: chi or echo. Database: PostgreSQL with sqlc. Deployment: Docker.

Code Style

• Follow Effective Go and Go Code Review Comments
• gofmt + goimports on all files
• No init() functions
• Exported types need godoc comments
• Use context.Context as first parameter on all service methods

Architecture

cmd/server/main.go      — entry point
internal/
  handler/              — HTTP handlers (thin, call services)
  service/              — business logic
  repository/           — database access (sqlc generated)
  middleware/            — HTTP middleware
  model/                — domain types
pkg/                    — shared utilities (if any)

Error Handling

• Use fmt.Errorf with %w for wrapping
• Custom error types with errors.As/errors.Is
• HTTP handlers return proper status codes
• Never log and return — do one or the other

Database

• sqlc for type-safe queries (sqlc generate)
• Migrations with golang-migrate
• All queries in internal/repository/queries/
• Connection pooling with pgxpool

Testing

• Table-driven tests
• testcontainers-go for integration tests
• httptest for handler tests
• go test ./... -race -cover before committing

Docker

• Multi-stage build (builder + runtime)
• Non-root user in final image
• Health check at /healthz
• Graceful shutdown with signal handling

Git

• Conventional commits: feat:, fix:, chore:
• Run go vet ./... before pushing