What a production AI build needs in place before the first prompt
4 min read
CLAUDE.md gets most of the attention, but on its own it is not enough. Three more files decide whether AI builds inside your system or alongside it.
1. An architecture file that answers every question AI will otherwise guess at
The failure mode: Your AI-generated code works in development and breaks in production because AI filled gaps in the architecture with assumptions nobody documented.
The architecture file sits next to CLAUDE.md and describes the system AI is working inside: the apps, how they connect, the auth model, the data model, the billing model, the deploy targets.
Without it, AI fills gaps with reasonable assumptions, and those assumptions compound across sessions until the problem becomes a refactor rather than a fix.
In the Control Beacon build, I had not fully documented the authentication configuration before starting.
- AI followed what was available and configured the auth service against the original tenant domain instead of the custom domain I was using. Everything worked in development.
- When the build reached production, users started hitting 401 errors - tokens issued by the custom domain were being validated against a different one.
- The fix was a single environment variable but finding the cause took hours.
That was not a coding error. The architecture file was missing the answer, so AI made one up.
Example architecture file contents:
## Apps - control-beacon-web (Next.js, Vercel) - control-beacon-api (Node, Fly.io) - control-beacon-desktop (Electron, auto-updater) [six more] ## Auth - Provider: Auth0, custom domain auth.controlbeacon.io - Tokens: httpOnly cookies only, never localStorage - Multi-tenant: every query filtered by organization_id ## Data - Primary DB: Neon Postgres - Row-level tenant isolation enforced at query layer - PII columns tagged in schema, never logged
2. A prompt exclusion list that every team member signs before getting AI access
The failure mode: A developer pastes a .env file into a chat to debug a deploy, and your production credentials leave your environment through a personal free-tier account that trains on the data.
The exclusion list is one page that names what must enter a prompt.