How to score your CLAUDE.md file (and why most configs rate below 5 out of 10)

You wrote a CLAUDE.md file. You put your project name in it, maybe a description of your tech stack, possibly a list of commands. Then you started a Claude Code session and it still ignored your conventions, ran the wrong test command, and created files in the wrong directory.

The file exists. It just does not work the way you expected.

After analyzing hundreds of CLAUDE.md files, a pattern emerged. Most files score between 3 and 5 out of 10 on a structured evaluation. They cover the basics but miss the sections that actually change Claude's behavior. The gap between a 4 and an 8 is not more words; it is the right categories.

The five categories that matter

A CLAUDE.md file does five jobs. Most files only do one or two of them.

1. Structure (where things live)

This is the most impactful section and the one most files get wrong. Without explicit file structure guidance, Claude reads directory listings and makes guesses. With it, Claude goes directly where you tell it.

# File Structure
- src/routes/ — API endpoints (one file per resource)
- src/models/ — Database models (Prisma schema in prisma/)
- src/middleware/ — Express middleware (auth, logging, validation)
- tests/ — Mirrors src/ structure. Every route has a test file.
- scripts/ — One-off scripts. Not imported by the application.

If your CLAUDE.md does not have a section like this, Claude will create files in the wrong place roughly half the time. The more complex your project, the more this matters.

2. Architecture guidance (how things connect)

Structure tells Claude where files go. Architecture tells Claude how they relate. This is the difference between "put routes in src/routes/" and "every route uses the controller pattern: route calls controller, controller calls service, service calls model."

# Architecture
- Routes are thin: validation + controller call only
- Controllers handle request/response shaping
- Services contain business logic (never import Express)
- Models are Prisma-generated, do not edit manually
- Shared types live in src/types/ and are imported by both frontend and API

Without this, Claude generates working code that does not match your patterns. It puts business logic in route handlers, mixes concerns, and creates one-off patterns that diverge from the rest of your codebase.

3. Coding conventions (how code looks)

This covers naming, formatting, and patterns. Claude has strong defaults from training data, but your project has its own rules. The most common missed conventions:

• Naming patterns (camelCase vs snake_case, file naming)
• Import ordering (built-in, external, internal)
• Error handling patterns (custom error classes, error boundaries)
• Component patterns (functional only, no default exports, props interface naming)

# Conventions
- TypeScript strict mode. No `any` types.
- Functions: camelCase. Components: PascalCase. Files: kebab-case.
- Prefer named exports. Default exports only for pages.
- Error handling: throw AppError subclasses, never raw Error.
- No console.log in production code. Use the logger from src/lib/logger.ts.

4. Testing setup (what to run and how)

This is the category most files skip entirely, and it causes the most wasted time. Without testing instructions, Claude either skips tests, runs the wrong command, or writes tests in the wrong style.

# Testing
- Framework: Vitest
- Run all: `npm test`
- Run single: `npx vitest run tests/routes/users.test.ts`
- Every new route needs a test file in tests/routes/
- Use `describe` blocks per endpoint, `it` blocks per scenario
- Mock external services with msw, never mock internal modules

The specific command matters more than you think. "npm test" vs "npx jest" vs "pytest" vs "go test ./..." — Claude does not know which one your project uses unless you tell it.

5. Guardrails (what to never do)

Guardrails prevent the kind of mistakes that waste 30 minutes to undo. They tell Claude what is off-limits, what needs confirmation, and what automated behavior to avoid.

# Guardrails
- Never delete files with rm. Move to .trash/ instead.
- Never force-push to main.
- Never modify database migrations after they have been applied.
- Do not add dependencies without asking first.
- Do not change the CI/CD pipeline without confirmation.

Without guardrails, Claude acts on its best judgment. That judgment is usually fine, but the 5% of cases where it is not can cost you a dropped database table or a force-pushed branch.

How scoring works

Each category contributes up to 2 points, for a total of 10. The scoring checks for:

• Structure (0-2): Does the file tell Claude where key directories and files live?
• Architecture (0-2): Are there patterns, layers, or relationships described?
• Conventions (0-2): Does it specify naming, formatting, or coding style rules?
• Testing (0-2): Is there a test framework, test command, and testing expectations?
• Guardrails (0-2): Are there explicit restrictions on what Claude should not do?

A file that says "This is a React project using TypeScript and Tailwind" scores about 1. It has some structure context but nothing actionable. A file with all five categories filled in with specific, concrete rules scores 8-10.

The most common mistakes

Too much description, not enough instruction

"This project is a web application for managing inventory" is a description. Claude reads it, acknowledges it, and still does not know where to put a new component. Replace descriptions with directives: "New components go in src/components/. Use the existing Button.tsx as a template for props interfaces."

Missing the test command

If Claude does not know how to run tests, it either skips them or guesses. "Run tests with npm test" takes five seconds to write and saves minutes every session.

No guardrails at all

Guardrails are not about restricting Claude. They are about encoding the lessons you already learned. Every project has things that should not be touched, commands that should not run, and patterns that should not be broken. Write them down.

Copy-pasting a README

Your README explains the project to new developers. Your CLAUDE.md explains the project to an AI coding agent. The audiences are different. A README has installation steps, feature lists, and screenshots. A CLAUDE.md has file paths, conventions, and working commands.

From a 3 to an 8: a practical upgrade path

If your CLAUDE.md currently scores low, do not rewrite it from scratch. Add one section at a time:

1. Add a file structure section. List your top-level directories and what goes in each one. This alone can take you from 1 to 3.
2. Add your test command. Just the framework name and the command to run tests. Two lines, 2 points.
3. Add 3-5 coding conventions. Pick the rules you find yourself correcting most often. Those are the ones Claude also gets wrong.
4. Add 3-5 guardrails. Think about the last time Claude did something you had to undo. Write that down as a "never do this" rule.
5. Add architecture notes. Describe how your layers connect, what calls what, where business logic lives.

Each step takes a few minutes and measurably improves your sessions.

Score your own file

The ContextKit Analyzer scores your CLAUDE.md across all five categories and gives specific suggestions for what to add. Paste your file, get a score, and see exactly which sections are missing.

It runs entirely in your browser. Nothing is uploaded, nothing is stored. You get a score you can share (it generates a URL with your results) and a concrete list of improvements.

If you do not have a CLAUDE.md yet, the ContextKit Generator builds one from scratch. Pick your stack, answer five questions, and export a production-ready config file.

Between the two tools, there is no reason to start from a blank file or stay at a score of 3. The improvements are specific, the process takes minutes, and the difference in your daily Claude Code sessions is immediate.