CLAUDE.md Completeness Grader

Grade any CLAUDE.md file on completeness. Letter grade A-F + missing-sections checklist + concrete suggestions. Stop shipping anemic project guides to your Claude Code agent.

What does CLAUDE.md Completeness Grader do?

Claude Code reads CLAUDE.md at the project root on every session and uses it as persistent project context. An empty or weak CLAUDE.md is the #1 cause of "Claude doesn't understand my codebase". This Actor scores yours on a 10-dimension rubric covering: project overview, tech stack, build/run/test commands, project structure, conventions, what NOT to do, security, testing, workflow, and agents/skills usage.

Paste raw markdown OR point it at a public GitHub repo (owner/name). The Actor returns a letter grade (A-F), a 0-100 score, the list of missing sections, and a concrete suggestion for each.

Why use CLAUDE.md Completeness Grader?

• Before onboarding Claude Code: catch missing context before the agent starts hallucinating
• Reviewing teammates' CLAUDE.md PRs: get an objective grade
• Auditing OSS repos for AI-readiness: pair with gh-repo-ai-readiness-score for a fuller picture
• Building your own project template: iterate until you hit A

How to use CLAUDE.md Completeness Grader

1. Either:
   • Paste your CLAUDE.md content directly into CLAUDE.md content, OR
   • Enter a GitHub repo (e.g., anthropics/claude-code) — the Actor fetches CLAUDE.md, then .claude/CLAUDE.md, then docs/CLAUDE.md
2. Click Start
3. Open the dataset row OR download claude-md-grade.md from the Storage tab

Input

• claudemdContent — raw markdown of the CLAUDE.md to grade (paste from clipboard)
• githubRepo — GitHub repo to fetch from (used only if claudemdContent is empty)

Provide one or the other. If you provide both, claudemdContent wins.

Output

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel. Each row contains:

{
  "source": "anthropics/claude-code",
  "charCount": 8240,
  "score": 84,
  "grade": "B",
  "sectionsDetected": {
    "projectOverview": true,
    "techStack": true,
    "commands": true,
    "structure": true,
    "conventions": true,
    "doNot": false,
    "security": true,
    "testing": true,
    "workflow": true,
    "agents": false
  },
  "missingSections": ["doNot", "agents"],
  "suggestions": [
    "Add a \"What NOT to do\" or \"Forbidden\" section. This is the single highest-value section for preventing AI hallucinations.",
    "Add a section listing which Claude Code sub-agents / skills the project uses."
  ]
}

Data table

Field	Meaning
source	Either inline or the GitHub repo path
charCount	Length of the CLAUDE.md examined
score	0-100 composite
grade	Letter grade A-F
sectionsDetected	Per-section boolean map
missingSections	List of rubric keys not detected
suggestions	One concrete fix per missing key
rubric	Full breakdown of every rubric item with weight + present flag

Rubric

Section	Weight
Project overview	15
Tech stack	12
Commands	15
Structure	10
Conventions	10
What NOT to do	12
Security	8
Testing	8
Workflow	5
Agents/skills	5
Length bonus	up to 5
Too-short penalty (< 400 chars)	-15

Grade thresholds: A >= 90, B >= 80, C >= 70, D >= 60, F < 60.

Pricing / Cost estimation

Pay-per-event:

• First grade: free
• Per-grade: $0.05
• Bulk (10+ files): $0.40 each
• Monthly project-watch subscription: $3/month

Tips and Advanced options

• For a private repo, set the GITHUB_TOKEN env var in the Actor's Source > Environment Variables tab
• Run on every CLAUDE.md PR in CI to enforce a grade floor (e.g., must stay >= B)
• Pair with the companion Actor gh-repo-ai-readiness-score for a full repo-level AI-readiness audit

FAQ, disclaimers, and support

Why these 10 sections?

They are derived from analyzing hundreds of CLAUDE.md files in the wild plus Anthropic's own memory feature docs. The "What NOT to do" section is weighted heavily because anti-instructions stop hallucinated edits far more reliably than positive instructions alone.

My CLAUDE.md got a C but it works fine

Grade reflects completeness, not vibes. A working codebase + a weak CLAUDE.md just means Claude can guess from context — but on a new repo, a fresh agent, or a complex bug, the gap will bite you.

Why is my A+ project graded C?

The grader is keyword-based, not LLM-based (to keep cost low). If you use unusual section names (e.g., "Manifesto" instead of "Overview"), it may not match. Try renaming to standard names or supply the alternative as a custom rubric in a future version.

Limitations

• The grader does regex-based section detection, not semantic. A clever team writing everything in narrative prose may score worse than a verbose project with shallow checklist sections
• Length penalty only fires below 400 chars
• Patterns are tuned for English; CJK / multilingual CLAUDE.md files may need future i18n support

Support

Companion repo: github.com/ianymu/claude-verify-before-stop — a Claude Code Stop hook that catches "task complete" hallucinations before they ship.

Built by Ian Mu — github.com/ianymu. Open an issue on the Actor's Issues tab if a real-world CLAUDE.md is being scored unfairly.