git:20260406.ebcc193 to git:20260406.9f29dd1

---

name: backend-systems-guidance

description: Canonical overlay for server-side networked code that needs stronger architecture, testing, reliability, and security discipline. Use alongside the repo's implementation skill when implementing or reviewing backend services, APIs, middleware, queues, repositories, or backend refactors.

---

# Backend Systems Guidance

This is a composable overlay, not a standalone workflow.

Use alongside the repo's implementation skill when the change touches backend

code.

This is the canonical backend overlay in this repo.

It extends the thin baseline `backend-guidance` overlay with stronger guidance

for non-trivial service boundaries, repositories, reliability, and trust

boundaries.

Prefer it over `backend-guidance` when the task includes new endpoints or

consumers, multi-layer refactors, repository or transaction work, auth or

trust-boundary logic, or backend review that needs explicit testing and

reliability checks.

Use the bundled references only when needed:

- [references/trigger-evals.md](references/trigger-evals.md) for lightweight

prompt checks when revising the trigger or scope

## When to use

- the repo has server-side networked code such as HTTP handlers, gRPC methods,

webhooks, queue consumers, or message producers

- the task adds or reshapes routes, controllers, services, repositories,

middleware, or request-processing boundaries

- the task changes auth, authorization, validation, idempotency, retries,

external requests, caching, or observability

- the task needs backend review beyond basic handler thinness, especially for

security, data access, or missing tests

## Not for

- HTTP client code, CLI tooling, offline batch scripts, or data pipelines with

no request or consumer boundary

- frontend-only work

- threat modeling or security audit work where `security` should be the primary

workflow skill

Do not fold infrastructure deployment workflows, outbound-client-only guidance,

or full security-audit checklists into this skill. Keep this overlay centered

on backend request and consumer systems plus their immediate reliability and

trust boundaries.

## Core workflow

1. Read the touched backend files and map the request or consumer path end to

end: boundary, service logic, data access, external calls, and state

changes.

2. Pick the mode before changing code:

- baseline backend change when the work is mostly a thin handler or small

service fix

- service-boundary change when responsibilities, data access, or dependency

direction may need to move

- reliability-hardening or review mode when the main risk is missing tests,

auth gaps, retries, observability, or unsafe failure handling

3. Keep the boundary thin: decode input, authenticate and authorize, validate,

call a service, map transport errors, and serialize output. Business

decisions belong in service code that can run without the transport layer.

4. Place persistence and external integrations deliberately:

- repositories or data adapters own query shape, batching, and transaction

details when that improves clarity or testing

- services coordinate business rules, idempotency, retries, and side-effect

ordering

- handlers and controllers do not reach directly into ORM or network clients

unless the change is truly trivial and stays trivial

5. Harden cross-cutting concerns at the edge:

- validate external input once at the boundary

- enforce auth and authorization before business actions

- set timeouts, retry rules, and destination allowlists for outbound calls

- use structured logging, correlation identifiers, and explicit error

mapping for observable failure paths

6. Choose the smallest test set that proves the change:

- unit tests for service logic and decision branches

- integration tests for handlers, consumers, repositories, and transaction

behavior

- auth and permission tests for protected flows

- contract or schema tests when the change alters external API or event

shapes

- load or concurrency tests only for changed hotspots, queue throughput, or

latency-sensitive paths

7. Review the result for boundary leaks, unsafe defaults, data-access

inefficiency, and missing verification before finishing.

## Decision rules

- Start with `backend-guidance` for ordinary backend edits. Use this overlay

when the task needs stronger design pressure, harder review, or explicit

backend quality gates.

- Keep handlers thin in responsibility, not by literal line count. If a

handler or consumer owns business decisions, retries, transaction branching,

or query orchestration, extract inward.

- Keep business logic transport-free. If testing a rule requires booting HTTP,

gRPC, or queue infrastructure, the logic is in the wrong place.

- Add a repository or data-access interface when it reduces duplication,

isolates non-trivial queries, helps transaction composition, or makes tests

materially simpler. Do not add one for single-call trivial CRUD.

- Prefer one validation pass at the outer edge plus typed internal data. Avoid

repeated validation in every layer unless a trust boundary changes.

- Treat retries as a design choice, not a default. Only retry idempotent or

explicitly deduplicated work, and pair retries with deadlines or backoff.

- Use idempotency keys or duplicate-detection for retried creates, webhook

handlers, and queue consumers that can be re-delivered.

- Every outbound request needs a timeout and failure policy. For user-controlled

destinations, apply allowlists or equivalent SSRF protections.

- Keep error handling explicit: domain code returns or throws domain-level

failures; boundary code maps them to HTTP, gRPC, queue, or job semantics.

- Measure before adding caching. Cache only stable read paths with clear

invalidation or bounded staleness.

## Validation

A backend change is done when, in addition to the base implementation skill's

validation:

- handlers or consumers stay as boundary glue and delegate business decisions to

testable service code

- data access and external I/O live behind clear seams when the change is

non-trivial

- external input, auth, and transport-specific error mapping stay at the edge

- retries, idempotency, timeouts, and failure handling are explicit where the

change can duplicate work or call remote systems

- tests cover the changed behavior at the correct level, including integration

coverage for boundary behavior and permission or failure cases when relevant

- new high-risk paths emit enough evidence to debug production behavior