backend-guidelines

Backend Guidelines

Purpose

Keep backend changes correct under real-world inputs, failures, concurrency, security boundaries, and operational constraints.

When to use it

• Implementing or reviewing APIs, commands, services, jobs, storage, queues, auth, permissions, integrations, or server-side business logic.
• Adding validation, serialization, caching, retries, transactions, migrations, or configuration.
• Debugging backend failures where root cause may involve data shape, race conditions, external services, or environment differences.

Instructions

1. Validate at trust boundaries: user input, HTTP/CLI args, files, environment, database records from older versions, webhooks, and third-party responses.
2. Keep domain rules close to domain logic. Do not bury business policy inside route handlers, persistence adapters, or transport glue.
3. Make API contracts explicit: request/response shape, status/error behavior, pagination, idempotency, compatibility, and authorization.
4. Handle persistence deliberately: transactions, ordering, uniqueness, migrations, rollback, nullability, and large-data behavior.
5. Design for retries and partial failure. External calls need timeouts, backoff/retry policy when appropriate, idempotency, and observable errors.
6. Treat auth and authorization as separate checks. Authentication proves who; authorization proves whether the action is allowed for this resource.
7. Avoid leaking secrets or sensitive data in logs, errors, metrics, test snapshots, generated files, or client-visible responses.
8. Keep configuration typed, validated, documented, and safe by default. Missing config should fail loudly when required.
9. Add tests at the right level: unit tests for domain rules, integration tests for contracts/persistence, regression tests for bugs, and boundary tests for invalid input and permission failures.
10. Report operational impact: migrations, new env vars, background jobs, performance risks, observability, rollout, and rollback.