--- description: "Teaches agents how to analyze a codebase and generate effective CLAUDE.md files with progressive disclosure." alwaysApply: true --- # 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 ## Playground

Input: Project description

Project: Next.js 16 + Supabase SaaS
Stack: TypeScript, Tailwind, Vitest
Special rules:
- Never SELECT * on users table
- Always run tests before commit
- Stripe is test-mode only in dev

Output: CLAUDE.md

# ProjectName

Next.js 16 SaaS with Supabase auth
and Stripe billing.

## Stack
Next.js 16 · Supabase · TypeScript
Tailwind · Vitest · Stripe

## Non-Negotiable Rules
1. Never `SELECT *` on users table
   — use USER_COLUMNS from lib/
2. Run `npx vitest run` before
   every commit
3. Stripe is ALWAYS test-mode in
   dev (sk_test_ keys only)

## Quick Commands
npm run dev   # localhost:3000
npm test      # full unit suite