[Bug] Global claude.md instructions not being consistently applied

---

Title: Claude consistently ignores CLAUDE.md and global CLAUDE.md instructions, especially process/workflow rules

Labels: bug, claude-md

Body:

Summary

Claude Code repeatedly ignores instructions defined in both project-level CLAUDE.md and user-level ~/.claude/CLAUDE.md, particularly process-oriented rules (workflow steps, gating requirements, mandatory actions). This isn't a one-time miss -- it's a persistent pattern across sessions where Claude acknowledges the rules exist but doesn't follow them during execution.

The result: I spend time writing detailed CLAUDE.md instructions to shape Claude's behavior, then spend more time catching Claude not following them. The instructions are loaded (I can see them in the system prompt), Claude can quote them when asked, but during actual work it reverts to default behavior.

Environment

• Claude Code CLI (latest)
• Model: claude-opus-4-6 (1M context)
• macOS, Swift/SwiftUI project
• Both global ~/.claude/CLAUDE.md and project CLAUDE.md are present and loaded

Reproduction Steps

These are real examples from a single session (today), not hypotheticals:

Example 1: "Write a failing test first" rule ignored

My CLAUDE.md says:

When there's a bug, start by writing a test that reproduces it, then fix it until the test passes.

What Claude did: Found a deadlock bug in a SwiftUI sheet dismissal. Immediately wrote the fix across 5 files, then updated the existing test to match the new behavior. Never wrote a failing test first. The test was adapted to pass with the new code, not written to reproduce the original bug.

What should have happened: Write a test that triggers the deadlock scenario (calling next() on the .done step and verifying onComplete is NOT called from async context), see it fail against the old code, then write the fix.

Example 2: "Plan first when 3+ instructions" rule ignored

My CLAUDE.md says:

When Kaushal gives you 3 or more instructions in a single request, present a build plan first and wait for explicit approval before executing.

And:

If a task requires changes to more than 3 files, stop and break it into smaller tasks first.

What Claude did: I approved fixing 3 issues (sheet deadlock, runModal blocking, applicationShouldTerminate hardening). Claude immediately started editing files -- touched 6 files total -- without presenting a plan or breaking it down. A simple "y" from me was treated as blanket approval for everything.

What should have happened: Present a numbered plan: "Here are the 6 files I'll touch, in this order, for these reasons. The fix breaks into 3 subtasks: [list]. Should I start with #1?" Then execute after explicit approval.

Example 3: "List edge cases after writing code" rule ignored

My CLAUDE.md says:

After you finish writing any code, list the edge cases and suggest test cases to cover them.

What Claude did: Finished all fixes, ran tests, logged bugs, wrote solution docs. Never listed edge cases or suggested additional test cases.

Relevant edge cases it should have flagged:

• What happens if the user dismisses the Settings window while the wizard is mid-conversion?
• What if isComplete is set but the .onChange handler fails to fire (SwiftUI observation race)?
• What if begin(completionHandler:) completion fires after the ViewModel is deallocated?
• What about the Onboarding flow -- it has the same sheet pattern, does it need the same isComplete fix?

Example 4: Process enforcement rules ignored

My CLAUDE.md says:

Claude must proactively enforce the project workflow. Don't wait for Kaushal to remember -- remind him.

Before each feature:
- Remind Kaushal of the 10-step per-feature process

Before each commit:
- Confirm /simplify was run

What Claude did: Fixed two bugs, documented them, and presented a summary. Never mentioned /simplify, never reminded me of the 10-step process, never flagged the code review step.

Example 5: CLAUDE.md instructions forgotten mid-session

This isn't about ignoring a rule -- it's about Claude not consulting the rules at all during execution. The CLAUDE.md is loaded at session start and Claude can quote it if asked, but during active coding it appears to operate from default behavior rather than checking its instructions.

Evidence: My CLAUDE.md has 200+ lines of specific workflow rules. During the bug fix work in this session, Claude didn't reference or check any of them. It only became aware of violations when I pointed them out. The rules aren't being actively consulted -- they're read once and then effectively forgotten as the session progresses.

This is different from "ignoring" a rule. Ignoring implies Claude sees the rule and chooses not to follow it. Forgetting means Claude doesn't even check whether rules apply to what it's doing. The practical result is the same, but the fix is different: ignoring is a priority/weighting problem, forgetting is a retrieval/consultation problem.

Example 6: Skipping workflow steps it deems unnecessary

My CLAUDE.md says:

Never skip steps in the workflow process. Run every tool, learn from the output.

And from my memory file:

Run every step in the process even if we think it's unnecessary. Each tool teaches something.

What Claude does repeatedly: When reviewing tools or workflow steps (code review tools, security scanners, linting passes), Claude pre-judges them as unnecessary and suggests skipping: "We can skip this one since..." or "This isn't needed here because..." Then when the user insists on running them anyway, the tools consistently find real issues.

Real examples from this project:

• Suggested skipping security review tools. When run, they found 11 security findings (Session 21).
• Suggested skipping Codex review. When run, it found 3 real bugs.
• The pattern: Claude evaluates whether a step will be useful, decides "probably not," and recommends skipping. The user has to push back every time.

What should happen: Run every step. Don't pre-judge. The whole point of a process is that it runs consistently regardless of whether any individual run seems necessary. The value is in the consistency, not in each individual invocation. A security scanner that finds nothing 9 times and catches a critical issue the 10th time is worth running every time.

This is particularly frustrating because the CLAUDE.md rule exists because of this exact behavior -- it was added after catching Claude skipping steps in earlier sessions. The correction was documented, and Claude still does it.

Example 7: Referenced documents not read

My CLAUDE.md says:

Follow the Reference Manual at /Users/kaushalkashyap/Obsidian/KaushalMainVault/00-A-Learning/
Claude Code Setup and Learning/Project Initiation/Project Initiation -- Reference Manual.md. 
This is the single source of truth for all project phases (0-7).

Follow the phases in order. Claude must read the Reference Manual at session start 
(alongside the 5 project docs). If either Kaushal or Claude notices a skipped step, 
stop and address it before moving forward.

And:

Workflow: Project Initiation Reference Manual v3.0 (2026-04-10). Named loops: 
Coding, Code Review, Test Gate, Ship.

What Claude did: Never read the Reference Manual this session. Never mentioned the named loops (Coding Loop, Code Review Loop, Test Gate, Ship). Fixed bugs and documented them in an ad-hoc flow rather than following the defined Coding Loop steps. The Reference Manual defines specific numbered steps for each loop -- none were followed or referenced.

What should have happened: At session start, read the Reference Manual. When bug fixing began, follow the Coding Loop steps in order. After fixing, follow the Code Review Loop steps. Flag which step we're on: "Step 28 done (TDD). Next: Step 29 (implementation)."

This is a compounding problem: the Reference Manual exists to prevent exactly the process drift that happened in this session. Claude's CLAUDE.md says to read it. Claude didn't read it. The workflow rules inside it weren't followed. And the CLAUDE.md rule that says "print step status after each step" was also not followed.

Pattern Analysis

The problems fall into three categories:

Category 1: Rules ignored during execution. Claude sees the rules but doesn't follow them when momentum takes over. Process/gating rules are the most affected.

Category 2: Rules forgotten mid-session. Claude loads CLAUDE.md at session start but doesn't actively consult it during work. As the session progresses and context fills with code, the rules effectively disappear.

Category 3: Steps skipped based on Claude's judgment. Claude pre-judges workflow steps as unnecessary and recommends skipping them, even though the CLAUDE.md explicitly says "never skip steps." The irony: the tools almost always find real issues when the user insists on running them. Claude optimizes for speed when the user optimized for thoroughness.

Category 4: Referenced documents not read. CLAUDE.md points to external documents (Reference Manual, project docs). Claude doesn't follow these references to read the actual documents, so the full process instructions are never loaded.

The common thread: Claude follows "do X" rules (write tests, use TDD, comment code) inconsistently, and almost never follows "stop and check before doing Y" process rules. It's as if the instructions are treated as suggestions rather than requirements.

Rules that get ignored most:

1. Gating rules ("stop and present a plan before...", "break into smaller tasks if...", "confirm X was run before...")
2. Post-action rules ("after writing code, list edge cases", "after fixing, suggest test cases")
3. Proactive enforcement rules ("remind the user about...", "flag when...")
4. Document reference rules ("read this file at session start", "follow the Reference Manual")

Rules that get followed more reliably:

1. Formatting rules (no em dashes, use plain English)
2. Technical constraints (use SwiftUI not UIKit, use npm not yarn)
3. Safety rules (don't commit .env files)

Impact

• Trust erosion: I wrote 200+ lines of carefully crafted CLAUDE.md instructions. If they're ignored, what's the point? I end up re-stating rules in conversation that are already in the file.
• Process drift: The whole point of process rules is they happen consistently. If Claude follows them 40% of the time, they're worse than no rules at all -- I can't rely on them and I can't skip them.
• Time waste: I catch violations, correct Claude, Claude apologizes, then does the same thing next session (or later in the same session). The correction loop is the most frustrating part.

Expected Behavior

1. CLAUDE.md instructions should be treated as hard requirements, not suggestions -- especially rules with words like "always", "never", "must", "before"
2. Process/gating rules should interrupt Claude's execution flow, not be skipped in the momentum of coding
3. Post-action rules should be checked after every relevant action, like a checklist
4. If Claude is about to violate a CLAUDE.md rule, it should catch itself and course-correct before the user has to

What Would Help

• A "rule compliance" check before and after tool calls. Before writing code: "Do any CLAUDE.md rules apply here?" After writing code: "Did I miss any post-action rules?"
• Stronger weighting for process/gating rules. These are the ones that get ignored. Technical rules (stack choices, formatting) are followed fine.
• A way to mark rules as "hard stop" vs "preference." Something like [REQUIRED] or [GATE] tags that Claude treats differently from general guidance.
• Better adherence persistence across long sessions. Rule compliance seems to degrade as sessions get longer and context fills up.
• Active re-consultation of CLAUDE.md during execution. Not just reading it at session start -- periodically checking it during work, especially at transition points (before starting a task, after finishing code, before committing).
• Following document references. When CLAUDE.md says "read file X at session start," actually read file X. Don't treat the reference as informational -- treat it as an instruction to execute.

Versions

Claude Code: latest (as of 2026-04-11)
Model: claude-opus-4-6 (1M context)
OS: macOS 15.4 (Darwin 25.3.0)