Why your repo conventions matter more than your AI agent

A file-system coding agent is the fastest junior you have ever hired. It reads 200 files before breakfast, holds the whole tree in context, and writes code that compiles on the first try.

It also picks its own design system.

Hand it "add a settings page" in a clean repo with no conventions written down, and you will get a page that uses bg-slate-900 while the rest of your app uses bg-[var(--surface-2)], a Modal that ignores the one you have shipped, and a form field that is a <div> with onClick instead of a <button>. It compiles. It passes the screenshot review. Three weeks later you grep for "Modal" and find eleven of them.

The model is clever. The prompt is a guess about your codebase. The codebase itself is the contract.

Conventions are how you program the agentCopy Anchor Link

Every agent reads the repo before it writes. The files it looks for are well documented: Claude Code loads CLAUDE.md at session start — project, user, or org scope — and treats it as context, while Cursor supports project rules in .cursor/rules/*.mdc plus AGENTS.md with frontmatter controlling when each rule applies. These are not README ornaments. They are the highest-use prompt you will ever write, because they run on every single session without anyone remembering to paste them.

A repo with no agent config is a repo where every prompt starts from zero. A repo with a sharp CLAUDE.md is a repo where the agent starts from your conventions. That difference compounds across every feature, every fix, every model upgrade.

The five conventions that make agents deterministicCopy Anchor Link

In practice the contract comes down to five things, each one a file the agent can read:

1. An agent entrypoint (CLAUDE.md / AGENTS.md). One page: what this repo is, how to run it, where things live, what is forbidden. Claude Code picks up CLAUDE.md automatically at session start; Cursor and Codex CLI honor AGENTS.md. Keep it under a page — a bloated entrypoint gets skimmed by humans and models alike.

2. One component layout, enforced by example. "Use the design system" is a wish. "New screens compose Button, Dialog, FormField from @otfdashkit/ui — never hand-roll a modal" is a convention. Name the components, name the import path, show one correct usage. The agent copies what it sees; make sure what it sees is the one true Button.

3. A token system, not color values. The bg-slate-900-versus-bg-[var(--surface-2)] bug from the intro happens because nothing told the agent your palette lives in tokens. Document the token source and forbid raw values. If your web and mobile apps share one token contract, say so — our design-system-as-agent-context guide covers that pattern in depth.

4. The auth and data pattern. Agents invent auth flows with total confidence. Write down yours: which provider, where the session lives, what a protected route looks like, which RLS policies guard the tables. One canonical example per pattern beats three paragraphs of prose.

5. A tested prompts directory. Store the prompts that work — "add a page," "add a billing flow," "add a screen to the mobile app" — as files in ai/prompts/, each one verified by running it against the real repo and checking the diff. Prompts rot like code; version them like code. More on the mechanics in Cursor rules for Next.js.

Five files. None of them is clever. Together they are the difference between an agent that extends your system and one that reinvents it per prompt.

Audit your repo in one afternoonCopy Anchor Link

You do not need a week-long standards project. Run this loop once and your next agent session starts from a contract:

1. Ask your agent to add a small screen without any new guidance, then diff what it chose: which button, which colors, which form primitives.
2. Every place it guessed wrong becomes one line in CLAUDE.md — the component name, the token path, the forbidden shortcut.
3. Move any prompt you paste twice into ai/prompts/ as a file, and re-run it once to confirm it still produces the right diff.
4. Repeat monthly. Conventions drift as the codebase grows; a fifteen-minute refresh keeps the contract honest.

The audit itself is the onboarding doc. A new hire — human or agent — reads the same files and gets the same answers. For the broader discipline of keeping generated code reviewable, see our agent-readable repository structure guide.

What this gets youCopy Anchor Link

The same agent, run twice on the same prompt, produces the same diff. That is not nothing — that is the difference between a tool and a teammate.

Three concrete wins:

• Determinism. Re-running the agent on a PR gives the same suggestions. Code review becomes "did the agent follow the conventions?" instead of "what did the agent pick this time?"
• Onboarding. A new dev runs claude in the repo and gets the same answer a senior would. The CLAUDE.md is also their onboarding doc.
• Survival across model churn. When the model behind the agent changes in three months, the conventions do not. Your design system survives the swap.

Where OTF sits in thisCopy Anchor Link

Every paid OTF kit ships with all five of those things, pre-written and tested against the kit itself. CLAUDE.md, .cursorrules, and AGENTS.md describing the kit's component layout, token system, auth pattern, and forbidden shortcuts. An ai/prompts/ directory with 20+ prompts for "add a page", "add a billing flow", "add a screen to the mobile app" — each one verified by running it through Claude Code and Cursor against the actual kit and checking the diff.

The point is not to lock you into OTF. It is that the convention contract is the part that does not change when the model does. Use whichever agent you want — Claude Code, Cursor, Codex CLI — and the kit's CLAUDE.md is the durable layer underneath the churn. The agent extends the kit instead of regenerating it. The kit's tokens stay the tokens. The kit's Button stays the only Button.

That is the part worth owning.

Start from a repo that already has the contract written: otf-kit.dev/templates.

SourcesCopy Anchor Link

• Anthropic. "CLAUDE.md memory." https://code.claude.com/docs/en/memory — session-start loading, project/user/org scope, context-not-enforced-configuration semantics.
• Cursor. "Rules documentation." https://cursor.com/docs/rules — project rules (.cursor/rules/*.mdc), user and team rules, AGENTS.md support, frontmatter controls.
• Anthropic. "Claude Code docs." https://code.claude.com/docs — file-system agent baseline (reads codebase, edits files, runs commands).
• OTF. "Design system is agent context." https://otf-kit.dev/blog/design-system-is-agent-context — shared token contract across web and mobile (internal companion).