# enable AI's Full Potential: Structure Your Codebase for Agent Success > Source: > Published: 2026-07-07 11:05:52+00:00 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 `` 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.