CLAUDE.md System Prompt Adherence Issue

Claude Code Bug Report: CLAUDE.md System Prompt Adherence Issue

Summary

Claude Code doesn't consistently follow CLAUDE.md project instructions without explicit user prompting, and loses this context when starting new instances.

Issue Description

When working in a codebase with CLAUDE.md instructions, Claude Code should automatically follow the documented project conventions and workflows without requiring the user to repeatedly ask "did you follow the CLAUDE.md instructions?"

Expected Behavior

• Claude Code should proactively read and follow CLAUDE.md instructions when they exist in the codebase
• Should treat CLAUDE.md as high-priority project-specific system prompt override
• Should automatically follow documented project conventions without explicit user reminders
• Should retain awareness of CLAUDE.md requirements across conversation instances
• Should proactively check CLAUDE.md compliance after completing tasks

Actual Behavior

• Claude Code completes technical work correctly but often ignores CLAUDE.md workflow requirements
• Requires explicit user prompting to remember project-documented conventions
• Loses context of CLAUDE.md instructions when starting new conversation instances
• Inconsistent adherence to documented project workflows
• Treats CLAUDE.md as optional guidance rather than required project conventions

Example Workflow Issue

Recent session example:

1. ✅ Claude successfully completed complex technical work
2. ✅ Maintained all test coverage and code quality
3. ❌ Did NOT automatically follow project's documented CLAUDE.md workflow
4. ❌ Required explicit user question: "did you follow the CLAUDE.md instructions?"
5. ✅ Only then followed the documented project conventions

Impact

• Reduces Claude Code's effectiveness as an autonomous development assistant
• Creates extra friction for users who document project conventions in CLAUDE.md
• Breaks the seamless experience of having an AI that respects project-specific workflows
• Forces users to micromanage adherence to their own documented processes
• Undermines the value of CLAUDE.md as a mechanism for project customization

Reproduction

1. Create a codebase with CLAUDE.md containing project-specific workflow instructions
2. Ask Claude Code to complete a significant task
3. Observe that Claude completes the technical work but doesn't follow CLAUDE.md requirements
4. Start a new conversation instance
5. Observe that Claude doesn't seem aware of CLAUDE.md context from previous sessions

Root Cause Analysis

• CLAUDE.md instructions appear to have lower priority than default Claude Code behavior
• No built-in mechanism to verify CLAUDE.md compliance after task completion
• Context retention issues prevent CLAUDE.md awareness across conversation instances
• Missing proactive CLAUDE.md checking as part of task completion workflow

Suggested Fix

• Treat CLAUDE.md as high-priority system prompt override, not optional guidance
• Add explicit CLAUDE.md compliance checks after completing tasks
• Improve context retention for CLAUDE.md requirements across conversation instances
• Make CLAUDE.md adherence a core part of Claude Code's task completion process
• Add internal prompting: "Have I followed all CLAUDE.md requirements for this project?"

Environment

• Claude Code via CLI
• Projects with documented CLAUDE.md specifying project-specific conventions
• Multiple conversation instances over time

User Impact

High - This affects the core value proposition of Claude Code as an autonomous development assistant that should understand and follow project conventions without constant reminders. Users invest time in documenting their workflows in CLAUDE.md and expect Claude Code to respect those investments.