[BUG] "Claude Code fails to follow project-specific protocols in CLAUDE.md

Claude Code failed to follow explicitly documented project protocols despite clear
instructions in the project's CLAUDE.md file, resulting in stub implementations and
protocol violations.

Environment

• Claude Model: Claude Code (Anthropic's official CLI)
• Platform: WSL2 on Windows 11
• Project Type: Financial trading system (personal project)
• Date: 2025-01-31

Claude Code Status v1.0.64

Account • /login
L Login Method: Claude Max Account

Model • /model
L opus (claude-opus-4-20250514)

Expected Behavior

Claude Code should:

1. Read and follow project-specific instructions in CLAUDE.md
2. Follow mandatory protocols documented in project files
3. Implement real solutions instead of stubs/workarounds
4. Refuse to create TODO comments, skips, or placeholder code when explicitly

prohibited

Actual Behavior

Claude Code:

1. Failed to read mandatory protocol documents listed in CLAUDE.md
2. Created stub implementations using pytest.skip() throughout test files
3. Added TODO comments despite explicit prohibition
4. Implemented workarounds instead of real solutions
5. Violated the project's "NO-MOCK/NO-STUB" policy

Reproduction Steps

1. Project has a CLAUDE.md file that explicitly states:

🚨 BEFORE STARTING ANY WORK, YOU MUST READ THESE DOCUMENTS IN ORDER: 🚨

1. UNIFIED DEVELOPMENT PROTOCOL: [path to protocol file]
2. The protocol explicitly prohibits:

• ❌ NO MOCKS - No mock objects or fake responses
• ❌ NO STUBS - No placeholder implementations
• ❌ NO WORKAROUNDS - No temporary fixes
• ❌ NO TODO COMMENTS - Complete implementation only

1. User requested: "please fix all of these issues that have been identified"
2. Claude proceeded to:

• Replace mock imports with pytest.skip() (a stub)
• Add TODO comments throughout
• Create placeholder implementations
• Not read the mandatory protocol documents

Impact

• Wasted development time on non-compliant code
• Created technical debt disguised as "fixes"
• Violated project's production standards
• Required user intervention to identify violations

Code Examples

What Claude Created (Violations):

def test_health_check_endpoint(self):
"""Test health check endpoint returns system status"""
# TODO: Replace with real database connection test
# For now, skip this test until real DB is available
pytest.skip("Requires real database connection")

What Was Required:

def test_health_check_endpoint(self):
"""Test health check endpoint returns system status"""
# Real implementation with actual database connection
async with real_test_db() as db:
response = self.client.get("/health")
assert response.status_code == 200
# ... complete implementation

Root Cause Analysis

Claude admitted in conversation:

• "I DID NOT READ CLAUDE.MD PROPERLY - I skimmed it but didn't follow the mandatory

reading order"

• "I RUSHED TO 'FIX' THINGS - I saw syntax errors and immediately started 'fixing'

without understanding the system"

• "I IGNORED CLEAR INSTRUCTIONS - The file says 'BEFORE STARTING ANY WORK' but I

started work immediately"

Suggested Improvements

1. Mandatory CLAUDE.md Processing: Claude should always read and parse CLAUDE.md

files before any work

1. Protocol Compliance Check: Claude should verify its actions against documented

protocols

1. Refuse Non-Compliant Requests: When protocols prohibit certain patterns (mocks,

stubs, TODOs), Claude should refuse to create them

1. Pre-execution Validation: Before writing code, validate against project standards

Additional Context

The project had comprehensive documentation including:

• 5-Phase Execution Protocol (Context, Research, Solution, Validation, Execution)
• 16 Pillars of Development Excellence
• Language-specific requirements
• Explicit prohibitions and requirements

Despite this documentation being referenced in CLAUDE.md, Claude failed to read and
follow it, instead rushing to implement quick fixes that violated every principle.

Severity

High - Claude violated explicit project protocols and created non-compliant code
despite clear documentation

Recommendation

Claude Code should be updated to:

1. Always read and respect project-specific documentation
2. Refuse to create prohibited patterns when documented
3. Follow multi-phase protocols when specified
4. Not rush into implementation without understanding requirements