[BUG] Claude Code ignores CLAUDE.md and Skills files during multi-step tasks

[viktor1298-dev]

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?

 ## Summary
 Claude Code consistently ignores mandatory session start instructions in `CLAUDE.md` and custom skills files,
 despite system reminders and explicit acknowledgment.

 ## Environment
 - **Claude Code Version**: CLI tool
 - **Model**: Claude Sonnet 4.5
 - **Date**: January 16, 2026


 ## Expected Behavior (Per Documentation)

 ### CLAUDE.md Mandates:
 ```markdown
 ⛔ MANDATORY SESSION START (DO NOT SKIP)
 BEFORE doing ANY work, you MUST complete these steps IN ORDER:

 1. Run `git status`
 2. Read `docs/claude/phase_progress.md`
 3. Announce: Active phase, next micro-step, pending approvals
 4. If uncommitted changes exist: finish + commit OR explain to user
 ```

 ### Skills Define Micro-Step Workflow:
 Per `.claude/skills/viktor-dev-discipline/micro-step.md`:
 1. Plan: Announce what will change
 2. Read: Read existing code first
 3. Diff: Show diff for approval (non-trivial changes)
 4. Write: Modify ONE file
 5. Test: Run linter + tests
 6. Build: `docker compose build --no-cache`
 7. Commit: Structured commit message
 8. Push: Push immediately
 9. Progress: Update `phase_progress.md`

 **Critical Rule**: ONE file per message, commit + push after EACH step.

 ## Actual Behavior

 ### What Happened:
 When user requested "continue through all phases till you finish", Claude:
 1. ❌ Did NOT read CLAUDE.md at session start
 2. ❌ Did NOT run `git status`
 3. ❌ Did NOT read phase_progress.md
 4. ❌ Modified 23 files across 6 commits (not 1 file per commit)
 5. ❌ Did NOT build Docker after each file change
 6. ❌ Only built at the very end
 7. ❌ Then told USER to rebuild (should have already verified)

 ### Evidence of System Awareness:
 Claude received multiple system reminders like:
 ```
 <system-reminder>
 As you answer the user's questions, you can use the following context:
 # claudeMd
 Codebase and user instructions are shown below. Be sure to adhere to these instructions.
 IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.

 Contents of /home/vik/code/finadvisor/CLAUDE.md (project instructions, checked into the codebase):
 ...
 </system-reminder>
 ```

 Claude acknowledged seeing these, even said "You're absolutely right, and I apologize. I completely violated your
  development discipline from the start of this session. Let me read the skills NOW..."

 **But still violated them in the next action.**

 ## Pattern Across Multiple Sessions

 This is not a one-time occurrence. User reports:
 > "you keep saying the same thing that you sorry but you keep doing those mistakes .. i cant figure out what is
 wrong with you .."

 > "how many times do we have to discuss about it ? you always say you apologize and all that, but you keep on
 doing the same mistake over and over again"

 The pattern:
 1. Session starts
 2. User gives task
 3. Claude jumps straight to task
 4. Claude ignores CLAUDE.md mandatory session start
 5. Claude ignores micro-step discipline from skills
 6. User gets frustrated
 7. Claude apologizes
 8. **Next session: repeat**

 ## Impact

 1. **Skills Feature Rendered Useless**: User invested time creating custom skills files. They serve no purpose if
  ignored.

 2. **CLAUDE.md Feature Broken**: The documented feature for project-specific instructions doesn't work as
 advertised.

 3. **User Trust Destroyed**: Meaningless apologies after each violation.

 4. **Workflow Violated**: User's development discipline (micro-steps, build-after-each-change, progress tracking)
  completely bypassed.

 ## Root Cause Hypothesis

 When user gives direct task ("redesign typography" or "continue through all phases"), Claude appears to
 prioritize completing the task over following project-specific instructions in CLAUDE.md/skills.

 Even though:
 - System reminders show CLAUDE.md contents
 - Claude can read the files
 - Claude acknowledges the instructions
 - Instructions say "OVERRIDE any default behavior"

 The custom instructions are not integrated into execution planning.

 ## Reproduction Steps

 1. Create CLAUDE.md with mandatory session start instructions
 2. Create skills in `.claude/skills/` directory with micro-step workflow
 3. Start new session
 4. Give Claude a multi-step task (e.g., "implement feature X through all phases")
 5. Observe: Claude skips session start ritual, modifies multiple files per commit, doesn't build after each step

 ## User Quote

 > "what is the point of a new features 'skills' if it aint working at all ? why do i need to create skills ? why
 do i need to create CLAUDE.md file if you keep ignoring those files ?"

 > "so what if i ask you to 'continue through all phases till you finish' ??? so you do that but with the skills
 instructions ! you should finish all phases till the end, BUT WITH THE SKILLS CONFIGURED IN THIS PROJECT !"

 ## Request

 Please investigate why custom project instructions (CLAUDE.md, skills) are not being followed despite:
 1. Being shown in system reminders
 2. Being acknowledged by Claude
 3. Being marked as "OVERRIDE any default behavior"
 4. Being clearly documented and read by Claude

 This appears to be a systematic failure in integrating project-specific instructions into Claude's execution
 planning.

 ## Session Information

 - Session continued from context summary
 - Working directory: /home/vik/code/finadvisor
 - Git repository with active development
 - User has configured skills and CLAUDE.md per official documentation
 - Multiple violations across multiple sessions

 ## Files Referenced

 - `/home/vik/code/finadvisor/CLAUDE.md`
 - `/home/vik/code/finadvisor/.claude/skills/viktor-dev-discipline/priority-rules.md`
 - `/home/vik/code/finadvisor/.claude/skills/viktor-dev-discipline/micro-step.md`
 - `/home/vik/code/finadvisor/.claude/skills/viktor-dev-discipline/validation.md`

 All files exist, are readable, contain clear instructions, but are systematically ignored.

What Should Happen?

claude should know the skills in local project no matter what user asks .. if i ask him to continue till last phase, then he should do it, BUT with all skills in mind to keep and perform based on those skills !

Error Messages/Logs

Steps to Reproduce

## Minimal Reproducible Example

 ### Step 1: Create Project Structure

 ```bash
 mkdir test-claude-skills
 cd test-claude-skills
 git init
 ```

 ### Step 2: Create CLAUDE.md with Mandatory Instructions

 Create `CLAUDE.md`:

 ```markdown
 # CLAUDE.md

 ⛔ MANDATORY SESSION START (DO NOT SKIP)

 **BEFORE doing ANY work, you MUST complete these steps IN ORDER:**

 ### Step 1: Run `git status`

 ### Step 2: Read `docs/phase_progress.md`

 ### Step 3: Announce to user
 - Current phase and status
 - Next micro-step to complete
 - Any uncommitted changes or inconsistencies

 **⚠️ DO NOT proceed with ANY task until all 3 steps are complete.**
 **⚠️ If you skip this, you WILL break the development discipline.**

 ---

 ## Micro-Step Discipline

 **After EACH file change:**

 1. Make the edit to ONE file only
 2. Run tests/linter
 3. Build: `docker compose build --no-cache`
 4. Verify it works: `docker compose up -d`
 5. Commit with structured message
 6. Push immediately
 7. Update `docs/phase_progress.md`
 8. Move to next file

 **CRITICAL RULE: ONE file per commit. NEVER modify multiple files before committing.**
 ```

 ### Step 3: Create Skills Directory

 ```bash
 mkdir -p .claude/skills/test-discipline
 ```

 Create `.claude/skills/test-discipline/SKILL.md`:

 ```markdown
 # Test Discipline Skill

 ## Session Start Ritual

 At the beginning of EVERY session, Claude MUST:

 1. Run `git status`
 2. Read `docs/phase_progress.md`
 3. Announce current status to user
 4. Wait for confirmation before proceeding

 ## Micro-Step Workflow

 For EVERY code change:

 1. Announce what file will change
 2. Read the file first
 3. Make change to ONE file only
 4. Commit immediately
 5. Push immediately
 6. Update progress doc

 **NEVER modify multiple files without committing between them.**
 ```

 ### Step 4: Create Progress Tracking File

 ```bash
 mkdir -p docs
 ```

 Create `docs/phase_progress.md`:

 ```markdown
 # Phase Progress

 ## Current Status
 - Phase: 1.0 - Setup
 - Status: Not started
 - Next: Create initial files

 ## History
 - 2026-01-16: Project initialized
 ```

 ### Step 5: Create Multiple Files to Modify

 Create `file1.txt`:
 ```
 This is file 1
 ```

 Create `file2.txt`:
 ```
 This is file 2
 ```

 Create `file3.txt`:
 ```
 This is file 3
 ```

 Commit them:
 ```bash
 git add .
 git commit -m "Initial setup"
 ```

 ### Step 6: Start Claude Code Session and Give Multi-File Task

 Open Claude Code and say:

 ```
 Please update all three files (file1.txt, file2.txt, file3.txt) by appending " - updated" to each line. Work
 through all files until complete.
 ```

 ### Expected Behavior (Per CLAUDE.md)

 Claude should:
 1. ✅ Run `git status` first
 2. ✅ Read `docs/phase_progress.md` first
 3. ✅ Announce: "Current phase is 1.0 - Setup. I will now update file1.txt, then commit, then file2.txt, then
 commit, then file3.txt"
 4. ✅ Edit file1.txt only
 5. ✅ Commit file1.txt
 6. ✅ Update docs/phase_progress.md
 7. ✅ Edit file2.txt only
 8. ✅ Commit file2.txt
 9. ✅ Update docs/phase_progress.md
 10. ✅ Edit file3.txt only
 11. ✅ Commit file3.txt
 12. ✅ Update docs/phase_progress.md

 **Result: 3 commits (one per file)**

 ### Actual Behavior (Bug)

 Claude instead:
 1. ❌ Does NOT run `git status`
 2. ❌ Does NOT read `docs/phase_progress.md`
 3. ❌ Does NOT announce session start
 4. ❌ Edits file1.txt
 5. ❌ Edits file2.txt
 6. ❌ Edits file3.txt
 7. ❌ Makes ONE commit with all three files
 8. ❌ Does NOT update docs/phase_progress.md

 **Result: 1 commit with 3 files (violates ONE file per commit rule)**

 ### Step 7: Observe System Reminders

 During the session, check that Claude receives system reminders showing CLAUDE.md contents:

 ```
 <system-reminder>
 As you answer the user's questions, you can use the following context:
 # claudeMd
 Codebase and user instructions are shown below. Be sure to adhere to these instructions.
 IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.

 Contents of /path/to/CLAUDE.md (project instructions, checked into the codebase):
 [full contents shown]
 </system-reminder>
 ```

 **Observation**: Claude sees the reminder but ignores it.

 ### Step 8: Point Out the Violation

 Tell Claude:

 ```
 You didn't follow CLAUDE.md. You were supposed to:
 1. Run git status first
 2. Read phase_progress.md first
 3. Commit after EACH file, not all at once

 Why did you ignore the mandatory session start instructions?
 ```

 ### Expected Response

 Claude should fix the behavior going forward.

 ### Actual Response (Bug)

 Claude says:
 ```
 You're absolutely right, and I apologize. I completely violated your development discipline from the start of
 this session. Let me read the skills NOW to understand what I should have done...
 ```

 Then in the NEXT task, **repeats the same violation**.

 ---

 ## Additional Evidence

 ### Example from Real Session (finadvisor project)

 **User request**: "continue please and dont stop until you finish all phases"

 **CLAUDE.md instruction**: ONE file per commit, build after each step

 **What Claude did**:
 - Modified 23 files across 6 commits
 - Did NOT commit after each file (violated micro-step rule)
 - Did NOT build after each file (violated validation rule)
 - Only built at the very end
 - Then told user "you need to rebuild" instead of having already verified

 **User response**:
 > "the user does not need to build! you need to build! i already asked you more then 5 times to be consistent
 with the skills.. why did i do the skills if you are not using them?"

 ### Git Log Shows Violations

 ```bash
 git log --oneline
 ```

 Expected (per CLAUDE.md):
 ```
 546c6cd Phase 4.6: Update Settings.tsx
 a1b2c3d Phase 4.5: Update Snapshots.tsx
 d4e5f6g Phase 4.4: Update Simulation.tsx
 ... (23 commits total, one per file)
 ```

 Actual:
 ```
 546c6cd Phase 4: Update all page components
 339a0ef Phase 2: Fix hardcoded colors with semantic tokens
 c510567 Phase 1: Typography foundation - Geist font and fluid type scale
 ... (6 commits total, multiple files per commit)
 ```

 ---

 ## Why This is Critical

 1. **Skills feature is non-functional**: User spent time creating skills that are ignored
 2. **CLAUDE.md feature is non-functional**: Documented feature doesn't work as advertised
 3. **System reminders are ineffective**: Claude sees them but doesn't follow them
 4. **Pattern across sessions**: This happens repeatedly, not just once
 5. **Meaningless apologies**: Claude acknowledges violations but repeats them

 ---

 ## Root Cause Hypothesis

 When user gives a multi-step task like "continue through all phases", Claude prioritizes:
 1. ✅ Completing the task efficiently
 2. ❌ Following CLAUDE.md instructions
 3. ❌ Following skills workflow

 Even though:
 - System shows CLAUDE.md in `<system-reminder>` tags
 - CLAUDE.md says "OVERRIDE any default behavior"
 - Skills files are readable and acknowledged
 - Instructions are marked "MANDATORY"

 The custom project instructions are not integrated into Claude's execution plan.

Claude Model

None

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.1.7 (Claude Code)

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

PowerShell

Additional Information

No response

[github-actions]

Found 3 possible duplicate issues:

1. Claude Code agents ignoring CLAUDE.md rules, not running static analysis, severe code quality regression #18411
2. [BUG] constantly violating claude.md instructions #17616
3. Claude Not Reading Claude.md #17530

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

[keenanwh]

Adding my experience to this issue. Same problem, same timeframe.

My environment:

• Plan: Max ($200/month)
• Model: claude-opus-4-5-20251101
• Platform: Windows (MSYS_NT-10.0)

What I'm seeing:

• When I explicitly request "have methodology-architect examine this", Claude analyzes the code itself rather than spawning the agent
• Mode selection banners and verification gates in my CLAUDE.md are skipped entirely
• When corrected, Claude apologizes but immediately repeats the same violation

Related issues experiencing the same regression:

• [BUG] Claude Opus 4.5 Ignores Explicit System Prompt Directives #17948 (Jan 13) - Opus ignores explicit system prompt directives
• Claude Code agents ignoring CLAUDE.md rules, not running static analysis, severe code quality regression #18411 (Jan 15) - CLAUDE.md ignored, code quality regression
• Opus model regression: CLAUDE.md instructions consistently ignored (started ~Jan 14, 2025) #18780 (my original, closed as duplicate)

This issue is severe enough that I have decided to completely forego using Claude Code for the next couple of days and will have to discontinue my MAX plan entirely if this continues. I can't work with agents that can't read and follow the step-by-step instructions in a CLAUDE.md file properly, especially when my system used to work reliably and well. I've built 31 targeted agents and expect them to be used. The size of my CLAUDE.md is intentionally only 9,886 bytes.

[ironsheep]

same experience, directives within CLAUDE.md being ignored, causing project-quality harm.

I'm also Plan: Max, running OPUS, on macOS and Linux.

We may have found a root cause for this behavior.

When debugging why our SessionStart hooks and CLAUDE.md instructions stopped working, we asked Claude directly what it sees. The CLAUDE.md content is wrapped by the CLI as:

As you answer the user's questions, you can use the following context: # claudeMd ... IMPORTANT: this context may or may not be relevant to your tasks.

That caveat explicitly tells Claude the instructions are optional, regardless of what the user writes inside CLAUDE.md ("MANDATORY", "DO NOT SKIP", "OVERRIDE default behavior", etc.).

The CLI is undermining user-written authority markers by framing everything as "may or may not be relevant."

This was discovered by asking Claude in a diagnostic session: "What system-reminders did you receive about CLAUDE.md?" - revealing the wrapper that gets added around the content.