go-api

name	go-api
description	Create a new Go API service with complete boilerplate, local development, and observability.
disable-model-invocation	true

Go API Service

Create a production-ready Go API service.

Instructions

When asked to create a new Go API service:

1. Ask for the service name (kebab-case, e.g., user-service, config-manager)
2. Ask for the module path (e.g., github.com/myorg/myservice)
3. Generate the complete project structure using the templates below
4. Replace placeholders ({SERVICE_NAME}, {SERVICE_NAME_SNAKE}, {SERVICE_NAME_PASCAL}, {MODULE_PATH}) with appropriate values

Parallel scaffold (optional)

Scaffolding is a fixed placeholder map applied across independent templates — a verified-pattern fan-out. Scaffold one representative file first (e.g. internal/api) with placeholders resolved, and confirm the substitutions and layout with the user. Once approved, fan out subagents to instantiate the remaining templates in parallel — the placeholder map is fixed, so the work is mechanical.

Project Structure

Generate the following structure:

{SERVICE_NAME}/
├── cmd/
│   └── api/
│       └── main.go
├── internal/
│   ├── api/
│   ├── config/
│   ├── contextx/
│   ├── deps/
│   ├── env/
│   ├── errorsx/
│   ├── httpx/
│   ├── logx/
│   ├── metrics/
│   ├── middleware/
│   ├── mysql/
│   ├── redis/
│   └── traces/
├── docs/
│   ├── projects/
│   │   ├── completed/
│   │   └── README.md
│   └── architecture.md
├── e2e/
├── local/
│   ├── config/
│   ├── mysql/
│   └── observability/
├── scripts/
├── go.mod
├── go.sum
├── Makefile
├── AGENTS.md
└── README.md

Key Patterns

Clean Architecture

handlers (HTTP) → service (business logic) → repository (data)
  → model (entities)

Package Naming

Use x suffix for packages that shadow stdlib: logx, httpx, timex, errorsx, contextx

Error Handling

return nil, fmt.Errorf(
    "service: failed to create config: %w", err)

Structured Logging

logger.LogAttrs(ctx, slog.LevelError, "create_config",
    slog.String("config_id", configID),
    slog.Any("err", err),
)

Tracing

spanFunc := func(ctx context.Context) error {
    traces.AddAttributesToCurrentSpan(ctx,
        attribute.String("config_id", configID),
    )
    return nil
}
err := traces.WithSpan(
    ctx, s.tracer, "service.CreateConfig", spanFunc)

Templates

When generating files, use the templates in the templates/ directory:

• Makefile
• MySQL Docker Compose
• Observability Stack
• Local Config
• internal/api
• internal/config
• internal/logx
• internal/middleware
• go.mod

Running Locally

After generation:

# First-time setup
make tools-install

# Start full stack (API + MySQL + Redis + Observability)
make run

# Run tests
make test

# Run integration tests
make test-integration

# Run all linters
make lint-all