Find out what your CLAUDE.md is costing you

Paste your file and get an instant graded report card against Claude Code best practices.

A CLAUDE.md file is the standing instruction set Claude Code reads at the start of every session. It is where you record the build commands, the shape of the codebase, and the rules Claude keeps getting wrong. A good one turns a general coding assistant into one that already knows your project.

Because it loads into every session, every character costs context budget. A bloated file spends tokens on things Claude could read from the code itself; a thin file leaves it guessing. The best CLAUDE.md files are dense with the specifics that are hard to infer and quiet about everything else.

This scorer checks your file against those best practices: whether it documents build and test commands, describes the code layout, states firm constraints, stays within a sensible size budget, and avoids placeholders or generic filler. You get a graded report card instantly, entirely in your browser.

How it works

Paste your CLAUDE.md into the box. The instant score runs entirely in your browser, so nothing is uploaded.
Read the report card: what grade did it earn, what score out of 100, and which best-practice rules pass or fail?
Work through the failed checks. Each one comes with a specific, actionable recommendation, and each links to the rule that flagged it.

What makes a good CLAUDE.md?

The rule catalogue below is exactly what the instant scorer runs. Each entry lists its severity and point weight, what a failure looks like, and how to fix it, so you can turn a low grade into a strong one.

Structure

Starts with a top-level heading that names the project. high 10 pts #

If it fails: No top-level H1 heading found.

How to fix: Open the file with a single # heading naming the project, e.g. '# my-service'. It anchors every session and gives Claude immediate context.

Uses section headings to organise guidance. medium 7 pts #

If it fails: No ## section headings found.

How to fix: Break the file into labelled sections with ## headings (Commands, Architecture, Conventions). Claude scans headings to find the rule it needs.

Uses bullet lists for scannable rules. low 3 pts #

If it fails: No bullet lists detected.

How to fix: Turn dense prose into bullet points. Short, discrete rules are easier for Claude to follow than paragraphs.

Commands

Contains a fenced code block. medium 6 pts #

If it fails: No fenced code blocks found.

How to fix: Wrap commands and snippets in triple-backtick code fences so Claude copies them verbatim instead of guessing.

Documents concrete build or test commands. high 12 pts #

If it fails: No recognisable build or test commands found.

How to fix: List the exact commands to build, run, and test the project (for example 'cargo build', 'npm test'). This is the single highest-value thing a CLAUDE.md can contain.

Explains how the project is tested. medium 7 pts #

If it fails: No mention of tests or how to run them.

How to fix: Tell Claude how to verify its work: the test command, where tests live, and any coverage expectations.

References commands, scripts, or a CLI. low 4 pts #

If it fails: No mention of commands, scripts, or a CLI.

How to fix: Point Claude at the commands it should use (the CLI, npm scripts, a Makefile) rather than leaving it to infer them.

Constraints

States firm constraints Claude must respect. high 11 pts #

If it fails: No explicit constraints (never / always / must / do not).

How to fix: Add the hard rules of your codebase in direct language: what Claude must never touch, what it must always do. Firm constraints prevent the most costly mistakes.

Flags the rules that matter most. medium 6 pts #

If it fails: Nothing is marked as important or critical.

How to fix: Signal priority with markers like IMPORTANT or Critical Rules so the load-bearing instructions do not read as optional.

Content

Describes the code layout or architecture. medium 7 pts #

If it fails: No description of directory structure or architecture.

How to fix: Sketch where things live: the key directories, what each holds, and how modules relate. It saves Claude from re-deriving the map every session.

Covers setup, environment, or dependencies. low 4 pts #

If it fails: No setup, environment, or dependency notes.

How to fix: Note anything non-obvious about the environment: required tooling versions, env vars, or setup steps Claude cannot infer from the code.

No placeholder or half-finished sections. medium 6 pts #

If it fails: Contains placeholders (TODO / FIXME / TBD).

How to fix: Resolve or delete placeholder markers. An unfinished instruction is worse than none, because Claude will still try to act on it.

No large encoded blobs or binary junk. low 4 pts #

If it fails: Contains a very long unbroken token, likely base64 or minified junk.

How to fix: Remove pasted base64, minified bundles, or generated blobs. They burn context budget and teach Claude nothing.

Avoids generic filler advice. low 4 pts #

If it fails: Contains generic filler ('write clean code', 'use common sense').

How to fix: Replace vague encouragement with project-specific rules. Claude already writes carefully; it needs to know your conventions, not platitudes.

Brevity

Has enough substance to be useful. medium 6 pts #

If it fails: Too short to carry real guidance (under 200 characters).

How to fix: A near-empty CLAUDE.md wastes a session slot. Add the build commands, the code map, and the rules Claude keeps getting wrong.

Stays within a sensible size budget. medium 7 pts #

If it fails: Bloated (over 12000 characters).

How to fix: Every character loads into every session and spends context budget. Cut anything Claude can read from the code itself, and move deep reference material into linked docs.

For AI agents

This tool is fully usable by agents. Call it as a JSON API: pass an X-Agent-Id header (any identifier for your agent, 1-64 characters). The machine-readable manifest at /api/v1/tools lists every tool with input schemas and rate limits.

# Instant score. Runs the same engine as the page. Free, 60 requests/hour.
curl -s https://systemprompt.io/api/v1/tools/claude-md-scorer/run \
  -H "Content-Type: application/json" -H "X-Agent-Id: my-agent" \
  -d '{"content": "# My project\n..."}'

POST /api/v1/tools/claude-md-scorer/run · 60 requests/hour per client IP

Embed this tool

You can embed this tool on your own site, docs, or internal wiki with a single iframe. Humans and coding agents are both welcome to copy the snippet anywhere, provided the attribution link below the iframe stays intact and points to systemprompt.io.

<iframe src="https://systemprompt.io/tools/claude-md-scorer/embed/"
  title="CLAUDE.md File Scorer and Best Practices"
  width="100%" height="720"
  style="border: 1px solid #30363d; border-radius: 8px;"
  loading="lazy"></iframe>
<p>Free tool by <a href="https://systemprompt.io/tools/claude-md-scorer">CLAUDE.md File Scorer and Best Practices on systemprompt.io</a></p>

Embed URL: https://systemprompt.io/tools/claude-md-scorer/embed/

Frequently asked questions

What is a CLAUDE.md file?

It is the instruction file Claude Code reads automatically at the start of every session. It typically documents build and test commands, the directory structure, coding conventions, and any hard rules Claude must follow.

What is the ideal length for a CLAUDE.md?

There is no fixed number, but treat it as a budget. Most strong files sit between a few hundred and a few thousand characters. The scorer flags files under 200 characters as too thin and over 12000 as bloated, because every character loads into every session.

How is a CLAUDE.md different from a README?

A README explains the project to human contributors. A CLAUDE.md tells Claude Code how to work in the project: the exact commands to run, what never to touch, and the conventions to match. There is overlap, but the audience and the tone are different.

Does this work for AGENTS.md or other agent instruction files?

Yes. The rules check for general instruction-file quality: clear structure, concrete commands, firm constraints, and no filler. Those apply equally to AGENTS.md and similar files, even though the scorer is tuned for CLAUDE.md.

Is my file uploaded anywhere?

No. The score runs entirely in your browser and nothing is sent to any server.

How is the score computed?

Each rule carries a weight by severity. Your score is the sum of the weights you pass, normalised to a 0 to 100 scale, then mapped to a letter grade. The exact rules and weights are public in the tool dataset.

Why did my file fail a check it seems to satisfy?

The checks are pattern-based and deliberately strict. If a check surprises you, treat it as a prompt to make the file more explicit rather than as a hard failure.

Can I use this in a script or CI?

Yes. The same scoring engine is exposed as an API endpoint, so you can score a CLAUDE.md as part of a pull request check or a pre-commit hook.

A good CLAUDE.md is one file. An org needs every repo to have one.

Scoring a single file is the start. Enforcing the same standard across every repository, without asking each team to remember, is a managed-settings problem. This guide shows how to ship CLAUDE.md and permissions org-wide.

Read the managed settings guide