auditing-instruction-hierarchy

Auditing a CLAUDE.md instruction hierarchy involves measuring per-file line counts against a 250-line target, detecting dynamic content that breaks prompt caching, and checking hierarchy precedence across user, project, and plugin layers to produce a prioritized keep, move, or drop trim list.

Prompt cache hit rates drop when CLAUDE.md files contain dynamic content like timestamps or run IDs. Auditing these instruction files identifies and flags cache-breaking lines so you can remove or relocate them to stabilize the prompt cache.

The line count limit for CLAUDE.md files targets 250 lines, with a 400-line hard cap. Auditing measures the total instruction footprint across user, project, and plugin layers to ensure files stay within these size budgets.

You should move project rules out of CLAUDE.md files when scope triage identifies workflow logic or project-only rules that belong in a skill, hook, or system reminder rather than always-on guidance, ensuring the instruction hierarchy remains lean.

Claude Code supports checking hierarchy precedence across user, project, and plugin CLAUDE.md instruction files. An audit verifies that rules are correctly scoped and separated into always-on guidance versus project-specific configurations.

The best way to reduce token usage at session start is to audit your CLAUDE.md instruction hierarchy for bloat, trim dynamic content that breaks prompt caching, and move workflow logic into skills or hooks to shrink the total instruction footprint.