How to craft CLAUDE.md for coding agents that respect your conventions

Coding agents follow the path of least resistance. By default, that's their own pre-training set — not your conventions, and not your codebase. The difference between an agent that extends your project and one that tramples it comes down to a single artifact: a first-class map of how your system works, what’s in-bounds, and what’s absolutely not.

A complete CLAUDE.md, .cursorrules, or AI_GUIDE.md closes this gap. The agent stops guessing and starts behaving like a real teammate. The OTF kits ship with this layer pre-compiled: file tree, import layout, conventions, anti-patterns, and tested prompts to target the kit, not regenerate it.

Let’s get specific about what belongs in these files, why each part matters, and what changes in the agent’s output when you get it right.

Why model defaults aren’t enough

Shipping with no explicit AI guide means your agent builds on the wrong foundation — its own defaults. For a model like Claude, that means:

• Directory layout based on the CommonCrawl average, not your code structure.
• Imports reorganized for "style" or "best practice", even when that breaks your local layering.
• Regenerating files from scratch, overwriting details that matter (env handling, localization, custom hooks).
• Adding lint or type rules that don't exist in your stack, or missing required ones.
• Making up new conventions to fill gaps instead of asking or copying existing code.

This is why model outputs so often feel like “throwaway” or disposable code — because, to the AI, they are. Any option is fine by default. Tell it otherwise or pay the price in diff churn and cleanup.

The difference is not subtle. With and without explicit project rules:

	Agent guess	Agent extend (with guide)
File placement	“utils/” or root	Slot into /lib/, /app/hooks/ as mapped
Import style	Defaults (absolute, relative, barrel)	Matched to existing import paths
Test coverage	Omits or invents test folders	Respects /test/ structure
APIs	"Best guess"	Calls the real factory functions
Comments	None or generic	Follows local JSDoc or docstring patterns

The win: make the agent look at your code, not its own pretraining.

What actually goes in CLAUDE.md and .cursorrules

Treat the project AI guide as a contract. Everything inside should be:

• Explicit: No “obvious” context left out.
• Enforced: If you break it, your tests/code reviewers yell.
• Mechanical: Claimed patterns that can be computed, not just vibes.

Let’s break down the essential sections, with real OTF kit examples.

Directory map and file boundaries

Your agent can’t follow conventions it can’t see. Paint an explicit map.

# Directory Map

- `/app/` — UI routes and page entrypoints
- `/lib/` — Pure business logic, reusable functions
- `/components/` — Shared UI primitives only, no server code
- `/hooks/` — React hooks _unused_ outside components
- `/utils/` — Legacy, do NOT add new files here
- `/types/` — TypeScript types only

A model will move code based on vague “organize by function vs feature” heuristics unless you tell it which directories actually exist, what goes in each, and (critically) which ones are legacy, frozen, or off-limits.

Import and export rules

This is where most agents invent conventions. List your real, enforced rules:

# Import Rules

- All imports use absolute paths (`from 'lib/foo'`), never relative (`from '../lib/foo'`)
- `@otfdashkit/ui` components are imported directly, never re-exported
- Side-effect imports (`import './globals.css'`) only in root layout files
- React hooks must be imported from `/hooks/`, never `/lib/`

Getting this wrong is the fastest way to ship broken, unscannable diffs.

Code style and “never do X” rules

The AI model is not your linter. Especially in tool-based projects, banning specific patterns closes real escape hatches:

# Never Do This

- Do NOT use `any` (TypeScript) — always use an explicit type or generic
- Do NOT mix client/server code in `/lib/`
- Do NOT use inline styles, only classnames from token map
- Do NOT introduce new dependencies (npm install) without review
- Do NOT use file names with uppercase letters (matches CI)

This is not a generic “best practices” list. It’s the list that, if violated, breaks your pipeline.

Custom patterns — the things unique to your repo

The killer feature of any agent config is the “this project is different” section. Real OTF kit diffs look like:

# Project-Specific Patterns

- All forms use `<FormField>` components — do NOT hand-roll inputs
- Only call API endpoints through `lib/apiClient.ts`
- All date math uses `dayjs`, never `Date` built-ins
- Whenever exporting a new page in `/app/`, update `route-map.ts`

These are the rules that, if not spelled out, WILL be missed by a model. They exist nowhere else but your repo.

Tested prompts and integration commands

Most AI tools now allow in-repo prompt config. The difference between a magic incantation and a reroll script is documentation:

# Custom Commands

- Add a component: "Add a new Button variant that matches `/tokens/buttons.json`, export from `/components/Button.tsx`"
- Wire up a new payment handler: "Follow `/lib/payments/README.md`, test with `stripe trigger`"
- Update design tokens: "Edit `/tokens/`, rebuild with `npm run update-tokens`"

Shipping these as copy-paste or in a prompt file makes the agent repeatable and aligned with your working style.

The OTF kits: shipped for agent alignment

Every OTF full-stack kit (SaaS Dashboard, Fitness, Booking) ships with:

• A CLAUDE.md in the root with:
  • Full directory map and roles
  • Import/export conventions
  • List of frozen/legacy folders
  • "Never do X" — patterns enforced by CI or reviewer
  • Project-specific patterns (custom UI, API boundaries, token updates)
  • Copy-paste tested prompts for 20+ common extensions (add auth, modify billing, extend dashboard columns)
• .cursorrules file for Cursor IDE, mapping:
  • Entry points for new pages/components
  • Rules for how agents rewrite or slot features
  • Hard “do not touch” (frozen) dirs
• All kits have real, greenlighted config — these are not AI hallucinations, but baked into the kit and enforced by scripts.

If you start with an OTF kit and wire up Claude or Cursor, the agent builds on your conventions — it never nukes them. It knows where server code belongs. It sees the design tokens. It doesn’t invent folder names.

[[COMPARE: agent default output vs kit-aligned output]]

A one-line difference: what changes in practice

Concretely, consider this agent prompt before and after an explicit config.

No AI config:

Add a new payment method to the app.

The agent (Claude, Cursor, v0) might:

• Write to /api/ AND /lib/ with inconsistent separation
• Add button components directly in page files
• Use whatever date library it "prefers"
• Invent new /services/ or /payments/ folders
• Break code style or lint checks

With OTF’s CLAUDE.md and .cursorrules:

Add a new payment method following the project conventions.

The agent will:

• Slot Stripe logic inside /lib/payments/
• Register new methods in route-map.ts as required
• Use <FormField> and design tokens
• Import dayjs (by rule), never built-ins
• Pass CI — never adds any, never inline CSS

The delta: time to usable PR drops, rework vanishes, and AI code is reviewable by humans as a peer — not a code dump.

Shipping tested prompts, not incantations

Every OTF kit doesn’t just drop files; it ships with a set of tested AI prompts for the most common extensions:

• CLAUDE.md includes at least 20 extension blueprints ("Add mobile fallback to Button", "Wire up user roles") that have been run against CLI agents and delivered working diffs.
• Prompts are phrased to match the kit’s structure exactly — import paths, token names, folder conventions baked in.
• If a new prompt is added (by a user or update), it’s re-run through the linter and the agent to verify output before being added.

This beats a repo-level "AI README" that’s just a list of random examples — everything in the config is known to work.

The agent is a collaborator, not a replacement

A coded, enforced CLAUDE.md or .cursorrules doesn't just make agents less likely to miss. It makes them usable as real teammates: they remember custom patterns, never break invariants, and can be trusted with complex diffs — not just greenfield files.

OTF ships this contract as the core layer in every paid kit. The starter files, the design tokens, the "do and don't" — all enumerated so an agent extends instead of guessing. This is the difference between shipping a tool that churns throwaway code and one that leaves your architecture stronger over time.

The layer under the model is your real IP: not just the code, but the rules by which it's extended. Template the rules, and the models will follow.