enable AI's Full Potential: Structure Your Codebase for Agent Success

A developer reports that structuring a codebase for AI agents—using folder-per-concern organization, explicit prop types, and rules files like .cursorrules or CLAUDE.md—can dramatically improve agent performance. The approach, demonstrated in OTF SaaS kits, allows agents to reliably ship features without manual coding by providing a clear map of the repo.

Cursor and Claude Code can take a 200-component design system and ship a working admin page without you writing a line. That's not marketing — I've watched it happen on an OTF SaaS kit. The catch is what the agent can do depends almost entirely on the shape of the repo you hand it. A codebase designed to be read by an agent looks nothing like the 4000-line single file most AI app builders produce. The difference isn't prompt magic. It's five boring structural properties, each of which costs almost nothing to add and roughly doubles what an agent can reliably do. OTF kits are the worked example — they're built this way on purpose — but the pattern works in any repo. An agent extends a codebase the same way a new hire does: by finding the file it needs without scrolling. A repo where every concern lives in its own folder, with one component per file and a barrel export at the root, gives the agent a map. A repo where everything is in app/page.tsx is a single ball of mud the agent has to reason about whole. The shape that works: src/ components/ Button/ Button.tsx Button.test.tsx index.ts Card/ ... lib/ auth.ts billing.ts db.ts routes/ dashboard.tsx settings.tsx Each folder is a unit. The agent can read Card/Card.tsx , understand the prop shape, write a <Card somewhere else, and never touch the rest. When a kit ships this way, the agent's mental model matches the file tree. When a sandbox ships a flat file, the agent's only option is to keep regenerating the whole thing. The cost of getting this wrong compounds. Every prompt you write into a flat-file repo has to re-explain the layout. Every prompt you write into a folder-per-concern repo just has to ask. Props are the API of a component. If the type is ButtonProps with explicit variants, the agent reads the file, sees exactly what variants exist, and picks the right one without guessing. If the type is any , the agent has to read the implementation — and at that point you're back to hand-coding. The really useful move is exporting props alongside the component: // components/Card/Card.tsx export type CardProps = { title: string description?: string footer?: React.ReactNode variant?: 'default' | 'elevated' | 'outlined' } export function Card { title, description, footer, variant = 'default' }: CardProps { ... } Now an agent prompt can be "use the Card component with variant='elevated' and a footer" and the agent doesn't have to invent a convention — it imports the type. The same pattern works for server functions, DB queries, and route handlers. Every kit ships exported prop types for this exact reason. This is the single highest-use change. Cursor reads .cursorrules . Claude Code reads CLAUDE.md . Most repos have neither. Both files are loaded into the agent's system context on every run, which means whatever you put there is permanent context the agent never has to rediscover. A working .cursorrules is short. It does three things: // .cursorrules - Use components from @otfdashkit/ui, do not write new ones - Tokens live in @otfdashkit/tokens; never hardcode colors/spacing - Server logic in src/lib/, route handlers in src/routes/ - One component per file; barrel-export from index.ts - DB access via typed queries; schema in src/db/schema.ts Every bullet above is an outcome — what to use, where to put things — and any agent can act on it. A repo with a 30-line conventions file out-performs a repo with 30,000 lines of undocumented code, every time. The mistake to avoid: writing the conventions in a README the agent never reads. The README is for humans, who can skim a 4,000-word doc and pull out the parts they need. An agent won't. It will read the rules file and ignore the rest. A CLAUDE.md tells the agent the rules. A folder of tested prompts tells it what success looks like. The difference is like the difference between a style guide and a tutorial — both are useful, but the tutorial is the one that actually moves you forward. The shape that works: ai/ prompts/ 01-add-a-new-page.md verified: agent produced working route 02-add-a-billing-plan.md verified: Stripe integration passed 03-add-a-mobile-screen.md verified: native build succeeded 04-add-an-api-endpoint.md 05-style-a-form-with-tokens.md ... Each prompt file has three sections: the task in plain English, the files the agent should touch, and the verification step "does it render?", "does the test pass?", "does pnpm ship succeed?" . Before a kit ships, someone has run every one of these prompts against the kit and confirmed the output is correct. The prompt files are part of the kit the same way source files are. This is the bit the sandbox tools don't have and can't easily produce: a verified example of "here's a thing the agent did correctly on this codebase, so the next prompt has a precedent to follow." Twenty verified prompts is a corpus. The agent reads it the way a new hire reads PRs. An agent can't reliably do a 12-step manual setup. It can reliably run one script. The kits ship pnpm dev , pnpm test , pnpm ship , and pnpm preview:mobile — each one does a complete, deterministic thing. The agent reads package.json , sees the scripts, and uses them. { "scripts": { "dev": "vite", "test": "vitest run", "build": "vite build", "ship": "node ./scripts/ship.mjs", "preview:mobile": "node ./scripts/preview-mobile.mjs" } } pnpm ship wires a custom domain, DNS, and TLS. The agent doesn't need to know how — it just runs the command. Every step that used to be tribal knowledge becomes a script, and every script is a single point of invocation the agent can hit. If you can express setup as a script, an agent can run it. If setup is a Slack thread, an agent cannot. COMPARE: a sandbox-generated single-file app vs. an OTF kit shipped as a foldered repo with rules and prompts | Property | Sandbox output | Agent-readable repo OTF kit | |---|---|---| | File layout | One 4000-line app.tsx | Folder-per-concern, one component each | | Types | Inferred, any , or missing | Exported props, full type coverage | | Conventions | None | .cursorrules + CLAUDE.md | | Example prompts | None | 20+ verified prompts in ai/prompts/ | | Setup | "Click deploy" | pnpm ship , pnpm preview:mobile | | Design system | Ad-hoc inline styles | Shared tokens across web + native | | Agent extending it | Regenerates from scratch | Adds new files in the right places | The right column isn't free, but it's not expensive either. A kit is built this way once and reused for every project you start from it. I started a SaaS dashboard last week by pasting npx otf-kit@latest saas-dashboard into a terminal. Two minutes later I had a folder with a 200-component design system, a Postgres schema, Stripe wired up, a .cursorrules , and a CLAUDE.md . The agent read the conventions file and used the right components on the first prompt. I asked it to add a billing-plan page; it produced one, the test passed, and the dev server rendered it without me touching the layout. CONCEPT: conventions written down, types exported, scripts idempotent — an agent-readable repo is a repo a new hire could also onboard from That's the test. If a senior engineer can join your repo on Monday and ship a feature on Friday with nothing but the README, the CLAUDE.md , and the existing code, an AI agent can do the same in an afternoon. If a senior engineer needs a 30-minute walkthrough to find where billing lives, an agent has no chance. Cursor and Claude Code will both look different in six months. The model behind them will be replaced twice over. The five properties above won't change — they're properties of the codebase, not the agent. A repo you build this week stays agent-readable through every model upgrade, because the agent is reading the file tree, the types, the conventions file, and the verified prompts. None of those depend on which model is in the loop. That's the layer the sandbox tools can't ship, because they don't have a repo to ship. They have a generated bundle. The bundle is great for a demo. It stops being great the moment you want to extend it, which is also the moment you want an agent to extend it for you. OTF kits exist for exactly this reason: a repo already shaped the way an agent and a new hire can read it, with the conventions, types, scripts, and verified prompts in place from day one. Use Cursor, use Claude Code, use whatever agent ships next — and start from a codebase that's ready for it.