AI product architecture

Use when an AI feature needs a stable boundary with a product, data service, or external integration.

Write an API contract for this AI-powered capability. Define the user job, resource model, request and response schema, validation, authentication, authorization, idempotency key, errors, timeouts, rate limits, audit events, versioning, and human-review state. Show one successful, one rejected, and one pending example. Keep model-specific behavior behind the service boundary.

Capability:
[PASTE CAPABILITY]
Consumers:
[PASTE CONSUMERS]
Data and risk context:
[PASTE CONTEXT]

Output: A versioned API contract with review and failure states.

Guardrails: Keep provider-specific details behind the boundary · Make pending and rejected states explicit · Do not expose sensitive data by default

Use before a new AI capability, integration, or client is added to a live product.

Review this API change for compatibility and product risk. Inspect schema evolution, backward compatibility, retries, pagination, auth scope, rate limits, partial failure, long-running work, human approval, auditability, and deprecation. Return breaking changes, safe defaults, migration steps, and the smallest contract test suite that should block release.

Current API:
[PASTE API]
Proposed change:
[PASTE CHANGE]
Clients and traffic:
[PASTE CLIENT CONTEXT]

Output: A compatibility review with migration and release tests.

Guardrails: Do not call a change safe without checking real clients · Separate additive, risky, and breaking changes · Preserve an exit path

Use when a product action should trigger work across services, agents, queues, or human review.

Design an event-driven workflow for this product action. Define the triggering event, event schema, producer, consumers, ordering needs, delivery semantics, deduplication, retries, dead-letter behavior, timeouts, human hand-off, audit trail, and user-visible status. Identify which work is synchronous and which can be asynchronous. End with a thin pilot architecture and the evidence needed to expand it.

Product action:
[PASTE ACTION]
Systems and consumers:
[PASTE SYSTEMS]
Reliability requirements:
[PASTE REQUIREMENTS]

Output: An event flow with observable state and recovery paths.

Guardrails: Do not hide asynchronous work from users · Every consumer needs a failure path · Keep event ownership explicit

Use before an agent, webhook, queue consumer, or retrying job can create a side effect.

Make this action safe to retry. Define the idempotency key, scope, storage and expiry, request fingerprint, state machine, duplicate response, timeout behavior, concurrency lock, compensation, and audit record. Explain what happens if the first attempt succeeds but the response is lost, or if two attempts arrive at the same time. Include API and test examples without inventing implementation details that are not supplied.

Action:
[PASTE ACTION]
Side effects:
[PASTE SIDE EFFECTS]
Retry and timeout behavior:
[PASTE BEHAVIOR]

Output: An idempotency design and test matrix for safe retries.

Guardrails: Assume delivery can repeat · Do not rely on client memory alone · Protect irreversible side effects

Use when an AI feature is becoming a system and responsibilities are drifting across the UI, backend, and model layer.

Map the runtime boundary for this AI product. Assign responsibilities across UI, API, application service, queue or workflow engine, data stores, retrieval, model provider, and human review. For each boundary define input, output, latency, state, security identity, observability, and failure behavior. Identify what should remain deterministic and what can be adaptive.

Product feature:
[PASTE FEATURE]
Current stack:
[PASTE STACK]
Usage and risk:
[PASTE CONTEXT]

Output: A clear runtime boundary map with ownership and failure behavior.

Guardrails: Do not add a service without a reason · Keep secrets and permissions server-side · Prefer a small reversible pilot

Use when a team is weighing serverless, containers, workers, managed services, or a custom platform for an AI workload.

Compare runtime options for this workload: managed serverless, long-running service, background worker, queue-based workflow, and a dedicated platform. Score them qualitatively against traffic shape, cold starts, streaming, long-running tasks, data locality, provider calls, operations, cost, security, and recovery. Recommend the smallest credible choice now and the signal that would justify changing it later.

Workload:
[PASTE WORKLOAD]
Constraints:
[PASTE CONSTRAINTS]
Team capabilities:
[PASTE TEAM]

Output: A runtime decision with explicit trade-offs and change signals.

Guardrails: Do not optimise for hypothetical scale · Include operations ownership · Keep the migration path visible

Use before a production launch or when incidents reveal an unclear dependency or recovery path.

Review this architecture for reliability. Trace the critical user journey across services, queues, model calls, data stores, and human checkpoints. Identify single points of failure, timeout and retry hazards, stale state, provider outages, data loss risks, alert gaps, recovery time, and user communication. Return launch blockers, mitigations, a rollback plan, and one game-day exercise.

Architecture:
[PASTE ARCHITECTURE]
Critical journey:
[PASTE JOURNEY]
Current telemetry and SLOs:
[PASTE TELEMETRY]

Output: A reliability review with launch blockers and recovery exercises.

Guardrails: Prioritise user impact · Do not confuse retries with recovery · Keep a human fallback

Use when an important AI product choice needs to remain understandable as the team and system change.

Write an architecture decision record for this choice. Capture the decision, context, constraints, options considered, evidence, security and operational implications, rejected alternatives, migration or rollback path, owner, and review date. Distinguish facts, assumptions, and unknowns. End with the signal that would cause the team to revisit the decision.

Decision:
[PASTE DECISION]
Context and evidence:
[PASTE EVIDENCE]
Constraints:
[PASTE CONSTRAINTS]

Output: A durable decision record with revisit criteria.

Guardrails: Do not backfill evidence · Make rejected options visible · Name a review date or trigger