AI Skill Report Card
Architecting Production Backend Systems
Quick Start13 / 15
When asked to build a service (e.g., "build a Go/Python/Node order-processing service with Postgres and Pub/Sub"), immediately produce, in this order:
- Repository tree (markdown,
└──syntax) - Every file, each starting with a path comment on line 1
- No prose between code blocks beyond a one-line section header
Example first output block:
# Repository Structure
.
├── cmd/
│ └── server/
│ └── main.go
├── internal/
│ ├── api/
│ ├── domain/
│ ├── repository/
│ └── observability/
├── deploy/
│ ├── terraform/
│ │ ├── main.tf
│ │ ├── variables.tf
│ │ └── outputs.tf
│ ├── Dockerfile
│ └── cloudbuild.yaml
├── .env.example
├── .gitignore
├── go.mod
└── README.md
Then emit each file in full, starting with:
Go// cmd/server/main.go package main ...
Recommendation▾
Add concrete before/after or good/bad code examples (e.g., a bad circuit breaker vs a good one) rather than only prose descriptions of practices
Workflow13 / 15
Progress checklist for every service build:
- Clarify runtime (language/framework), datastore, and messaging boundaries from the request — infer sane Google-stack defaults if unstated (Go or Python, Postgres via Cloud SQL, Pub/Sub, Redis for cache)
- Emit repository tree
- Emit domain layer: entities + Pydantic/Zod/struct validation, explicit error types
- Emit repository/data layer: connection pool config (min/max conns, idle timeout), retry wrapper (tenacity/exponential backoff), migrations
- Emit service/business logic layer: circuit breaker wrapping all external calls, context propagation, timeout budgets
- Emit transport layer (HTTP/gRPC): input validation, structured error responses, correlation ID middleware,
/healthz(liveness),/readyz(readiness including dependency pings) - Emit observability: structured JSON logger, trace ID injection, Prometheus/OpenTelemetry metric hooks
- Emit graceful shutdown handling (SIGTERM drain, in-flight request completion, pool close)
- Emit config layer: env-var driven, validated at boot, fail-fast on missing required vars
- Emit Dockerfile: multi-stage, distroless/alpine final stage, non-root user, minimal attack surface
- Emit
cloudbuild.yaml(or GitHub Actions) with lint → test → build → scan → deploy stages - Emit Terraform:
main.tf,variables.tf,outputs.tf— VPC, IAM least-privilege service accounts, autoscaling compute (Cloud Run/GKE), Secret Manager bindings - Emit
.env.example,.gitignore, lint config (.golangci.yml/ruff.toml/.eslintrc) - Emit dependency manifest with pinned versions
- Emit
README.mdlast: architecture rationale, local run, test commands, deploy pipeline - Self-run the evaluation metric mentally before final output; fix any gap silently, don't narrate the check
Recommendation▾
Include a fuller worked example showing at least one complete file end-to-end so Claude sees the exact expected format/detail level
Best Practices
- Default to explicit over implicit: no framework "magic" auto-wiring without a comment explaining what it does.
- Every external boundary (DB, cache, queue, downstream HTTP/gRPC service) gets: connection pool bounds, timeout, retry with jitHered backoff, circuit breaker.
- Every public-facing input gets schema validation before it touches business logic — reject fast with structured 4xx payload (
{error_code, message, trace_id}). - Logs are structured JSON only:
{timestamp, severity, trace_id, span_id, message, ...fields}. Neverfmt.Println/printin production paths. - Config is validated at process start; missing/invalid required env vars cause immediate exit(1) with a clear log line — never fail silently at request time.
- IAM in Terraform: one dedicated service account per service, scoped roles only (never
roles/ownerorroles/editor), Workload Identity for GKE where applicable. - Container images: multi-stage build, final stage is
distroless(oralpinewith packages stripped), runs as non-root UID, read-only root filesystem where feasible. - Concurrency defaults: bound worker pools, bounded channels/queues, explicit max in-flight request limits — never unbounded goroutines/async tasks on untrusted input.
- Always include both liveness (
/healthz— process is up) and readiness (/readyz— dependencies are reachable) as separate endpoints.
Common Pitfalls
- Do NOT use
// TODO,pass # implement later,..., or any stub — every branch, including rare error paths, is fully implemented. - Do NOT emit a Dockerfile running as root or using a bloated base (
ubuntu:latest, fullpython:3.xwithout slim/distroless). - Do NOT skip the path-comment header on any file — this is non-negotiable for direct commit-readiness.
- Do NOT hand-wave Terraform with
# add your VPC here— write the full resource blocks. - Do NOT use floating dependency versions (
^,latest, unpinned) — pin exact or tilde-locked versions known to be non-vulnerable. - Do NOT narrate the internal evaluation checklist in the output — it's a silent self-check, not user-facing content.
- Do NOT produce partial file trees that omit config/IaC/CI files "for brevity" — completeness is the entire point of the exercise.