Why Does Claude Code Ignore Your Instructions? A Deep Dive into Rules, Entry Files, and Best Practices

Why rules are ignored

When CLAUDE.md grows large, Claude Code may still read the file but some directives are effectively ignored. The cause is not only model limitation; packing many heterogeneous items into a single entry file pushes older rules into the corner of the context.

Rule not loaded – Rules placed in sub‑directories or with path prefixes are only read when the corresponding file is accessed. Use the /memory or /context commands to verify what is currently loaded.

Rule too vague – Generic reminders such as “keep code clean” lack actionable boundaries. Agents need concrete actions (e.g., which inputs to validate, which calls must stay outside transactions, which files must not be edited).

Rule overridden by later tasks – In long sessions the context becomes crowded; newer information tends to dominate, causing earlier rules to be effectively ignored.

Rule unsuitable for model memory – High‑risk constraints (e.g., never edit .env, never run destructive commands) belong to system‑level enforcement (hooks, permissions, CI) rather than natural‑language reminders.

Consequently, CLAUDE.md should serve only as an entry‑point “work card” that tells Claude Code the project purpose, tech stack, common commands, evidence of completion, and frequent error assumptions. The more specific the content, the better.

Anthropic’s steering documentation recommends keeping the entry file under 200 lines to stay within the context budget.

Rule layering

Organize rules into five layers, distinguishing between what the model sees, what the workflow calls, and what the system enforces. Misplacing a rule leads to it being ignored.

Concrete API rules (suitable for the entry file)

- API handlers validate input and shape responses only.
- Services own business orchestration and transactions.
- External HTTP and LLM calls must stay outside DB transactions.
- Separate code changes, local checks, deployment status, and production evidence in summaries.

Vague reminders (limited practical guidance)

- Write clean code.
- Follow best practices.
- Be careful with security.
- Keep the project organized.

High‑risk rules (require hard enforcement)

- Never edit <code>.env</code>.
- Never run destructive commands.
- Always run tests before commit.
- Never deploy without approval.

These high‑risk rules should be enforced via permissions, hooks, or CI scripts rather than relying on Claude Code to remember them.

Separate concerns

Local rules belong in sub‑directories such as .claude/rules/ so they load only where relevant. Complex processes (release flow, migration, review) belong in Skills , which are reusable workflow assets. Subagents act as temporary whiteboards for heavyweight analysis (search, log inspection, dependency comparison). They return only conclusions, evidence, and recommendations, keeping the main session lean.

Practical checklist when a rule is ignored

Check if the rule is actually loaded using /memory or /context.

Ask whether the rule is specific enough and scoped to the relevant directories.

Determine if the rule describes a process that should be a Skill instead.

Assess the accident cost; if high, move the constraint to a Hook, permission rule, or CI check.

Answering these questions resolves many “why was it ignored?” mysteries.

Reference materials

Anthropic: Steering Claude Code – CLAUDE.md files, skills, hooks, rules, subagents and more

Claude Code Docs: How Claude remembers your project

Claude Code Docs: Extend Claude with skills

Claude Code Docs: Create custom subagents

Claude Code Docs: Hooks reference

Claude Code Docs: Configure permissions

Illustrations

Rule hierarchy and soft‑reminder vs. hard‑boundary comparison: