engineering-senior-developer

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).