backend-guidance

Backend Guidance

This is a composable overlay, not a standalone workflow. Use alongside the matching principle skill (for example, coding-guidance-cpp) when the change touches backend code. Add project-core-dev only when repository-specific completion checks still need to be discovered or reported.

Choose the activity before applying the rules below:

• for implementation, make only the requested backend changes and validate them
• for review, inspect and report prioritized findings with evidence; do not edit files or require findings to be fixed unless the user also asks for remediation

Use this as the thin default backend overlay for ordinary backend work. If the task includes service-boundary refactors, repository or transaction work, queue or webhook reliability, stronger testing expectations, or explicit trust-boundary hardening, prefer backend-systems-guidance.

Routing examples:

• thin route handler that delegates to existing service logic -> use this skill
• small message consumer bug fix with no retry or persistence redesign -> use this skill
• new endpoint with authz, repository, transaction, retry, or observability changes -> use backend-systems-guidance
• security audit of an endpoint or tenant membership/authorization boundary -> use security first; add security-identity-access when identity, session, or tenant authorization is central, and add the backend overlay only for implementation structure

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.
• Decode, normalize, and validate the external transport shape at the untrusted boundary before it reaches business logic. Do not confuse that check with domain invariants that the service or domain owner must enforce.
• Keep transport-only concerns at the edge: request decoding, authentication, and transport-specific error mapping. Enforce authorization in the earliest shared policy layer that every relevant entrypoint traverses; an edge-only authorization check is sufficient only when no other entrypoint can bypass it.
• Keep business invariants in service or domain code and persistence invariants in the data layer. Avoid duplicate checks that enforce the same contract, but do not remove a check merely because another layer validates a different concern.
• Use dependency injection where it makes tests simpler — not as a default architectural pattern.