Go Service Template REST

An agent-native Go REST service template with real architecture, delivery constraints, and proof.

Use this template · Quickstart · Documentation

Quickstart

Create a repository from the template and start the service:

gh repo create my-service \
  --template Dankosik/go-service-template-rest \
  --public \
  --clone

cd my-service
make template-init \
  MODULE=github.com/your-org/my-service \
  CODEOWNER=@your-org/backend
make check
make run

Your agent can start immediately: Codex reads AGENTS.md, Claude Code reads
CLAUDE.md, and Qwen Code reads QWEN.md. All three use the same repository
rules, specialist agents, and reusable skills.

What You Get

This is a working service scaffold, not only a prompt collection. The code,
generated sources, database lifecycle, CI, and agent instructions share one
ownership model.

Why This Template

Generic agent prompts often miss the constraints that make a Go service safe
to change: package ownership, context, error identity, generated sources,
migrations, partial failure, shutdown, and current proof.

Traditional Go templates provide code and commands but rarely tell an agent
how to make a non-trivial change without inventing architecture or declaring
success from an unrelated test.

This template connects both sides:

• one repository contract instead of a heavyweight prompt in every request;
• direct handling for small changes and durable artifacts only when decisions
  must survive;
• OpenAPI, PostgreSQL, telemetry, tests, security, and delivery already wired;
• completion claims tied to fresh evidence of the same scope.

Before adding the first production feature, use the
production feature checklist.

How It Works

flowchart LR
    A["Codex / Claude Code / Qwen"] --> B["Shared repository contract"]
    B --> C{"Risk-proportional path"}
    C -->|Direct| D["Small local change"]
    C -->|Structured| E["Spec + design + tasks"]
    C -->|Orchestrated| F["Multi-owner coordination"]
    D --> G["Go service change"]
    E --> G
    F --> G
    G --> H["Claim-scoped proof"]

The workflow keeps three paths:

• Direct — clear, local, reversible work with one owner and bounded proof.
• Structured — non-trivial work whose decisions need a spec.md,
  tasks.md, and only the design or test artifacts that add value.
• Orchestrated — broad, multi-owner, hard-to-reverse, or multi-session work.

Public contracts, persisted data, security, money, concurrency, deployment,
and cross-service ownership receive explicit decisions and matching proof
without forcing every task through the heaviest process.

Agent Support

Representative specialists cover API contracts, architecture, data, domain
invariants, security, reliability, concurrency, observability, performance,
testing, delivery, and Go maintainability. Skills are loaded only when the
current decision or failure needs them.

See Agent Harness and
Spec-First Workflow for the complete routing
contract.

Repository Layout

cmd/service/                 service entrypoint and bootstrap lifecycle
internal/app/                use cases and domain-facing application logic
internal/infra/http/         HTTP transport and middleware
internal/infra/postgres/     PostgreSQL adapters
api/openapi/service.yaml     API source of truth
internal/api/                generated OpenAPI artifacts
env/migrations/              SQL migrations
specs/                       durable task decisions when needed
.agents/skills/              canonical reusable skills
.codex/agents/               Codex specialist agents

Use the placement guide
before choosing packages or tests.

Quality Gates

Performance work uses the narrowest matching benchmark level. DigitalOcean is
preferred only when doctl is already installed and authorized; local
benchmarks remain the supported fallback. See Benchmarking.

Documentation

• Repository Architecture
• Project Structure and Module Organization
• Build, Test, and Development Commands
• Spec-First Workflow
• Agent Harness
• Benchmarking
• Railway Deployment Profile

Community

Contributions are welcome. Read CONTRIBUTING.md, use the
issue forms for bugs and feature proposals, and follow the
Code of Conduct.

Report vulnerabilities privately through SECURITY.md.

Released under the MIT License.