1. CLAUDE.md is for agent behaviour, not project knowledge
CLAUDE.md defines HOW the agent should work: communication style, workflow patterns, task management, definition of done. It does NOT contain project-specific technical details—those belong in README.md files.
2. README.md files are the knowledge graph
Each package/directory can have a README.md with domain-specific context. Agents read these just-in-time when working in that area. This keeps initial context lean while making deep knowledge available.
3. Tests are the documentation
Long-lived markdown should cover architecture and principles only. Detailed behaviour documentation belongs in executable tests. If behaviour isn't tested, it's not guaranteed.
4. CLAUDE.md is not customised
The standard CLAUDE.md (standard/CLAUDE.md) should be copied exactly into projects. It is designed to work universally. All project-specific content belongs in README.md files.
- Install — Set up the standard CLAUDE.md in a new project
- Migrate — Refactor an existing CLAUDE.md, moving content to READMEs
- Audit — Check if a project follows progressive disclosure principles
Wait for response before proceeding.
Intent-based routing:
- "set up CLAUDE.md", "add agent config" → workflows/install.md
- "CLAUDE.md is too big", "slim down", "refactor" → workflows/migrate.md
- "is this right?", "check conformance" → workflows/audit.md
After reading the workflow, follow it exactly.
README.md distribution:
project/
├── CLAUDE.md # Agent behaviour (~80 lines)
├── README.md # Project overview, links to packages
├── packages/
│ ├── api/
│ │ └── README.md # API-specific context
│ └── web/
│ └── README.md # Web-specific context
└── docs/
└── {feature}/ # Ephemeral planning docs
| Workflow |
Purpose |
| install.md |
Install standard CLAUDE.md into new project |
| migrate.md |
Migrate existing CLAUDE.md content to READMEs |
| audit.md |
Audit project for progressive disclosure conformance |
|
|
- CLAUDE.md is an exact copy of
standard/CLAUDE.md
- README.md at project root with overview and navigation
- Package-level README.md files for domain-specific context
- Tests document behaviour, not markdown files
1---2name: developing-claude-code-meta3description: MUST be loaded when setting up, installing, migrating, reviewing, auditing, or checking CLAUDE.md files in projects. Covers installing the standard CLAUDE.md into new projects, migrating existing CLAUDE.md content to READMEs (progressive disclosure), and auditing projects for conformance. Invoke PROACTIVELY when user mentions CLAUDE.md, project setup, agent configuration, or code meta files.4---56<essential_principles>7The goal is a small, focused CLAUDE.md that loads into every conversation while project-specific details live in README.md files throughout the codebase. This follows the progressive disclosure principle: essential instructions load immediately, domain knowledge loads just-in-time.89**1. CLAUDE.md is for agent behaviour, not project knowledge**10CLAUDE.md defines HOW the agent should work: communication style, workflow patterns, task management, definition of done. It does NOT contain project-specific technical details—those belong in README.md files.1112**2. README.md files are the knowledge graph**13Each package/directory can have a README.md with domain-specific context. Agents read these just-in-time when working in that area. This keeps initial context lean while making deep knowledge available.1415**3. Tests are the documentation**16Long-lived markdown should cover architecture and principles only. Detailed behaviour documentation belongs in executable tests. If behaviour isn't tested, it's not guaranteed.1718**4. CLAUDE.md is not customised**19The standard CLAUDE.md (`standard/CLAUDE.md`) should be copied exactly into projects. It is designed to work universally. All project-specific content belongs in README.md files.20</essential_principles>2122<never_do>23- NEVER modify `standard/CLAUDE.md` content — it must be copied exactly into projects24- NEVER add project-specific content to CLAUDE.md (use README.md files instead)25- NEVER create more than 2 levels of README navigation (CLAUDE.md → README.md → package READMEs)26- NEVER duplicate content between CLAUDE.md and README.md — single source of truth27- NEVER skip verifying CLAUDE.md matches the standard after installation or migration28</never_do>2930<escalation>31Stop and ask the user when:32- Project structure is unconventional (no clear packages or module boundaries)33- Content doesn't fit KEEP/MOVE/DELETE categories during migration34- Existing README.md files conflict with the suggested structure35- You've attempted the same step 3+ times without success36- Changes would affect more than 10 files37</escalation>3839<intake>40What would you like to do?41421. **Install** — Set up the standard CLAUDE.md in a new project432. **Migrate** — Refactor an existing CLAUDE.md, moving content to READMEs443. **Audit** — Check if a project follows progressive disclosure principles4546**Wait for response before proceeding.**47</intake>4849<routing>50| Response | Next Action | Workflow |51|----------|-------------|----------|52| 1, "install", "setup", "new", "create" | Confirm project path | workflows/install.md |53| 2, "migrate", "refactor", "move", "convert" | Analyze existing CLAUDE.md | workflows/migrate.md |54| 3, "audit", "check", "review", "assess" | Scan project structure | workflows/audit.md |5556**Intent-based routing:**57- "set up CLAUDE.md", "add agent config" → workflows/install.md58- "CLAUDE.md is too big", "slim down", "refactor" → workflows/migrate.md59- "is this right?", "check conformance" → workflows/audit.md6061**After reading the workflow, follow it exactly.**62</routing>6364<quick_reference>65**CLAUDE.md**: Copy `standard/CLAUDE.md` exactly. Do not modify.6667**README.md distribution:**68```69project/70├── CLAUDE.md # Agent behaviour (~80 lines)71├── README.md # Project overview, links to packages72├── packages/73│ ├── api/74│ │ └── README.md # API-specific context75│ └── web/76│ └── README.md # Web-specific context77└── docs/78 └── {feature}/ # Ephemeral planning docs79```80</quick_reference>8182<reference_index>83- `standard/CLAUDE.md` — The canonical CLAUDE.md (copy exactly into projects)84- `references/progressive-disclosure.md` — Why and how to distribute content to READMEs85- `references/claude-md-sections.md` — Purpose of each CLAUDE.md section86</reference_index>8788<workflows_index>89All in `workflows/`:9091| Workflow | Purpose |92|----------|---------|93| install.md | Install standard CLAUDE.md into new project |94| migrate.md | Migrate existing CLAUDE.md content to READMEs |95| audit.md | Audit project for progressive disclosure conformance |96</workflows_index>9798<success_criteria>99A well-configured project:100101- CLAUDE.md is an exact copy of `standard/CLAUDE.md`102- README.md at project root with overview and navigation103- Package-level README.md files for domain-specific context104- Tests document behaviour, not markdown files105</success_criteria>
diegosouzapw