CLAUDE.md Generator

Purpose: Teach an AI agent how to analyze a codebase and produce a high-quality CLAUDE.md file with progressive disclosure.

Overview

A great CLAUDE.md is the single most impactful file in a repository for AI-assisted development. It tells the agent what it needs to know — and nothing more. This skill teaches you how to create one.

Principles

1. Concise over comprehensive — 200 lines max for CLAUDE.md. Details go in agent_docs/.
2. Universal, not personal — Write for any agent, not a specific model.
3. No linting rules — Agents get these from config files. Don't duplicate.
4. Progressive disclosure — Top-level has critical info. agent_docs/ has deep dives.
5. Imperative rules — "Never do X" and "Always do Y" are clearer than explanations.

Process

Step 1: Analyze the Codebase

Scan these files first:

• package.json / Cargo.toml / pyproject.toml — stack and dependencies
• Existing config files (.eslintrc, tsconfig.json, etc.) — already-encoded rules
• README.md — project purpose (but don't copy it)
• Recent git history — active patterns and conventions

Step 2: Identify Critical Rules

Look for:

• Data access patterns — ORMs, query builders, column selection rules
• Numeric conventions — score ranges (0-1 vs 0-100), currency units
• Auth patterns — how auth is handled, typed clients, middleware
• Architecture constraints — "never import X from Y", module boundaries
• Testing patterns — test file locations, mocking conventions, assertion styles
• Common gotchas — things that break builds or cause subtle bugs

Step 3: Structure the CLAUDE.md

# {Project Name}

{One paragraph: what the project is and does}

## Stack

- {Framework} + {Language} + {Styling}
- {Database/backend}
- {Testing framework}

## Quick Reference

```bash
{dev command}      # {what it does}
{test command}     # {what it does}
{build command}    # {what it does}

Workflow

• {Branch strategy}
• {Deploy process}

Critical Rules

• {Rule name} — {concise explanation}
• {Rule name} — {concise explanation}

Agent Docs (read when relevant)

### Step 4: Create agent_docs/ Files

For each deep topic, create a focused file:

- `agent_docs/project_structure.md` — file layout, key directories, naming conventions
- `agent_docs/development_workflow.md` — git workflow, environments, migrations, deployment
- `agent_docs/common_gotchas.md` — debugging issues, form validation, auth quirks
- `agent_docs/testing.md` — writing and running tests, mocking patterns

Each agent_docs file should be **self-contained** — an agent reads it independently.

---

## Anti-Patterns

- Copying the entire README into CLAUDE.md
- Listing every file in the project
- Including linting rules the agent gets from config
- Writing paragraphs when bullet points suffice
- Including setup instructions (agents don't run npm install)
- Documenting obvious conventions (standard Next.js patterns, etc.)

---

## Quality Checklist

- [ ] CLAUDE.md is under 200 lines
- [ ] Every rule is actionable ("Never X", "Always Y")
- [ ] No duplicate info from config files
- [ ] agent_docs/ table has clear "when to read" triggers
- [ ] A new developer (or agent) could be productive after reading just CLAUDE.md
- [ ] No personal preferences disguised as project rules