Skip to main content

CLAUDE.md Optimization & Symlink Audit Analysis

Date: 2026-02-19 Author: Claude (Opus 4.6) Task: [H.0] Ad-hoc analysis Status: Analysis complete, pending implementation

Executive Summary​

Three files are loaded every conversation: Core CLAUDE.md (~3,700 tokens), Rollout-master CLAUDE.md (~1,100 tokens), MEMORY.md (~2,800 tokens) = ~7,600 tokens per conversation.

Through deduplication, trimming overexplained rationale, and moving context-specific MEMORY.md content to topic files, ~2,165 tokens (28%) can be saved with zero information loss.

Additionally, a symlink audit reveals 375 regular CLAUDE.md files vs 99 symlinks across the repository tree. At the root submodule level, 76/78 are correctly symlinked. The bulk of regular files (171) are nested copies inside coditect-dev-generative-ui-development.

Product strategy implication: CLAUDE.md must remain CODITECT-controlled (symlinked to protected installation) so customers cannot modify it. This is critical for ensuring maximum value delivery.

Part 1: Token Budget Analysis​

Files Loaded Per Conversation​

FileBytesLinesEst. TokensPurpose
Core CLAUDE.md (.coditect/CLAUDE.md)14,744306~3,700Framework directives
Rollout-master CLAUDE.md4,295131~1,100Project-specific
MEMORY.md11,181160~2,800Session memory
Total30,220597~7,600

Part 2: Cross-File Duplication​

2.1 TRIPLE DUPLICATION: Git Push Safety​

The identical directive appears three times per conversation:

LocationLinesBytes
Core CLAUDE.md lines 39-424~400
Rollout-master CLAUDE.md lines 50-556~400
MEMORY.md lines 19-235~250
Total waste11 redundant~650

Action: Remove from rollout-master and MEMORY.md. Keep only in core.

2.2 DOUBLE DUPLICATION: Analysis Preservation​

LocationLinesNotes
Core CLAUDE.md lines 137-17438Full protocol with "why" rationale
MEMORY.md lines 25-306Summary + lesson learned

Action: Remove from MEMORY.md. Keep only the unique lesson learned line (J.29 compaction).

2.3 DOUBLE DUPLICATION: Session Log Location​

LocationLines
Core CLAUDE.md lines 127-1337
MEMORY.md lines 153-1597

Action: Remove from MEMORY.md.

2.4 DOUBLE DUPLICATION: Document Placement​

LocationLines
Core CLAUDE.md line 1511
MEMORY.md lines 62-654

Action: Remove from MEMORY.md.

2.5 OVERLAP: Agent System​

Location/which/moe-agents/moe-workflow/agentTask() distinction
Core CLAUDE.md (lines 196-206)YesNoNoYesYes
Rollout-master CLAUDE.md (lines 107-118)YesYesYesYesNo

Action: Merge into one section in core CLAUDE.md. Add /moe-agents, /moe-workflow, /moe-judges. Drop the "Common:" agent name list. Remove Agent System from rollout-master.

Part 3: Overexplained Protocols (Core CLAUDE.md)​

3.1 Analysis Preservation Protocol (38 lines -> ~15)​

  • Lines 164-167: 4 bullets explaining "why both filename and path" — redundant with the example
  • Lines 169-174: 6 "Why this matters" bullets — justification, not instruction
  • Lines 143-149: 6 "when to save" bullets — could be 1 general rule

3.2 Session Logging Protocol (24 lines -> ~14)​

  • Lines 114-116: 3 sentences restating what the table already says
  • Line 123: "Why" explanation — redundant after the mandate

3.3 Task ID Protocol (35 lines -> ~20)​

  • Lines 84-92: Step-by-step grep instructions — could be 2 lines
  • Lines 81-82: "Project Association" explanation could be 1 line

Savings Summary​

SectionCurrentProposedSavings
Analysis Preservation38 lines~15 lines~1,000 bytes
Session Logging24 lines~14 lines~450 bytes
Task ID Protocol35 lines~20 lines~600 bytes
Subtotal~2,050 bytes (~510 tokens)

Part 4: MEMORY.md Context-Specific Bloat​

These sections are loaded every conversation but only relevant for specific features:

SectionLinesBytesRelevance
PDF-to-Markdown v2.528~2,000Only for PDF work
UDOM Pipeline v1.324~1,700Only for UDOM work
Codestoryai Sidecar12~800Only for sidecar R&D
Browser Extraction6~400Only for browser work
Total70~4,900 (~1,225 tokens)

Action: Move to topic files (memory/pdf-to-markdown.md, memory/udom-pipeline.md, etc.). Leave 1-line pointers in MEMORY.md.

Part 5: Stale / Outdated Content​

ItemCurrent ValueActual ValueLocation
Agent count"776"805Core line 198
Commands count"377"389Core line 249
Scripts count"581"617Core line 251
Hooks count"118"128Core line 251
Skills count"445"451Core lines 180, 250
Version footer"3.3.0"Frontmatter says "3.1.0"Core line 304 vs 5
MEMORY.md typetype: skillShould be type: referenceMEMORY.md line 3
MEMORY.md tokenstokens: ~1000Actual ~2,800MEMORY.md line 11
Rollout component count"3,458"3,553Rollout line 130

Part 6: Missing Content​

Missing CommandIn Quick Commands?In Agent System?
/moe-agents <use-case>NoNo
/moe-workflow <task>NoNo
/moe-judges <target>Quick Commands onlyNo
/git-submodule-commit-allNoN/A
/session-statusNoN/A

Part 7: YAML Frontmatter​

Both files have YAML frontmatter (~200 bytes each) for MoE classification. Claude doesn't use it for behavior.

FileFrontmatter LinesBytes
Core CLAUDE.md16~400
MEMORY.md16~200
Total32~600 (~150 tokens)

Action: Remove frontmatter from both.

Part 8: Total Optimization Potential​

CategoryBytes SavedTokens Saved
Pure duplicates removed~1,350~340
Overexplained protocols trimmed~2,050~510
MEMORY.md context-specific -> topic files~4,500~1,125
YAML frontmatter removed~600~150
Stale "Common:" agent list removed~150~40
Total~8,650~2,165

Reduction: ~28% (30,220 -> ~21,570 bytes)

9.1 Root-Level Submodule CLAUDE.md​

TypeCountNotes
Symlink -> ~/.coditect/CLAUDE.md76Correct
Regular file (coditect-core/CLAUDE.md)1This IS the master source
Regular file (agent-labs/CLAUDE.md)1Third-party repo (brainqub3)
Total7876/78 correctly symlinked

9.2 All CLAUDE.md Files (Including Subdirectories)​

TypeCount
Regular files375
Symlinks99
Total474

9.3 Regular Files by Category​

CategoryCountDescriptionAction
NESTED-GENUI171Inside coditect-dev-generative-ui-development/submodules/Stale copies of other repos
ARCHIVE52Old v4/archived contentHistorical, low priority
ENTERPRISE-PCF19Per-industry APQC PCF processesIndustry-specific context
CORE-OTHER19Inside coditect-core (various)Need case-by-case review
VENTURES18Customer/JV subdirectoriesCustomer project context
CORE-DOCS18coditect-core internal/docsSubdirectory context
CORE-DIST17Distribution/packagingBuild context
LABS14Lab research subdirectoriesResearch context
DEV12Dev submodule subdirectoriesDev project context
ROLLOUT-DOCS11rollout-master docs/Subdirectory context
CORE-TOOLS11coditect-core tools/Tool-specific context
PRODUCTS2Product subdirectoriesProduct context
CLOUD2Cloud subdirectoriesInfra context
OTHER8Various one-offsCase-by-case

9.4 Product Strategy: CLAUDE.md Control​

Requirement: CLAUDE.md must be CODITECT-controlled. Customers should not edit it.

Current enforcement:

  • Root-level: Symlinks to protected installation (76/78 correct)
  • Subdirectory: Regular files (375) — not controlled

Two categories of subdirectory CLAUDE.md:

  1. Root-level context (should symlink to master): These provide the core CODITECT framework directives. Already symlinked at root level.

  2. Subdirectory context (project-specific): Files like docs/security/CLAUDE.md, tools/mcp-context-graph/CLAUDE.md — these provide context about that specific subdirectory's codebase. These are NOT copies of the master; they contain different, location-specific content.

Recommendation:

  • Root-level CLAUDE.md in each repo: MUST be symlink (already 97.4% compliant)
  • Subdirectory CLAUDE.md files: These should also be symlinked to a CODITECT-controlled location OR generated/managed by CODITECT tooling, not hand-edited
  • The coditect-dev-generative-ui-development nested copies (171 files) should be cleaned up as they're stale duplicates from before the symlink convention was established
  1. Quick wins (dedup + stale fixes): Remove duplicates from rollout-master and MEMORY.md, fix stale counts
  2. Core CLAUDE.md optimization: Trim overexplained protocols, merge Agent System sections, add missing commands
  3. MEMORY.md cleanup: Move context-specific content to topic files
  4. Symlink enforcement: Script to audit and convert root-level CLAUDE.md files to symlinks
  5. Product strategy: Design CODITECT-managed subdirectory CLAUDE.md system