Optimize CLAUDE.md files using a 4-tier architecture for rules, examples, and workflows. Use when the user asks to optimize, refactor, or improve a CLAUDE.md file, reduce its token usage, improve sub-agent convention adherence, or create a more maintainable project documentation structure. Also use when analyzing existing CLAUDE.md files to identify optimization opportunities or when setting up new CLAUDE.md files following best practices.
Optimize CLAUDE.md files using a 4-tier architecture that balances token efficiency with convention adherence, especially for sub-agents.
Do NOT extract everything into skills. Skills are demand-loaded (only when explicitly invoked), so conventions placed in skills won't be followed by sub-agents or during normal coding unless someone remembers to invoke the skill first.
Instead, use a 4-tier architecture:
Critical rules, project structure, and commands. These are compact one-liners loaded into every context, including sub-agent contexts. Also includes a Mandatory Rules section for operational/safety rules that apply to the orchestrator and all agents.
What goes here: project overview, tech stack, directory structure, commands, compact critical rules (Code Standards), mandatory operational rules (tool usage, file safety), convention/skill navigation tables.
Claude Code also loads CLAUDE.md files placed in subdirectories — scoped to that subdirectory. When working on files within a subdirectory, Claude sees both the root CLAUDE.md and the subdirectory's CLAUDE.md. This enables layer- or domain-specific instructions without bloating the root file.
When to use subdirectory CLAUDE.md files:
domain/CLAUDE.md (no infrastructure imports, pure business logic), infrastructure/CLAUDE.md (adapter patterns, repository implementations), application/CLAUDE.md (use case orchestration, DTO rules), presentation/CLAUDE.md (controller conventions, request validation)src/OrderBundle/CLAUDE.md), Go packages (pkg/auth/CLAUDE.md), bounded contexts in DDD (src/Billing/CLAUDE.md)packages/api/CLAUDE.md vs packages/web/CLAUDE.mdWhen NOT to use:
Keep subdirectory CLAUDE.md files compact — same Tier 1 principles as root: purpose, key constraints, specific commands. Never duplicate root content; only add what is unique to that directory.
Hard constraints stored in .claude/rules/. Claude Code automatically loads all .md files in this directory into every session — no explicit reading required. These are binary constraints (MUST/NEVER) that, if violated, produce incorrect or dangerous results.
What goes here: "Always X", "Never Y", "Must Z" rules. No code examples needed — just the constraint. Each rule file should end with a cross-reference to the corresponding examples file.
Detailed patterns with code examples packaged as skills with user-invocable: false. Claude auto-triggers these based on description relevance — no explicit "read this file" instruction needed. Optionally scoped to specific file patterns using the paths frontmatter field.
What goes here: detailed code examples, full pattern descriptions, Good/Bad comparisons, API reference for project-specific helpers, anti-patterns with explanations.
Frontmatter:
---