Claude Code reads CLAUDE.md at the start of every session. A good one is short, specific and names the project’s real commands and folders. Paste yours to see what to fix.
The quick check catches the mechanical problems — vague rules, missing commands, secrets, personal paths, an AGENTS.md that never loads. Below the checker, four annotated examples show each one next to its fix.
1 lines · 0 words · 0.0 KB. The quick check runs right in your browser.
Quick check
Paste your file on the left — notes appear right away.
Review of the meaning
An AI model rates specificity, anchors, staleness, bloat, contradictions and security. The text goes to the model only for the review and is not stored anywhere.
Before and after
Four files with the problems the quick check catches most often, each next to a fixed version. Load either one into the checker above and watch the notes appear and disappear.
Rules Claude cannot check
Every line sounds right and none of them can be verified, and there is not one command in the file.
Before
# My app
Write clean code and follow best practices.
Be careful with the database.
Keep things organized where possible.
The quick check says
Important: No build or test commands
Important: Vague rule
After
# My app
## Commands
- Install: `npm install`
- Tests: `npm test` — must pass before you commit
- Lint: `npm run lint`
## Rules
- API handlers live in `src/api/handlers/`
- Do not edit files in `db/migrations/`; add a new migration instead
Fixed: “Clean code” became a command that has to pass: Claude can run npm test and see the answer.
Fixed: “Be careful with the database” became the one thing that actually goes wrong: editing an old migration.
Fixed: “Organized” became a folder name, which Claude can follow without guessing what you meant.
A file with your laptop in it
CLAUDE.md is usually committed, so a password and a path from your machine end up in everyone's repository.
Before
# Shop
- Tests: pnpm test
- Local DB password: changeme-local-42
- My notes on the checkout flow: /Users/sam/notes/checkout.md
The quick check says
Stop: Looks like a secret: a password or token
Important: Personal path
After
# Shop
- Tests: `pnpm test`
- Local database settings come from `.env.local`, which is not committed
- Checkout flow notes: @docs/checkout.md
Fixed: The password left the file entirely. Claude only needs to know where settings come from, not what they are.
Fixed: The notes moved into the repository and are imported with @docs/checkout.md, so they load for everyone, from a path that exists on every machine.
Fixed: Personal notes that should stay personal belong in CLAUDE.local.md, which you do not commit.
AGENTS.md named, never loaded
The team's rules live in AGENTS.md for other agents too. This CLAUDE.md points at it in words — and because a CLAUDE.md exists, Claude Code does not read AGENTS.md on its own.
Before
# Project
The team's rules are in AGENTS.md, read it first.
- Use plan mode for changes under `src/billing/`
The quick check says
Important: No build or test commands
Tip: AGENTS.md won’t be read on its own
After
@AGENTS.md
## Claude Code
- Use plan mode for changes under `src/billing/`
AGENTS.md, next to it
# Agent instructions
- Install: `npm install`
- Tests: `npm test`
- Do not edit `db/migrations/`; add a new migration instead
Fixed: @AGENTS.md on the first line imports the shared file, so Claude reads it first and the Claude-only line after it.
Fixed: The commands stay in AGENTS.md, where Codex, Cursor and the rest read them too — one copy, not two that drift apart.
Fixed: If you have no Claude-only lines at all, you can delete CLAUDE.md: with none in the project, Claude Code reads AGENTS.md directly.
Shouting instead of enforcing
Capitals do not make a rule binding. CLAUDE.md is context Claude weighs, so a rule that must hold every time needs something that enforces it.
Before
# API
- Tests: npm test
- NEVER push to main.
- NEVER commit .env files.
- ALWAYS run the linter. IMPORTANT: this is a MUST.
The quick check says
Tip: A lot of shouting: ALWAYS / NEVER 5 times
After
# API
- Tests: `npm test`; lint: `npm run lint` — both must pass before a commit
- Work on a branch and open a pull request; nobody pushes to main
- `.env` is listed in `.gitignore`, so `git add` skips it
Fixed: The linter rule became a command with a condition, which is checkable, instead of a volume level.
Fixed: The .env rule moved out of the prose and into .gitignore: git refuses to stage an ignored file unless someone forces it with -f, whether or not the model remembers the line. The CLAUDE.md line only says where the guard lives.
Fixed: With the shouting gone, the remaining rules read as equally important — which they are.