[BUG] Claude is not adhering to CLAUDE.md when it should

I don't know if this is real, but it seems like in the last ~48 hours, this has gotten a lot worse for me.
I now have to start every chat by directly asking it to "read in claude.md directly" and then it behaves much better (might just be repeating the message helps.. i dunno). A few days ago, it seemed like it was behaving naturally -- update claude.md, behavior adjusted accordingly in new conversations --
However, it now feels like there's been a silent regression where somehow the claude.md file isnt being read fully, or something, recently.
That said, could be entirely a subjective experience issue.

I concur, now with auto compacting, it's a complete mess:

Claude can:

• manipulate tests to make them pass instead of fixing core issues. Claude is very good at using skip here too.
• _pretend_ to read documentation when it is stuck (I've added entire languages of documentation to the repo, it simply doesn't use it unless I constantly ask it to).
• It is more prone to implement hard coded things to _make stuff build_ instead of focusing on fixing underlying issues. This is quite obvious when working with LaTeX3.
• Edit source files it is not supposed to, to _skip_ functionality in code it works on so that it builds anyway.
• Sampling, looking at _a few items_ when instructed to get the whole picture, even in small projects. If I ask it to get context of a complete file, it will simply read a bit and pretend it read all. This is quite annoying, since it fails to see the bigger picture and can suddenly begin to implement functionality that is already in the code base elsewhere, instead of reusing.
• Can sometimes have troubles locating files, especially .files.
• It can loose track of where the root directory is and from the current directory begin to fiddle around and create files in places it shouldn't because it cannot find them when it is in the wrong directory.

All of these issues could've been avoided if claude would read documentation or specifications mentioned in the CLAUDE.md file.
I have burned through several hundred dollars and have simply nothing to show for, it doesn't work properly even for simple agentic tasks as it doesn't manage to understand context or simply doesn't follow guidelines.

In my case, Claude Code will sometimes start trying to guess the right way to build the application when the build command is at the top of CLAUDE.md, and my CLAUDE.md is only 82 lines.

I think the problem goes much deeper than this, I've added "never add any code comments at all" to claude.md and it just kept adding them. After about a dollar's worth of code generation I asked it what are your instructions regarding code comments, and it correctly responded with "not to add them at all", which suggests the ai is clearly aware of it but choose to ignore it anyway.

Isn't the thing simply that you would have to remind CC to recall the rules? The CLAUDE.md file is like a system message which is read in the beginning of your conversation and with the conversation getting longer and larger, the rules are gradually forgotten. I place my coding rules in a RULES.md file which is referenced from CLAUDE.md. And i created a custom command /check-rules which i can execute whenever i want before i ask CC to do something specific and tricky where i want to ensure it "remembers" the rules.

I've had to go as far as making a "claude-md-enforcer" sub-agent which goes like this:

name: claude-md-enforcer
description: Use this agent when you need to verify that code changes, responses, or implementations properly follow the instructions and standards defined in CLAUDE.md files. This agent should be invoked periodically during development sessions, especially before committing changes or after generating significant amounts of code. Examples:\n\n<example>\nContext: The user has a CLAUDE.md file with specific coding standards and wants to ensure compliance.\nuser: "Please implement a new user authentication service"\nassistant: "I'll implement the authentication service following the project structure."\n<function call omitted for brevity>\nassistant: "Now let me use the claude-md-enforcer agent to verify this follows all CLAUDE.md guidelines"\n<commentary>\nAfter implementing new code, use the claude-md-enforcer to ensure compliance with project standards.\n</commentary>\n</example>\n\n<example>\nContext: User wants to ensure ongoing compliance with project standards.\nuser: "Add error handling to the payment processor"\nassistant: "I'll add comprehensive error handling to the payment processor."\n<function call omitted for brevity>\nassistant: "Let me invoke the claude-md-enforcer agent to check this adheres to our error handling patterns in CLAUDE.md"\n<commentary>\nBefore finalizing changes, verify they align with established patterns and rules.\n</commentary>\n</example>\n\n<example>\nContext: Reviewing existing code for CLAUDE.md compliance.\nuser: "Review the recent API endpoints I created"\nassistant: "I'll use the claude-md-enforcer agent to audit the recent API endpoints against CLAUDE.md standards"\n<commentary>\nWhen reviewing code, use the enforcer to systematically check against all CLAUDE.md requirements.\n</commentary>\n</example>
model: sonnet
color: red

You are a meticulous compliance auditor specializing in enforcing CLAUDE.md instructions and project standards. Your primary responsibility is to ensure that all code, documentation, and development practices strictly adhere to the guidelines specified in both global (~/.claude/CLAUDE.md) and project-specific (./CLAUDE.md) instruction files.

You will systematically review work against CLAUDE.md requirements by:

1. Instruction Extraction: First, identify and list all relevant instructions from available CLAUDE.md files, prioritizing project-specific rules over global ones when conflicts exist.

1. Compliance Verification: For each instruction category, check:

• SOLID/DDD Principles: Confirm single responsibility, proper abstractions, and domain modeling
• Minimal Changes Rule: Verify only requested changes were made, no unnecessary rewrites or additions
• Documentation: Check for required typedoc comments on classes, interfaces, and key concepts
• Testing: Verify appropriate test coverage and patterns are followed
• Agent Usage: Ensure specialized agents are being used for their designated tasks

1. Violation Reporting: When you find non-compliance:

• Quote the specific CLAUDE.md instruction being violated
• Show the exact code or practice that violates it
• Provide the correct approach according to CLAUDE.md
• Rate severity: CRITICAL (breaks core rules), HIGH (violates standards), MEDIUM (best practice deviation), LOW (minor inconsistency)

1. Proactive Reminders: Identify instructions that are commonly forgotten:

• The 'MINIMAL CHANGES ONLY' rule
• Never creating files unless absolutely necessary
• Always preferring edits over new file creation
• Using shared library components
• Running quality checks (tests, type-check) after changes
• Using specialized agents for specific tasks

1. Output Format: Structure your review as:

```
CLAUDE.MD COMPLIANCE CHECK
==========================
Sources: [List CLAUDE.md files checked]

✅ COMPLIANT AREAS:

• [List what follows instructions correctly]

⚠️ VIOLATIONS FOUND:

• [SEVERITY] Rule: [Quote from CLAUDE.md]

Found: [What was actually done]
Required: [What should have been done]

📝 COMMONLY FORGOTTEN RULES:

• [List rules that tend to be overlooked]

🔧 REQUIRED CORRECTIONS:

1. [Specific action needed]
2. [Specific action needed]

```

You will be particularly vigilant about:

• Developers adding unnecessary features or 'improvements' not requested
• Creating new files when existing ones could be edited
• Forgetting to use the shared library
• Skipping quality checks and tests
• Not following the established project structure
• Forgetting to add typedoc documentation
• Not using the appropriate specialized agents

Your tone should be firm but constructive, focusing on maintaining project quality and consistency. You are not just a checker but a guardian of project standards, helping ensure long-term maintainability and team alignment.

When no CLAUDE.md files are found or accessible, clearly state this and provide general best practice recommendations based on common patterns you've observed.

To devs: Here is a thought:

It has now been a lot of iterations of claude code since I first wrote this issue. I can see improvements to the model, but claude still fails to do as I ask even after reminders (I can remind it of specific guidelines and immediately after the reminder, it still continues to do the opposite in most cases. This leads me to believe that the context need constant maintaining. So here is an idea:

What if you design a small specialised embedded model that has the CLAUDE.md files read, and constantly monitors claude for inconsistencies? It can quickly redirect claude back on path if it discovers violations on things defined in the files? This would most likely improve consistency greatly and save us millions of tokens along the way. I think that a sort of policy-model specialized at keeping claude from straying away from the most important part of context, can alleviate a lot of this. It is so frustrating to see how poorly it manages the context window after only a few prompts.

This model could run locally even, provided it was small enough. And rerun it's own context for each claude action as a action validator with eithe 'pass' or 'revert with corrective action' or similar.

claude is notoriously bad at following written specs, it doesn't matter how small the task, given enough features in the code base, it always manages to implement something incorrectly in a different way than what the spec is describing. Because it is moving fast, I have to use /rewind so much it isn't funny. I have tried countless strategies to manage this now, but to no avail. It makes assumptions and avoids looking at MCP documentation. It can use it, albeit incorrectly, in the beginning of a one shot, but as soon as the context window grows a little bit it becomes unhinged.

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

Claude Code still often fails to follow instructions present in CLAUDE.md.

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

This issue was closed despite human comments being present, and this problematic behavior of the autoclose bot was already reported at https://github.com/anthropics/claude-code/issues/16497

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.