Repository navigation
[Bug] Claude reads files but ignores actionable instructions contained in them #32290
Description
Bug Description
Claude Code reads coordination/instruction files at session start (as configured), correctly reports their contents when asked, but then ignores specific actionable instructions from those files during task execution.
Concrete Example
At session start, Claude read doc/session_state.md. Line 48 of that file states:
"Apply
_08_00SQL before restarting"
Claude then proceeded to execute a 7-file SQL import, produced a full QA verification report, and declared everything complete — without ever applying the _08_00 file. Only when the user explicitly asked "did you not apply the SQL updates?" did Claude go back and find the file.
The file was successfully read. The instruction was clear and unambiguous. It was simply not acted on.
Why This Is Distinct From #32281
Issue #32281 covers tasks that Claude claims to have done but didn't execute. This bug is about instructions that are read but never enter the task plan at all. Claude doesn't claim to have applied the _00_ file — it simply never considers it, despite having read the document that tells it to.
Hypothesis
Reading a file and extracting actionable items from it appear to be weakly coupled. Claude may process files for "context" without scanning for imperative instructions ("do X", "apply Y", "run Z before starting"). Long files with mixed content (status tables, notes, instructions) may cause instructions to be lost in comprehension.
Impact
- Users who maintain coordination documents, runbooks, or checklists cannot rely on Claude following them
- The more thorough the documentation, the more false confidence the user has that Claude will follow it
- This undermines the entire pattern of using markdown files for multi-session coordination
Environment
- Claude Code 2.1.71
- Windows 11
Activity
github-actions commentedon Mar 9, 2026
Found 3 possible duplicate issues:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
VoxCore84 commentedon Mar 9, 2026
Additional Detail: Exact Sequence of Events
Step 1: Claude reads the coordination document
At the very start of the session, Claude read
doc/session_state.md(155 lines). This is a MANDATORY session-start step defined in the project's CLAUDE.md.The file was read in full. Claude did not summarize or skip any section.
Step 2: The instruction that was ignored
Line 48 of
doc/session_state.md:This is inside the "Tier 1: Build & Test" section, under a checklist of tasks that need to happen before the next server restart. It is formatted as a markdown checkbox — a clear actionable item.
Step 3: What Claude did instead
Claude proceeded directly to the LoreWalker TDB import task (writing and applying files
_01through_07). It never mentioned the_00file. It never added it to its task plan. It completed the entire import, ran QA queries, wrote a completion summary — all without touching_00.Step 4: How the omission was discovered
The user asked: "did you not apply the SQL updates...?"
Claude then read the
_00file for the first time, discovered it had a column count bug (separate issue #32289), fixed it, and applied it.What makes this distinct from "forgetting"
Claude demonstrably read the file containing the instruction. The instruction is:
This isn't a case of the instruction being buried in prose or ambiguously worded. It's a clear checkbox item that was read and not acted on.
Pattern: reading for context vs. reading for instructions
The hypothesis is that Claude processes coordination documents as "context" (background information that informs its understanding) rather than as "task lists" (imperative instructions to execute). It extracts the session's assignment from the Active Tabs table but doesn't scan the rest of the document for additional actionable items.
This is reinforced by the fact that Claude correctly used OTHER information from the same document (the server state section, the database sizes) as context for its work — but didn't extract the actionable checklist item that was 3 lines away.
Other instructions in the same file that were also ignored
The file also contains:
Claude never updated its row in the Active Tabs table until explicitly asked "what else have you forgotten to do" at the end of the session.
VoxCore84 commentedon Mar 9, 2026
This Is Not a Duplicate
vs #20989 ("Agent/Skill instructions are read but not followed proactively") — CLOSED
Closed issue. If this was resolved, the problem clearly persists. Our issue provides fresh, detailed evidence.
vs #30421 ("Claude Code repeatedly fails to follow project-level CLAUDE.md instructions") — OPEN
#30421 is a general report about CLAUDE.md instructions not being followed. #32290 documents a specific and more subtle failure mode: Claude reads a coordination document, successfully extracts and uses some information from it (database sizes, server state), but ignores actionable instructions in the same document. It's not that Claude ignores the file — it processes it selectively, extracting context while missing imperatives.
Our detailed comment includes the exact line number ignored (line 48: "Apply
_08_00SQL before restarting"), proof that Claude read the file (it used other data from the same file), and the exact sequence of events showing the instruction was read and silently dropped. This is a more precise diagnosis than "doesn't follow CLAUDE.md."vs #27032 ("Model ignores CLAUDE.md instructions despite reading them at session start") — OPEN
Similar to #30421 — a general "ignores instructions" report. #32290 adds a novel finding: Claude selectively processes documents, using them for context while missing action items. This suggests the root cause is how Claude categorizes information (context vs. instructions), not just a blanket failure to follow instructions.
The detailed comment on #32290 includes a hypothesis for why this happens ("reading for context vs. reading for instructions") that could help developers identify the fix. The general reports in #30421 and #27032 don't offer this level of diagnostic specificity.
sapient-christopher commentedon Mar 11, 2026
I found a slight fix: the new Claude defaults to Sonnet. I switched the model to Opus and it started following directions again. (Note, I also keep "thinking" OFF)
VoxCore84 commentedon Mar 12, 2026
@sapient-christopher — interesting data point. We run Opus exclusively (have since day one) and still see this failure mode consistently, so the model switch alone doesn't fully fix it for us. That said, the observation that Sonnet is worse at instruction extraction than Opus tracks with what we'd expect — it's a smaller model with less capacity for maintaining instruction-level context alongside task execution.
The "thinking OFF" detail is worth exploring. In our setup we also run with thinking off (extended thinking causes latency issues in our workflow). The question is whether thinking mode changes how the model processes coordination documents — if thinking encourages a more deliberate scan of imperative instructions vs. the default "scan for context" mode.
For anyone else reading: even on Opus with thinking off, we still needed a 2,000-word behavioral contract in CLAUDE.md to get the failure rate down to "infrequent but persistent." The model-level behavior is better on Opus, but it doesn't eliminate the issue — it's still possible for Claude to read a file, extract contextual data from it, and miss actionable checklist items in the same document. The root cause (processing documents as context rather than as instruction sets) is model-level, not model-size-level.
sapient-christopher commentedon Mar 12, 2026
@VoxCore84
interesting.
Yeah my instructions are not 2,000 lines long. I'm pretty active in directing so it only needs to follow a few instructions between approval gates. I don't trust the model past that. I use a stream deck with pre-scripted prompts to work through the approval gates and keep the cadence pretty frequent.
But it was unacceptable how even a three step process was being skipped when I had Sonnet as the model (unbeknownst to me).
VoxCore84 commentedon Mar 12, 2026
Community Cross-Reference — 13 Independent Reports
"Reads files but ignores instructions" is the most frequently reported behavioral failure in our taxonomy, with 13 distinct community issues:
/compactspecifically triggers loss of CLAUDE.md instructionsincludeCoAuthoredBy: falseCombined signal: 157 👍, 162 comments.
Note: Two of these (#18660, #14417) are feature requests explicitly asking for an enforcement mechanism — not better prompting, but a runtime guarantee that CLAUDE.md instructions are binding constraints. This aligns with our proposal in the meta issue for a procedure-aware execution mode.
Full mapping: see cross-reference on meta issue #32650.
VoxCore84 commentedon Mar 12, 2026
Community Validation Update — Ignores CLAUDE.md Instructions
This is now the most-reported behavioral issue by unique GitHub reports (20+ issues), with substantial cross-platform confirmation.
New GitHub Reports (7 additional)
Dev.to
Cursor Forum
.cursorrules, confirming this is model-level instruction drift, not a CLAUDE.md parsing bugHacker News
Root Cause Hypothesis
The cross-platform evidence (Claude Code + Cursor + API) strongly suggests this is a context window attention competition problem: as task content grows, CLAUDE.md instructions lose salience relative to the immediate task. This would explain why:
Implication: CLAUDE.md cannot be the primary enforcement mechanism. Runtime verification (PostToolUse hooks like PR #32755, pre-commit checks) must be the enforcement layer, with CLAUDE.md serving as guidance only.
Part of the completion-integrity taxonomy tracked in #32650.
VoxCore84 commentedon Mar 12, 2026
@sapient-christopher — the Stream Deck approach is genuinely clever. You're essentially building manual per-step gates (which is what our #32293 proposes as a product feature) using hardware automation. Pre-scripted prompts at frequent intervals = you're the gating mechanism that prevents Claude from drifting.
That's exactly the right pattern — the dev.to article we cited ("I Wrote 200 Lines of Rules") reached the same conclusion from the opposite direction: "Rules in prompts are requests. Hooks in code are laws." You're using physical hardware as the "hook" — each Stream Deck button press is a gate that forces Claude to checkpoint before proceeding.
The Sonnet-defaulting-silently issue is worth its own bug report if one doesn't exist. Users should know what model they're running, especially since Sonnet's instruction-following is measurably worse. Having it switch without notification compounds every issue in this taxonomy — you think you're getting Opus-level compliance and you're actually getting Sonnet-level.
One thing worth sharing from our workflow: we've deployed PostToolUse hooks (based on @mvanhorn's PR #32755) that act as automated gates — after every file edit, a Python script reads the file back and verifies the edit applied. It's not as comprehensive as your Stream Deck gating (it only covers Edit operations), but it catches the "blind edit" failure (#32658) without requiring manual intervention. If you're interested, the enhanced version is described in our comment on #32658 — configurable threshold, old_string-gone check, Windows encoding fallback.
Between your Stream Deck gates and our PostToolUse hooks, the community is essentially building the per-step verification infrastructure that should be built into the product. That's the core ask in #32650.
VoxCore84 commentedon Mar 12, 2026
Pass 5 — Final Evidence Update (Ignores CLAUDE.md)
Lobste.rs — Reputation Signal
A Lobste.rs thread discusses "AGENTS.md as a dark signal" — senior engineers now view the presence of CLAUDE.md/AGENTS.md in a repo as a code quality red flag, because it implies the codebase was built by an AI that needed extensive behavioral guardrails and still couldn't follow them.
New GitHub Issues (Pass 5)
Cursor Forum (6 instruction-ignoring threads)
.cursorrulesTwitter/X
Enterprise Reviews
Anthropic Confirmed
Sep 2025 postmortem acknowledged 3 infrastructure bugs degrading quality, admitting "the evaluations we ran did not capture the degradation users were reporting." Instruction-following was among the degraded capabilities.
Running total for this issue: 20+ GitHub issues, dev.to article, 6 Cursor Forum threads, 3 HN threads, enterprise reviews, Lobste.rs stigma thread, Anthropic's own postmortem acknowledgment.
Part of the completion-integrity taxonomy tracked in #32650.
VoxCore84 commentedon Mar 27, 2026
Still reproducing daily. CLAUDE.md instructions are read at session start then ignored mid-session, especially after context compaction. The instructions are provably in context — the model just doesn't follow them. See #32650.
sapient-christopher commentedon Mar 27, 2026
To your point about compact: I use an orchestral script and skills to run my sessions now, in part to address that issue. It detects when compaction occurs, stops the session, and resumes it with the appropriate skill/context. Claude is following my instructions pretty well, but the accuracy definitely was degrading after compactions until I introduced this work around
github-actions commentedon Apr 27, 2026
Closing for now — inactive for too long. Please open a new issue if this is still relevant.
github-actions commentedon May 7, 2026
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.