ai-agent-engineering-playbook

Design and review Backend-for-Frontend transport boundaries. Use when implementing or changing request parsing, response mapping, streaming proxy behavior, CORS, header allowlists, authentication boundaries, timeouts, cancellation, error envelopes, or upstream orchestration.

Design and review frontend streaming contracts. Use when handling server-sent events, WebSocket messages, async iterables, stream parsers, reducer state, terminal states, progress timelines, cancellation, retries, or UI updates driven by runtime events.

Design and review LangGraph backend contracts. Use when creating or changing graph state, nodes, edges, reducers, commands, sends, checkpoints, runtime events, provider adapters, tool adapters, prompts, terminal states, or resumable workflows.

Design and review structured tool-result rendering. Use when rendering tool calls, tool messages, structured tool outputs, status cards, fallback JSON/text displays, parser boundaries, display status mappings, or unknown tool results.

Design and review type contracts across package, service, frontend, backend, tool, event, and transport boundaries. Use when defining schemas, discriminated unions, runtime parsers, error envelopes, schemaVersion fields, or duplicated transport/domain types.

Guide stable API and interface design. Use when creating or changing public module boundaries, REST or GraphQL endpoints, event contracts, SDK methods, data transfer objects, error envelopes, or cross-team interfaces.

Conduct multi-axis code review. Use before merging code written by an agent or human, when assessing diffs for correctness, maintainability, security, tests, observability, and contract risk.

Guide systematic root-cause debugging. Use when tests fail, builds break, runtime behavior is unexpected, logs show errors, or repeated fixes are not resolving the same issue.

Build production-quality frontend interfaces. Use when creating or modifying UI components, layouts, interaction states, responsive behavior, accessibility, visual polish, or user-facing workflows.

Deliver changes in small verifiable increments. Use when implementing a multi-file feature, refactor, migration, bug fix, or any task that is large enough to become risky if completed in one pass.

Guide robust Node.js and TypeScript engineering. Use when working on Node services, scripts, CLIs, tests, streams, async workflows, module boundaries, environment configuration, logging, caching, profiling, or graceful shutdown.

Add or review observability. Use when adding logs, metrics, traces, audit events, health checks, alerts, or production diagnostics for features, background jobs, APIs, tools, and integrations.

Optimize application performance with evidence. Use when latency, throughput, memory, bundle size, rendering speed, Core Web Vitals, query time, startup time, or resource usage matters.

Harden software against security risk. Use when handling user input, authentication, authorization, sessions, secrets, file uploads, external integrations, webhooks, browser data, storage, or privileged actions.

Drive implementation with tests. Use when fixing bugs, changing behavior, adding logic, modifying contracts, or proving that agent-written code works and remains safe across regressions.