Official guidance, community patterns, and a step-by-step reduction plan for over-grown CLAUDE.md files.
How to design production-grade CLAUDE.md files. Covers Anthropic's official recommendations, the facts-vs-procedures split, what must stay inline vs. what moves to skills/rules/docs, and the radical-reduction migration plan.
Three official positions directly affect what should and should not be in [Your Project]'s CLAUDE.md:
Insight A: CLAUDE.md should be under 200 lines. Anthropic explicitly states this target. The [Your Project] file is 2,091 lines — ten times the recommendation. The official docs warn: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions." This is not advisory; it's a documented failure mode. The [Your Project] file's length is its single biggest structural vulnerability.
Insight B: Skills replace in-line procedures. Anthropic's skill system (SKILL.md files in .claude/skills/) is designed for exactly the kind of multi-step procedures that dominate [Your Project] §§2, 3, 13, 17, and 18. Skills load on-demand — they cost zero tokens until invoked. [Your Project] currently embeds all procedures in the root CLAUDE.md, paying the full context cost every session regardless of whether the session needs them.
Insight C: Hooks are deterministic; CLAUDE.md is advisory. Anthropic draws a hard line: hooks guarantee execution, CLAUDE.md influences behavior. The [Your Project] session-end protocol (§18) is currently advisory — Claude can forget or skip it. Converting it to a Stop hook plus a skill makes it mechanically enforced.
Insight D: CLAUDE.md hierarchy is automatic. Claude Code walks up the directory tree and loads every CLAUDE.md it finds. [Your Project] could use this to split content: [pipeline-directory]CLAUDE.md for pipeline-specific rules, src/CLAUDE.md for viz-specific rules. These only load when Claude works in those directories. This is the Anthropic-endorsed version of the splitting strategy from the Startup Framework.
Insight E: Auto-memory exists. Claude Code can write its own learnings to ~/.claude/auto-memory/. The [Your Project] instinct system (§14.2) is a manual version of this. The two systems can coexist: auto-memory for Claude's self-corrections, instinct files for project-specific verified patterns.
Insight F: @-imports for cross-references. CLAUDE.md supports @path/to/file imports. Instead of copying full sections, [Your Project] can write @docs/[PATTERNS_TOPIC].md and Claude loads it inline. This is the cleanest way to split without losing coherence.
Insight G: Command → Agent → Skill architecture. This is the canonical orchestration pattern: a slash command (/weather-orchestrator) invokes an agent, which invokes skills. [Your Project]'s worker bridge (§17) is a custom implementation of this pattern. The question is whether to migrate to the native architecture or keep the custom bridge.
Insight H: Subagent frontmatter is structured. Agent .md files support YAML frontmatter with model, tools, disallowedTools, permissionMode, maxTurns, skills, mcpServers, memory, isolation, effort, and color. [Your Project]'s agent definitions (§11) are prose-based. Migrating to frontmatter would make them machine-parseable and align with Claude Code's native agent system.
Insight I: 200-line budget, manual /compact at 50%. Reinforces Anthropic's position with a concrete compaction trigger.
Insight J: Behavioral rules should be concise and imperative. The entire file is 65 lines. It achieves more behavioral control with 7 sections than most 2,000-line CLAUDE.md files. Key patterns already in [Your Project] but stated more sharply: "If you write 200 lines and it could be 50, rewrite it", "Don't 'improve' adjacent code", "Match existing style even if you'd do it differently."
Insight K: No project-specific content. Karpathy's file is pure behavioral guidance — no project context, no architecture, no data contracts. This is the opposite end of the spectrum from [Your Project]'s approach. The lesson is not to copy this style but to recognize that behavioral rules and project context serve different purposes and should be structurally separated.
Insight L: BMAD for architecture, plan mode for features. The BMAD method (brainstorm → spec → validate → implement) maps directly to [Your Project]'s Phase 1–3 workflow. The insight is that [Your Project]'s phases are already good — but they should be skills, not CLAUDE.md sections.
Insight M: "Skills can replace MCP servers." Skills are transparent (you can read the instructions), while MCP servers are opaque. [Your Project]'s pipeline procedures are currently embedded in CLAUDE.md; converting them to skills gives the same benefits as a custom MCP server but with full auditability.
What to improve: Reduce the root CLAUDE.md from 2,091 lines to ~150–200 lines by migrating content to skills, subdirectory CLAUDE.md files, .claude/rules/, and docs/ with @-imports.
Why it matters: Anthropic's docs explicitly state adherence degrades beyond 200 lines. At 2,091 lines, Claude is statistically ignoring many of [Your Project]'s rules. This is the single highest-impact change.
Derived from: Anthropic Best Practices, Memory docs, shanraisshan (Insight A, D, F, I)
Migration plan:
| Current Section | Lines | Move To | Mechanism |
|---|---|---|---|
| §2 Phase-by-Phase Protocols | ~200 | .claude/skills/explore/, /implement/, /debug/, /refactor/, /scaffold/ |
Skills (on-demand) |
| §3 Reusable Prompt Patterns | ~60 | .claude/skills/prompt-patterns/SKILL.md |
Skill |
| §5 File & Folder Structure | ~100 | docs/[PROJECT_MAP].md, referenced via @docs/[PROJECT_MAP].md |
@-import |
| §5 [output-schema-file] Schema | ~180 | docs/[DATA_CONTRACT].md, referenced via @docs/[DATA_CONTRACT].md |
@-import |
| §10 [graph rendering library] API Reference | ~30 | .claude/skills/g6-api-verify/SKILL.md |
Skill |
| §11 Agent Roster | ~170 | .claude/agents/*.md (one file per agent with frontmatter) |
Native agents |
| §12 Project C (agent framework) Patterns | ~100 | Absorb into root CLAUDE.md rules (tiers, status block) | Inline (reduced) |
| §13 RAG/CRAG Patterns | ~200 | docs/[PATTERNS_TOPIC].md |
@-import |
| §14 ECC Patterns | ~100 | .claude/skills/learned/ + hooks config |
Skills + hooks |
| §16 an open-source monitoring project Patterns | ~200 | docs/[PATTERNS_TOPIC].md (routing table stays canonical in [llm-router-module]) |
@-import |
| §17 Worker Bridge | ~100 | .claude/workers/README.md (already partially there) |
Docs |
| §18 Session End Protocol | ~90 | .claude/skills/[skill-name]/SKILL.md (already exists) + Stop hook |
Skill + hook |
What remains in root CLAUDE.md (~150 lines):
- Project Status table (15 lines)
- Project Identity & stack (15 lines)
- Session Start ritual (10 lines)
- Hard bans (15 lines, single canonical location)
- Risk triage (15 lines)
- Automation tiers (20 lines)
- Layer separation rules (10 lines)
- Theme token rules (5 lines)
- Emergency brake (5 lines)
- @-imports to docs/ (10 lines)
- Key Jira queries (10 lines)
- Git commit rules (10 lines)
→ emplates/claude-md-template.md — fill-in-the-blanks CLAUDE.md starter with status table, identity, rules, automation tiers, and reference pointers.