# Agents ignore our CLAUDE.md rules and go straight to the codebase. How do we make context actually stick?


URL: https://getunblocked.com/answers/agents-ignore-claude-md-rules-how-to-make-context-stick/
Published: 2026-10-30T15:30:00Z
Updated: 2026-10-28T00:00:07Z
Author: Dennis Pilarinos
Categories: Context Engine, Engineering Insights

**Short answer:** Rules get skipped because a rules file is guidance, not enforcement. Anthropic says Claude treats CLAUDE.md as context, and adherence drops past 200 lines. Make it stick: cut the file to what the agent cannot learn from code, make the first rule 'gather context from a source you can query', enforce that step with a hook, and write each convention as a pointer to a real example.

---
Agents skip CLAUDE.md rules because a rules file is advice and the codebase is evidence. **A rules file** is the markdown an agent loads at the start of every session, and the three vendors in the table below describe it as context or guidance. A rule such as "use the shared error helper" is a claim the agent cannot check. The code it opens next is something it can check, so when the two disagree, the code wins. Context sticks when you stop asking the file to carry knowledge it cannot prove. Keep it short, make the first rule "gather context before acting" from a source the agent can query, enforce that step with a hook, and write every convention as a pointer to a real example.

| Vendor | File | Length guidance | How the vendor describes it |
| --- | --- | --- | --- |
| Anthropic (Claude Code) | CLAUDE.md, AGENTS.md, .claude/rules/ | Under 200 lines | "Context, not enforced configuration" |
| Cursor | .cursor/rules/\*.mdc, AGENTS.md | Under 500 lines | "Included at the start of the model context" |
| GitHub (Copilot) | .github/copilot-instructions.md, AGENTS.md | Not stated (2 pages, only in its generate prompt) | "Guidance and preferences" |


## Why the rules get ignored

Anthropic's documentation is direct. "Claude treats CLAUDE.md files as context, not enforced configuration, so how you write instructions affects how reliably Claude follows them" ([Claude Code memory docs](https://code.claude.com/docs/en/memory)). There is "no guarantee of strict compliance, especially for vague or conflicting instructions." Anthropic targets "under 200 lines per CLAUDE.md file" because "longer files consume more context and reduce adherence". When two lines contradict each other, Claude "may pick one arbitrarily". A March 2026 paper finds that LLMs show "significant performance degradation as context length increases" ([Cao et al., arXiv](https://arxiv.org/abs/2603.20432)).

The best-practices guide adds: "If Claude keeps ignoring a line that is in CLAUDE.md, adding IMPORTANT probably won't fix it. Either the file has grown long enough that the line gets lost, or the line is a rule that can't have exceptions, in which case it belongs in a hook" ([Claude Code best practices](https://code.claude.com/docs/en/best-practices)).

Cursor says rule contents "are included at the start of the model context," keeps them "under 500 lines" and asks you to "provide concrete examples or referenced files" ([Cursor rules docs](https://cursor.com/docs/context/rules)). GitHub calls `copilot-instructions.md` and `AGENTS.md` "guidance and preferences" and warns against "conflicting sets of instructions" ([GitHub Copilot docs](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)).

Underneath, most rules are prose without evidence. Consider "we retry three times." The agent cannot verify it, so it reads the retry loop, finds five, and trusts five.

## Keep the file short and make the first rule "gather context"

Anthropic's sample CLAUDE.md is about ten lines. The test for what belongs is whether it is something "Claude couldn't work out from the code itself" (best practices). Our [audit for a bloated CLAUDE.md](https://getunblocked.com/blog/audit-fix-bloated-claude-md/) walks through the cut.

What survives is still claims, so replace most of them with one instruction that points at a source the agent can query. **A context engine** is a service that indexes code history, pull requests, tickets, chat threads and docs together and returns one cited answer. Unblocked's docs suggest the line "Use the `context_research` MCP tool before planning or modifying unfamiliar code" ([Unblocked skills docs](https://docs.getunblocked.com/unblocked-mcp/skills)). The rules file now says one thing the agent can act on, and the answer arrives with the PR that explains why.

Arthur Rodolfo, Software Engineer at Clio, runs his workflow this way: "I built a step called 'enrich' that runs before any code gets written. The agent asks Unblocked for everything — the ticket, the Slack context, what's been done in related repos — and then it starts implementing. It's especially powerful for cross-repository work where you'd otherwise have to do all that archaeology yourself." The rules file carries one instruction and the context engine supplies the evidence.

## Enforce the gather step with a hook, not a sentence

A "gather context first" line gets followed most of the time. For every time, Anthropic is explicit: "If something has to happen every time, make it a hook, a deny rule, or a managed setting. CLAUDE.md is for guidelines, and Claude is allowed to decide a guideline doesn't apply" (best practices). **A hook** is a script the harness runs at a fixed point in the agent loop, and hooks "apply regardless of what Claude decides to do" (memory docs). A `PreToolUse` hook runs "before a tool call executes," and exit code 2 blocks the action ([Claude Code hooks reference](https://code.claude.com/docs/en/hooks)). Cursor's hooks in `.cursor/hooks.json` block the same way, with exit code 2 ([Cursor hooks docs](https://cursor.com/docs/agent/hooks)).

The pattern is small and yours to write. For example, a `PreToolUse` hook on Edit and Write checks for a marker the gather step leaves behind and exits 2 with a one-line reason when it is missing. The agent reads the reason, runs the research call, and the edit goes through. Anthropic warns that every hook "will occasionally fire when it shouldn't, and someone has to maintain each one", so keep the enforced set small.

## Put conventions where the agent can check them

A rule the agent can verify is a rule it keeps. Anthropic's examples of effective instructions are all checkable: "API handlers live in `src/api/handlers/`" instead of "Keep files organized" (memory docs). Cursor asks for "referenced files". So write each convention as a pointer, such as "Error handling: follow `src/lib/errors.ts`, see PR #4120 for why". The agent opens the file, sees the pattern, and the code and the rule now agree.

Two more moves shrink the always-loaded file. Path-scoped rules in `.claude/rules/` load "only when Claude works with matching files" (memory docs). Procedures move to skills, which load on demand: create one "when a section of CLAUDE.md has grown into a procedure rather than a fact" ([Claude Code skills docs](https://code.claude.com/docs/en/skills)). [Agent skills vs rules files vs retrieved context](https://getunblocked.com/blog/agent-skills-vs-rules-files/) has the full split. Conventions decided in a PR review or a Slack thread belong in the retrieved layer, because that is the only place the evidence lives.

## How to tell it is working

Confirm the file loads first: run `/context` and look under Memory files, and an `InstructionsLoaded` hook logs which files loaded and why. Then rerun the failing task: give the agent a job where the code contradicts a rule and watch which one wins. Before the fix the code wins silently; after it, the agent should surface the conflict with the PR or thread behind the rule.

Count three things for two weeks. Tool calls before the first edit should fall. We measured this once: same prompt, same model, with and without a context engine, and tool calls dropped from 80 to 29 ([same prompt, same model, different context](https://getunblocked.com/blog/same-prompt-same-model-different-context/)). Review rounds per PR should fall as the agent starts from the team's decisions. And watch the corrections you type in chat, which Claude Code writes into auto memory, loaded every session up to "the first 200 lines or 25KB" (memory docs). If the same correction keeps appearing there, the rule is still prose. Turn it into a pointer or a hook, and it stops coming back.

## Read more

- [How to Audit and Fix a Bloated CLAUDE.md File](https://getunblocked.com/blog/audit-fix-bloated-claude-md/)
- [Agent Skills vs Rules Files vs Retrieved Context: What Goes Where in 2026](https://getunblocked.com/blog/agent-skills-vs-rules-files/)

## Related answers

- [There is drift between our repos and our documentation and agents cannot tell. What handles this?](https://getunblocked.com/answers/documentation-drift-between-repos-and-docs-for-ai-agents/)
- [How do I mark old Confluence pages as deprecated so AI stops using them?](https://getunblocked.com/answers/mark-confluence-pages-deprecated-for-ai/)
- [MCP tools are eating the whole context window in Claude Code. How do other teams give agents company context?](https://getunblocked.com/answers/mcp-tools-filling-claude-code-context-window/)
- [We have context all over the place and constantly being generated. How do we organize it so AI pulls the right thing?](https://getunblocked.com/answers/organize-scattered-context-so-ai-pulls-the-right-thing/)