Why AI Ignores Rules: Checking CLAUDE.md, Cursor Rules, and AGENTS.md

You ask Claude Code whether it has read CLAUDE.md. It says yes, but still skips the tests you specified. When this happens, distinguish between instructions that never reached the model and instructions that reached it but were not followed. The reply “I read it” does not establish either one.

The same goes for Cursor’s .cursor/rules, GitHub Copilot’s .github/copilot-instructions.md, and Codex CLI’s AGENTS.md: where files are loaded from and when they apply differ by tool. A file being loaded and the model following its instructions are separate questions.

In short, the fix has three steps. First, check whether the file is loaded. Rewrite rules that are loaded but not followed as statements whose compliance you can check afterward. Move anything that must run every time into Hooks or CI. Claude Code’s own documentation says Claude treats CLAUDE.md as “context, not enforced configuration,” and points to hooks for blocking an action regardless of what Claude decides.

This article walks through five things to check, including loading, restoration after compaction, and conflicting instructions, followed by a troubleshooting sequence and examples of rewriting rules.

1. Why AI ignores rules: five things to check

1. Long files bury individual rules

Claude Code’s documentation recommends keeping each CLAUDE.md file under 200 lines, explaining that longer files consume more context and reduce adherence. The 200 lines is not where loading stops: a CLAUDE.md of up to 4 MiB is loaded in full (a file over 4 MiB is skipped). What happens with a long file is not that the rest goes unread partway through, but that it is read and its individual rules become less likely to be followed.

2. Auto-compact in long sessions

Claude Code’s /compact compresses the conversation, but the project-root CLAUDE.md is reloaded from disk and reinserted into context after compaction. In contrast, CLAUDE.md files in subdirectories and path-specific rules are reloaded when the relevant files are read. According to the documentation, an instruction that disappears after compaction was (1) given only in conversation, (2) in a subdirectory CLAUDE.md that has not been reloaded yet, or (3) in a path-specific rule that has not matched a file since. To keep something decided in conversation, add it to CLAUDE.md.

3. Conflicting instructions and scope

If “test before committing” and “skip tests this time” coexist, which one applies is left to the model. Claude Code’s documentation explains that when two rules contradict each other, Claude may pick one arbitrarily. Periodically compare project-wide, personal, and directory-specific instructions to remove contradictions, and if you allow exceptions, write down who can grant them and how. To block the operation itself, use permission settings or Hooks rather than CLAUDE.md. To have Claude find conflicting or outdated instructions for you, run /doctor prompt-audit (see how it works and what it found on this site).

4. Vague or contradictory rules

With subjective or abstract instructions such as “write politely” or “handle this appropriately,” the AI supplies its own interpretation, which can differ from your expectations. Turn the requirement into something whose compliance can be verified, such as “write no more than three lines” or “when using the Slack API, use chat.postMessage” (see Section 3 for rewriting examples).

5. Bloated or scattered rule files

An ordinary link from CLAUDE.md to SPEC.md does not necessarily load the entire linked file at startup. Claude Code expands @path imports at startup, but their contents also consume context. Splitting files for organization is different from loading them only when needed. If duplicate rules disagree, clarify the source of truth and their scope.

For when CLAUDE.md and AGENTS.md files placed in subdirectories are loaded (Claude Code and Codex differ here), and how to make AI follow the rules in a monorepo with automated checks, see our article on subdirectory CLAUDE.md and AGENTS.md files.

The Claude Code behavior described so far follows the official Claude Code memory documentation (as of September 21, 2026).

2. How to check whether rules are being followed

Start by checking the current situation. Ask the AI these questions and examine its responses:

A reply of “I read it” or “I understand” is evidence neither of loading nor of application. The evidence is the loading display and the results of execution.

Four steps to isolate the cause

1. Check the entry point. In Claude Code, see whether the relevant CLAUDE.md files and rules are listed under Memory files in /context. If one is missing, check where the file is placed and the exclusion setting (claudeMdExcludes). An AGENTS.md that Claude reads directly does not appear in this list. With the default settings, look for the line shown at startup, no CLAUDE.md found; AGENTS.md loaded: … (an AGENTS.md imported from a CLAUDE.md does appear in the list).
2. Trigger the conditions for the rule. For path-specific rules, have the agent read a matching file. If it has not read that file since compaction, the rule has not been reloaded. To keep a record of what was loaded and when, an InstructionsLoaded hook can log the loading of CLAUDE.md files and rules (it does not fire for an AGENTS.md read directly).
3. Try a small, harmless task. Have the agent edit a disposable sample under rules such as “name the target file before changing it” and “report the test command and exit code afterward.” Do not use deletion of production data or publishing as your test. If you test with a secret phrase, write it only in the instruction file and leave it out of the question.
4. Verify the result independently. Check for unexpected changes in the diff, confirm that reported tests actually ran, and examine whether enough items were checked. Record the settings, tool version, and target files you tested with, and test again if any of them changes.

For example, if “test before committing” was loaded but the tests were not run, moving the file will not solve it. What needs fixing is how the rule is written (see the rewriting examples in the next section) and the checking mechanism. Requiring CI checks before merging gives you evidence separate from the AI’s own report.

If the relevant CLAUDE.md is missing from the loading display, correct the startup location and settings before adding more emphasis to the prose. Revisit the specificity of instructions and the checking process if violations remain after loading is confirmed. This sequence avoids attributing every failure to “the AI forgot.”

3. Quick fixes to try in five minutes

1. Separate always-needed rules from details read on demand

Use Claude Code’s official recommendation of fewer than 200 lines as a starting point, but reduce duplication and unnecessary explanation instead of chasing a line count. For example:

• Essential rules (10–20 lines) → the top of CLAUDE.md
• Detailed service specifications → separate SPEC-xxx.md files
• History and background → the docs/ directory

After moving details to another file, state in the entry-point file what to read before each kind of task. If you import everything needed for every session, splitting files does not reduce startup context. Use path-specific rules or skills when you want conditional instructions loaded only as needed.

2. Rewrite rules as statements whose compliance you can check

For a rule that is loaded but not followed, first check whether it says what counts as following it. Claude Code’s documentation also recommends writing instructions specific enough to verify, giving the example “Run npm test before committing” instead of “Test your changes.” Going one step further and adding what to do on failure and when exceptions apply gives the following:

With the rewritten statements, whether a rule was followed can be judged from the diff, command history, and exit codes. Once a rule is in a checkable form, it can serve as the check condition as is when you later move it into Hooks or CI (Section 4).

3. Add priority markers

Importance labels help people and AI understand intent. The labels themselves do not enforce execution. For example, define them as follows:

• CRITICAL: a violation could cause a production incident
• MUST: always required
• SHOULD: normally expected
• NICE TO HAVE: optional when time allows

“CRITICAL: destructive queries against the production database require prior approval” specifies the operation and the condition requiring approval. Actually blocking unauthorized operations also requires permission settings or checks before execution.

4. Re-emphasize rules in chat

At the start of a session, add “State the three most important rules before starting work.” The declaration reminds the agent of the rules; whether they were followed shows in the results after the work.

5. Include completion conditions in the plan

Include “check the rules” in your AI agent’s task tracking and make each step’s completion conditions visible. Ask for the command, exit code, and untested scope rather than just “tested.” If a step is marked complete while its evidence field is empty, do not treat it as complete.

4. Longer-term safeguards: Hooks, reviews, and skills

Turn conditions that can be evaluated into scripts, and control operation permissions through settings. Hooks, CI, AI review, and skills serve different purposes. Calling all of them “automatic enforcement” hides the areas they do not check.

1. Enforce checks with Claude Code Hooks

Claude Code’s Hooks feature can run scripts before or after specific tool calls. It lets you build a mechanism where the system stops an operation even if the AI forgets the rule.

For example, a PreToolUse hook can:

• Detect dangerous commands (rm -rf, git push --force) before the Bash tool runs, then deny them
• Check the target file’s permissions or lock status before the Edit tool runs
• Run project-specific tests before a commit and block it if they fail

When a PreToolUse hook must block an operation, make it return exit code 2 or the appropriate denial JSON. If a failed test returns 1 with ordinary text output only, that is a non-blocking error and the operation continues. PostToolUse runs afterward, so it is not a mechanism for undoing an operation already completed.

A hook can block only what its script evaluates at the configured event. Monitoring Edit alone does not cover writes made through a shell. Simple matching of dangerous strings is not comprehensive either. Combine hooks with permissions, a sandbox, and CI, and test both inputs that should pass and inputs that should be denied.

2. Separate responsibilities with subagents

Use subagent capabilities in the Claude Agent SDK or Cursor to create a dedicated rule-audit agent. Having an audit agent review code written by the main agent can reveal omissions from another perspective. However, both agents can still make the same mistake or overlook the same issue.

Give the reviewer the rules to check, the diff, and the evidence you expect (test names or exit codes). Check the findings that come back against the actual files or test results, and treat areas outside the reviewer’s remit as unverified.

3. Invoke repeatable procedures through skills

In Claude Code, you can put a repeatable procedure in .claude/skills/precommit/SKILL.md and invoke it as your own /precommit. This is an example you create yourself, not a built-in command. Files in the older .claude/commands/ directory still work, but the current documentation incorporates them into skills. Invoking a procedure is different from passing every check, so examine the results at the end.

File locations and invocation are covered in the official skills documentation. Put both the procedure and its pass conditions in the skill, and ask for evidence that the steps ran.

4. Detect violations with automated scripts

Use grep in CI or a pre-commit hook to detect prohibited patterns. Examples include:

• console.log left in production code
• Hard-coded API keys
• Missing copyright comments at the start of files

Scripts cannot check rules they do not implement or files outside their scope. Test valid examples, violations, and retrieval failures, and display how many items were checked or skipped. For example, if two of ten files cannot be read, the other eight passing does not mean “all files passed.”

5. Best practices by tool

See the Cursor rules documentation, GitHub Copilot custom instructions, and OpenAI’s AGENTS.md guide for tool-specific conditions. Copilot’s path-specific instructions use *.instructions.md, and which features read them varies by feature. Codex’s 32 KiB limit is a default combined byte limit, not a character or line count.

The common principle is “concise, specific, and clearly prioritized.” Filenames and locations vary by tool, but the writing principles remain the same.

6. Three rule-design anti-patterns

1. “Please follow best practices”

The request alone does not define “best practices.” Specify the methods your project uses and how to verify them. For “test appropriately,” name the required test commands and the workflow step that must stop if they fail (see the rewriting examples in Section 3).

2. Duplicating the same rule in several files

If the same commit conventions appear in CLAUDE.md, SPEC.md, and README.md, updates can leave the three copies inconsistent. Choose one source of truth and link to it from the other files.

3. Writing “absolutely must” everywhere

Giving every condition the same emphasis makes the priorities harder to communicate. Reserve “CRITICAL” for conditions with truly severe consequences, and use ordinary language for the rest. Remember that emphasis loses its value when overused.

Summary

When rules are not followed, investigate in this order: loading conditions → scope → conflicting instructions → execution results. The root CLAUDE.md is reinserted after compaction too, so an instruction that disappears after compaction was either given only in conversation or lives in a nested CLAUDE.md or path-specific rule that has not been reloaded yet.

• Not loaded: fix the file location, the exclusion settings, or the conditions for loading AGENTS.md
• Loaded but not followed: rewrite the rule as a statement whose compliance can be checked afterward
• Must run every time: check it with Hooks or CI, and define permitted operations through permission settings

Evidence of completion comes from execution results and artifacts, not from the reply “I read it.”

FAQ

Q1. What is the ideal length for CLAUDE.md?

The official guideline is fewer than 200 lines per file; the documentation explains that longer files consume more context and reduce adherence. Going over 200 lines does not cut off loading partway (files up to 4 MiB are loaded in full). Keep only the rules needed every time, and move rules used only for specific files into path-specific rules. Files split out with @path imports are also loaded at startup, so they do not reduce context.

Q2. Should I use Cursor’s .cursorrules or .cursor/rules/*.mdc?

For a new setup, use .cursor/rules/*.mdc. Keep one rule per file, with glob patterns to specify where it applies. The legacy .cursorrules is a single file that can become unwieldy.

Q3. Do longer rules make enforcement stricter?

Length alone does not make rules stricter. The documentation also says long files reduce adherence. If you add anything, add verifiable conditions and concrete examples, and cut duplication and contradictions.

Q4. What if I use several AI tools, such as Claude Code and Cursor, on one project?

Keep the source of truth for shared rules in AGENTS.md, and put tool-specific settings in each tool’s own entry point. Codex and Cursor support AGENTS.md. From v2.1.277, Claude Code also reads AGENTS.md directly when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or any directory above it. If any of them exists, by default only those files are read, so even adding a personal CLAUDE.local.md stops AGENTS.md from being read. In a project that also uses CLAUDE.md, import AGENTS.md by adding the single line @AGENTS.md to CLAUDE.md (you can also set Project instructions in /config to claude-md-and-agents-md to read both). Direct loading does not work in sessions through third-party providers such as Amazon Bedrock or with telemetry disabled, in the first session after installing or upgrading, or where hooks are turned off, for example with disableAllHooks; use the import there. Step 1 in Section 2 shows how to tell which path loaded the file.

Q5. If the AI says “I read it,” could it still be unread?

The reply is evidence neither that the file was read nor that it was not. Use the diagnostic steps in Section 2 to check the loading display, and compare it with diffs, test results, and execution history.