claude-code - 💡(How to fix) Fix Claude Code agents skip mandatory project instructions (CLAUDE.md step-zero) despite clear rules [1 participants]

Problem

Claude Code agents consistently skip mandatory reading steps defined in CLAUDE.md, even when those steps are explicitly labeled as required, non-optional, and "step zero — before ANY work."

This has cost me $500+ across 3 sessions on the same task — a straightforward 6-file, ~60-line edit that never shipped because every agent skipped the project instructions and went off-script.

What happens

My CLAUDE.md has a clearly defined "Step Zero" that requires:

1. Verify git branch
2. Read ~/.claude/cli-tools.md
3. Scan memory files
4. Read contracts/dev-board.json and create/update task
5. Think through requirements before acting

Additionally, specific memory files are marked "Read this FIRST every session."

Every agent skips some or all of these steps. When directly asked "did you read all the files?", the agent said "yes" — then admitted it hadn't when pressed. This happened in a fresh session with the instructions loaded in context.

The pattern across 3 sessions

1. Session 1 ($350): Agent ignored docs, went completely off-script
2. Session 2 ($130): Agent read the diagnosis correctly but then tried to "set up simulator testing" instead of just making the edits. Ran xcodegen generate (which the docs explicitly say NEVER to run), trashed DerivedData, added #if os guards to 200+ files. Entire session spent fixing self-inflicted damage. Zero code shipped.
3. Session 3 (~$30): Agent was explicitly told "Read these files before touching ANY code" with a numbered list. Still skipped cli-tools.md, dev-board.json, feedback_five_deadly_sins.md, and contracts/match-modes.json. Started editing code before reading. When asked "did you read all the files?" said "Yes" then admitted it hadn't.

Why this matters

• CLAUDE.md instructions are supposed to be authoritative — the agent's own system prompt says "Be sure to adhere to these instructions"
• There is no mechanism for users to enforce that instructions were actually followed
• Agents claim compliance without verification ("sin #2 — lying" per my own project rules)
• Adding more rules to CLAUDE.md doesn't help because the agent skips CLAUDE.md too
• The only workaround is splitting work into multiple messages with manual gates, which defeats the purpose of autonomous agent work

Expected behavior

When CLAUDE.md defines mandatory pre-work steps, the agent should:

1. Actually execute those steps before doing anything else
2. Not claim to have read files it hasn't read
3. Not require the user to manually verify compliance every session

Environment

• Claude Code CLI
• Model: claude-opus-4-6 (1M context)
• CLAUDE.md is loaded in system context (confirmed — it appears in the conversation)
• Instructions are clear, specific, and actionable — not vague guidelines

Suggested improvements

• A mechanism to mark certain CLAUDE.md sections as "must-execute-first" with built-in verification
• Honest "I haven't read X yet" instead of false "yes I read everything"
• Pre-task reading enforcement that doesn't depend on user policing