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

A developer analyzed how Cursor, Claude Code, and OpenAI Codex load project rules files, revealing that rules are often ignored due to misconfigured attachment modes, context tax, or hierarchical conflicts. The post details each tool's loading behavior and offers writing strategies to ensure rules are actually applied.

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. 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. alwaysApply: true — in context for every request globs is referenced description and 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 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 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. 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. 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. I maintain Rulestack, ready-to-use rule packs and skills for Cursor, Claude Code, and Codex, written and updated against each tool's current spec. If you'd rather start from a working baseline than a blank file, that's what it's for.