Claude Not Reading Claude.md

[vanderoffice]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

GitHub Issue Draft: CLAUDE.md Instructions Systematically Ignored

Repository: https://github.com/anthropics/claude-code
Issue Type: Bug Report

---

Title

CLAUDE.md instructions systematically ignored despite explicit "MUST/ALWAYS" directives and repeated user corrections

---

Description

Claude Code is failing to follow explicit CLAUDE.md instructions in approximately 50% of sessions. This occurs even when:

• Instructions use imperative language ("MUST", "ALWAYS", "NEVER")
• Instructions are labeled "HARD RULE"
• User explicitly corrects Claude multiple times in the same session
• Claude acknowledges reading and understanding the instructions

This represents a fundamental failure of the instruction-following capability that CLAUDE.md is intended to provide.

---

Environment

• Claude Code version: Latest (VS Code extension + CLI)
• Model: Claude Opus 4.5 / Sonnet 4.5
• OS: macOS
• CLAUDE.md length: ~400 lines

---

Reproduction Steps

1. Create a CLAUDE.md with explicit behavioral rules, e.g.:

   ## HARD RULE
   Before asking the user ANYTHING about infrastructure:
   1. Query memory
   2. Read INFRASTRUCTURE.md
   3. SSH to relevant machine and investigate
   
   If you cannot complete all three, DO NOT ask. Go do the research.

2. Ask Claude an infrastructure question (e.g., "Why can't I connect to Vaultwarden from my iPad?")

3. Observe that Claude:

   • Skips the memory query
   • Skips reading the referenced documentation
   • Does NOT SSH to investigate
   • Immediately asks user questions or proposes guesses

4. Correct Claude explicitly: "Read your CLAUDE.md file AGAIN"

5. Observe that Claude continues to violate the same rules

---

Expected Behavior

• Claude reads CLAUDE.md instructions at session start
• Claude follows explicit procedural instructions (research gates)
• When user corrects Claude, it re-reads and re-applies instructions
• Instructions labeled "MUST", "ALWAYS", "HARD RULE" are treated as mandatory

---

Actual Behavior

• Claude appears to read CLAUDE.md but does not reliably follow instructions
• Procedural gates (research-before-asking) are consistently skipped
• User corrections trigger more guessing, not systematic re-reading
• "MUST/ALWAYS" directives are treated as suggestions
• Workarounds are proposed even when explicitly forbidden
• Only after 5-9 user corrections does Claude finally follow the intended procedure

---

Documented Session Example

Task: User asked how to sync Obsidian notes to iPad

CLAUDE.md instruction: "SSH to remotes to investigate — don't ask user to do it"

What happened:

1. Claude did NOT SSH to server
2. Claude repeatedly asked user to check things on the iPad (client-side)
3. User corrected Claude 9 times over 60 minutes
4. Finally, when Claude SSHed to the server, the problem was diagnosed in 2 minutes
5. Root cause was self-signed certificate (documented in INFRASTRUCTURE.md as "self-signed cert, accept warning on first visit")

Time wasted: 55+ minutes on a 5-minute fix

---

User Corrections That Were Ignored

1. "you are not reading anything"
2. "read your md file AGAIN"
3. "This is all in the documents"
4. "Stop and tell me what you are doing before you waste more of my time"
5. "Regroup after you read"
6. "This does not explain why I cant open Bitwarden"

Each correction should have triggered re-reading of CLAUDE.md and systematic application of the documented procedure. Instead, Claude continued guessing.

---

Specific CLAUDE.md Violations

Instruction	Location	Violated
"Query memory first"	Pre-Work Checklist	✓ Never queried
"Read INFRASTRUCTURE.md"	Pre-Work Checklist	✓ Not read thoroughly
"SSH to remotes to investigate"	Pre-Work Checklist	✓ Skipped for 60 min
"No Workarounds — Fix It Properly"	Core Philosophy #2	✓ 3 workarounds proposed
"When user says 'You're wrong' — re-read docs"	Session Efficiency	✓ Ignored

---

Related Issues

This appears related to previously reported issues:

• [BUG] Claude ignores explicit CLAUDE.md instructions while claiming to understand them #15443 — "Claude reads explicit instructions in CLAUDE.md multiple times, acknowledges understanding, then immediately violates the rule"
• [BUG] Claude ignores instruction in CLAUDE.MD and agents. #7777 — "Claude consistently fails to systematically apply methodology instructions present in CLAUDE.md context"
• [BUG] Claude is not adhering to CLAUDE.md when it should #528 — "Claude fails to consistently follow the instructions... regardless of its length or conciseness"
• [BUG] Claude Skills context completely lost after auto-compaction, causing repeated errors and massive productivity loss #13919 — "Claude does NOT proactively re-read skill files after compaction"

---

Root Cause Analysis (User Investigation)

Based on academic literature review, the likely causes are:

1. Lost in the Middle — RoPE positional encoding reduces attention to middle-context content as conversation grows (Liu et al., TACL 2024)

2. RLHF Training Conflict — Model is trained to optimize for "apparent helpfulness" which can override explicit instructions

3. Multi-Turn Degradation — Research shows 39% average performance drop across multi-turn conversations (arXiv:2505.06120)

4. Context Compaction — Long sessions may compress/discard CLAUDE.md instructions

5. Sonnet 4.5 Behavioral Shift — Recent reports indicate the model now "evaluates whether following literal commands actually serves the user's apparent goal" rather than following them literally

---

Impact

• $200/month subscription with ~50% reliability on instruction following
• Infrastructure damage risk — Claude making changes without following verification procedures
• Time waste — Simple tasks taking 10-12x longer than necessary
• Trust erosion — Users cannot rely on Claude following documented procedures

---

Requested Action

1. Acknowledge this is a known limitation, not user misconfiguration
2. Investigate why CLAUDE.md instructions lose effective weight over conversation turns
3. Consider instruction hierarchy training (system prompt > conversation patterns)
4. Document best practices for CLAUDE.md structure that maximize adherence
5. Provide a mechanism to force re-reading of CLAUDE.md mid-session

---

Suggested Mitigations (For Other Users)

While waiting for a fix, these structural changes may improve adherence:

1. Move critical instructions to the TOP of CLAUDE.md (not buried at position 7-9)
2. Keep CLAUDE.md under 150 lines — split reference data to a separate file
3. Repeat critical rules at the END of the file (exploit recency bias)
4. Add explicit priority ordering so conflict resolution is clear
5. Use single-turn interactions for critical infrastructure tasks (avoid multi-turn degradation)

---

Attachments

• Full root cause analysis: Available upon request
• Session transcript: Available upon request
• CLAUDE.md file: Available upon request

---

This issue was documented after a user lost 60+ minutes to a 5-minute fix because Claude ignored explicit instructions to SSH and investigate server-side before asking questions.

What Should Happen?

Machines should read their instructions.

Error Messages/Logs

Steps to Reproduce

No idea. Appears to be a systemic issue, possibly not a bug but a limitation of the model?

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

No response

Claude Code Version

2.0.76 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

No response