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

Resolved 💬 12 comments Opened Mar 16, 2025 by Swoy Closed Jan 7, 2026

Environment

  • Platform (select one):
  • [X] Anthropic API
  • [ ] AWS Bedrock
  • [ ] Google Vertex AI
  • [ ] Other: <!-- specify -->
  • Claude CLI version: 0.2.45 (Claude Code)
  • Operating System: Fedora 41
  • Terminal: Konsole

Bug Description

Claude fails to consistently follow the instructions provided in the CLAUDE.md file, regardless of its length or conciseness. Additionally, it appears to forget or disregard updates to the file during a session. A specific issue is that rules related to comments are ignored. For example, if a rule states that no comments should be included in the code, Claude still adds them, often "discussing with itself" throughout the code base.

Steps to Reproduce

  1. Run claude in any code base
  2. Create a CLAUDE.md file containing the following content (this is python specific):
Before each task, YOU MUST follow the 9 rules below. Repeat them to yourself before you do any task the user gives you.
<base-instructions>
    <rule id="1" name="No Hardcoding">Use configuration files or environment variables. Enums are allowed.</rule>
    <rule id="2" name="Fix Root Causes">No workarounds; address issues properly.</rule>
    <rule id="3" name="Remove Legacy Code">Delete old code when replacing it; no shims or compatibility layers.</rule>
    <rule id="4" name="Minimal Comments">Code must be self-explanatory; use comments only when necessary.</rule>
    <rule id="5" name="Avoid Circular Dependencies">Keep modules loosely coupled.</rule>
    <rule id="6" name="Use Logging">Always use logging facilities; no print statements.</rule>
    <rule id="7" name="Mandatory Testing">Ensure 100% test coverage, including edge cases. No artificial test data.</rule>
    <rule id="8" name="No Unused Imports">Remove any imports that are not in use.</rule>
    <rule id="9" name="Follow Documentation">Verify implementation against relevant documentation (docs/vendors/).</rule>
</base-instructions>
  1. Observe that Claude fails to adhere to these rules in code generation.
  2. Update the CLAUDE.md file and rerun Claude, noting that it sometimes still references older versions.

Expected Behavior

Claude should strictly adhere to the rules defined in CLAUDE.md, ensuring consistent code quality, proper test implementation, and adherence to project-specific guidelines. The model should also respect updates to the file and apply them when the user request it.

Actual Behavior

  • Claude does not consistently follow the defined rules.
  • It does not reprocess CLAUDE.md for each task or session.
  • Rules are sometimes outright ignored, especially those related to comments.
  • In some cases, the model seems to do the opposite of what is instructed.
  • Updating CLAUDE.md does not always take effect, leading to confusion and inconsistent behavior.
  • Attempts to enforce adherence through manual reminders have proven ineffective.

Additional Context

<!-- Add any other context about the problem here, such as screenshots, logs, etc. -->

View original on GitHub ↗

This issue has 12 comments on GitHub. Read the full discussion on GitHub ↗