All terms
Agents & tools
.cursorrules / repo instruction files
Also known as: .cursorrules, AGENTS.md, CLAUDE.md, repo instruction file, agent context file
Plain-text files (.cursorrules, AGENTS.md, CLAUDE.md) at the repo root that tell coding agents how your codebase works — conventions, dependencies, gotchas.
What it means
Repo instruction files are the way coding agents pick up codebase-specific context without you re-explaining it every session. The pattern: a markdown or plain-text file at the repo root containing the rules a fresh agent needs to know — testing conventions, import patterns, deployment quirks, what NOT to touch.
Cursor reads .cursorrules. Claude Code reads CLAUDE.md (and respects any AGENTS.md it finds). Codex has its own conventions. Most modern coding agents either follow one of these formats or look at all of them.
A good repo instruction file is short (a few hundred lines max), specific (real examples beat abstract principles), and actively maintained. Bad ones are aspirational ("we believe in clean code") and rot fast. The best ones read like onboarding notes for a new senior engineer: "if you touch the auth module, run pnpm test:auth first; the migration system is brittle, don't add columns without coordinating; we use Vitest, not Jest, regardless of what you may have seen elsewhere."
Example
Your CLAUDE.md says: "This is a Next.js 16 codebase with Turbopack. APIs and conventions may differ from your training data — read node_modules/next/dist/docs/ before writing code. Tests are in Vitest. Skip mocking the database; we use a real test DB."
Why it matters
Without a repo instruction file, coding agents waste tokens re-discovering things every session and often get them wrong. With one, you front-load the context once and every session is sharper. It's the highest-ROI 30 minutes you can spend on agent-assisted dev.