playbooks

home / skills / vadimcomanescu / codex-skills / senior-backend

senior-backend skill

/skills/.curated/platform/senior-backend

This skill helps you design robust backend APIs and services by enforcing contracts, safety, observability, and maintainable migrations.

npx playbooks add skill vadimcomanescu/codex-skills --skill senior-backend

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
1001 B
---
name: senior-backend
description: "Backend engineering workflows for designing and implementing robust APIs and services: data modeling, authN/authZ, error handling, performance, migrations, observability, and operational safety. Use when building or reviewing backend code, defining API contracts, planning DB changes, or writing backend design docs."
---

# Senior Backend

Ship backend changes that are correct, observable, and easy to operate.

## Quick Start
1) Define contract first (API/events): inputs, outputs, errors, idempotency.
2) Define data ownership: schema changes, migrations, backfills, rollback.
3) Implement with safety:
   - validation, authZ, rate limits
   - structured errors + logging + metrics
4) Prove it: tests + a local “smoke path” + monitoring hooks.

## Optional tool: scaffold backend docs
```bash
python ~/.codex/skills/senior-backend/scripts/scaffold_backend_docs.py . --out docs/backend
```

## References
- API guidelines: `references/api-guidelines.md`

Overview

This skill codifies senior backend engineering workflows for designing and delivering robust APIs and services. It focuses on contract-driven design, data ownership and safe migrations, authentication and authorization, error handling, observability, and operational safety. Use it to guide code reviews, design docs, and implementation plans to ensure changes are correct and easy to operate.

How this skill works

The skill inspects API contracts, data models, and deployment plans to surface gaps in inputs, outputs, error semantics, idempotency, and ownership. It checks for essential safety features such as validation, authZ, rate limiting, structured errors, logging, and metrics, and recommends testing and monitoring hooks. It also guides migration strategies, rollback plans, and backfill approaches to minimize risk.

When to use it

  • Designing or reviewing an API contract or event schema
  • Planning database schema changes, migrations, or backfills
  • Implementing authN/authZ, validation, or rate limiting
  • Writing backend design documents or RFCs
  • Preparing releases that require operational testing and monitoring

Best practices

  • Start contract-first: specify inputs, outputs, error types, and idempotency up front
  • Declare explicit data ownership and migration/backfill plans before writing code
  • Implement validation, authorization, and rate limits early in the request path
  • Emit structured errors, logs, and metrics for every failure mode
  • Ship a local smoke path and automated tests that cover success, failure, and rollback
  • Add monitoring hooks and SLO-focused alerts before deployment

Example use cases

  • Reviewing a pull request that adds a new public REST endpoint and ensuring its contract and errors are well-defined
  • Planning a rolling migration that adds a nullable column, a backfill job, and a rollback plan
  • Designing service-to-service authZ and rate limiting for a high-throughput internal API
  • Creating a design doc that lists observability gaps and required metrics for a new feature
  • Defining end-to-end tests and a smoke path to validate operational readiness in staging

FAQ

What does 'contract-first' mean in practice?

Define API inputs, outputs, error codes, and idempotency guarantees before implementation so clients and services have a stable expectation.

How should I approach risky schema changes?

Declare ownership, design non-blocking migrations, implement backfills with throttling, and include a clear rollback plan and monitoring to detect regressions.