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

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.

#!/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:

{
  "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:

/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.