[Bug] Claude reads files but ignores actionable instructions contained in them

[VoxCore84]

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_00 SQL 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

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] Agent/Skill instructions are read but not followed proactively #20989
2. Claude Code repeatedly fails to follow project-level CLAUDE.md instructions #30421
3. Model ignores CLAUDE.md instructions despite reading them at session start #27032

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[VoxCore84]

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:

- [ ] Apply `_08_00` SQL before restarting

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 _01 through _07). It never mentioned the _00 file. 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 _00 file 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:

• Unambiguous ("Apply X before Y")
• Actionable (a specific file to run against a specific database)
• Relevant (the session was applying SQL files to the same database)
• Formatted as a checklist item (standard task-tracking format)

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:

• Line 26: "Before starting work, check this file. If another tab owns a file or task, don't touch it. Update your row when you start and when you finish."

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]

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_00 SQL 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]

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]

@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]

@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]

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:

Issue	👍	Comments	Key Detail
#2544	38	13	"CLAUDE.md Mandatory Rules Consistently Ignored Across Multiple Repositories"
#2901	20	31	"Frequently violates explicit project and user instructions"
#4017	20	18	/compact specifically triggers loss of CLAUDE.md instructions
#8961	15	17	Ignores deny rules in settings.local.json
#4554	13	8	Sub-agent instructions overridden by name-based inference
#7777	12	17	"Ignores instruction in CLAUDE.MD and agents"
#4287	12	11	Ignores includeCoAuthoredBy: false
#18660	7	6	Explicitly requests enforcement mechanism — "read but not reliably followed"
#5055	5	13	"Violates user-defined rules despite acknowledging them"
#8043	5	13	"Persistent Instruction Disregard and Output Quality Degradation"
#26533	4	13	"Ignores document instructions, repeats failed solutions"
#18454	3	9	"Ignores CLAUDE.md and Skills files during multi-step tasks"
#14417	3	3	Requests mechanism to make CLAUDE.md instructions binding

Combined 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.