How often should I audit my CLAUDE.md?

Audit after any workflow change — a new test runner, deploy target, or directory move — and whenever the agent repeats the same mistake. Quarterly pruning keeps stale rules from accumulating.

What is the single highest-value line in a CLAUDE.md?

The exact test command with its flags and runner named. It is used constantly, Claude cannot always infer it from package.json alone, and getting it wrong wastes a full loop every session.

Should every rule have an enforcement mechanism?

Rules that must never be violated should. Back those with a PreToolUse hook, a CI check, or a lint rule, and treat the rest of the file as advisory guidance that shapes behavior without guaranteeing it.

Does /init produce a good CLAUDE.md?

It produces a starting point from what Claude discovers in the codebase. Refine from there by adding what Claude could not discover — conventions, anti-patterns, and rationale — and cutting the parts it can simply read from the code.

Agent instruction guide

CLAUDE.md Best Practices Checklist — Audit Your File Against 8 Rules

Run your CLAUDE.md through eight checks: size, specificity, exact commands, anti-patterns, structure, contradictions, enforcement, and staleness.

Direct answer

Audit a CLAUDE.md against eight checks. Size: under 200 lines. Specificity: every rule concrete enough to verify, so 'run npm test before committing' not 'test your changes'. Commands: build, test, and lint with exact flags and any non-default tool named. Anti-patterns: two real mistakes your team has hit, which beat generic guidance. Structure: markdown headers and bullets, not dense paragraphs. Contradictions: no rule that conflicts with another CLAUDE.md up the tree or in .claude/rules/. Enforcement: anything that must always happen moved to a hook. Staleness: no commands or paths that no longer exist.

Open CLAUDE.md Reviewer

When to use this

You inherited a CLAUDE.md and want a systematic pass over it.
You are standardizing CLAUDE.md files across several repositories.
The file has not been reviewed since it was generated by /init.

Steps

Paste the full CLAUDE.md into the reviewer and read the numbered findings.
Count the lines. Over 200, move sections into path-scoped rules or skills.
Replace every rule you cannot verify with a concrete instruction naming a command or path.
Confirm the build, test, and lint commands are exact, including flags and the actual test runner.
Add two anti-patterns the team has really hit, then remove any rule Claude already follows without being told.
Verify every command and path in the file still exists in the repository.

Example review focus

CLAUDE.md excerpt

# CLAUDE.md

## About
Our app is a modern, scalable platform built with best-in-class tooling.

## Guidelines
- Write maintainable code.
- Add tests where appropriate.
- Use TypeScript.

## Setup
Run yarn install and yarn start.

What to fix

Fails six of eight checks. The About section is marketing and changes nothing. All three guidelines are unverifiable. The commands are stale if the repo moved to npm. Rewrite: `npm run dev` for the dev server, `npm run test` (Vitest, not Jest), `npm run lint` before any commit, plus two real anti-patterns — do not edit files under src/generated/, and do not add a dependency without asking.

Common mistakes

Do not treat a passing checklist as enforcement; CLAUDE.md guides behavior, hooks and permissions block it.
Do not keep stale commands; a wrong command is worse than a missing one, because Claude will run it.
Do not add rules for behavior Claude already gets right; each extra rule dilutes the ones that matter.
Do not skip the contradiction check in a monorepo; ancestor CLAUDE.md files load too, and claudeMdExcludes can skip the irrelevant ones.

FAQ

How often should I audit my CLAUDE.md?: Audit after any workflow change — a new test runner, deploy target, or directory move — and whenever the agent repeats the same mistake. Quarterly pruning keeps stale rules from accumulating.
What is the single highest-value line in a CLAUDE.md?: The exact test command with its flags and runner named. It is used constantly, Claude cannot always infer it from package.json alone, and getting it wrong wastes a full loop every session.
Should every rule have an enforcement mechanism?: Rules that must never be violated should. Back those with a PreToolUse hook, a CI check, or a lint rule, and treat the rest of the file as advisory guidance that shapes behavior without guaranteeing it.
Does /init produce a good CLAUDE.md?: It produces a starting point from what Claude discovers in the codebase. Refine from there by adding what Claude could not discover — conventions, anti-patterns, and rationale — and cutting the parts it can simply read from the code.

Related CLAUDE.md guides

Review CLAUDE.md for Token Waste

Find vague, repeated, or unused CLAUDE.md instructions that cost tokens every Claude Code turn without improving behavior.

CLAUDE.md Missing Commands Checklist

Check whether a CLAUDE.md includes the build, test, lint, dev server, deploy, and verification commands an agent needs before editing.

CLAUDE.md Repo Boundaries and Rules

Write CLAUDE.md rules that tell agents which files to edit, which files to avoid, and how to handle dirty worktrees safely.

Review CLAUDE.md Before Converting to AGENTS.md

Clean a CLAUDE.md first, then convert it into AGENTS.md, Cursor rules, GitHub Copilot instructions, or Windsurf rules.

What Should Go in a CLAUDE.md File

Decide what belongs in CLAUDE.md and what belongs in the README, a path-scoped rule, or a skill. One test per line, applied to a real file.

Claude Code Is Not Following CLAUDE.md — How to Fix It

Diagnose why Claude Code ignores your CLAUDE.md: the file never loaded, the rule is vague, two files contradict, or the rule needs a hook instead.

CLAUDE.md vs .claude/rules vs Skills — Which File Owns What

Route each instruction to the right file: always-loaded CLAUDE.md, path-scoped .claude/rules/, or on-demand skills. One question decides it.

Desk gear for long writing sessions

A few things that help if you write docs, tickets, and specs on a laptop all day.

Dock

Anker 5-in-1 USB-C Hub

One cable turns a laptop into a desk setup. Drives a 4K display, charges at up to 85W, and adds three data ports.

4K HDMI output
85W max power delivery
1x USB-C + 2x USB-A, 5Gbps each
MacBook Pro, MacBook Air, Dell

Check price on Amazon →Monitor · I use this

Dell 27" S2725QC 4K

The monitor I write and review documents on. 163 PPI keeps small text sharp, and USB-C carries video and power on one cable.

3840x2160 IPS, 163 PPI
120Hz, 4ms, FreeSync Premium
99% sRGB
USB-C, HDMI, DisplayPort

Check price on Amazon →Laptop

Apple MacBook Neo 13" (A18 Pro)

The cheapest way into an Apple-silicon machine that runs local models. Fanless, and the Liquid Retina panel holds small text at a full day of reading.

A18 Pro chip, built for Apple Intelligence
8GB unified memory, 256GB SSD
13-inch Liquid Retina display
1080p FaceTime HD camera

Check price on Amazon →

Amazon affiliate links. We earn a commission on qualifying purchases at no extra cost to you.