What is a CLAUDE.md file?

CLAUDE.md is Claude Code's project memory file. It's loaded into context at the start of every session, so it's where you put build/test commands, architecture notes, code-style pointers, and repo-specific rules Claude can't infer from the code.

What makes a good CLAUDE.md?

Short and specific. Every line costs context tokens on every single session, so the best files are under ~100 lines, use concrete commands instead of vague guidance, link out to deeper docs instead of inlining them, and never restate rules a linter or formatter already enforces.

How is the score calculated?

100 points across six categories: size and token budget, specificity, progressive disclosure, structure, content essentials (commands, architecture), and anti-patterns like linter duplication, shouting, and vague filler. Each finding shows the exact deduction and the fix.

Is my CLAUDE.md uploaded when I grade it?

No. The grader runs entirely client-side in your browser. Nothing you paste is sent to a server, logged, or stored.

Why shouldn't CLAUDE.md repeat my linter rules?

Prose rules like 'use 2-space indentation' or 'no semicolons' waste tokens and are less reliable than tooling — Claude Code sees your linter/formatter output directly. Keep mechanical style in ESLint/Prettier/Ruff configs and use CLAUDE.md for what tools can't check.

CLAUDE.md Grader — Free Score & Linter for Your Claude Code Config

The rubric

Six categories, 100 points

The score rewards what actually changes Claude's behavior per token spent — and penalizes the patterns that quietly make Claude Code worse.

📏

Size & token budget

CLAUDE.md is prepended to every session. Under ~120 lines is lean; 500+ lines means degraded instruction-following and a permanent context tax.

🎯

Specificity

Vague filler ('best practices', 'properly', 'robust') is scored down hard — every rule should be concrete enough that you could check compliance.

🪜

Progressive disclosure

Big files should link out (@docs/architecture.md) instead of inlining. Claude reads linked docs only when the task needs them.

🤖

Linter duplication

Indentation, quotes, semicolons, import order — if a formatter can enforce it, prose shouldn't. Those lines cost tokens and get ignored anyway.

🧱

Structure & essentials

Headings and bullets beat prose walls. Exact build/test commands and a repo-layout note are the highest-value lines you can write.

🚫

Anti-patterns

IMPORTANT/NEVER/ALWAYS spam, role-play preambles, and anything that looks like a committed secret.

CLAUDE.md best practices

What an A-grade CLAUDE.md looks like

Think of it as the onboarding doc you'd give a brilliant engineer who rejoins your team every morning with no memory of yesterday.

▹

Commands first

The ## Commands section pays for itself instantly: dev server, test runner, lint, build — with exact flags. Without it, Claude runs npm test in a pnpm repo and burns a turn.

▹

Rules Claude can't infer

Don't describe what the code already shows. Do write the invariants that live in your team's heads: 'DB access only through lib/db.ts', 'never edit generated/ files'.

▹

Link, don't inline

Reference deeper docs with @docs/architecture.md or markdown links. The file stays under budget and the detail is still one hop away when a task needs it.

▹

Prune it monthly

CLAUDE.md rots like any doc. When Claude keeps doing something wrong, add one precise rule; when a rule stops mattering, delete it. The grader is a fast pruning loop.

FAQ

CLAUDE.md questions

Where does CLAUDE.md live?+

At the repo root (checked in, shared with your team). Claude Code also reads ~/.claude/CLAUDE.md for personal global preferences and CLAUDE.local.md for personal per-repo notes. Subdirectory CLAUDE.md files load when Claude works in that directory.

How long should a CLAUDE.md be?+

As short as it can be while covering commands, layout, and your non-obvious rules. Under ~120 lines (roughly 1,500 tokens) is a good budget — remember it's paid on every session, forever.

Should I generate my CLAUDE.md with /init?+

/init is a fine starting point — it scans the repo and drafts one. But generated files trend long and generic. Run the draft through this grader, cut what the code already says, and keep the rules only your team knows.

What's the difference between CLAUDE.md and a system prompt?+

CLAUDE.md is project memory layered on top of Claude Code's own system prompt. It shouldn't define a persona ('you are an expert engineer') — it should carry project facts and rules the model can't infer.

Is my file uploaded when I grade it?+

No. The grader is pure client-side JavaScript — nothing you paste leaves your browser, and you can use it offline once the page loads.

My score is low but Claude works fine — does it matter?+

The score measures efficiency and reliability headroom. A bloated or vague file often 'works' until a long session, where the context tax and buried rules start causing missed instructions. Trimming is cheap insurance.

Go further

Want the configs already done right?

The ClaudeThings kits ship production-grade agents, skills, and commands — written to the same bar this grader enforces, so your whole Claude Code setup starts at an A.

🛠️

Engineering Kit

Battle-tested Claude skills & workflows for builders.

✓ 58 agents · 61 skills · 159 commands
✓ Security, testing & code-review skills
✓ Every skill formatted to spec
✓ Lifetime updates

Get the Engineering Kit

📣

For founders

Marketing Kit

Turn Claude into your growth team.

✓ 31 agents · 42 skills · 32 commands
✓ Content, SEO & email-sequence skills
✓ Landing-page & funnel templates
✓ Lifetime updates

Get the Marketing Kit

Or grab all 89 agents, 103 skills & 181 commands in the Complete Bundle →