CLAUDE.md Grader

How to use it

Paste the contents of your CLAUDE.md into the box. The grader scores it out of 100 as you type, shows roughly how many tokens it costs, and lists what to fix with line numbers. Everything runs in your browser. Your text is never sent to a server.

Why it matters: Claude Code reads CLAUDE.md at the start of every session, so each line is paid for again on every request. A short file full of specific, checkable rules works better than a long one full of good intentions.

What we check

The score is the sum of seven categories. Each one is explained so you can decide whether you agree.

• Length and token budget (20 points). Full marks under about 2,000 tokens. Points fade out up to 4,000 and again up to 8,000, and a file over 8,000 tokens loses almost everything here.
• Essentials present (25 points). A project overview near the top (6), a build or run command (3), a test command (3), a lint or typecheck command (2), a conventions section (5) and an architecture or key directories section (6). We look for headings and keywords, and for commands inside code blocks or backticks.
• Specific, not vague (15 points). Each vague phrase costs 3 points. We flag wording such as "write clean code", "follow best practices", "be careful", "make sure to", "as needed", "where appropriate", "good code", "properly", "high quality", "industry standard" and "try to", and suggest how to make the rule concrete.
• Leaves formatting to tools (10 points). Rules about indentation, semicolons, quote style, trailing commas, line length and import order are better enforced by Prettier, ESLint, Black or Ruff. Each one costs 3 points.
• Progressive disclosure (5 points). If the file is long and holds big reference sections, we suggest moving detail into separate docs and pulling them in with @path/to/file imports or links. Files that already do this, or are short, get full marks.
• Emphasis used sparingly (5 points). More than three words in capitals such as MUST, NEVER, ALWAYS, IMPORTANT or CRITICAL lose points, because emphasis only works when it is rare.
• Hygiene and safety (20 points). Possible secrets such as keys starting with sk-, ghp_, whsec_ or AKIA (a strong error), unfilled placeholders such as <your project>, TODO, TBD or empty template fields, absolute paths that only work on one machine, duplicate lines, very long lines, and a file with no headings at all.

Grades: 90 and above is Excellent, 75 and above is Good, 50 and above is Needs work, and anything lower is Poor.

FAQ

Where does CLAUDE.md go?

Put it in the root of your project so it is shared with your team, or in your home .claude folder for personal rules that apply to every project. Claude Code loads it at the start of each session.

How long should a CLAUDE.md be?

As short as you can make it while still covering how to build, test and navigate the project. Under 2,000 tokens is a good target. If you need more, move the extra detail into other files and import them with @path/to/file.

Is my CLAUDE.md uploaded anywhere?

No. The grader is plain JavaScript running in your browser tab. There are no network calls, and nothing is stored.

Why does it complain about formatting rules?

A formatter enforces style every time, for free. A sentence in CLAUDE.md costs tokens on every request and can still be ignored. Add the format command to your Commands section and let the tool do the work.

Is a score of 100 the goal?

No. Use the score to spot problems, then apply judgment. A rule that looks vague to a checker may be clear to your team.

Want your whole workflow tuned, not just one file? Agentsforce ships 38 ready-made specialists for Claude Code. This grader is not affiliated with Anthropic.