enabling AI's Full Potential: Bridging the Gap from Sandbox to Production

Lovable and Cursor are impressive AI coding tools, but both suffer from a lack of context that prevents seamless handoff from prototype to production. A developer proposes a solution: three files at the repo root—CLAUDE.md, .cursorrules, and AGENTS.md—that agents read automatically to enforce naming conventions, tech stack decisions, and project rules. This approach bridges the gap between sandbox agents and file-system agents, enabling production-ready AI-assisted development.

Lovable will ship you a working prototype in a coffee break. Cursor can refactor a 200-file real codebase in an afternoon. Both are genuinely impressive, both enable something real, and both have the same blind spot: context. The sandbox agent forgets your stack the second you close the tab. The file-system agent reads your repo and invents its own conventions. Neither one carries your engineering decisions from prototype to production — because the context they need isn't in the model, it isn't in the prompt, and it isn't on the splash page of the tool. It lives in the repo, in files most projects never write. Here's how to actually fix that. COMPARE: sandbox agent vs file-system agent — what each one does well, what each one forgets, and the gap between them There are two families of AI coding tool, and they solve different jobs. Sandbox agents — Lovable, Bolt, v0, Rork. You describe an app, they generate it in a hosted environment. Fast, pretty, complete with a deploy URL. The catch: the codebase is theirs, the conventions are theirs, and the moment you want a real backend, real auth, a real billing integration, you're rewriting. File-system agents — Cursor, Claude Code. They read your actual repo, edit your actual files, run against your real test suite. capable, but they're only as good as the map you give them. Open a fresh project and they'll happily invent a routing convention that conflicts with the one in your head, name a component three different ways, and reach for a library you stopped using last year. Neither is wrong. They solve different jobs. The thing nobody does well is the handoff. A language model doesn't have a codebase. It has a sliding window. Everything it knows about your project has to fit in that window, every turn, and whatever doesn't fit, it has to guess at. The things an agent will guess at, in order of how badly they go wrong: Button.tsx vs button.tsx vs Btn.tsx . The model picks one per file and changes its mind halfway through. variant or intent ? size="md" or size="medium" ? Without a reference, every component becomes a coin flip.You can put all of this in a prompt. You can paste it into every chat. You'll forget. The model will forget faster. The right home for this is a file the agent reads on its own, every session, before it touches a line of code. CONCEPT: three files at the repo root — CLAUDE.md, .cursorrules, AGENTS.md — read automatically by the major file-system agents There's a small, boring set of files that turn a file-system agent from a clever intern into something that ships to production. You write them once, they sit at the repo root, and any agent that knows how to read a repo which is all of them, now picks them up automatically. CLAUDE.md — read first by Claude Code. Plain markdown. Project overview, tech stack with rationale, naming conventions, the commands an agent should know pnpm dev , pnpm test , pnpm db:push , and the rules you want enforced. There is no required schema, which is the whole problem and the whole point. .cursorrules — same job, different file name, picked up by Cursor. Same content, mostly. Cursor merges it with its own rules and applies them on every edit. AGENTS.md — the emerging cross-tool standard. A growing handful of agents now read this — the OpenAI Codex CLI, Goose, and a long tail of editors and plugins starting to pick it up. You don't need to maintain three. Most teams keep CLAUDE.md and .cursorrules synced, and watch AGENTS.md converge. The cost is half an hour, once. Here's a CLAUDE.md that's actually useful — the kind that ships a kit to production: Project overview This is a SaaS dashboard. Users sign up, create a workspace, and manage projects inside it. Auth is email + password with optional OAuth Google . Billing is two tiers, handled by our payment provider. Tech stack - Web: TypeScript. The framework handles routing, data fetching, and server actions. Server state stays on the server where possible. - Database: Postgres. ORM migrations live in /db/migrations. - Auth: session cookies, httpOnly, sameSite=lax. - Billing: Checkout for upgrades, customer portal for downgrades. - Email: transactional templates in /emails. Conventions - Components in /components, one file per component, named after the component Button.tsx exports Button . No default exports. - Server actions live in /app/actions, named <verb <Thing .ts. - Validation: schema-first, one per server action, exported alongside. - Errors: throw a typed AppError, never return { error: string }. - Styling: design tokens only, no inline colors, no arbitrary values in component files. If you need a new color, add it to the tokens package first. Commands the agent can run - pnpm dev local dev - pnpm test vitest - pnpm typecheck tsc --noEmit - pnpm db:migrate apply migrations to local Postgres - pnpm db:studio database studio, port 4983 Don'ts - Don't add a new dependency without flagging it. The bundle is audited monthly. - Don't change auth shape. The session format is load-bearing. - Don't write any file outside the directories listed above unless I ask. That's the file. There's nothing magic in it. What it does is collapse a hundred micro-decisions — the ones the model would otherwise guess at, badly — into a single read. The agent's first 200 tokens used to be "what is this project". Now they're "what does this project want me to do." Three steps, in order, no agent required to start: 1. Pick an agent. Cursor for in-editor refactors and PR-sized work. Claude Code for repo-wide tasks, migrations, anything multi-file. Both are real, both are good, pick by shape of work, not by loyalty. 2. Write the context file. Start with one. CLAUDE.md if you use Claude Code, .cursorrules if you use Cursor, AGENTS.md if you live in the long tail. Don't write all three on day one. Write the one your current agent reads, and let the next session's first run tell you what it didn't understand. 3. Make the agent tell you what it guessed. A useful first prompt: "Read CLAUDE.md . Then list every convention in this codebase you would have invented yourself if the file didn't exist. For each one, point to the line that documents it." Anything it lists that isn't in the file is a gap. Fill the gap. The file grows by one section per week, and after a month the agent stops guessing. The OTF kits are the same component — same name, same props, same look — on web, iOS, and Android, from one codebase. ~200 components, design tokens that flip a theme across all three, copy-paste CLI or npm install . $99 per kit, $149 for the bundle. SaaS Dashboard ships full-stack — auth, billing, DB, payments wired. Fitness is one codebase for iOS, Android, and web. Booking does what it says on the tin. Every kit ships with all three context files, populated and tested against the latest model versions. CLAUDE.md covers the kit's stack and conventions. .cursorrules mirrors it. AGENTS.md is generated from the same source. Plus a ai/prompts/ directory with 20+ tested prompts — "add a new table", "wire a new billing tier", "add a new page to the dashboard", "add a new mobile screen" — that have been run against the actual kit, not hallucinated against a sample. The reasoning is simple: a kit is most useful when an agent can extend it without asking you 40 questions. A kit is most fragile when every developer who touches it makes the same architectural decisions from scratch, badly, in different files. When you run pnpm otf:check one of the scripts every kit ships , it walks the design checklist — 24 items — and fails the build if anything's off. The same script wires into a pre-commit hook, so an agent's PR doesn't reach a human reviewer until the structure holds. A human catches what a checklist can't. A checklist catches what a vibe-coding session won't. The win isn't a faster agent. The win is an agent that doesn't drift. A refactor PR that doesn't rename every variant. A new page that uses the same Button as every other page, on the same breakpoints, with the same focus ring, on web and mobile, from the same component. A new developer — or a new agent session — opens the repo on a Monday morning, reads one file, and starts writing code that fits. The sandbox tools will keep shipping prototypes. The file-system agents will keep getting better. The repos that survive the handoff are the ones where the engineering decisions are written down somewhere the model can find them. That somewhere is three files at the root, and the discipline to keep them honest. That's the part that doesn't change when the model does.