Elite Backend Engineering

This skill defines how backend systems must be designed, implemented, validated, and delivered.

It is language-agnostic. It applies to any serious backend stack. It is not tied to a specific framework, runtime, ORM, or cloud provider.

Its purpose is simple:

• produce correct backend systems
• avoid backend slop
• prevent unmaintainable architecture
• force clarity, discipline, and safe delivery

---

1. Use This Skill When

Use this skill for:

• API design
• service implementation
• backend refactors
• backend architecture decisions
• data flow design
• integration design
• background jobs and async workflows
• reliability and observability work
• performance-sensitive backend changes
• backend testing strategy

Do not use this skill for:

• frontend-only work
• small throwaway scripts with no backend lifecycle
• purely cosmetic refactors with no backend implications

---

2. Core Standard

Backend work must be:

• correct
• explicit
• testable
• observable
• secure
• maintainable
• minimal in complexity
• production-oriented

Do not optimize for cleverness. Do not optimize for novelty. Do not optimize for “impressive architecture.”

Optimize for:

• correctness
• operational safety
• simplicity
• long-term maintainability

---

3. First Principle: Understand Before Implementing

Before writing or changing backend code, resolve these questions:

Domain

• What problem does this backend change solve?
• What are the core business rules?
• What must always be true after the operation completes?

Interface

• What are the inputs?
• What are the outputs?
• What errors can occur?
• What are the invalid states?

Operational Reality

• What are the latency, scale, and throughput expectations?
• What consistency model is required?
• What happens on timeout, retry, partial failure, or duplicate request?
• What observability is required?
• What security controls are required?

If these are unclear, do not invent hidden assumptions. Surface them explicitly in the design.

---

4. Architecture Doctrine

4.1 Prefer the Simplest Architecture That Fully Solves the Problem

Start with the simplest correct design.

Do not introduce:

• microservices
• event sourcing
• CQRS
• sagas
• distributed workflows
• heavy caching layers
• advanced async orchestration

unless the requirements clearly justify them.

Simple systems are easier to reason about, test, and operate.

4.2 Clear Boundaries Are Mandatory

Separate backend systems into clear responsibilities.

At minimum, separate:

• transport or delivery layer
• application or orchestration layer
• domain or business logic layer
• persistence and external integration layer
• shared contracts, schemas, and types

Do not mix these concerns inside one file or one function.

4.3 Transport Layers Must Not Contain Business Logic

Handlers, controllers, routes, or endpoints must:

• parse input
• call application logic
• return a response
• map known errors correctly

They must not contain:

• core business rules
• persistence logic
• data access details
• hidden side effects

4.4 Business Logic Must Be Framework-Agnostic

Core business rules must not depend on transport details. They must be testable in isolation.

4.5 Persistence and Integrations Must Be Isolated

Database access, queues, file systems, caches, and external APIs must be behind explicit boundaries. Do not spread direct integration calls across the codebase.

---

5. Modularity Rules

5.1 One Responsibility Per File or Module

Each file or module should have one clear purpose.

If one unit is doing multiple unrelated things, split it.

5.2 No God Files

Large files are usually a design failure.

If a file is growing because it contains:

• transport logic
• business logic
• validation
• persistence
• external API calls
• transformation utilities

it must be broken apart.

5.3 Folder Structure Must Communicate Architecture

The project structure must make responsibilities obvious.

A new engineer should be able to understand:

• where contracts live
• where business logic lives
• where persistence lives
• where integrations live
• where tests live
• where configuration lives

If the structure hides responsibility, the structure is wrong.

---

6. Contracts First

6.1 Define Explicit Contracts

Every backend boundary must have an explicit contract.

That includes:

• request shape
• response shape
• error shape
• event shape
• message shape
• job payload shape
• persistence model boundaries where relevant

6.2 Versioning Must Be Deliberate

If a contract is externally consumed, versioning and compatibility must be considered explicitly.

Do not break consumers casually.

6.3 Errors Must Be Designed, Not Improvised

Define:

• validation errors
• authorization errors
• not found cases
• conflict cases
• rate limit cases
• dependency failures
• internal failures

Do not collapse all failures into vague generic errors.

6.4 Idempotency Must Be Considered

For writes, retries, async workflows, webhooks, payments, or external integrations, explicitly determine whether idempotency is required. If duplicate execution can corrupt state, design for idempotency.

---

7. Typing, Validation, and Data Discipline

7.1 Strong Typing Where the Language Supports It

Use the strongest practical type guarantees available in the stack.

Do not rely on vague dynamic shapes when explicit types or schemas are available.

7.2 Validate All External Input

Every boundary must validate incoming data:

• request bodies
• query parameters
• route parameters
• headers where relevant
• webhook payloads
• queue messages
• scheduled job inputs
• configuration values

No external input is trusted by default.

7.3 Nullability and Optionality Must Be Explicit

Do not hide absence, partial state, or uncertainty. Make optional fields, nullable fields, defaults, and required fields explicit.

7.4 Centralize Configuration

Configuration must come from a single governed source. Do not scatter environment access and configuration parsing throughout the codebase.

---

8. Error Handling and Observability

8.1 No Silent Failure

Never swallow errors. Never log and continue unless the behavior is intentionally safe and documented.

8.2 Errors Must Be Captured With Context

Every operationally relevant failure must include enough context to debug:

• request or operation identity
• actor or caller where appropriate
• affected resource
• failure reason
• retry context if applicable

8.3 Structured Observability Is Mandatory

Backend systems must support:

• structured logging
• metrics
• tracing or equivalent request correlation
• health visibility for critical paths

8.4 Correlation Must Exist Across Boundaries

Requests, jobs, and events must be traceable through the system. Do not create black boxes between services or layers.

---

9. Security Baseline

These are mandatory defaults:

• validate all external input
• enforce authentication where required
• enforce authorization on sensitive actions
• use least privilege for data and service access
• never hardcode secrets
• never trust client-provided authorization claims without verification
• use parameterized or safe query mechanisms
• rate limit externally exposed sensitive surfaces where appropriate
• verify webhook authenticity where applicable
• treat file, network, and deserialization boundaries as hostile by default

Security must be built in, not patched in later.

---

10. Data and Consistency Rules

10.1 Define Invariants

Before implementing writes, define what must remain true in the data model.

10.2 Define Transaction Boundaries

For state changes, determine:

• what must happen atomically
• what may happen asynchronously
• what may fail independently
• what requires compensation or retry

10.3 Consistency Tradeoffs Must Be Explicit

If a workflow is eventually consistent, state that explicitly. Do not let implicit eventual consistency leak into code by accident.

10.4 Concurrency Must Be Considered

For mutable state, consider:

• duplicate requests
• races
• reordering
• retries
• partial completion

If concurrency can break correctness, address it directly.

---

11. Performance and Scalability

11.1 Measure Before Optimizing

Do not guess performance bottlenecks. Identify the actual hot path.

11.2 Optimize the Right Things

Focus on:

• query efficiency
• batch behavior
• pagination
• payload size
• network round trips
• concurrency limits
• timeouts
• connection or resource pool usage
• caching only where justified

11.3 Caching Requires an Invalidation Strategy

Never add cache without answering:

• what is cached
• when it becomes stale
• how it is invalidated
• what happens on cache miss
• whether stale reads are acceptable

11.4 Backpressure and Timeouts Must Exist

Any external dependency or async workload must have:

• timeout behavior
• retry policy where justified
• failure handling
• concurrency limits where needed

---

12. Testing Discipline

Testing is not optional.

12.1 Test Types

Use the right level of testing for the problem:

• unit tests for isolated business logic
• integration tests for real component interaction
• contract tests for interface guarantees
• end-to-end tests only for high-value flows
• load or stress testing only when scale or throughput matters

12.2 Minimum Required Coverage of Risk

Tests must cover:

• happy path
• invalid input
• authorization failures
• not found cases
• conflict cases
• dependency failure cases
• retry or idempotency behavior where relevant
• edge cases around state and concurrency where relevant

12.3 Tests Must Be Isolated

Each test must run independently. No hidden state coupling. No dependence on execution order.

12.4 Do Not Use Production Dependencies in Tests

Tests must not depend on:

• production databases
• real third-party APIs
• shared mutable external state
• real secrets

Mock or isolate external systems deliberately.

12.5 Backend Changes Are Not Done Until Validation Passes

After backend changes, run the strongest validation available for the stack:

• formatter
• linter
• type checker or static analysis
• build or compile checks
• relevant test suites

Do not call the work complete until these pass.

---

13. Comment Policy

Do not over-comment.

Allowed comments:

• non-obvious tradeoffs
• important invariants
• known constraints
• behavior that would otherwise be misunderstood

Do not add comments that restate obvious code.

Clean structure and names are preferred over comment clutter.

---

14. Delivery Rules

14.1 Finish the Full Logical Task

Do not treat a backend task as done when only the happy path is implemented.

Completion requires:

• implementation
• validation
• tests
• error handling
• observability considerations
• security considerations
• cleanup of obvious edge cases

14.2 No Partial Backend Quality

Do not leave behind:

• dead code
• debug artifacts
• hidden TODOs for critical correctness gaps
• inconsistent error handling
• mixed architectural styles

14.3 Safe Change Management

For meaningful backend changes, consider:

• migration impact
• backward compatibility
• rollout risk
• fallback or rollback path
• monitoring after release

---

15. Anti-Patterns

Reject these immediately:

• business logic in handlers or routes
• direct persistence logic spread through the codebase
• direct external API usage everywhere with no abstraction
• giant files with mixed responsibilities
• hidden global state
• unvalidated external input
• silent failure
• vague catch-all error handling
• missing authorization checks
• premature distributed architecture
• caching with no invalidation strategy
• retries with no idempotency thinking
• tests coupled to execution order
• backend work shipped without validation
• architecture designed to look impressive rather than remain operable

---

16. Response Standard

When using this skill, the backend response should be decision-complete.

It should make these things explicit:

• assumptions
• boundaries
• contracts
• validation approach
• error model
• security model
• observability plan
• testing plan
• tradeoffs
• rollout or migration risk when relevant

Do not produce backend code or architecture that leaves core decisions implicit.

---

17. Final Backend Checklist

Before finalizing any backend work, confirm all of the following:

• requirements are explicit
• domain invariants are identified
• boundaries are clear
• contracts are explicit
• external input is validated
• business logic is isolated
• persistence and integrations are isolated
• error handling is deliberate
• observability exists for critical paths
• security controls are present
• consistency and concurrency risks were considered
• performance assumptions were not guessed blindly
• tests cover the meaningful risk
• validation tools pass
• no major anti-patterns remain

---

18. Enforcement Rule

When uncertain:

• choose the simpler design
• make the contract explicit
• isolate the responsibility
• validate the input
• make failure observable
• test the behavior
• remove unnecessary complexity