# Agents ignore instruction files because the files are advisory and too long; enforce hard rules with hooks

> CLAUDE.md and Cursor rules are context the model may not follow, so shorten and sharpen them, check they loaded, and use a Claude Code PreToolUse hook for rules that must never be broken.

## Answer

An instruction file is text placed in the model's context, not a rule the tool enforces. The Claude Code docs say Claude treats CLAUDE.md as "context, not enforced configuration". Files that are long, vague or contradictory are followed less reliably, so shorten and sharpen them and confirm they actually loaded. For a rule that must never be broken, use a Claude Code `PreToolUse` hook, which blocks the action whatever the model decides. Checked 2026-09-28.

## Details

A hook is a shell command that Claude Code runs at a fixed point in its lifecycle. Unlike an instruction, it always runs. The complaint is common: issue 15443 in the Claude Code repository ("Claude ignores explicit CLAUDE.md instructions while claiming to understand them") was closed as a duplicate, and a Cursor staff member wrote in a forum thread on 2025-12-10 that there is "known instability with project rules auto-apply, even with `alwaysApply: true`".

### Symptom, cause, fix

| Symptom | Likely cause | Fix |
|---|---|---|
| Claude never mentions a rule | File not loaded | Run `/context` and check **Memory files**. If the file is missing, Claude cannot see it. |
| Rule followed early, dropped later | File too long | Target under 200 lines per file. Longer files reduce adherence. |
| Inconsistent behaviour | Two rules contradict | Claude may pick one arbitrarily. Remove outdated or conflicting lines. |
| Vague rule skipped | Wording | "Use 2-space indentation" beats "format code nicely". |
| One critical line skipped | Buried among many | Add emphasis such as "IMPORTANT" to that line only. |
| Rule must never be broken | Advice cannot guarantee | Use a `PreToolUse` hook. |
| Cursor rule has no effect in Cmd/Ctrl+K | Rules are for Agent | Cursor docs: rules are used by Agent (Chat); they are not applied to Inline Edit. |
| Cursor rule file has no effect | Wrong file type | Cursor docs: a plain `.md` file in `.cursor/rules` is ignored because it has no frontmatter with `description`, `globs` and `alwaysApply`. Add that frontmatter. |
| Cursor `alwaysApply` rule unreliable | Known instability | Cursor staff acknowledged it in the forum thread above. Keep rules under 500 lines. |

A Cursor community guide dated 2026-02-20 reports that a rule with `alwaysApply: false` still loaded in agent mode in the author's tests. This is one user's report, not Cursor documentation.

### Diagnose in order

1. Confirm the file loaded (`/context` in Claude Code; the rules list in Cursor settings).
2. Check length and remove contradictions, see [[how-to-write-agents-md]].
3. Check the tool is the right one: Cursor rules do not affect Inline Edit.
4. Check `AGENTS.md` is not being skipped by a `CLAUDE.md`, see [[agents-md-vs-claude-md]].
5. If the rule is a hard requirement, move it out of the text file into a hook.

### Example: block edits to `.env` files

Save as `.claude/hooks/block-env.sh` and run `chmod +x` on it. It reads the hook input from stdin, extracts `tool_input.file_path` with `jq`, and exits with code 2 to block.

```bash
#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
NAME=$(basename "$FILE_PATH")
case "$NAME" in
  .env|.env.*)
    echo "Blocked: $FILE_PATH is an env file. Ask the user to change it." >&2
    exit 2
    ;;
esac
exit 0
```

Register it in `.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-env.sh" }
        ]
      }
    ]
  }
}
```

The hooks reference says exit code 2 blocks the tool call and passes stderr to Claude. I tested only the script logic offline, by piping sample JSON into it, not inside Claude Code:

```text
/app/.env        -> Blocked: ... exit 2
/app/.env.local  -> Blocked: ... exit 2
/app/src/main.ts -> exit 0
/app/docs/env.md -> exit 0
```

The matcher covers only the `Edit` and `Write` tools. A shell command such as `echo x > .env` goes through `Bash` and needs its own hook or a permission rule.

### Common mistakes

- Repeating a rule in capitals five times instead of shortening the file.
- Expecting a text rule to work as a security control.
- Testing a Cursor rule with Inline Edit.
- Adding a `CLAUDE.local.md` that hides `AGENTS.md`.

## See also

- [[how-to-write-agents-md]]
- [[agents-md-vs-claude-md]]
- [[claude-code-skills-vs-subagents-vs-hooks]]
- [[run-coding-agent-safely-sandbox-container]]

## Sources

- [Claude Code — How Claude remembers your project](https://code.claude.com/docs/en/memory)
- [Claude Code — Best practices](https://code.claude.com/docs/en/best-practices)
- [Claude Code — Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide)
- [Claude Code — Hooks reference](https://code.claude.com/docs/en/hooks)
- [Cursor — Rules](https://cursor.com/docs/context/rules)
- [Cursor Community Forum — How do I get cursor to actually follow my coding rules?](https://forum.cursor.com/t/how-do-i-get-cursor-to-actually-follow-my-coding-rules/145718)
- [Cursor Community Forum — community guide on rules not working](https://forum.cursor.com/t/how-to-figure-out-why-your-cursor-rules-arent-working/152439)
- [anthropics/claude-code issue 15443 — Claude ignores explicit CLAUDE.md instructions](https://github.com/anthropics/claude-code/issues/15443)

## Sources

- [Claude Code — How Claude remembers your project](https://code.claude.com/docs/en/memory)
- [Claude Code — Best practices](https://code.claude.com/docs/en/best-practices)
- [Claude Code — Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide)
- [Claude Code — Hooks reference](https://code.claude.com/docs/en/hooks)
- [Cursor — Rules](https://cursor.com/docs/context/rules)
- [Cursor Community Forum — How do I get cursor to actually follow my coding rules?](https://forum.cursor.com/t/how-do-i-get-cursor-to-actually-follow-my-coding-rules/145718)
- [Cursor Community Forum — How to figure out why your Cursor rules aren't working (community guide)](https://forum.cursor.com/t/how-to-figure-out-why-your-cursor-rules-arent-working/152439)
- [anthropics/claude-code issue 15443 — Claude ignores explicit CLAUDE.md instructions](https://github.com/anthropics/claude-code/issues/15443)