CODE-SAURABH/OpenSkills / backend-dev
backend-dev
VerifiedProduction-grade backend development guidance — language and framework agnostic. Use when the user asks to build an API, design a backend service, create a database schema, implement authentication, write business logic, structure a backend project, or produce server-side code of any kind.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.5 KB |
SKILL.md
View on GitHub---
name: backend-dev
description: Production-grade backend development guidance — language and framework agnostic. Use when the user asks to build an API, design a backend service, create a database schema, implement authentication, write business logic, structure a backend project, or produce server-side code of any kind.
---
# Backend Development
Approach every backend task as a senior engineer who has been burned by shortcuts in production. You are not here to make something that works once — you are here to make something that works at 3am on a Saturday when no one is watching. Every decision defaults to correctness, observability, and maintainability over cleverness or speed.
---
## Step 0: Ground the Work Before Writing a Line
Before any code, establish:
1. **What is this service's single responsibility?** Name it in one sentence. If you can't, the scope needs splitting.
2. **What are the data boundaries?** What goes in, what comes out, what persists.
3. **What can fail?** External calls, DB writes, auth checks — enumerate failure points before coding happy paths.
4. **What does done look like?** Define the contract: endpoint, schema, or interface the caller expects.
State these four things explicitly to the user if the brief is ambiguous. Never silently assume.
---
## Execution Workflow
Before writing any implementation code, work through these steps in order:
1. **Understand the contract** — name the endpoint or function signature, its inputs, outputs, and error cases
2. **Map the layers** — decide what belongs in `api/`, `services/`, `repositories/`, and whether any new models or errors are needed
3. **Identify external dependencies** — list every DB call, external API, queue, or file system access the feature requires
4. **Enumerate failure modes** — for each dependency, ask: what happens if it is slow, returns nothing, or fails entirely?
5. **Define the tests first** — name the unit test cases before writing the implementation; if you cannot name them, the design is unclear
6. **Then implement** — follow the layer rules, apply the coding standards, handle every failure mode you named
Do not skip to implementation. A feature built on a vague contract costs more to fix than the time spent grounding it.
---
## Folder Structure
Always generate a clean, domain-driven folder structure. The structure must communicate the architecture at a glance. Follow this pattern regardless of language or framework:
```
project-root/
├── src/
│ ├── api/ # Route handlers / controllers — thin layer only
│ │ └── v1/ # Versioned from day one
│ ├── services/ # Business logic — no framework code here
│ ├── repositories/ # All data access — DB queries live here only
│ ├── models/ # Domain entities and data types
│ ├── middleware/ # Auth, logging, rate limiting, error handling
│ ├── config/ # Environment config, constants, feature flags
│ ├── utils/ # Pure helper functions — stateless, no side effects
│ └── errors/ # Custom error classes and error codes
├── tests/
│ ├── unit/ # One test file per source file
│ ├── integration/ # Tests that hit real DB / external services
│ └── fixtures/ # Shared test data and factories
├── migrations/ # Database migration files — versioned, never edited
├── scripts/ # One-off ops scripts, seeding, utilities
├── docs/ # API docs, ADRs, architecture diagrams
├── .env.example # Template — never commit .env
├── Dockerfile # Multi-stage, non-root user
├── docker-compose.yml # Local dev environment
└── README.md # Setup, run, test — nothing else
```
**Rules:**
- `api/` handlers must be thin — validate input, call a service, return a response. No business logic.
- `services/` must be framework-agnostic — they should be callable from a test without spinning up a server.
- `repositories/` are the only place that know about the database. No raw queries elsewhere.
- Never cross layers — a `repository` never calls a `service`, a `model` never imports `middleware`.
---
## API Design
Every API must be designed contract-first. Define the interface before implementing it.
**Mandatory conventions:**
- Version from day one: `/api/v1/resource`
- Use correct HTTP methods: GET (read), POST (create), PUT (replace), PATCH (partial update), DELETE (remove)
- Return consistent HTTP status codes — never return 200 for an error
- For new REST APIs, default to a consistent response envelope:
```json
// Success
{ "data": { ... }, "meta": { ... } }
// Error
{ "error": { "code": "RESOURCE_NOT_FOUND", "message": "...", "details": [...] } }
```
Use this as the starting point unless the project has an established convention — consistency within a codebase matters more than the specific shape.
- Paginate all list endpoints — cursor-based preferred for large datasets, offset for simple cases
- Never expose stack traces or database errors in responses
- Every endpoint must have an OpenAPI/schema definition — auto-generate where possible
**Request handling checklist for every endpoint:**
- [ ] Validate and sanitize all input at the boundary before it touches any logic
- [ ] Authenticate — verify identity
- [ ] Authorize — verify permission for this specific resource
- [ ] Execute business logic via service layer
- [ ] Return typed, documented response
---
## Code Quality Standards
Every piece of generated backend code MUST follow these rules — no exceptions:
### Types & Contracts
- All function signatures must have explicit input and output types
- Define data contracts (schemas/interfaces/structs) for every external boundary: API input, API output, DB row, event payload
- No implicit any / untyped parameters — if a type is unknown, make it explicit and handle it
### Error Handling
- Never swallow errors silently — every caught error must be logged or re-thrown
- Use custom error classes with error codes, not raw strings
- Distinguish operational errors (invalid input, not found) from programmer errors (null dereference, wrong type)
- All async operations must have error handling — no unhandled promise rejections, no unchecked results
- Errors bubble up to a single top-level error handler that formats and logs them consistently
### Defensive Programming
- Validate all external input: API requests, environment variables, config values, message queue payloads
- Fail fast — check preconditions at the top of a function, not buried in the middle
- Never trust external data: third-party APIs, user uploads, webhook payloads
### Naming & Clarity
- Functions named as verbs: `getUserById`, `sendWelcomeEmail`, `calculateTax`
- Variables named as nouns: `userId`, `orderTotal`, `connectionPool`
- No abbreviations unless universally understood (`id`, `url`, `http`)
- One concept per function — if a function does two things, split it
- Comments explain *why*, not *what* — if the code needs a comment to explain what it does, rewrite the code
### Constants & Configuration
- No magic numbers or magic strings anywhere in business logic
- All configuration comes from environment variables — never hardcoded
- Group related constants into named objects/enums
- Every required environment variable must be validated on startup — crash early with a clear message rather than failing mysteriously later
---
## Database Rules
- **Migrations only** — never mutate a schema manually; every change is a versioned, reversible migration file
- **Indexes driven by query patterns** — add indexes for the queries you actually run; over-indexing slows writes; document the query that justifies each index in the migration comment
- **Transactions when atomicity is required** — wrap multi-step writes that must succeed or fail together in a transaction; not every multi-row operation needs one — use judgement
- **Soft deletes when the business requires it** — use `deleted_at` timestamps when audit history, undo, or compliance matters; hard deletes are correct when data has no retention requirement
- **Timestamps everywhere** — every table gets `created_at` and `updated_at` by default
- **Parameterized queries only** — never interpolate user input into a query string
- **Connection pooling** — configure min/max pool size; never open unbounded connections
- **Read replicas when scale requires it** — design repositories so read/write routing can be introduced later without touching service code; do not add the complexity before you need it
---
## SOLID and Dependency Design
Apply SOLID principles as engineering judgement, not as a checklist. The goal is code that is easy to change, easy to test, and honest about its dependencies.
- **Single Responsibility** — a module has one reason to change. A service that sends emails and processes payments will be painful to test and painful to change. Split them.
- **Open/Closed** — extend behaviour by adding code, not by editing existing logic. New payment providers, new notification channels, new export formats should slot in without touching working code.
- **Liskov Substitution** — any implementation of an interface must honour the contract of that interface. A mock in tests must behave like the real thing in the ways the caller depends on.
- **Interface Segregation** — callers should not depend on methods they do not use. A `UserRepository` interface used by the auth service should not expose bulk-export methods only the admin service needs.
- **Dependency Inversion** — high-level modules (services) depend on abstractions, not on concrete implementations (a specific DB client, a specific email provider). Wire concrete implementations at the composition root.
- **Composition Root** — all dependency wiring happens in one place at startup. Services do not construct their own dependencies. This makes the dependency graph readable and testable.
**Avoid over-engineering.** Do not introduce abstractions speculatively. Create an abstraction only when one of these is true:
- Multiple implementations exist now or are planned imminently
- The dependency crosses an external boundary (DB, HTTP, file system, queue)
- The dependency is nondeterministic (time, random, environment)
- It must be replaced in tests with a controlled substitute
- It represents a stable domain capability that multiple consumers will share
If none of these apply, use the concrete type directly.
---
## Reliability and External Dependencies
Every call that leaves the process boundary is a call that can fail, hang, or return inconsistent results. Design for this explicitly.
- **Timeouts** — set an explicit timeout on every outbound call; never rely on the remote end to close the connection
- **Retries with backoff** — retry transient failures (network errors, 429s, 503s) with exponential backoff and jitter; do not retry non-idempotent operations unless the operation is safe to repeat
- **Idempotency** — design write operations to be safely retryable; use idempotency keys for payment and order operations; ensure that processing a message twice produces the same outcome as processing it once
- **Message queues** — use queues to decouple producers from consumers and to absorb load spikes; consumers must be idempotent; dead-letter queues are mandatory for any queue used in production
- **Transactional outbox** — when a DB write and a message publish must happen together, write the event to an outbox table in the same transaction as the business data, then publish from the outbox asynchronously; this prevents silent message loss on process crash
---
## Authentication & Authorization
- Use short-lived access tokens + refresh token rotation as the default auth pattern
- Hash all passwords with a strong adaptive algorithm (bcrypt cost ≥ 12, or argon2id)
- Store tokens in httpOnly cookies for browser clients; never in localStorage
- Implement RBAC — every protected route checks both authentication (who are you?) and authorization (can you do this to this resource?)
- Verify resource ownership on every request — a user fetching `/orders/123` must own order 123
- Implement account lockout after repeated failed attempts
- Rotate secrets on a schedule; invalidate all sessions on password change
- Never log passwords, tokens, secrets, or PII in any log line — ever
---
## Unit Testing
Every service function, utility, and repository method gets a unit test. No exceptions.
**Structure of every test file:**
```
describe('<ModuleName>', () => {
describe('<methodName>', () => {
it('returns X when given valid input Y')
it('throws ErrorCode.X when input is missing')
it('calls dependency Z exactly once with correct args')
it('does not call dependency Z when condition is false')
})
})
```
**Rules:**
- Test behaviour, not implementation — test what a function does, not how it does it
- One assertion concept per test — a test that checks three things is three tests
- Mock all external dependencies (DB, HTTP, file system, clock) in unit tests — a unit test never hits the network or disk
- Use factories/builders for test data — never hardcode raw objects scattered across test files
- Test the sad path as rigorously as the happy path: invalid input, missing data, dependency failures, edge cases
- Every test must be independent — no shared mutable state between tests, no order dependency
- Aim for 80%+ line coverage on `services/` and `utils/`; 100% on critical auth and payment paths
**For every public function, generate tests that cover:**
- [ ] Happy path with valid input
- [ ] Missing required input
- [ ] Invalid type / format input
- [ ] Boundary values (empty string, zero, max int, null)
- [ ] Dependency throws an error
- [ ] Dependency returns empty / null
- [ ] Concurrent / race condition if applicable
---
## Integration Testing
- Integration tests live in `tests/integration/` and run against a real database (use containers or an in-memory equivalent)
- Test the full stack from HTTP request to DB response for critical paths
- Each integration test must clean up its own data — use transactions that rollback, or explicit teardown
- Test unhappy paths at the integration level too: DB constraint violations, duplicate keys, connection failures
---
## Security Checklist
Before marking any backend feature complete, verify:
- [ ] All inputs validated and sanitized at the API boundary
- [ ] SQL/NoSQL injection impossible (parameterized queries / ORM)
- [ ] Authentication required on all non-public endpoints
- [ ] Authorization checks resource ownership, not just role
- [ ] Sensitive data (passwords, tokens, keys) never logged or returned in responses
- [ ] Rate limiting applied to auth endpoints and expensive operations
- [ ] CORS configured to a whitelist, not `*` for credentialed requests
- [ ] Security headers set on all responses
- [ ] Dependencies audited for known vulnerabilities
- [ ] Secrets loaded from environment, not source code
---
## Observability
Every backend service must be observable from day one:
- **Structured logging** — every log line is a machine-readable JSON object with: `timestamp`, `level`, `message`, `correlationId`, `service`, and relevant context fields
- **Correlation IDs** — generate a unique ID per request at the entry point; thread it through every log line, every downstream call
- **Log levels used correctly**: `DEBUG` for dev-only detail, `INFO` for significant state changes, `WARN` for recoverable issues, `ERROR` for failures that need attention
- **Health endpoints** — every service exposes `/health` (liveness) and `/ready` (readiness) with no auth required
- **Key metrics to instrument**: request count, error rate, latency (p50/p95/p99), DB query time, external call duration
- **Never log PII** — mask emails, phone numbers, card numbers before they reach any log line
---
## Environment & Configuration
- Every environment variable required at startup must be listed in `.env.example` with a description comment
- Validate all required env vars on startup — if one is missing, crash immediately with a clear error naming the missing variable
- Separate config by environment: `development`, `test`, `staging`, `production`
- Never use production credentials in development or test environments
- Feature flags for anything that needs to be toggled without a deploy
---
## Docker & Local Dev
Every backend project ships with:
**Dockerfile (multi-stage):**
- Stage 1: install dependencies
- Stage 2: build / compile
- Stage 3: minimal runtime image, non-root user, only production artifacts
**docker-compose.yml:**
- App service
- Database service with a named volume
- Cache service (if applicable)
- Any other backing services (queue, search, etc.)
- Health checks on all services
- Environment variables loaded from `.env`
---
## Definition of Done
A backend feature is not done until:
- [ ] Folder structure follows the project convention
- [ ] All inputs validated at the API boundary
- [ ] Business logic isolated in the service layer
- [ ] Data access isolated in the repository layer
- [ ] All error cases handled and logged
- [ ] Unit tests written for all service and utility functions
- [ ] Integration test written for the critical path
- [ ] Security checklist passed
- [ ] OpenAPI / schema definition updated
- [ ] `.env.example` updated if new env vars added
- [ ] README updated if setup steps changed
- [ ] No secrets, no magic numbers, no TODO comments left in committed code
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |