# claude-md-builder

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

- Author: 30DaiStartup
- Repository: 30DaiStartup/AI3Consulting-resources
- Version: 20251208102629
- Stars: 5
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/30DaiStartup/AI3Consulting-resources
- Web: https://mule.run/skillshub/@@30DaiStartup/AI3Consulting-resources~claude-md-builder:20251208102629

---

---
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:**
```markdown
## 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.