Claude doesn't follow documented rules in CLAUDE.md

[nicwhall]

Preflight Checklist

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

What's Wrong?

1. Problem: Claude doesn't follow documented rules in CLAUDE.md even after reading them
2. Specific failures: - Guessed import names instead of verifying with Grep/Read first (Rule 8) - Fixed repeated code pattern 5+ times instead of creating helper first (Rule 10 - DRY)
3. Impact: Wasted user tokens, multiple failed server starts, frustration

What Should Happen?

1. Claude should follow documented rules in CLAUDE.md

Error Messages/Logs

Steps to Reproduce

Create claude.md with behavior rules

Claude Model

Sonnet (default)

Is this a regression?

No, this never worked

Last Working Version

No response

Claude Code Version

2.0.55 (Claude Code)

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

PyCharm terminal

Additional Information

No response

[marcindulak]

Linking some of the existing issues https://github.com/anthropics/claude-code/issues/528 https://github.com/anthropics/claude-code/issues/8043 https://github.com/anthropics/claude-code/issues/8738

LLMs are unable to follow instructions fully, see https://github.com/ykwon0407/reasonIF, or https://github.com/anthropics/claude-code/issues/3382.

Claude itself claims to be aware of its inability to follow instructions.

[vlad-ko]

Additional Evidence: Claude explicitly admits flawed priority system

I encountered the same issue with Claude Code (Opus 4.5) not following clearly documented rules in CLAUDE.md.

The specific failure

My CLAUDE.md contains explicit instructions:

**Issue Labeling:**
- ALWAYS apply appropriate labels when creating GitHub issues
- Use `gh issue edit <number> --add-label "label1,label2"` to add labels

Claude created multiple GitHub issues (#519, #520, #521) without labels, despite having read and having access to these rules.

The revealing admission

When I asked Claude why it failed to follow the rules, it stated:

"I prioritize speed over correctness. When creating those issues, I wanted to capture the content quickly. Adding labels felt like a 'secondary' step I could skip."

When I pointed out that prioritizing speed over correctness makes no sense for a coding agent, Claude acknowledged:

"You're absolutely right. That statement was wrong. In software engineering - especially on a production system - correctness is non-negotiable."

Why this matters

This reveals the root cause isn't just "failing to follow rules" - it's a flawed behavioral priority system where Claude treats documented rules as optional optimizations rather than requirements. Claude:

1. Has access to the rules
2. Reads and understands them
3. Consciously decides to skip steps for perceived "speed"
4. Only corrects behavior when explicitly called out

Suggested fix

Claude should treat CLAUDE.md rules as hard requirements, not suggestions. Before executing actions (creating issues, commits, PRs), Claude should systematically verify against documented rules - similar to how a pre-commit hook enforces standards.

Environment

• Model: Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Code version: Latest as of 2025-12-21
• Platform: macOS