What are project rules? Cursor, Claude Code, Codex, Grok

Rules are instructions a coding agent loads from files, so you stop repeating the same conventions in every prompt. They cover build commands, files not to touch, and how a part of the repo is put together.

The four tools don’t use one filename. Cursor has .cursor/rules. Claude Code has CLAUDE.md and .claude/rules/. Codex and Grok Build read AGENTS.md. Codex also uses the word “rules” for a different file, covered below.

How rules work

When a session starts, the tool finds the instruction files for that directory and puts their text into the context window. The model sees them on later turns in that session. Nothing in these files blocks a commit or fails a test. The agent is more likely to follow a short, concrete line than a long style guide.

Path-scoped rules wait until the agent is actually in those files. That keeps a monorepo’s frontend notes out of a backend task.

Rules in each tool

Claude Code

Claude Code reads CLAUDE.md at the start of a session: managed policy for an organization, ~/.claude/CLAUDE.md for you, and ./CLAUDE.md or ./.claude/CLAUDE.md for the project. It also walks parent directories. Files are concatenated, from the broader scope to the more specific, not overridden. Subdirectory files load when Claude reads or edits a file there.

.claude/rules/ holds one topic per Markdown file. A rule with no paths field loads at launch, with the same priority as .claude/CLAUDE.md. A paths list loads when Claude uses Read, Write or Edit on a matching file, and also when a Bash read such as cat or head on a single file hits a match.

The memory docs say to keep a CLAUDE.md under about 200 lines. Move a procedure that only matters for one area into a path-scoped rule or a skill. Instructions are context, not enforced configuration, so write lines you could check. /init drafts a starter CLAUDE.md. /context shows which memory files loaded.

See Claude Code memory.

OpenAI Codex

Codex reads AGENTS.md before it works. In ~/.codex it takes AGENTS.override.md if that file exists and is non-empty, otherwise AGENTS.md. From the project root down to your working directory, each folder contributes at most one file, in that same order, then any fallback names in project_doc_fallback_filenames. Closer files are concatenated later, so they can override broader guidance.

The combined project instructions stop at project_doc_max_bytes, 32 KiB by default. Empty files are skipped. /init writes a scaffold. Codex rebuilds this chain when a run starts.

The page titled Rules is a different feature. Those are experimental .rules files, Starlark, that decide whether a command may run outside the sandbox: allow, prompt or forbidden. A user file lives at ~/.codex/rules/default.rules. Project files under the project’s .codex/rules/ load only when that config layer is trusted. That is a permission control, not a coding convention.

See AGENTS.md in the Codex docs and command rules.

Cursor

Cursor project rules are .mdc files in .cursor/rules. A plain .md file in that folder is ignored, because it has no frontmatter. AGENTS.md is the plain-Markdown alternative, in the project root and in subdirectories. Nested files combine with parents, and the more specific file wins.

Four types come from alwaysApply, description and globs:

/create-rule in Agent writes a file with that frontmatter. Team and Enterprise plans can also set team rules from the dashboard. Precedence when guidance conflicts is Team Rules, then Project Rules, then User Rules. Rules do not apply to Cursor Tab.

The rules docs say to keep a rule under 500 lines, and to put anything that must always be in context in the rule body. An @file mention is a pointer. The agent reads that file with its tools. The file is not pasted in for you.

See the Cursor rules docs.

Grok Build

Grok loads AGENTS.md, Agents.md, AGENT.md, CLAUDE.md, Claude.md and CLAUDE.local.md, plus every *.md file in .grok/rules/. It also reads .claude/rules/ and .cursor/rules/ for compatibility. The docs describe those compatibility directories as *.md files. Deeper files win on conflict. Files ignored by .gitignore are skipped, which keeps CLAUDE.local.md out when it is ignored.

Global rules come from ~/.grok/. Inside a git repo, Grok walks from the root down to the working directory. Files are loaded in full, with no size cap. The docs say short, specific instructions are followed more reliably than long ones.

For one run, grok --rules "Always use TypeScript for new files" appends that text to the system prompt. grok inspect lists each rules file it found, with the path and an approximate token count.

See AGENTS.md in the Grok Build docs.

Details checked against each vendor’s documentation in October 2026.

A real example

This is a path-scoped rule for a blog whose posts are Markdown files in src/posts/. In Cursor, save it as .cursor/rules/posts.mdc:

---
description: Conventions for Markdown posts
globs: src/posts/**/*.md
alwaysApply: false
---

- The description is plain text, 120 to 160 characters, with no backticks.
- Don't add an updated field unless a fact in the post changed.
- Don't put secrets, tokens or private hostnames in the post.

In Claude Code, the same constraint is a path rule at .claude/rules/posts.md. The field name is paths, not globs:

---
paths:
  - "src/posts/**/*.md"
---

# Posts

- The description is plain text, 120 to 160 characters, with no backticks.
- Don't add an updated field unless a fact in the post changed.
- Don't put secrets, tokens or private hostnames in the post.

Codex and Grok Build will follow a short AGENTS.md in the repo root for repo-wide commands, and a nested file next to the posts if only that tree needs the rule. One root file is enough when the rule is short.

In Codex, a command allowlist is a separate file. This one allows npm test outside the sandbox:

prefix_rule(
    pattern = ["npm", "test"],
    decision = "allow",
    justification = "The test script is safe to run outside the sandbox",
)

Save that as ~/.codex/rules/default.rules and restart Codex. Check it with codex execpolicy check before you trust it.

When to use rules

Add a rule when the agent makes the same mistake on a second task. The fact belongs in a file if you would otherwise paste it into every prompt: the test command, the directory layout, a file it must not edit.

Skip a rule for a one-time task. Put that in the prompt. Skip it for formatting a linter already enforces. Skip it for a long procedure you only need sometimes. That is a skill, which loads when you invoke it, instead of sitting in context on every chat.

Pitfalls

A rule the model can see is still advice. Claude Code’s docs say CLAUDE.md is context, not enforced configuration. Two contradicting lines can go either way. Cursor resolves a conflict by precedence, and the earlier source wins: team, then project, then user. A project rule that asks for long explanations beats a user rule that asks for short ones.

Always-on rules spend context on every turn. Claude Code’s guidance is about 200 lines for a CLAUDE.md. Cursor’s is under 500 lines for a rule. Codex stops adding project instructions at 32 KiB by default. Grok Build has no size cap and still says short files are followed more reliably. If a rule only matters for src/posts/, scope it, or the agent is carrying it while it edits a layout.

The filenames don’t cross over cleanly. Cursor ignores a .md file in .cursor/rules/. Grok Build’s compatibility read of that folder is documented as *.md. An AGENTS.md is the file all four can use, with the Codex and Grok discovery rules above, and with Claude Code able to read it in place of or alongside CLAUDE.md.

Codex .rules files are experimental, and they match a command prefix, not a coding style. A script Codex cannot safely split, one with redirection or $(), is judged as a single bash -lc invocation. A linear && chain is split, and the strictest matching decision wins.

Related on flaviocopes.com

• What is an AGENTS.md file is the longer guide to the shared instructions file, including nested files and the Codex size limit.
• Make coding agents write less puts output rules in CLAUDE.md, AGENTS.md and a Cursor .mdc file, and shows why a vague “be concise” line gets ignored.
• AI coding agent context: how to document project decisions is where the “why” goes when a rule should only state the decision.
• CLI Tools Cabinet catalogs the command-line tools on your Mac, with a clitools command an agent can query. That replaces a rule that tries to list every flag of every tool you have installed.

Related glossary entries

• Context window: The context window is everything a coding agent can see at once. How to check it, free it and keep it small in Claude Code, Codex, Cursor and Grok Build.
• Permission modes: Permission modes decide what a coding agent can do without asking. The modes in Claude Code, Codex, Cursor and Grok Build, and what YOLO mode really skips.
• Cursor Tab: Cursor Tab suggests the next edit as gray text while you type. How Tab, Escape, and jump-in-file work, and the next-message predictions in Codex and Grok.

All AI glossary entries →

Want me to talk about your product? You can sponsor this site.