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