Rules for agents

An agent in Cursor or Claude Code reads your files, runs commands and changes code. Rules tell it who you are, how the project works and where the limits are. Here's where to put them, how to have one file for both tools, and templates to copy. As of 25 October 2026.

  • Cursor
  • Claude Code
  • AGENTS.md

🧭 Two layers: you and the project

The agent gets rules from two places. What applies to you, and what applies to a specific project.

Your rules

Apply in all projectsCursor: Customize → Rules → User Rules
Claude Code: the file ~/.claude/CLAUDE.md

  • Language, system (Windows, macOS), style of answers.
  • What the agent may do on its own and what it should ask about.
  • On Windows, ~ is the folder %USERPROFILE%, i.e. C:\Users\name.

Project rules

Live in the project and go into gitAGENTS.md, CLAUDE.md, .cursor/rules/, .claude/rules/

  • What the project does, how to run and test it, where things are.
  • Code conventions and workflows the agent won't figure out by itself.
  • Every tool and every computer where you open the project has them.
  • They even survive switching accounts. They live in the project, not in your AI account, so they load by themselves after you log in with another account.

A rule is not a lock

  • The agent treats rules as guidance. It mostly follows them, but it can overlook them.
  • What must never get through (deleting history, deploying) is guarded by a hook or permissions.
  • How to do it is in Guardrails and safety.

🖱️ Cursor

Based on Cursor's documentation. Details and more templates are in the Cursor guide.

User Rules

  • Customize → Rules → User Rules. Plain text, applies in all projects.
  • Good for your style and limits. The project description doesn't belong here.

AGENTS.md

  • Plain markdown in the project root, no header. The simplest way to project rules.
  • An AGENTS.md in a subfolder is added to the parent one. When they contradict each other, the one in the subfolder wins.

.cursor/rules/

  • .mdc files with a description, globs and alwaysApply header. Cursor ignores a plain .md in this folder.
  • Four types: Always Apply (always), Apply to Specific Files (only for certain files), Apply Intelligently (based on the description) and Apply Manually (via @).
  • One rule under 500 lines. Split bigger ones.

⌨️ Claude Code

Based on the Claude Code documentation. It works the same in the terminal, in VS Code and in the app.

CLAUDE.md

  • ~/.claude/CLAUDE.md: your rules for all projects.
  • CLAUDE.md in the project root (or .claude/CLAUDE.md): project rules, they go into git.
  • CLAUDE.local.md: your notes on the project that don't belong in git. Add it to .gitignore.
  • A CLAUDE.md in a subfolder loads once Claude starts working with files in it.

.claude/rules/ and imports

  • Rules by topic in .md files. With a paths: header they load only for files that match it.
  • A line @path/to/file in CLAUDE.md pulls in another file. Up to four levels deep.
  • An import doesn't save space. The imported file loads in full.
  • One CLAUDE.md under 200 lines. Claude follows longer files less well.

Useful commands

  • /init writes a first CLAUDE.md based on the project. It also picks up Cursor rules from .cursor/rules/.
  • /memory shows all rule files and turns automatic memory on or off.
  • /context shows under Memory files what actually loaded.

Automatic memory

  • Claude writes down notes from your corrections by itself in ~/.claude/projects/<project>/memory/.
  • At the start of every session the first 200 lines load, 25 KB at most.
  • It's plain text. Go through it now and then and delete what no longer applies.

🔗 One file for both tools

When you use both Cursor and Claude Code, don't keep two versions of the rules. They drift apart and then the agent does something different in each tool.

AGENTS.md is the base

  • Put the project description and shared rules into AGENTS.md in the root.
  • Cursor, Codex, GitHub Copilot and, since version 2.1.277, Claude Code read it.
  • Claude Code reads it on its own only when there's no CLAUDE.md or CLAUDE.local.md in the project or above it. Your ~/.claude/CLAUDE.md doesn't matter.

When you want a CLAUDE.md too

  • Write @AGENTS.md on the first line of CLAUDE.md, and below it only instructions for Claude Code.
  • Claude then loads AGENTS.md once, even though it can read it on its own.
  • On Windows, use an import, not a symlink. A symlink needs admin rights and git on Windows may check it out as a plain text file.

What goes where

  • What applies always and everywhere (style, limits): User Rules and ~/.claude/CLAUDE.md, or at the top of AGENTS.md.
  • What applies to one tool only: only Cursor reads .cursor/rules/; only Claude Code reads .claude/rules/ and CLAUDE.md.
  • Don't copy a rule into two files. One place, a link from the other.

Check it: in Claude Code run /context and see whether the file is under Memory files.

🔁 Git rhythm

When the agent should save work and when to send it out. Git for beginners is in GitHub for beginners.

Commit at the end of a task

  • No commit after every tiny change. At the end of a complete piece of work, 1–3 commits by topic.
  • A message in the form “type: what changed”, for example fix: PDF export.
  • A commit lives only on your computer. You can go back to it any time.

Push is a different thing

  • A push sends the work to GitHub and often triggers a website deploy or tests (CI).
  • Several commits can go out with one push. One build instead of ten.
  • The agent only suggests a push, lists what will go out and waits for your instruction.

Several agents on one project

  • When several windows or agents work on a project at once, they share one staging area for commits.
  • Have the agent commit with the files listed: git commit -m "…" -- file1 file2. Before that, have it check git diff --cached --stat.
  • Otherwise someone else's unfinished work gets mixed into the commit, like deleted files from another window.

🧠 The agent changes memory and rules only after agreeing

The agent can write to memory and to rule files on its own. That's why it needs limits here too.

Writing only with consent

  • Have it ask before it writes anything into memory or the rules. Then you know what changes where.
  • Have it propose a new thing together with the file it belongs in.

Don't shorten rules

  • A rule like “never X without agreeing first” is not shortened, rephrased or replaced with something “similar” by the agent, not even during a cleanup.
  • You can fence important parts with the markers <!-- LOCKED --> and <!-- /LOCKED --> and write in the rules that the agent doesn't touch them.

Important workflows from a file

  • Have the agent always read releases, deploys and similar workflows from a file, not from memory. Reading costs less than a broken production.
  • After a long chat is compressed into a summary, have it read the rules again.

🔧 When the agent doesn't follow the rules

The most common causes according to the Cursor and Claude Code documentation.

Rules that are too long

  • The longer the file, the harder it is to follow. Cursor advises under 500 lines per rule, Claude Code under 200 lines per CLAUDE.md.
  • Move what applies only to part of the project into a rule with globs or paths.

Rules contradict each other

  • The agent then picks one, and it may not be the one you want.
  • Go through all the places: User Rules, AGENTS.md, .cursor/rules/, CLAUDE.md and memory.

Too vague or unnecessary

  • The agent knows common commands and the style a linter enforces. Don't write them.
  • Link to files, don't copy their content. Copies go stale.
  • Add a new rule only when the agent keeps making the same mistake.

📋 Templates and prompts to copy

Replace the yellow parts in square brackets with your own. The rules follow the same standards as the rules for chat: what you want and why, no shouting.

Your rules (User Rules and ~/.claude/CLAUDE.md) CursorClaude Code 
# My rules for the agent

## About me
- Write in English.
- I work on [Windows 11 / macOS / Linux]. Write commands for [PowerShell / Git Bash / zsh].
- Level: [beginner / intermediate / pro]. When you use a new term, add one sentence on what it means.

## How to work
- For a bigger change (several files, a new feature, a refactor), first write a short plan and wait for my approval.
- Fix a small thing (a typo, one line) straight away and say what changed.
- When you're not sure about something, say so and state what you're basing it on. Don't invent libraries and functions that don't exist.
- Report the result in three parts: Verified (passed a test, a run or reading the file), Inferred (follows from the context but not checked) and Not verified. Write “works” and “done” only when you have proof.
- When something fails, write technically why and suggest a fix.
- Always read release and deploy workflows from a file, not from memory.

## Limits
- You may commit at the end of a task, with the files listed (git commit -m "…" -- files). Several agents may work on the project at once.
- Push and deploy only on my instruction in the current message, because a push triggers [a website deploy / CI]. Before a push, list what will go out.
- Before you write anything into memory or the rules, ask.
- Don't run commands that delete history or work (git reset --hard, git push --force, git clean). Tell me why they'd be needed and I'll decide.
- Don't open .env files and keys, they contain passwords. Tell me what should be in them.
AGENTS.md for the project CursorClaude CodeCodexCopilot

Save it as AGENTS.md in the project root.

# AGENTS.md

## What this project is
- [1–2 sentences: what the project does and for whom]
- Technologies: [e.g. Node 22, React 19, Vite]

## How to run it
- Install: `[npm install]`
- Development: `[npm run dev]`
- Tests: `[npm test]`
- Check before a commit: `[npm run lint]`

## Where things are
- `[src/]` [what's there]
- `[docs/]` [what's there]

## How to work
- After a change, run the tests and the check and say whether they passed. If you don't run them, say why.
- Stick to the style of the surrounding code. Propose a new library first, with a reason.
- At the end of a task, sum up what changed and how to verify it.

## Limits
- Push to the main branch and deploys only on instruction. [A push triggers a website deploy.]
- Don't open .env files and don't write anything from them into code or commits.
A CLAUDE.md that only loads AGENTS.md Claude Code

Only when you need instructions that apply just in Claude Code. Otherwise AGENTS.md alone is enough.

@AGENTS.md

## Only for Claude Code
- [Instructions that apply only here. For example: bigger changes in the src/payments/ folder go through Plan mode first.]
Let the agent write AGENTS.md CursorClaude Code 
Explore this project and write an AGENTS.md file in the root with the sections What this project is, How to run it, Where things are, How to work and Limits.

- Take the commands for running, tests and checks from package.json, README and the config. Don't make them up.
- For folders, write in one sentence what's in them. Skip folders like node_modules and dist.
- Leave anything you can't find out from the project as [fill in] and list it for me at the end.
- The whole file under 150 lines.
Don't change anything while exploring, only read. Show me the file before you save it.
Unify the rules for Cursor and Claude Code CursorClaude Code

When your rules are already scattered across several files.

I want to have the project rules in one place for both Cursor and Claude Code.

Read AGENTS.md, CLAUDE.md, .cursorrules and everything in the .cursor/rules/ and .claude/rules/ folders that exists in the project. Then suggest:
1. what to move into AGENTS.md because it applies to all tools,
2. what to keep only for Cursor or only for Claude Code, and why,
3. rules that are in two files or contradict each other.

Show the result as a table: rule, where it is now, where it belongs. Don't move or delete anything until I approve the proposal.
Next: Guardrails and safety → ← Back to Set up AI