claude-md-builder

name	claude-md-builder
description	Build and maintain high-quality CLAUDE.md files that maximize Claude Code efficiency. Use when creating a new CLAUDE.md for a project, auditing/improving an existing CLAUDE.md, or when the user mentions "claude.md", "agents.md", "onboarding Claude", or wants to improve their Claude Code workflow.

CLAUDE.md Builder

Create concise, high-leverage CLAUDE.md files that onboard Claude Code to any codebase.

Core Principle

LLMs are stateless. CLAUDE.md is the only file that goes into every Claude Code session—it's the highest leverage point of the entire harness. Every line matters.

The Three Questions

A good CLAUDE.md answers:

1. WHAT — Tech stack, project structure, key directories (especially for monorepos)
2. WHY — Project purpose, what each part does
3. HOW — Commands to build, test, verify changes; tools to use (e.g., bun vs node)

Golden Rules

Rule	Rationale
< 60 lines ideal, never > 300	Research shows LLMs follow ~150-200 instructions max; Claude Code's system prompt already uses ~50
Universally applicable only	Claude Code tells the model to ignore CLAUDE.md if not relevant to the current task
No code style rules	Use linters/formatters instead—LLMs are expensive, slow linters
Pointers over copies	Reference file:line instead of pasting code—snippets go stale
Never auto-generate	/init output is bloated; hand-craft every line

Progressive Disclosure Pattern

Don't stuff everything into CLAUDE.md. Instead:

1. Create an agent_docs/ folder with focused markdown files
2. Add a brief index in CLAUDE.md pointing to them
3. Claude reads only what's relevant to the current task

Example structure:

project/
├── CLAUDE.md              # <60 lines, universal context only
└── agent_docs/
    ├── architecture.md    # System design, service relationships
    ├── database.md        # Schema, migrations, query patterns
    ├── testing.md         # Test commands, coverage requirements
    ├── deployment.md      # CI/CD, environments, release process
    └── conventions.md     # Patterns specific to this codebase

Example CLAUDE.md index section:

## Documentation
Read relevant files from `agent_docs/` before starting work:
- `architecture.md` — service boundaries, communication patterns
- `database.md` — schema design, migration workflow
- `testing.md` — how to run and write tests
- `deployment.md` — release process, environments
- `conventions.md` — project-specific patterns (read existing code first)

Workflow

Creating a New CLAUDE.md

1. Analyze the codebase — Identify tech stack, structure, key commands
2. Draft the three sections — WHAT, WHY, HOW (see references/template.md)
3. Apply progressive disclosure — Move non-universal content to agent_docs/
4. Verify line count — Target <60 lines; hard max 300
5. Review every line — Ask: "Does Claude need this in every session?"

Auditing an Existing CLAUDE.md

1. Count lines and instructions — Flag if >100 lines
2. Check for violations:
   • Code snippets (should be file references)
   • Style guidelines (should be in linter config)
   • Task-specific instructions (should be in agent_docs/)
   • Auto-generated boilerplate
3. Extract to agent_docs/ — Create focused files for extracted content
4. Rewrite index — Brief pointers with descriptions
5. Final review — Ensure only universal context remains

Anti-Patterns to Remove

• ❌ Lengthy code examples or snippets
• ❌ Database schema dumps
• ❌ API endpoint documentation
• ❌ Style guides / formatting rules
• ❌ Rarely-used commands
• ❌ Task-specific workflows
• ❌ Boilerplate from /init or auto-generation

Quick Reference

Run cat references/template.md for a starter template. Run cat references/checklist.md for the audit checklist.