backend-guidance

name	backend-guidance
description	Overlay for server-side networked code — HTTP handlers, gRPC services, message consumers. Use alongside the repo's implementation skill when implementing or reviewing backend logic.

Backend Guidance

Read AGENTS.md first. This is a composable overlay, not a standalone workflow. Use alongside the repo's implementation skill (e.g. coding-guidance-cpp, project-core-dev) when the change touches backend code.

When to use

The repo has server-side networked code: HTTP route handlers, gRPC service methods, message/event consumers, or similar request-processing pipelines.

Not for

HTTP client code, CLI tools that make outbound requests, batch processors, or offline data pipelines. These do not have the handler/service/boundary shape this skill addresses.

Rules

• Keep handlers thin in responsibility, not by literal line count — parse input, call a service function, map transport concerns, serialize output. If a handler starts owning business decisions, extract that logic into a service or core module.
• Keep business logic testable without transport — no HTTP context, no gRPC metadata leaking into domain functions.
• Isolate data access behind an interface when it simplifies testing. Do not add an abstraction layer when the data access is trivial or test-only.
• Validate and sanitize external input at the boundary, before it reaches business logic. Internal calls between trusted modules do not need redundant validation.
• Keep boundary-only concerns at the edge: authentication, authorization, request decoding, transport-specific error mapping, and idempotency checks where applicable.
• Use dependency injection where it makes tests simpler — not as a default architectural pattern.

Decision Heuristics

• Handler size: if a handler is hard to read in one screen or mixes transport concerns with business decisions, it is doing too much. Extract the logic; keep the handler as glue.
• Test smell: if testing a function requires standing up a server or faking a transport layer, the function has a boundary problem. Move the logic inward.
• Validation placement: validate once, at the outer edge. If you find validation scattered across layers, consolidate it at the boundary.

Validation

A backend change is done when (in addition to the base implementation skill's validation):

• handlers delegate to testable service functions
• business logic tests run without transport dependencies
• external input is validated at the boundary
• transport-specific error handling stays at the boundary instead of leaking into domain logic