System plan mode instructions override user CLAUDE.md workflow directives
Description
User-defined workflow instructions in the global ~/.claude/CLAUDE.md file are overridden by system-injected plan mode instructions, despite CLAUDE.md explicitly declaring override authority.
Setup
Global ~/.claude/CLAUDE.md contains custom workflow rules like:
## Workflow & Standards
### Task Tracking
- Write plan to `tasks/todo.md` (project-relative) with checkable items. Check in before starting.
- Track progress: mark items complete as you go, with high-level summaries.
- After ANY correction from the user: update `tasks/lessons.md` with the pattern and a rule to prevent recurrence. Review lessons at session start.
The CLAUDE.md header states:
IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.
Problem
When EnterPlanMode is invoked, the system injects a <system-reminder> with competing workflow instructions:
- "Write your final plan to the plan file (the only file you can edit)" -- conflicts with user's
tasks/todo.mddirective - "This supercedes any other instructions you have received" -- directly contradicts the CLAUDE.md override declaration
- The 5-phase workflow injected by plan mode replaces the user's custom workflow steps entirely
In practice, Claude follows the system-injected plan mode instructions and ignores the user's CLAUDE.md workflow. The user's tasks/todo.md never gets written, tasks/lessons.md is never checked at session start, and progress tracking follows the system's TaskCreate/TaskUpdate tools instead of the user's specified format.
Expected Behavior
User CLAUDE.md instructions marked as overrides should take precedence over system-injected workflow prompts. If a user defines their own planning/tracking workflow, plan mode should respect it rather than replacing it with its own.
Suggested Approaches
- Plan mode system prompts should defer to user CLAUDE.md when workflow conflicts are detected
- Plan mode could avoid injecting workflow instructions that conflict with explicitly declared user overrides
- The "supercedes any other instructions" language in the plan mode prompt should not apply to user CLAUDE.md directives
Impact
Users who define custom workflows in their global CLAUDE.md cannot rely on them being followed when plan mode is active. This undermines trust in CLAUDE.md as the authoritative configuration for Claude Code behavior.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗