AI Agent Guide

AI agents should use these docs to inspect the right code, preserve risky invariants, and verify changes before handing work back.

On this page

Safe edit rules

Identify the behavior, boundary, data model, provider, and failure modes before editing.
Read route, service, persistence, schema, config, and nearby tests for risky areas.
Keep routes thin and do not move provider SDK details into UI.
Preserve idempotency for webhooks, jobs, billing, notification delivery, and retries.
Run the smallest targeted test slice, then pnpm run quality.

Feature prompt

Add <feature> to this app. First identify the route entrypoints, feature-owned server logic, UI surface, persistence, schema changes, provider integrations, env vars, jobs, webhooks, and tests. Keep route files thin, preserve auth and billing boundaries, and show the verification commands you ran.

Inspect first

src/features/settings/server/actions/website-settings.ts
src/lib/auth/guards/route.ts
src/lib/supabase/server.ts

Verify

pnpm run test:features
pnpm run quality

Debug prompt

Debug <bug> in this app. Reproduce the failing behavior, inspect the owning feature module, read nearby tests, trace server/client boundaries, identify the root cause, add regression coverage when practical, and call out any data repair separately.

Inspect first

src/features/billing/server/checkout/service.ts
src/features/notifications/server/outbox/services/worker.ts
src/lib/security/webhooks/request.ts

Verify

pnpm run test:features
pnpm run quality

Refactor prompt

Refactor <area> in this app without changing behavior. Preserve public routes, provider contracts, schema behavior, env names, tests, and operational logs. Split by responsibility only where the current module is dense enough to justify it.

Inspect first

src/features/billing/server/checkout/service.ts
src/features/notifications/server/outbox/services/worker.ts
src/lib/auth/rbac/nav-config.ts

Verify

pnpm run test:features
pnpm run quality

Common AI mistakes

Mistake	Correction
Documenting assumptions instead of shipped behavior	Inspect the referenced source paths first and document what the app actually does.
Adding generic wrappers	Use direct feature-owned modules unless duplication is real and stable.
Skipping operational checks	Always inspect auth, billing, webhooks, cron, RLS, grants, and request ids when those boundaries are touched.
Inventing env aliases	Use canonical env names only unless a migration plan explicitly requires aliases.
Making UI-only changes to remove a feature	Trace routes, feature code, schema, jobs, webhooks, tests, and docs before removal.