How Cursor, Claude Code, and Codex actually load your project rules (and why yours get ignored)

Rulestack — Sat, 11 Jul 2026 13:51:16 +0000

Every AI coding tool now has a "project rules" file. Cursor has .cursor/rules, Claude Code has CLAUDE.md, OpenAI Codex has AGENTS.md. Teams write them once, watch the agent ignore half of it, and conclude the feature is broken.

Most of the time the feature isn't broken. The rules file is written for a human reader, and each tool consumes it differently. Here's how the three tools actually load rules as of mid-2026, and the writing habits that transfer across all of them.

Cursor: rules are conditionally attached, not always read

Modern Cursor rules live in .cursor/rules/ as .mdc files with frontmatter (the old single-file .cursorrules has been dropped from the current docs entirely — treat it as deprecated and migrate). The frontmatter decides when the rule enters context:

---
description: "Conventions for API route handlers"
globs:
  - "src/api/**/*.ts"
alwaysApply: false
---

- Every handler validates input with zod before touching the DB
- Return typed error envelopes, never raw strings

The part people miss: there are effectively four attachment modes.

Always Apply (alwaysApply: true) — in context for every request
Apply to Specific Files (the mode older docs called "Auto Attached") — pulled in when a file matching globs is referenced
Apply Intelligently (formerly "Agent Requested") — the agent reads the description and decides whether to fetch the rule
Apply Manually — only when you @-mention it

So if your rule has a vague description like "general best practices" and no globs, it sits in Apply Intelligently mode and the model has no reason to ever pull it. The rule isn't ignored — it was never loaded. Give globs to anything file-scoped, and write descriptions like an API doc: what the rule covers, when to use it.

Claude Code: everything loads up front, so tokens are the budget

Claude Code reads CLAUDE.md automatically at session start: your user-level file (~/.claude/CLAUDE.md), the project root file, and files from parent directories; deeper CLAUDE.md files in subdirectories join when work touches those folders. You can also compose with imports:

See @docs/architecture.md for the module map.

The consequence of "loads every session" is that CLAUDE.md is a context tax. Every line you add is a line the model carries through the whole session, whether it's relevant to the current task or not. Long, unprioritized files don't fail loudly — they just dilute attention until the instruction you cared about loses to noise.

What works: keep the root file short and non-negotiable (build commands, hard constraints, "never do X because Y"), and push detail into imported or nested files that only load where they matter.

Codex: AGENTS.md is a merge chain, deepest wins

Codex looks for AGENTS.md in your home config (~/.codex/AGENTS.md), the repo root, and nested directories, merging as it goes — the file closest to the code being edited takes precedence on conflicts. AGENTS.md is also an open convention adopted by a growing list of tools, so it doubles as the vendor-neutral place for agent instructions.

The failure mode here is the opposite of Cursor's: everything does load, so people dump monoliths into the root file. Then a subdirectory rule silently overrides a root rule and nobody notices until the agent "randomly" changes behavior between folders. Treat the hierarchy as scoping, not duplication: repo-wide invariants at the root, module-specific conventions next to the module, and never state the same rule at two levels.

Five habits that transfer across all three

1. Write imperatives at the decision site. "Use keyword arguments for all function definitions" beats "code should be readable". The agent applies rules at the moment it makes a choice; phrase rules as the choice.

2. Explain the why on negative constraints. "Don't use merge, use rebase" gets pattern-matched away under pressure. "Don't create merge commits — this repo's tooling assumes linear history" survives, because the model can reason about when it applies.

3. Pay the token tax deliberately. All three tools ultimately stuff your rules into a context window. A 400-line rules file isn't 4x better than a 100-line one; it's usually worse. Prune anything the tool already does by default.

4. Scope rules to where they're true. Glob-attached rules in Cursor, nested CLAUDE.md in Claude Code, per-directory AGENTS.md in Codex — all three give you locality. A rule that's only true for src/api doesn't belong in the root file.

5. Test rules like code. After writing a rule, give the agent a task where the rule should fire and watch. If it doesn't fire, the fix is usually specificity or placement, not repetition. Rules files deserve version control, review, and occasional deletion — they drift out of date exactly like documentation because they are documentation, just with a machine reader.

The one-hop rule

A pattern that shows up in all three ecosystems: agents reliably follow one pointer, and quietly bail on two. A root rule that says "for API conventions, read docs/api-rules.md" works. A root rule pointing to a doc that points to another doc doesn't.

One carve-out: Claude Code's @import syntax is mechanical, not judgment-based — imports expand recursively at load time (up to a documented depth of four hops), so chained @ imports do arrive in context. The one-hop rule is about plain-text pointers, where the agent chooses whether to go read the file. If your rules need structure, either use a mechanical include where the tool offers one, or make each referenced file self-contained so a single hop is always enough.