Your AI agent ignores the spec. Here is why, and what fixes it
You wrote the rules down in CLAUDE.md, Cursor rules, AGENTS.md or a PRD, and the agent still builds something else, as if it never read them.
How we know
The loading rules and limits are quoted from each tool's own documentation as read in November 2026: Claude Code's memory docs and best practices, OpenAI's Codex AGENTS.md guide and Cursor's rules docs. The long-context finding is Liu et al., "Lost in the Middle" (2023). What Entalpa does is checked against its MCP tool reference. We have not measured how often agents ignore a spec, so this page describes the causes and the fixes, not a rate.
What it looks like
- A rule from
CLAUDE.mdis followed for the first few tasks and then quietly stops being followed. - The feature works, but misses an acceptance criterion that is written, word for word, in the PRD in
docs/. - A Cursor rule you wrote for the API folder is never applied when you edit files there.
- After a long session, the agent asks about something you settled an hour ago.
- You add IMPORTANT and capital letters to the line, and it still gets missed.
Why the agent does it
Every one of these tools treats your instructions as text in the prompt, not as rules it is bound by. Claude Code's documentation says so directly:
CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions.
Claude Code documentation, Troubleshoot memory issues
Within that, a spec gets missed for one of five reasons, and each needs a different fix.
| Cause | What happens | Source |
|---|---|---|
| It never loaded | A CLAUDE.md in a subdirectory loads only when Claude works in that directory. Claude reads AGENTS.md only when there is no CLAUDE.md on the path. A Cursor rule set to Apply Intelligently needs a description, and one set to Apply to Specific Files needs a pattern that matches. A PRD in docs/ is read only if the agent decides to open it. | Claude Code memory docs, Cursor rules docs |
| It is too long | Claude Code recommends under 200 lines per CLAUDE.md, because longer files reduce adherence, and an on-demand file over its size limit arrives cut off. Codex stops adding instruction files once they reach 32 KiB combined. Cursor says to keep rules under 500 lines. | Claude Code memory docs, Codex AGENTS.md guide, Cursor rules docs |
| It conflicts | Two files disagree, or your rule competes with the tool's own built-in guidance. In Claude Code's words, if two instructions contradict each other, Claude may pick one arbitrarily. | Claude Code memory docs |
| It was compacted away | Long sessions are compacted into a summary. The project-root CLAUDE.md is re-read from disk afterwards, but a rule you typed in the chat, or a spec you pasted, is now whatever the summary kept. | Claude Code memory docs and best practices |
| It is buried | Models use information at the start and the end of a long context better than in the middle. One acceptance criterion on page twelve of a pasted PRD competes with everything else in the window. | Liu et al., Lost in the Middle (2023) |
the real problem
The spec is a document the agent may or may not have in front of it, at a length it may or may not hold on to. Writing it more forcefully does not change that. Getting the right part of it in front of the agent at the right moment does.
What helps, even without new tools
- Check what actually loaded before rewording anything. In Claude Code,
/context alllists the files under Memory files, and/memoryopens them. In Codex, runcodex --ask-for-approval never "Summarize the current instructions."from the repository root. In Cursor, check each rule's type and file pattern. - Keep the always-loaded file short: under 200 lines for
CLAUDE.md. Move rules that apply to one area into.claude/rules/files withpaths:frontmatter, Cursor rules set to Apply to Specific Files, or a nestedAGENTS.md, so they load when the agent works there and stay out of the way otherwise. - Write lines you could check. "Use 2-space indentation" works better than "format code nicely", in Claude Code's own example. Requirements are the same: "returns 404 for an unknown id" gets followed, "handles errors gracefully" does not.
- Remove conflicts. Read all your instruction files side by side now and then, and delete the older of two rules that disagree.
- Turn rules that cannot bend into hooks or deny rules. A hook runs at a fixed point whatever the model decides. Claude Code's best practices put it this way: if you keep adding emphasis to a line and Claude still misses it, the line belongs in a hook.
- Give each task its slice of the spec, not the whole PRD. Point the agent at the requirements for this task only, ask it to restate their acceptance criteria before it writes code, and to check each one before it says it is done.
- Run
/clearbetween unrelated tasks, so the next task does not inherit a long, half-compacted history. - Turn acceptance criteria into tests. A test fails whether or not the agent remembered the sentence.
These all work. The slice per task and the tests are the strongest, and both depend on someone cutting the right part of the spec for every task and keeping it current, which is the step that gets skipped by the third week.
How Entalpa handles it
Entalpa keeps the spec out of the context window and lets the agent fetch the part it needs, when it needs it, over MCP. The spec is structured: stakeholders, user stories, and requirements with acceptance criteria, each with a stable id such as REQ-12. Nothing has to be pasted, so nothing has to survive compaction; the agent can read the same requirement again at any point in the session.
- The agent pulls only what the task touches:
requirements_listfiltered by label,project_searchacross stories and requirements, orrequirements_get_manyfor the ids it needs. A handful of requirements with their acceptance criteria, not forty pages. - Your instructions file shrinks to one line: before working on a feature, read its requirements from Entalpa and check their acceptance criteria before you finish.
- The agent writes back what it did on each requirement:
implementation_status,code_referenceandtest_reference. You see which requirements it says are done and which test it says covers each one, instead of finding the missed criterion in review. - When a story changes, the requirements built on it are flagged as suspect, and
requirements_listwithsuspect_onlyreturns just those, so the agent does not work from wording that is out of date. - Lock a requirement and its wording cannot be changed over MCP until a person unlocks it in Entalpa, so the agent cannot make code and spec agree by editing the spec.
Entalpa does not run your tests or check the code against the criteria for you. It puts the right requirements in front of the agent and keeps a record of what the agent says it did, which you can check. Setup takes one command for Claude Code, Cursor, Codex and other agents.
Questions this raises
Why does Claude Code ignore my CLAUDE.md?
Usually for one of four reasons: the file did not load (check /context all), it is long enough that adherence drops (Claude Code recommends under 200 lines), two instructions conflict and Claude picked one, or the rule was typed in the chat and lost when the session was compacted. CLAUDE.md reaches Claude as a message it tries to follow, not as enforced configuration.
Why is Cursor not applying my rules?
Check the rule type. A rule set to Apply Intelligently needs a description so the agent can decide it is relevant, a rule set to Apply to Specific Files needs a pattern that matches the files you are working on, and a rule set to Apply Manually loads only when you @-mention it. Cursor also recommends keeping rules under 500 lines.
Why does Codex ignore part of my AGENTS.md?
Codex stops adding instruction files once their combined size reaches project_doc_max_bytes, 32 KiB by default, and builds the instruction chain once when a run starts. Raise the limit or split instructions into nested AGENTS.md files, then ask Codex to summarize the current instructions to see what it loaded.
Does writing IMPORTANT or ALL CAPS help?
Not much with current models. Claude Code's best practices say piling on emphasis mostly makes Claude over-apply the rule. If a rule cannot bend, make it a hook or a deny rule; if a line gets lost in a long file, make the file shorter.
How do I make an AI agent follow a PRD?
Do not hand it the whole PRD. Give it the requirements for the task in front of it, with acceptance criteria it can check, ask it to restate them before coding, and turn them into tests where you can. Entalpa does the slicing over MCP: the agent reads only the requirements a task touches and writes back what it implemented and which test covers it.
Entalpa gives your agent one locked source of truth
Structured, traceable requirements your agent reads over MCP — so it works from a curated spec instead of reconstructing your project every session. Free to start, no card, and reading or writing your project over MCP never spends credits.