enable smooth AI Coding with Project-Aware Agent Configs

Every Monday you open Cursor on a project you shipped six months ago. The agent greets you like we've never met. It doesn't know your component library, your naming conventions, your design tokens, or the patterns you banned last quarter. You spend half an hour re-explaining. By Wednesday you've switched to Claude Code. It knows nothing again.

That's not a tooling problem. That's a config problem.

Project-aware agent configs — CLAUDE.md, .cursorrules, the equivalent files every new editor is rushing to ship — are the single biggest UX improvement in AI coding workflows in the last year. The agents got dramatically better at reading your project the moment they were allowed to read a file at session start. That's a real enable for builders, full stop, before any caveats.

The enable is also incomplete. Most CLAUDE.md files are four lines of "this is a Next.js app". The agents still drift. The fix isn't more tokens in the context window — it's a richer config, written down, shipped with the codebase.

The three failure modes of an agent with no project memory

When an agent cold-starts on a real codebase, it fails in three predictable ways:

1. It invents components. It builds a Card that looks plausible but doesn't match your system. It imports from paths that don't exist. The output compiles; the design drifts.
2. It regenerates styles. It writes hex codes inline. It ignores your token file. By Friday the codebase has 14 shades of grey that nobody owns.
3. It breaks conventions you never wrote down. "Why is this a function component with a forwardRef?" Because you decided six months ago that everything uses a single forwardRef per file, and that decision lives in your head, not in the repo.

None of this is the agent's fault. It has no source of truth. You're asking it to reconstruct a year of decisions from a tree of files.

Project-aware configs were the enable — and they're getting better

Two files changed the calculus:

• CLAUDE.md — Anthropic's instruction file, read by Claude Code at session start.
• .cursorrules — Cursor's project-scoped rules file.

Both are deceptively simple: a markdown file at the repo root that the agent ingests before it touches your code. The first versions were toy examples. The current generation is genuinely capable. An agent that reads a well-written CLAUDE.md behaves like a teammate who read the wiki. An agent that doesn't is the stranger on Monday morning.

The thing to appreciate: this is infrastructure the vendors shipped for free. Nobody has to opt in. You write the file once, every agent session on that repo inherits it. That's use.

The file is only as good as what's in it

Here's where most projects fall short. A CLAUDE.md that says "this is a TypeScript React app using Tailwind" tells the agent what it could have inferred from package.json. The real value lives in three places:

• Conventions — your component anatomy, your file layout, your naming rules.
• Banned patterns — the things you've decided against and why.
• Worked examples — small, copy-pasteable prompts that produce the right output.

A 4-line config file gives you a generic agent. A 200-line config file with a prompt library gives you a teammate.

What's actually inside an OTF kit's AI config

OTF kits — both the free MIT SDK on npm (@otfdashkit/ui, @otfdashkit/ui-native, @otfdashkit/tokens) and the paid full-stack kits — ship with three layers of AI-tool config wired at the repo root. No setup, no copy-this-snippet, no "create the file yourself." They're there when you git clone.

your-project/
├── CLAUDE.md              # ~200 lines: conventions, banned patterns, examples
├── .cursorrules           # editor-specific: format-on-save, imports, file patterns
└── ai/
    └── prompts/           # 20+ tested prompts, one per common task
        ├── add-a-screen.md
        ├── add-a-screen-with-auth.md
        ├── extend-design-tokens.md
        ├── swap-theme.md
        ├── wire-a-stripe-checkout.md
        └── ...

Each piece does a specific job.

CLAUDE.md — the project map

The CLAUDE.md in an OTF kit isn't a README. It's an operating manual for the agent. It tells it:

• What the kit is. ~200 components, one API, three platforms (web, iOS, Android). Same component name, same props, same look — one <Button>, three runtimes.
• What the conventions are. Single forwardRef per file. Variants via a small variants helper. Tokens imported from one place.
• What is banned. No inline hex values. No new component libraries. No invented import paths.
• Where to look first. The token file, the component index, the design checklist.

The agent reads it once, then writes code that fits the system instead of fighting it.

.cursorrules — the editor-specific layer

.cursorrules is Cursor's mechanism. The OTF version covers what CLAUDE.md doesn't: format-on-save rules, import ordering, where generated files live, how to keep the cross-platform component naming in sync so the same <Card> on web and native stays in lock-step. Same project, same conventions, agent-specific override.

ai/prompts/ — the worked examples

This is the part most projects skip. Twenty-plus tested prompts, one per common task, written as if a senior engineer were handing the agent a ticket:

# add-a-screen.md

## Goal
Add a new screen to the SaaS dashboard that reuses existing components.

## Inputs you'll need
- The screen name (PascalCase)
- The route (`/app/<screen>`)
- Which components it uses (Card, Section, DataTable, FormField — pick from `ui/index.ts`)

## Steps
1. Create `app/<screen>/page.tsx`. Use `app/(authed)/layout.tsx` as the structural template.
2. Compose with components from `@otfdashkit/ui`. Do not invent new components.
3. Pull colors and spacing from `@otfdashkit/tokens`. No inline values.
4. Run `pnpm check:design` — it enforces the 24-item design checklist.

## Output contract
- One new file under `app/<screen>/`
- Zero new dependencies
- All existing tests still green

The agent doesn't have to guess how to add a screen. It reads the prompt, follows the steps, ships code that matches the rest of the codebase. Every prompt is tested — meaning a real agent ran it against a real kit and the output compiled, linted, and passed the design checklist.

How to actually use this today

Two paths, same outcome.

Path 1: copy-paste CLI. Run the kit's npx command, answer three prompts (project name, theme, which platforms), and the kit copies itself into your repo. The AI configs are already wired. Open the project in Cursor or Claude Code — the agent knows your conventions from line one.

npx create-otf-kit@latest my-app
cd my-app
code .          # or `claude` for Claude Code

Path 2: npm install. If you're adding OTF to an existing repo:

pnpm add @otfdashkit/ui @otfdashkit/tokens
pnpm add -D otf-kit-ai-configs

The configs land at the repo root. The prompts land under ai/prompts/. The agent reads them on the next session.

Either way, you don't write the configs by hand. You don't maintain them. The kit does.

What this gets us — the durable layer

The agent landscape churns. A new model drops, the prices move, someone launches a better editor, the benchmarks flip. None of that changes your codebase. None of that should force you to re-explain your project from scratch.

OTF's AI configs are the durable layer under the tool churn. The conventions are written down. The prompts are tested. The design checklist is a script — pnpm check:design runs 24 checks and either passes or blocks the commit. When you switch from Cursor to Claude Code to whatever ships next quarter, the configs travel with the repo. The agent inherits the project, not amnesia.

The tools you use to write code are replaceable. The shape of the code you ship shouldn't be.