# 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

```markdown
# {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)

| File | When to read |
|------|-------------|
| `agent_docs/{file}.md` | {trigger condition} |
```

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