TL;DR
A coding agent that keeps breaking a rule in CLAUDE.md, AGENTS.md or .cursor/rules has usually hit one of two problems: the rule never reached the model for that task, or it arrived and lost out to the task. These files are context, not enforcement. Check what loaded, rewrite the rule so a diff can show compliance, and move the decidable parts into checks before the edit, at the end of the turn or in CI. You then know which edit paths remain unchecked.
Emphatic wording did not stop the edits
In August 2026 a developer on the Cursor forum described marking paths as accessible but not editable in .cursor/rules, adding emphatic "do not edit" wording, and watching the agent edit those files anyway. A Cursor staff reply agreed with their diagnosis: rules are injected into the model's context as guidance, not applied as a runtime block, and the reliable way to stop an edit is a hook.
Nine months earlier, a Claude Code user on Hacker News asked whether AI code assistance is fundamentally unenforceable without hooks. Their CLAUDE.md was ignored, especially after automatic compaction, and they asked whether markdown guidelines can work at scale in any tool.
First, find out whether the rule was in context
Each tool decides differently when an instruction file enters context.
Claude Code loads CLAUDE.md files from your working directory and the directories above it when the session starts. Files in subdirectories load when Claude reads files in those directories, and rules in .claude/rules/ with a paths field load only when Claude works with matching files (Claude Code memory documentation). /context shows the loaded memory files, and an InstructionsLoaded hook can log which files loaded, when and why.
Cursor applies a project rule in one of four ways: always, when the agent judges it relevant from its description, when a file matching its glob is in context, or when you mention it with @ (Cursor rules documentation). Cursor also ignores plain .md files in .cursor/rules; project rules need the .mdc format with frontmatter.
Codex reads one instruction file per directory from the project root down to the directory you started in, joins them in that order, and stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default (Codex AGENTS.md guide). An instruction past that cap does not reach the model.
| What you see | Likely cause | What to check |
|---|---|---|
| A rule for one package is ignored only in some sessions | The file loads on demand and the agent never touched that directory | Claude Code /context; the rule's location and paths or glob |
| A rule stops working partway through a long session | Compaction dropped a conversation-only instruction or a nested rule has not reloaded | Whether the rule lives in a file at all, and which files were reloaded |
A Cursor rule works only when you @-mention it | The rule type depends on the agent judging relevance | Rule type in the .mdc frontmatter |
| Later rules in a large instruction set never take effect | Combined instructions exceed the tool's size limit | Codex project_doc_max_bytes; total instruction size |
Proving that rules loaded before an edit takes records that differ by tool; the article on checking that an agent loaded the project instructions compares them.
When the rule loaded and was still broken
Anthropic's troubleshooting guide is direct about this case: CLAUDE.md arrives as a user message after the system prompt, and strict compliance is not guaranteed, particularly for vague or conflicting instructions. It recommends keeping each file under about 200 lines, because longer files reduce adherence, and warns that the model may pick arbitrarily between two contradicting instructions. Three edits make compliance more likely, though not certain:
- Make the rule checkable. "Put tests in
/tests, mirroring/src" can be verified from a diff. "Keep things organized" cannot. - Remove the contradiction. Search every instruction file the tool loads, including personal and nested ones, for a rule that says the opposite.
- Move scoped rules to where they apply. A frontend convention loaded into every backend task competes with the task itself. The article on using the right rules for each part of a monorepo shows how to keep each package's conventions out of the way until its files change.
Decide which parts of a rule a script can check
Most project rules mix three kinds of statement. Some are decidable: a test file either contains .only( or it does not. Some can only be flagged for judgment: a hex literal in a component may break "use design tokens" or be a deliberate exception. Some no script can check: "read the module docs before editing" describes a process. Keep the judgment rules in writing, and move the decidable parts into a linter rule, type check, test or small script.
Paqad's rule map at commit 29548baf records each rule statement with a verifiability class and whatever checks it:
| Rule statement (abridged) | Class | What checks it |
|---|---|---|
Do not swallow an exception in an empty catch | Deterministic | ESLint no-empty already covers it, so no new script |
| Make every colour value resolve to a design token | Heuristic | A script flags hex literals in .tsx and .jsx files |
| When code and docs disagree, fix the mismatch in this change | Unverifiable | Recorded with the reason: agreement is a judgment |
Put the checks where a violation is cheapest to stop
A check can run at three points, and each one sees a different slice of the work.
Before the edit. Claude Code runs a PreToolUse hook before a tool call and lets it deny that call; Cursor and Codex have comparable pre-tool hooks. It stops a violation before it lands, but only for the calls its matcher names: Claude Code's hook documentation shows the tool call proceeding whenever the matcher does not match (Claude Code hooks reference). Paqad's pinned source registers its Claude Code pre-edit gate for Edit|Write|NotebookEdit and its Codex gate for ^apply_patch$, so a file changed through sed -i or an output redirect goes through neither. Test the block once, too: in all three tools a hook that errors or times out generally lets the action proceed.
When the agent's turn ends. A completion check inspects the changed files and can refuse to call the work finished. It does not prevent the write, but it catches results from routes the pre-edit hook never saw before you receive them.
In CI. A pipeline check sees every commit pushed through it, whichever tool, person or path produced it, though not local work that is never pushed. Its feedback is slowest, and it is the only one that does not depend on each developer's local hooks.
Keep a record of what was checked and what was not
You cannot verify directly that the agent followed the rules. You can verify which rules were in context for this change, which checks ran and what they found, and which actions nothing checked.
In Paqad, paqad-ai rules load works out the applicable rules from the changed file paths, prints their text into the session and writes rules-loaded.json with each rule's ID, the matching paths, a hash of the loaded text, the session and the time. On the wired Claude Code and Codex CLI paths, a covered source edit is refused until that record exists. The source code is explicit about the limit: the record attests loading and acknowledgment, never comprehension.
Results must also show when a check did not run: zero findings from zero armed scripts looks like a clean pass unless the report gives the armed count, as Paqad's enforcement code does.
The third part is the one most setups leave out: the edit paths no check covers, such as shell writes, tools without hooks and a teammate's editor that only reads instructions. Paqad 1.93.0 puts Cursor, Windsurf, GitHub Copilot and five other hosts in an advisory tier, where Paqad runs no hook of its own and the rules stay guidance until a native hook, CI or a reviewer checks the result. To produce a loading record and an armed-check count for changes in your own repository, try Paqad; its documentation lists which hosts it wires for pre-edit checks.
Frequently Asked Questions
Why does my coding agent keep ignoring the project rules?
Because instruction files reach the model as context, and context can be missing for one task or outweighed by the task itself. Before rewriting a rule, rule out the boring causes: a Cursor rule saved as plain .md instead of .mdc, a nested file the agent never had reason to open, or a combined instruction set past Codex's size cap.
How can I tell whether a rule was missing from context or loaded but not followed?
Ask the tool, not the agent. The agent's account of the rules it read is generated text; the loading views listed above are recorded facts. If the record shows the rule loaded for this task and the edit still broke it, stop moving files around and work on the wording, the conflict or a check.
Which rules should be checked by scripts instead of left as written instructions?
Rules whose violation shows in the files alone: forbidden patterns, file placement, naming, required test markers, banned imports. A rule that needs judgment can still get a warning-level check that a person resolves, which keeps the exception visible instead of silently allowed.
Where in the workflow should those checks run so they catch a violation before it spreads?
If you can add only one, add the CI check, because it covers every pushed commit whatever produced it; then add pre-edit hooks for the tools that support them. After installing a blocking hook, trigger it once with a known violation, since a matcher that names the wrong tool lets the edit through without any visible sign.
What evidence would let me trust a change while still showing which actions the checks could not cover?
The three-part record above, kept short enough to read in a minute. It does not show that the model understood the rules. It tells the reviewer which parts of the diff no check examined, which is where a human review should start.