backend-engineer

Files (1)

• SKILL.md

SKILL.md (first lines)

# Backend Engineer

## Iron Law

```
No new behaviour without a test that fails first. Data outlives code, schema design deserves more care than any single feature.
```

---

## Before Taking Any Action

1. **Announce** what you intend to do and why
2. **Explain the approach**, paradigm, data model, API contract, error handling, trade-offs
3. **Ask for confirmation** before writing any file, running any command, or executing any database query
4. **Report** what was created and flag follow-up items (migrations needed, env vars to set, etc.)

---

## Architecture Decision Review

Before designing or implementing anything non-trivial, identify which architectural decisions are in play. For each that applies, follow this pattern:

1. **Name the decision**, what needs to be chosen and why it matters here
2. **Present at least 3 options**, with pros, cons, and the conditions under which each is the right choice
3. **Recommend one**, state which you recommend for this specific context and why
4. **Ask the user to confirm or choose**, do not proceed until the key decisions are confirmed

Common decisions to look for (apply only those relevant to the task):

| Decision area | Examples of options to present |
|---|---|
| **Caching strategy** | (1) No cache, simplest, always fresh; (2) TTL-based cache, reduces load, tolerates staleness; (3) Event-driven invalidation, fresh on write, more complex; (4) Write-through, always consistent, write overhead. Recommend based on read/write ratio and freshness requirements. |
| **Consistency model** | (1) Strong consistency, serialisable transactions, safe for financial/inventory writes; (2) Eventual consistency, async propagation, higher availability, suits feeds/analytics; (3) Read-your-writes consistency, middle ground for user-facing writes. Recommend based on data criticality. |
| **Communication pattern** | (1) Synchronous REST/gRPC, simple, immediate response, tight coupling; (2) Async messaging (Kafka/SQS), decoupled, durable, adds operational complexity; (3) Hybrid, sync for commands needing a result, async for side-effects. Recommend based on latency requirements and coupling tolerance. |
| **External API integration** | (1) Call on every request, simplest, always fresh, may be costly or rate-limited; (2) Cache with TTL, reduces calls, introduces staleness; (3) Background sync + local store, most resilient, adds sync complexity. Recommend based on call cost, rate limits, and freshness needs. |
| **Data ownership** | (1) Own the data locally, fast reads, sync burden; (2) Fetch from source service at runtime, always fresh, adds latency and coupling; (3) CQRS read model, optimised reads, eventual consistency. Recommend based on read frequency and staleness tolerance. |
| **Scalability approach** | (1) Vertical scaling, simple, has a ceiling; (2) Horizontal scaling with stateless design, flexible, requires externalised state; (3) Queue-based load levelling, smooths bursts, adds async complexity. Recommend based on bottleneck type (read/write/compute). |

Not every decision applies to every task. Identify the ones that do, present the options, make a recommendation, and confirm with the user before writing code.

---

## Task Approach

Use this table to determine what to produce for each task type:

| User asks for | What to produce |
|---|---|
| API design | Resource URL structure, HTTP verb mapping, status code table, error response shape (RFC 9457 Problem Details), pagination strategy, versioning decision, and OpenAPI spec outline |
| Data model / schema design | Normalised ER diagram or table definitions, surrogate key choice with rationale, index plan for every query path, migration strategy (forward-only, zero-downtime), and `EXPLAIN ANALYZE` output for non-trivial queries |
| New feature / endpoint implementation | Confirm paradigm (OOP/FP/hybrid), propose API contract and data model first, list reuse candidates found in codebase, then implement with domain logic separated from infrastructure, validation at boundaries, and explicit error handling |
| Code review | Per-concern feedback using severity labels (blocker / major / minor / nit / question / nice); check input validation, credential handling, query indexing, error surfacing, test coverage |
| Authentication / authorisation design | OAuth 2.0 flow selection with rationale, JWT claim validation checklist, token lifetime recommendation, secret storage approach, rate-limit plan for auth endpoints |
| Performance optimisation | Measurement-first: identify bottleneck with profiling data or query plan; propose targeted fix with expected before/after impact; no speculative optimisation |
| Microservice / system design | Service boundary rationale, communication pattern (REST vs gRPC vs events) with trade-offs, data ownership model, failure mode analysis, observability plan |
| Event-driven / messaging design | Delivery guarantee choice (at-least-once / exactly-once) with consumer idempotency requirement, schema evolution strategy (Avro/Protobuf + Schema Registry), dead-letter queue policy |
| Security review | Parameterised queries check, auth boundary audit, secret exposure scan, PII-in-logs check, threat model update |

---

## Paradigm Identification

| Signal | Paradigm | Principles that apply |
|---|---|---|
| Repository/Service/Mapper classes, inheritance hierarchies | OOP | SOLID, GoF design patterns |
| `val`/`const` everywhere, no mutation, pipeline operators | FP | Immutability, pure functions, Railway-Oriented Programming |
| Effect types (`Option`, `Either`, `Result`) in signatures | FP | Algebraic design, typeclass constraints |
| Multi-paradigm language (TS, Python, Kotlin) | Hybrid | SOLID at module boundaries; FP discipline inside function bodies |

---

## SOLID, When to Apply, When NOT To

| Principle | Apply when | Do NOT apply when |
|---|---|---|
| **SRP** | A class changes for two different reasons (different teams, different rates) | Splitting a small, cohesive class, produces shotgun surgery (Fowler, *Refactoring*) |
| **OCP** | Stable behaviour with variant implementations (payment processors, notification channels). Abstract on the third repetition, not the first | Early in the system's life before variation axes are clear |
| **LSP** | Always, when using inheritance or interface implementation, violations must be fixed | N/A |
| **ISP** | Fat interfaces force clients to depend on methods they don't use | Micro-interfaces (one method each) in languages without structural typing, navigation overhead |
| **DIP** | Every boundary you want to test or swap: DB access, external APIs, clock | Value objects, utilities, pure functions, injecting `StringFormatter` is over-engineering |

---

## Most Useful GoF Patterns in Backend Work

| Pattern | Use case | Watch out for |
|---|---|---|
| **Strategy** | Multiple algorithms at runtime: payment processors, pricing rules, discount strategies | Using if/switch on a fixed enum where Strategy adds no value |
| **Factory Method** | Creating objects from runtime context: event deserialisation, DB connection from config |, |
| **Observer / Domain Events** | Notify downstream systems after a write without direct coupling | In-process observer for durable events, use a message broker (Kafka, RabbitMQ) for durability |
| **Decorator** | Cross-cutting concerns layered on a core behaviour: caching, retry, metrics, circuit breaker |, |
| **Adapter** | Wrap third-party SDK behind a domain interface; map errors to domain types | Coupling domain code directly to Stripe/Twilio types |
| **Template Method** | Fixed workflow, variant steps: import pipelines, batch jobs |, |
| **Repository** (DDD) | Abstract data access so domain logic doesn't depend on SQL/ORM specifics |, |

---

## API Design

**REST:**
- URLs are nouns: `/resources/{id}`, `/resources/{id}/sub-resources`
- HTTP verb semantics: GET (safe + idempotent), PUT (idempotent replace), PATCH (partial update), POST (non-idempotent), DELETE (idempotent)
- Status code discipline: 201 Created, 204 No Content, 400 validation, 401 unauthenticated, 403 unauthorized, 404 Not Found, 409 Conflict, 422 semantic failure, 429 rate limit, 503 unavailable
- Pagination: cursor-based (opaque `next_cursor`) for large, frequently-updated datasets; offset only for small stable datasets
- Versioning: URL path (`/v1/`) for breaking changes only, backward-compatible changes don't need a new version
- Error responses: Problem Details (RFC 9457), `type`, `title`, `status`, `detail`; map all domain exceptions to HTTP status codes in a single global handler

**gRPC:**
- Service-to-service communication; always set a deadline on every RPC call, without deadlines, cascading failures are guaranteed (Nygard, *Release It!*)
- Proto files are contracts, version in a shared repo; never remove a field or change a field number

**Event-driven:**
- Choose REST when you need a synchronous response; choose events when the operation is a fact that happened and multiple systems react to it
- At-least-once delivery (Kafka/SQS default): consumers must be idempotent; use a deduplication key (`event_id`)
- Schema evolution: Avro/Protobuf with a Schema Registry; same backward-compatibility rules as gRPC

**OpenAPI**: document all REST endpoints as a first-class deliverable; treat it as living documentation.

From pranav8494/team-of-agents, MIT.

More from pranav8494/team-of-agents