/claude-md-generator

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.

# 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

# 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

# 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

# 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:

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": [{
    "