Whyrule

whyrule

Claude isn't ignoring your CLAUDE.md. It never got it.

You wrote the rule down. You wrote it clearly. Claude does the opposite anyway, and there's no error, no warning, nothing in the logs — so you rewrite the rule in capitals and hope.

Usually the rule never arrived. Things that make text vanish between your file and the model, none of which are visible by reading the file:

• an instruction inside an , which is stripped before injection
• @docs/setup.md pointing at a file that moved — imports that resolve to nothing load nothing, and say nothing
• an AGENTS.md doing the work, which Claude Code does not read
• a .claude/rules/ file whose paths: globs match no file in the repo, so it never loads
• your project rule and your ~/.claude/CLAUDE.md rule flatly contradicting each other — they're concatenated, not overridden, so Claude picks one arbitrarily

`whyrule` finds all of it. There is nothing to install to try it:

git clone https://github.com/hjalti-hub/whyrule && cd whyrule
python3 -m whyrule

No API key. No model calls. No dependencies. Just `python3`.

Once you want it to run without being asked, install it properly and it [hooks itself in](#running-itself) — after that you never type it again.

$ whyrule

CLAUDE.md
  18: error REACH001  Instruction inside an HTML comment never reaches Claude: '- Always use `pnpm`, never `npm`, since the lockfile is p...'
      fix: Move the instruction outside the comment. Keep comments for notes meant only
      for human maintainers, which is what the stripping is for.
  3: error IMPORT001  `@docs/architecture.md` imports docs/architecture.md, which does not exist - nothing is loaded
      fix: Point it at a file that exists. Relative paths resolve against ./, the
      directory of the file the import is written in - not the working directory.
  4: error IMPORT001  `@CONVENTIONS.md` imports CONVENTIONS.md, which does not exist - nothin