How to write agent rules (.cursorrules / CLAUDE.md) that work

Every AI coding agent starts each session knowing nothing about your project's conventions. Rules files fix that. Cursor reads project rules (the older single .cursorrules file, and the newer rules in a .cursor/rules folder). Claude Code reads CLAUDE.md. Many other agents, including Codex, read an AGENTS.md file, and tools like Cline, Windsurf, and GitHub Copilot have their own instruction files. File names and exact features change, so check each tool's docs, but the writing principles are the same.

Why most rules files do not work

The common failure is a rules file that reads like a motivational poster: "Write clean, maintainable code. Follow best practices. Be thorough." The agent already tries to do that. These lines cost context and change nothing.

The second failure is length. A rules file that tries to cover everything gets partially ignored, and contradictions creep in. Rules work when each line changes behavior you would otherwise have to correct by hand.

The test for every line

Before you add a rule, ask: "Would the agent do something different without this?" If not, delete it. Good rules are things the agent cannot infer, or keeps getting wrong.

What to put in

1. The stack, with versions

State the language, framework, and major library versions. "Next.js with the App Router, TypeScript strict, Tailwind." Version matters because models may default to older APIs.

2. Commands

How to install, run, test, lint, and build. This is the highest-value section in most files, because it lets the agent check its own work. Write the exact commands.

3. Project map

A few lines on where things live: "API routes in app/api, shared components in components/ui, do not edit files in generated/." Keep it short; the agent can read the tree.

4. Conventions the agent keeps getting wrong

This section should grow from real corrections. If you keep telling the agent "use the existing fetcher helper, not raw fetch", that becomes a rule. Be concrete and give the example name.

5. Boundaries and workflow

This is where rules earn their keep for vibe coders:

• "Keep diffs small. One change per task."
• "Before editing more than three files, propose a plan and wait."
• "Do not add new dependencies without asking."
• "Never change environment files, secrets, or deployment config."
• "Run the tests after changes and report the result."

What to leave out

• Generic advice like "write good code" or "use meaningful names".
• Secrets. Never put API keys, tokens, or passwords in rules files. They are usually committed to the repo.
• Whole style guides. Let your linter and formatter enforce style, and tell the agent to run them.
• Stale information. An out-of-date rule is worse than none. Review the file when the project changes.

A template you can copy

# Project rules

## Stack
- TypeScript (strict), React, Vite
- Styling: Tailwind. No CSS-in-JS.

## Commands
- Install: npm install
- Dev: npm run dev
- Test: npm test
- Lint and format: npm run lint && npm run format

## Layout
- src/features/*: one folder per feature
- src/lib/*: shared helpers. Use src/lib/api.ts for all network calls.
- Do not edit src/generated/*

## Working rules
- Keep diffs small. One task per change.
- If a change touches more than 3 files, post a short plan first and wait.
- Do not add dependencies without asking.
- Do not touch .env files or deploy config.
- After changes, run lint and tests and report results.
- If you are unsure, ask one question instead of guessing.

That is enough for most projects. It fits on a screen, and every line changes behavior.

Cursor specifics

Cursor's newer project rules live as separate files in a rules folder, and can be scoped so some apply always and others only for matching files or when relevant. That lets you keep a short always-on file and put, say, database conventions in a rule that applies only to your data layer. The legacy .cursorrules file at the repo root still works in many setups, but check Cursor's docs for current recommendations.

Claude Code specifics

CLAUDE.md in the project root is loaded into context for sessions in that repo. You can also have a personal file for preferences that apply to all your projects, and files in subfolders for parts of a monorepo. Because it is loaded every time, keep it lean. Claude Code can help draft the first version from your repo; edit the result down hard.

Using more than one agent

If you use both Cursor and Claude Code, or switch between agents, avoid maintaining several diverging files. Keep one source of truth, such as an AGENTS.md, and have the tool-specific files point to or include the same content where the tool supports it. Contradictory rules across files are a quiet source of strange behavior.

Iterate like you would on code

1. Start with stack, commands, and three to five working rules.
2. Every time you correct the agent for the same thing twice, add a rule.
3. Every month or so, delete rules that no longer apply.
4. Commit the file so changes are reviewed like code.

If you would rather start from tested starting points, the Cursor/Claude Code Agent Rules Pack has starter rules for both tools, focused on small diffs and asking before wandering. Still choosing an agent? Read our guide to Cursor, Claude Code, and others, or browse the tools directory.

FAQ

What is the difference between .cursorrules and CLAUDE.md?

Both are plain-text project instructions. Cursor reads its project rules, including the older .cursorrules file, and Claude Code reads CLAUDE.md. The content can be very similar; the file name and loading behavior differ by tool.

How long should a rules file be?

Short enough to read on one screen is a good target for the always-loaded part. Every line should change the agent's behavior. Move specialized guidance into scoped rules or separate docs.

Should I commit agent rules files to git?

Usually yes, so your team and your future self get the same behavior and changes are reviewed. Keep personal preferences in your user-level settings and never put secrets in rules files.

Why does my agent ignore my rules?

Common causes are rules that are too long, vague, contradictory, or stale, or a file in the wrong location for that tool. Make rules concrete, trim the file, and check the tool's docs for where it looks for instructions.