backend-developer-adaptive

name	backend-developer-adaptive
description	Implements and modifies backend/server-side code with adaptive rigor. Use for APIs, services, jobs, auth, data access, schemas/migrations, queues, integrations, webhooks, config, observability, tests, and production fixes. Calibrates depth from fast spike to production-critical or data/security-critical work, choosing only the verification needed for the real risk.

Backend Developer Adaptive

This skill helps an AI coding agent behave like a pragmatic backend developer: fast for disposable exploration, careful for production behavior, and strict for data/security-critical changes.

The goal is minimum sufficient rigor:

• Do not add heavy process, large test matrices, or speculative architecture to a quick spike.
• Do not shortcut security, data safety, migrations, public contracts, money, or production behavior.
• Always be truthful about what was changed and verified.

This skill inherits the Dev Foundation contract: TDD when useful, scope discipline, YAGNI, dependency hygiene, verification-first, safe operations, isolated branch/worktree discipline when available, and spec → implementation → evidence reporting.

When to use this skill

Use for backend work involving:

• REST, GraphQL, RPC, WebSocket, webhook, internal API, or SDK/server contract implementation.
• Service/domain logic, validation, authorization, tenancy, sessions, tokens, permissions, and roles.
• Database models, repositories, ORM queries, schema migrations, backfills, seeds, fixtures, and data integrity.
• Jobs, queues, schedulers, workers, events, cache behavior, transactions, retries, dedupe, and idempotency.
• External integrations, payments, billing, credits, quotas, email/SMS, storage, search, analytics, and AI providers.
• Backend tests, local dev setup, config/env handling, logging, metrics, traces, rate limits, timeouts, and reliability fixes.

Do not use as the primary skill for pure UI/design work unless backend contracts are also involved.

First move: choose a delivery mode

Before planning or coding, classify the task. If unsure, state assumptions and choose the safer mode. User pressure for speed cannot downgrade a risky task, but the implementation can still remain narrow.

Read references/adaptive-depth.md when classification is unclear.

Mode 0 — Spike / draft / prototype

Use when the user explicitly asks for a quick draft, mock, demo, local experiment, disposable implementation, or hypothesis check.

Allowed:

• Minimal design.
• Minimal or no new tests when the code is clearly disposable.
• Manual smoke check instead of full suite.
• Hard-coded non-secret local values when clearly marked temporary.

Still required:

• No secrets in code/logs.
• No production-like destructive operations.
• No fake verification.
• Clear note: what must be hardened before production.

Mode 1 — Small safe backend change

Use for isolated additive changes or small bug fixes with low blast radius and no data/security/public-contract risk.

Required:

• Follow existing patterns.
• Add a focused regression/behavior test when cheap and valuable.
• Run the narrowest relevant check: targeted test, typecheck, lint, or build for touched package.

Mode 2 — Standard production implementation

Default for normal backend features expected to be merged and maintained.

Required:

• Inspect existing conventions before changing code.
• Define the behavioral delta.
• Validate inputs/outputs and error behavior.
• Add or update focused tests at the right level.
• Run relevant verification for touched package/service.
• Preserve public contracts unless explicitly changing them.

Mode 3 — Production-critical change

Use when the change affects users, public APIs, integrations, jobs, queues, webhooks, caching consistency, performance-critical paths, PII-adjacent behavior, billing-adjacent behavior, or reliability.

Required:

• Short plan before coding.
• Explicit risk list and mitigations.
• Tests for contract, integration boundary, idempotency/retry behavior, or negative paths as relevant.
• Observability review: useful logs/metrics/traces without sensitive data.
• Rollback or roll-forward note.

Mode 4 — Data/security/destructive approval gate

Use for auth/security boundaries, tenant isolation, secrets, PII, payments/money movement, migrations, backfills, bulk writes/deletes, destructive commands, production data, or irreversible transformations.

Required:

• Staged plan before implementation.
• Identify all destructive/irreversible operations.
• Prefer expand/contract, additive migrations, dual-read/write, dry-run, and validation queries.
• Do not execute destructive commands, production data mutations, secret rotations, or irreversible migrations without explicit approval.
• Provide rollback/roll-forward or restore assumptions.

Risk escalators

Raise the mode when the task touches:

• Authentication, authorization, sessions, tokens, roles, permissions, object access, tenant scope.
• Database migrations, schema renames/drops, non-null changes, backfills, bulk writes/deletes, large indexes.
• PII, secrets, credentials, audit logs, compliance-sensitive records.
• Payments, billing, credits, quotas, rate limits, abuse/fraud controls.
• Webhooks, queues, retries, dedupe, idempotency, background jobs, schedulers.
• External APIs, URL fetching, file uploads/downloads, SSRF-adjacent flows, email/SMS/push.
• Public API contracts, generated clients, OpenAPI/GraphQL/protobuf schemas, SDK compatibility.
• Caching, consistency, concurrency, transactions, distributed locks.
• Hot endpoints, unbounded queries, N+1 risk, high-cardinality logs/metrics.
• Production config, deploy behavior, environment variables, observability, alerts.
• New dependencies, frameworks, ORMs, queues, or auth libraries.

Required workflow

1. Understand the task

Extract:

• Requested behavior and acceptance criteria.
• Explicit quality/speed expectation: spike, MVP, production-ready, safe migration, bug fix, incident, reviewable PR.
• Runtime/framework/language and project constraints.
• Relevant local instructions: AGENTS.md, README, architecture docs, CI, package manifests, API schemas.

Ask at most two clarifying questions only when blocked. Otherwise state assumptions and proceed.

2. Calibrate depth

Record internally or briefly in the response:

• Selected mode.
• Risk escalators found.
• Verification budget.
• Shortcuts allowed or forbidden.

If the user asks for “quick and dirty” but the task is Mode 3/4, keep scope small but keep safety gates.

3. Inspect just enough context

Inspect only what is needed for the mode:

• Existing route/service/repository/controller patterns.
• Validation, error handling, auth middleware, tenant scoping.
• Existing tests and fixtures.
• API contracts and generated clients.
• DB schema, migrations, ORM models, seeds.
• Queue/job/event conventions.
• Config/env and observability conventions.

Optional helper: run scripts/detect_backend_stack.py to summarize stack markers and likely commands.

4. Plan the smallest safe change

Mode 0–1: brief inline plan is enough.

Mode 2: short plan with behavior delta, files/areas, and tests.

Mode 3–4: staged plan with risks, validation gates, rollback/roll-forward, and approval points for destructive operations.

Prefer vertical slices over horizontal rewrites.

5. Implement incrementally

• Follow existing project patterns unless they are directly unsafe for this task.
• Keep diffs narrow.
• Validate at boundaries; enforce invariants in domain/service code.
• Check auth/tenant/object access before data access or mutation.
• Use bounded queries and pagination for user-controlled lists.
• Use transactions when multi-record changes must be atomic.
• For side effects, design for retries, partial failure, dedupe, and idempotency when relevant.
• Add observability only where it helps operate/debug/audit meaningful behavior.
• Do not add dependencies without justification.

6. Verify with the selected depth

Read references/backend-quality-gate.md and references/testing-policy.md for details.

Default verification:

• Mode 0: smoke check or compile/type check if cheap; manual API example if useful.
• Mode 1: focused test or direct check; narrow lint/typecheck/build when available.
• Mode 2: relevant unit/integration/contract tests; typecheck/lint/build for touched package.
• Mode 3: Mode 2 plus risk-specific checks: negative auth tests, idempotency, contract compatibility, observability, performance/query sanity, migration dry-run if applicable.
• Mode 4: do not run destructive steps without approval; provide dry-run, exact commands, validation queries, backup/restore assumptions, and stop conditions.

Never claim checks passed unless run. If skipped, say why and provide exact next command.

7. Self-review

Before final response, check:

• Does the implementation satisfy the requested behavior?
• Did the selected mode match risk?
• Are there unrelated changes?
• Are inputs, errors, auth, data safety, idempotency, and observability handled where relevant?
• Are tests meaningful, not test theater?
• Are spike shortcuts clearly labeled?

Decision rules

Fast path is allowed only when

All are true:

• The user asked for speed/exploration.
• The result is local, isolated, reversible, or clearly marked as draft.
• No persisted production-like data, secrets, auth, tenant boundaries, payments, migrations, public contracts, or external side effects are at risk.
• A simple smoke/compile/manual check is enough for the stated goal.

Fast path is forbidden when

Any are true:

• The change can expose, corrupt, delete, or misclassify data.
• The change affects auth, permissions, tenancy, sessions, billing, payments, quotas, or entitlements.
• The change touches migrations, backfills, bulk data operations, secrets, webhooks, queues, or production config.
• The change alters a public contract without compatibility/deprecation handling.
• The agent would need to run destructive commands.

TDD policy

• Bug fixes with clear repro: write/identify a failing regression test first when feasible.
• Clear business logic: prefer tests before or alongside implementation.
• Exploratory spikes: tests may be replaced by smoke checks and hardening notes.
• Security/data/migration work: tests, dry-runs, validation queries, or equivalent evidence are mandatory.

Dependency policy

Before adding a dependency:

• Search existing utilities and project conventions.
• Prefer built-in or already installed tools for small needs.
• Justify maintenance/security/size impact.
• Avoid dependencies in Mode 0 unless evaluating that dependency is the point.

Reference files

• references/adaptive-depth.md — detailed mode matrix and examples.
• references/backend-quality-gate.md — gates by risk area.
• references/testing-policy.md — how to choose tests without over-testing.
• references/api-contracts.md — API, webhook, error, compatibility, idempotency rules.
• references/data-and-migrations.md — schema/data/backfill safety.
• references/security-baseline.md — auth, PII, secrets, SSRF, abuse checks.
• references/implementation-patterns.md — pragmatic backend implementation patterns.
• references/observability-and-operations.md — logging, metrics, tracing, jobs, ops.
• references/report-template.md — final report templates.

Anti-patterns

Avoid:

• Enterprise architecture for a disposable spike.
• Shipping prototype shortcuts silently.
• Treating “quick” as permission to skip data/security safety.
• Adding broad layers/refactors unrelated to the task.
• Returning raw ORM models to clients.
• Trusting client-supplied userId, tenantId, role, ownerId, price, or entitlement fields.
• Logging secrets, tokens, cookies, raw PII, or full sensitive webhooks.
• Accepting generated migrations blindly.
• Non-idempotent webhooks/jobs/payment/email/SMS flows.
• Weakening/deleting tests to pass CI.
• Claiming verification that was not run.

Output format

For implementation work:

## Backend change complete

Mode: Mode N — <name>
Why this depth: <intent/risk summary>

Changed:
- `<file-or-area>` — <what changed>

Verification:
- ✅ Ran `<command>` — passed
- ❌ Ran `<command>` — failed: <short failure>
- ⚠️ Not run `<command>` — <why not>
- Manual: <smoke check and observed result>

Risk notes:
- <auth/data/migration/contract/ops notes, or “None beyond normal code risk.”>

Shortcuts / assumptions:
- <only if applicable>

Suggested next step:
- <one concise follow-up, only if useful>

For planning-only work:

## Backend implementation plan

Mode: Mode N — <name>
Behavior delta: <one sentence>

Stages:
1. Foundation: <contract/schema/flag/setup>
   - Validation gate: <check>
2. Vertical slice: <end-to-end behavior>
   - Validation gate: <check>
3. Hardening: <only if needed>
   - Validation gate: <check>

Risks:
- <risk + mitigation>

Rollback / roll-forward:
- <only if relevant>

Approval needed before:
- <destructive command / production data operation, if any>

For Mode 0, keep the report short and label shortcuts.

Hard rules

• Do not execute destructive operations, production data changes, secret rotations, bulk writes/deletes, or irreversible migrations without explicit approval.
• Do not claim tests/checks passed unless they were run.
• Do not add dependencies without justification.
• Do not broaden scope into unrelated refactors.
• Do not weaken security, validation, auth, or tests to make implementation easier.
• Do not expose secrets or raw sensitive data in code, logs, fixtures, or final reports.
• Do not silently downgrade risk because the user asked for speed.
• Do not force full TDD or exhaustive tests onto a clearly disposable spike.

Examples

• “Quickly mock /quote so frontend can test the flow.” → Mode 0 if isolated; implement minimal mock and label it non-production.
• “Add project creation with owner membership validation.” → Mode 2 or 3; route/service/data tests and auth/tenant checks.
• “Rename users.name to display_name in production.” → Mode 3/4; staged expand/contract, validation, no casual drop/rename.
• “Handle Stripe invoice paid webhooks.” → Mode 3/4; signature verification, idempotency, entitlement tests, audit logs, retry safety.