CLAUDE.md linter: check your file against Claude Code best practices

Published 2026-11-11 · Last updated 2026-11-11 · Docs checked 2026-11-11

CLAUDE.md best practices, from Anthropic's Claude Code docs: keep each file under 200 lines, write instructions Claude can verify, remove rules that contradict each other, keep keys out, and move rules with zero exceptions into hooks. Paste yours below.

Lint your CLAUDE.md

Runs in your browser. Nothing you paste or drop is uploaded or stored. No AI model reads it.

Paste a CLAUDE.md, CLAUDE.local.md, AGENTS.md or rules file, or drop the file here

Choose file

Results show here as soon as there is something to check.

A CLAUDE.md template from Anthropic's docs

This is the example on Anthropic's best practices page. It passes every check here. Each line is something Claude could not work out from the code: the exact commands, which helper to use, a directory that looks dead but is not, and a setup trap.

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

The page lists what belongs in the file: how to confirm work (test, typecheck and lint commands), places where the code is misleading, decisions that are not in the repo, and anything you have had to correct twice.

CLAUDE.md best practices, with the source for each

Stay under 200 lines per file. Longer files "consume more context and reduce adherence" (memory docs).
Make each line checkable: "Run npm test before committing" instead of "Test your changes" (memory docs).
Remove contradictions. If two instructions conflict, "Claude may pick one arbitrarily" (memory docs).
Put rules for one part of the code in .claude/rules/ with a paths: filter, and procedures in skills (best practices).
Move rules that can never bend into a hook, a deny rule or a managed setting. "CLAUDE.md is for guidelines" (best practices).
Drop IMPORTANT, ALL CAPS, "think hard" and "don't be lazy". The docs list them under what you can stop doing.
Keep personal notes in CLAUDE.local.md and add it to .gitignore (memory docs).

Rules this linter checks

15 rules: 2 problems, 7 warnings and 6 tips. A problem means Claude will not load the file or the file leaks something. A warning goes against a line in the docs. A tip is worth a look but can be right for your project.

Rule	What the docs say	Level
File is 4 MiB or smaller	"Claude Code skips a file over 4 MiB." Memory: My CLAUDE.md is too large	problem
No API keys, tokens or passwords	"Project instructions (./CLAUDE.md or ./.claude/CLAUDE.md) are team-shared instructions, shared with team members via source control." Memory: Choose where to put CLAUDE.md files	problem
Under 200 lines	"Target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Memory: Write effective instructions	warning
Under 40,000 characters if it loads on demand	"When a subdirectory CLAUDE.md or a rules file that loads on demand is over a per-file size limit, Claude receives only the start of it. 200K context window: 40,000 characters." Memory: Claude ignores the end of my subdirectory CLAUDE.md	warning
Instructions are concrete enough to verify	"Write instructions that are concrete enough to verify: "Use 2-space indentation" instead of "Format code properly"." Memory: Write effective instructions	warning
No instructions that contradict each other	"If two instructions contradict each other, Claude may pick one arbitrarily." Memory: Write effective instructions	warning
No repeated lines	"Every line in it takes a little of Claude's attention on every task, whether it's relevant or not." Best practices: Keep CLAUDE.md short	warning
@imports are not wrapped in quotes	"A path wrapped in quotes isn't imported at all, with or without the backslashes." Memory: Import additional files	warning
Grouped under headings, no dense paragraphs	"Group related instructions under markdown headers and bullets. Organized sections are easier for Claude to follow than dense paragraphs." Memory: Write effective instructions	warning
@imports stay inside the project	"Imported files are expanded and loaded into context alongside the CLAUDE.md that references them. ... An import in a project-level memory file is external when its path resolves outside your working directory." Memory: Import additional files	tip
No IMPORTANT or ALL CAPS emphasis	"Current ones follow a plainly worded line, and piling on emphasis mostly makes Claude over-apply the rule." Best practices: What you can stop doing	tip
Zero-exception rules belong in hooks	"If something has to happen every time, make it a hook, a deny rule, or a managed setting. CLAUDE.md is for guidelines." Best practices: Enforce the rules that can't have exceptions	tip
No file trees or architecture Claude can read from the repo	"Describe your architecture and file layout in CLAUDE.md: Claude reads the repo itself. Only write down what isn't in there." Best practices: What you can stop doing	tip
No prompt habits written for older models	""think hard", "be thorough" ... Effort is the control for that. "Tell Claude to keep going, loop until done, don't be lazy": lines like that are more likely to cause over-work than fix a stall." Best practices: What you can stop doing	tip
AGENTS.md is imported, not mentioned in words	"A CLAUDE.md that tells Claude in words to read AGENTS.md: Claude sees AGENTS.md only if it decides to open the file. ... replace the sentence with an @AGENTS.md import." Memory: Remove an earlier AGENTS.md workaround	tip

How it works

It splits the file into lines and marks fenced code blocks, inline code and block-level HTML comments. Claude Code strips those comments before Claude reads the file, and it does not treat @ inside code as an import, so most rules skip them too.
It counts lines, characters (Unicode code points, like wc -m) and UTF-8 bytes for the size rules.
The secret check scans every line, code blocks included, for known key formats (Anthropic, OpenAI, GitHub, AWS, Slack, Google, Stripe, private keys) and for key = value pairs. Matches are masked in the results.
The text rules use fixed word lists. Vague phrases come from the docs' own examples ("Format code properly", "Test your changes"). Conflicts are pairs such as two package managers, two indent sizes, or the same phrase after "always" on one line and "never" on another.
@path imports are found the way the docs describe: outside code spans, and a quoted path is flagged because Claude Code does not import it.

Every rule quotes a line from How Claude remembers your project or Best practices for Claude Code, both read on 2026-11-11.

What it does not check

Stale paths and commands. The linter cannot see your repo. Run /doctor prompt-audit in Claude Code for that.
Whether imported files exist, or the four-hop limit on nested imports.
Whether a rule is right for your project. The heuristics flag phrases, not meaning, so read each finding before you act on it.
Conflicts across files, such as your user CLAUDE.md against the project one. Paste them together to check.

FAQ

What are the CLAUDE.md best practices?

Anthropic's memory docs and best practices page boil down to this: keep each file under 200 lines, write instructions concrete enough to verify, group them under headings, remove contradictions, and only write down what Claude cannot work out from the code. Rules that must hold every time go in hooks or permission rules, not in CLAUDE.md.

How long should a CLAUDE.md be?

Under 200 lines. The docs say longer files "consume more context and reduce adherence" (Write effective instructions). Claude Code shows a warning at startup when a file is over the recommended length, and skips a file over 4 MiB entirely (My CLAUDE.md is too large).

Is there a CLAUDE.md template?

Anthropic's best practices page has a short example with three sections: Commands, Conventions and Gotchas. It is reproduced below under "A CLAUDE.md template from Anthropic's docs". You can also run /init in Claude Code to generate a first version from your codebase, then delete what you do not need.

What should not go in CLAUDE.md?

File trees and architecture overviews Claude can read from the repo, multi-step procedures (put those in a skill), rules for one part of the code (put those in .claude/rules/ with a paths: filter), personal preferences (put those in CLAUDE.local.md and gitignore it), and anything secret, since a project CLAUDE.md is shared through source control.

Do @imports make CLAUDE.md shorter for Claude?

No. The docs say imports "help you organize a long file but don't reduce its context cost, because imported files load together with the CLAUDE.md that imports them" (Write effective instructions). To load instructions only when they matter, use path-scoped rules.

Does Claude Code read AGENTS.md?

Yes, from v2.1.277 on. By default it reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it (AGENTS.md). To keep both, put @AGENTS.md at the top of your CLAUDE.md. A sentence asking Claude to read AGENTS.md is not the same thing: Claude sees the file only if it decides to open it.

Is this the same as /doctor prompt-audit?

No. /doctor prompt-audit runs inside Claude Code (v2.1.283 or later), uses Claude to read your files and can check paths and commands against your real repo (Audit your instruction files). This linter runs fixed text rules in a web page, needs no install and sees only the text you paste. Use this one for a quick check, the audit for stale paths.

Is my CLAUDE.md uploaded anywhere?

No. The rules run in JavaScript in your browser. There is no backend, no API key and no model call. A dropped file is read locally with the browser's File API.

Sources

All checked 2026-11-11.

How Claude remembers your project (Claude Code docs): https://code.claude.com/docs/en/memory
Best practices for Claude Code: https://code.claude.com/docs/en/best-practices
Skills (Claude Code docs): https://code.claude.com/docs/en/skills