# CLAUDE.md Completeness Grader (`ianymu/claude-md-completeness-grader`) Actor Grade any CLAUDE.md file on completeness. Checks overview, tech stack, commands, structure, conventions, what NOT to do, security, testing, workflow, and agents sections. Outputs letter grade A-F plus a concrete checklist of missing pieces and how to fix them. - **URL**: https://apify.com/ianymu/claude-md-completeness-grader.md - **Developed by:** [Yanlong Mu](https://apify.com/ianymu) (community) - **Categories:** AI, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 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](https://docs.anthropic.com/en/docs/claude-code/overview) 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](https://apify.com/ianymu/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: ```json { "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](https://apify.com/ianymu/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](https://docs.anthropic.com/en/docs/claude-code/memory). 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](https://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](https://github.com/ianymu). Open an issue on the Actor's Issues tab if a real-world CLAUDE.md is being scored unfairly. # Actor input Schema ## `claudemdContent` (type: `string`): Raw markdown text of your CLAUDE.md. If empty, githubRepo will be used. ## `githubRepo` (type: `string`): Fetch CLAUDE.md from a public GitHub repo. Format: 'owner/name' or full URL. Tried paths: CLAUDE.md, .claude/CLAUDE.md, docs/CLAUDE.md. ## Actor input object example ```json { "githubRepo": "anthropics/claude-code" } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "githubRepo": "anthropics/claude-code" }; // Run the Actor and wait for it to finish const run = await client.actor("ianymu/claude-md-completeness-grader").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "githubRepo": "anthropics/claude-code" } # Run the Actor and wait for it to finish run = client.actor("ianymu/claude-md-completeness-grader").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "githubRepo": "anthropics/claude-code" }' | apify call ianymu/claude-md-completeness-grader --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=ianymu/claude-md-completeness-grader", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "CLAUDE.md Completeness Grader", "description": "Grade any CLAUDE.md file on completeness. Checks overview, tech stack, commands, structure, conventions, what NOT to do, security, testing, workflow, and agents sections. Outputs letter grade A-F plus a concrete checklist of missing pieces and how to fix them.", "version": "0.0", "x-build-id": "LRaP4JzbwtoSMmIhF" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ianymu~claude-md-completeness-grader/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ianymu-claude-md-completeness-grader", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/ianymu~claude-md-completeness-grader/runs": { "post": { "operationId": "runs-sync-ianymu-claude-md-completeness-grader", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/ianymu~claude-md-completeness-grader/run-sync": { "post": { "operationId": "run-sync-ianymu-claude-md-completeness-grader", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "claudemdContent": { "title": "CLAUDE.md content (paste directly)", "type": "string", "description": "Raw markdown text of your CLAUDE.md. If empty, githubRepo will be used." }, "githubRepo": { "title": "GitHub repo (owner/name)", "type": "string", "description": "Fetch CLAUDE.md from a public GitHub repo. Format: 'owner/name' or full URL. Tried paths: CLAUDE.md, .claude/CLAUDE.md, docs/CLAUDE.md." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```