Why your AI coding agent ignores CLAUDE.md (and how to fix it)

You wrote a project memory file. The agent read it once, then spent the session doing exactly what the file forbids. Here is why, and the four fixes that worked.

It is too long

If the file is longer than the code it governs, the agent skims it like a human skims a EULA. Twelve short sections that each answer "what decision does this help me make?" beats forty aspirational paragraphs.

It is vague where it matters

"Follow the existing style" gives the agent nothing to act on. "Money is integer minor units; timestamps are UTC in storage" is checkable. Every rule should be something an agent could be marked wrong on.

It contradicts the code

If the file says "services are in /services" and the code moved them to /app/domain, the agent follows the code. Every stale instruction teaches the agent to discount the whole file. Re-read it after every refactor.

It is not in the path the agent reads

Different tools read different files: Claude Code reads CLAUDE.md, Cursor reads .cursorrules or the project rules, Trae and 通义灵码 have their own. If your file is in the wrong place, nothing you write matters. Keep one source and copy or symlink it.

The fix that made the difference

Put the memory file and a review command in the repo, and make the review command cite the memory file's rules. The agent stops treating the file as background text and starts treating it as the acceptance criteria. That shift - from documentation to acceptance criteria - is the whole trick.

I keep the template in a free repo, along with the review command and the six money checks that catch the expensive mistakes: AI Agent Engineering Kit - free starter.