engineering-senior-developer

Este extracto es una copia guardada durante la revisión. La fuente externa contiene la versión completa y actual.

---
name: engineering-senior-developer
description: "Lead complex software implementation, architecture decisions, and reliable delivery across any modern technology stack. Use when you need pragmatic architecture tradeoffs, technical plan creation from ambiguous requirements, code quality improvements, production-safe rollout strategies, observability setup, or senior engineering judgment on maintainability, testing, and operational reliability."
metadata:
  version: "1.0.0"
---

# Senior Development Guide

## Overview
This guide covers the workflow, standards, and patterns for delivering production-grade software across web, backend, mobile, and platform work. Use it when planning implementation, making architecture tradeoffs, improving code quality, or shipping safely.

## Delivery Workflow

### 1. Understand the problem
- Clarify goals, constraints, success metrics, deadlines, and non-goals. If any of these are missing, ask before writing code — never assume.
- Identify unknowns: if >2 unknowns exist, add a spike task (max 2 hours, concrete deliverable) before committing to an estimate.
- Propose a minimal viable technical approach first. If the approach requires >5 days of work, look for a simpler alternative or split into phases.
- Define acceptance criteria before implementation. Every criterion must be verifiable — "works correctly" is not a criterion; "returns 200 with JWT containing user_id claim" is.

### 2. Plan implementation
- Break work into small, testable milestones. Each milestone must be mergeable independently — if milestone B cannot ship without milestone A, they are one milestone.
- If a change touches >5 files, write a 1-paragraph plan before starting. If >15 files, write a design doc (see references/design-docs.md).
- Plan rollback: every database migration must be reversible. If a migration drops a column, first deploy code that stops reading it, then drop in the next release.
- For any new external dependency (API, service, database), define: timeout (default 5s), retry policy (3 attempts, exponential backoff), circuit breaker threshold (5 failures in 60s), and fallback behavior.

### 3. Implement and verify
- Functions >40 lines: split. Files >300 lines: split. If a function takes >4 parameters, introduce a config/options object.
- Test at the right level: pure logic = unit test. API endpoints = integration test. Critical user flows = E2E test (max 5 E2E tests per feature — they are slow and flaky).
- Every new API endpoint must have: input validation (Zod/Pydantic/class-validator), error response schema, rate limit, and at least one integration test.
- Every database query on a table with >10k rows must have an index. Run EXPLAIN ANALYZE and reject sequential scans on large tables.
- Never catch an error and swallow it silently. Log it with context (operation, input, correlation ID) or re-throw. Catch only errors you can handle.
- Backward compatibility: if changing a shared type or API response shape, grep all consumers. If >0 consumers depend on the old shape, use expand-migrate-contract (add new field, migrate consumers, remove old field).

### 4. Ship and stabilize
- Before merging: run the full test suite locally, verify no lint/type errors, check bundle size / binary size if applicable.
- Deploy with observability: every deploy must be visible in metrics within 5 minutes. If you cannot tell from a dashboard whether the deploy is healthy, add instrumentation before deploying.
- After deploy: monitor error rates and p95 latency for 30 minutes. If error rate increases >2x or p95 doubles, roll back immediately — do not debug in production first.
- Capture tech debt within 48 hours of discovering it. Each debt item must have: description, impact (latency/reliability/developer velocity), estimated effort, and owner. Unowned debt does not get fixed.

## Engineering Standards
- Every API endpoint must document: request/response schema, error codes with meanings, authentication requirement, and rate li