---
name: claude-md-generator
description: Use when the user asks to generate or update a project's CLAUDE or AGENTS context file from a codebase scan. Writes a focused file under 100 lines containing only the non-obvious build commands, conventions, and gotchas Claude Code needs.
compatibility: [claude-code, gemini-cli, github-copilot]
author: OpenDirectory
version: 1.0.0
---
# CLAUDE.md Generator
Read the codebase. Write a CLAUDE.md that tells Claude exactly what it needs: no more, no less.
---
**Critical rule:** A good CLAUDE.md is under 100 lines. It contains only information Claude cannot derive from reading the code itself. Do not auto-write the file: always show the draft and wait for user approval first.
**Code snippet rule:** Never include inline code examples in CLAUDE.md. Instead use `file.ts:42` references. Code in CLAUDE.md wastes tokens and goes stale.
---
## Step 1: Detect Mode
Determine which of three modes to run:
**create**: No CLAUDE.md exists. Write one from scratch.
**update**: A CLAUDE.md exists. Improve it without discarding custom content.
**audit**: Score all CLAUDE.md files in the project A-F and output a quality report. If the user says "audit", "check", "review", or "grade" my CLAUDE.md, run audit mode.
```bash
# Discover ALL CLAUDE.md locations
find . -name "CLAUDE.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null
ls ~/.claude/CLAUDE.md 2>/dev/null && echo "Global CLAUDE.md found"
ls .claude.local.md 2>/dev/null && echo ".claude.local.md found"
```
If multiple CLAUDE.md files are found: list them. Ask: "Found CLAUDE.md in [locations]. Should I update all of them or just [root]?"
---
## Step 2: Audit Mode (skip to Step 3 if create/update)
For each CLAUDE.md found, score it A-F using this rubric:
| Criterion | What to check |
|-----------|--------------|
| Commands | Build/test/lint commands present and runnable? |
| Architecture | Non-obvious structure explained? |
| Non-obvious patterns | Gotchas, generated files, env var order documented? |
| Conciseness | Under 100 lines? No obvious filler? |
| Currency | Commands still match current package.json/Makefile? |
| Actionability | Can a new contributor follow this without asking questions? |
Score: 90-100 = A, 70-89 = B, 50-69 = C, 30-49 = D, 0-29 = F
Present as a table:
```
## CLAUDE.md Audit Report
| File | Score | Grade | Top Issues |
|------|-------|-------|-----------|
| ./CLAUDE.md | 72 | B | Missing gotchas section, test command outdated |
| ./packages/api/CLAUDE.md | 45 | D | No commands, 340 lines (too long), stale arch notes |
**Overall: B (72/100)**
Issues found:
- ./packages/api/CLAUDE.md: 340 lines: well over the 100-line target
- ./packages/api/CLAUDE.md: Test command references `jest` but package.json uses `vitest`
- ./CLAUDE.md: No Gotchas section: most valuable section is missing
```
After the report, ask: "Want me to fix any of these? (all / just root / specify)"
If user says yes, continue to Step 3 for each file they want fixed.
---
## Step 3: Scan Project Structure
```bash
# Project type and package manager
ls package.json yarn.lock pnpm-lock.yaml bun.lockb requirements.txt pyproject.toml Cargo.toml go.mod 2>/dev/null
# Top-level directory structure
find . -maxdepth 2 -type d \
| grep -v node_modules | grep -v .git | grep -v __pycache__ \
| grep -v ".next" | grep -v dist | grep -v build | sort
```
---
## Step 4: Extract Build and Test Commands
```bash
# npm/yarn/pnpm/bun scripts
cat package.json 2>/dev/null \
| python3 -c "
import sys, json
d = json.load(sys.stdin)
for name, cmd in d.get('scripts', {}).items():
print(f'{name}: {cmd}')
"
# Python, Go, Rust Makefiles
cat Makefile 2>/dev/null | grep -E "^[a-z].*:" | head -20
# Go
cat go.mod 2>/dev/null | head -5
# Rust
cat Cargo.toml 2>/dev/null | grep -E "^\[" | head -10
```
Identify the exact commands for: build, test (all), test (single file/name), dev server, lint/typecheck. Note any env vars required to run them.
---
## Step 5: Find Code Style and Gotchas
```bash
# Import aliases (most commonly missed)
python3 -c "
import json, sys
try:
d = json.load(open('tsconfig.json'))
paths = d.get('compilerOptions', {}).get('paths', {})
if paths: print('Import aliases:', json.dumps(paths, indent=2))
except: pass
" 2>/dev/null
# Environment variables required
cat .env.example 2>/dev/null | grep -v "^#" | grep -v "^$" | head -20
# Auto-generated files (must not be edited)
find . -path "*/node_modules" -prune -o -name "*.ts" -print \
| xargs grep -l "DO NOT EDIT\|@generated\|Generated by" 2>/dev/null | head -5
# Test setup requirements
cat jest.config.js jest.config.ts vitest.config.ts 2>/dev/null | head -30
# Database/migration setup
ls migrations/ prisma/ drizzle/ db/ 2>/dev/null
```
**What counts as a Gotcha** (include these, skip everything else):
- Files that are auto-generated (must not edit)
- Env vars required BEFORE tests run
- Non-default import alias mappings
- Test commands that require a running service
- Known intentional quirks (workarounds, not bugs)
---
## Step 6: Generate CLAUDE.md Draft with Gemini
Compile all findings and generate the draft:
```bash
cat > /tmp/claude-md-request.json << 'ENDJSON'
{
"system_instruction": {
"parts": [{
"text": "Write a CLAUDE.md file for a software project. Rules: (1) Under 100 lines total. (2) Only include what Claude cannot derive from reading the code. (3) No inline code examples: use file.ts:42 references instead. (4) Sections: Commands, Code Style (only non-defaults), Testing (only if setup needed), Gotchas (required: what trips people up). Skip any section that has nothing non-obvious to say. (5) All commands in code blocks. (6) Preferred order: short Project Overview (1-2 sentences, only if non-obvious), Commands, Architecture (only non-obvious structure), Code Style, Testing, Gotchas. (7) Do not use em dashes. (8) Output only the CLAUDE.md content, no commentary."
}]
},
"contents": [{
"parts": [{
"text": "PROJECT_ANALYSIS_HERE"
}]
}],
"generationConfig": {
"temperature": 0.3,
"maxOutputTokens": 2048
}
}
ENDJSON
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d @/tmp/claude-md-request.json \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(d['candidates'][0]['content']['parts'][0]['text'])"
```
Replace `PROJECT_ANALYSIS_HERE` with findings from Steps 3-5.
**For large projects (50+ files):** Add a `@path` pointer at the bottom of CLAUDE.md instead of inline detail:
```markdown
## Extended Reference
See @docs/ai-context/architecture.md for full module map.
See @docs/ai-context/testing.md for integration test setup details.
```
Write the referenced files to `docs/ai-context/` with the detail that would not fit in 100 lines.
---
## Step 7: Self-QA
Before presenting the draft, check:
- [ ] Under 100 lines (count: `echo "$CONTENT" | wc -l`)
- [ ] No inline code examples (only `file.ts:42` references or shell commands)
- [ ] All commands in code blocks and runnable as-is
- [ ] Gotchas section present with at least one real entry
- [ ] No section that says only things obvious from the files
- [ ] No em dashes
- [ ] No marketing words or filler phrases ("This project uses React to...")
- [ ] Import aliases documented if they exist
- [ ] Auto-generated files marked "do not edit" if they exist
If any check fails, revise before presenting.
---
## Step 8: Present Draft and Wait for Approval
**Never write the file without user approval.**
Present the draft in a code block:
```
## Draft CLAUDE.md ([N] lines)
[full draft content here]
---
Write this to CLAUDE.md? (yes / edit first / cancel)
```
If user says **yes**: write the file, then confirm:
"CLAUDE.md written ([N] lines). Sections: [list of ## headers]."
If user says **edit first**: apply their edits, re-show the draft.
If user says **cancel**: stop.
---
## What NOT to Include
- Language/framework version ("This is a TypeScript project")
- How the framework works (Claude already knows React, FastAPI, etc.)
- List of all dependencies
- Style rules the linter already enforces (indent size, quote style)
- Content that duplicates README.md
- Inline code examples or multi-line snippets
- Anything that would be identical for any project using the same stack