Claude Md Restructure

CLAUDE.md Restructure

Optimize CLAUDE.md files for session-continuous projects. Target: <8KB while preserving workflow-block.txt injection.

Quick Start

Most common workflow:

1. Analyze current state:

   python3 scripts/analyze_claude_md.py CLAUDE.md
   

2. Externalize Workflow (biggest impact, ~8KB savings):

   python3 scripts/externalize_workflow.py CLAUDE.md --dry-run
   python3 scripts/externalize_workflow.py CLAUDE.md
   

3. Migrate Decision Log (if >10 entries):

   python3 scripts/migrate_decision_log.py CLAUDE.md --dry-run
   python3 scripts/migrate_decision_log.py CLAUDE.md
   

4. Apply Modular Disclosure (outsource resolved sections):

   python3 scripts/apply_progressive_disclosure.py CLAUDE.md
   

5. Verify result:

   python3 scripts/analyze_claude_md.py CLAUDE.md
   # Expected: Exit code 0 (Healthy <8KB)
   

When to Use

Core Principles

1. Workflow Reference (nicht Inline-Injection)

Best Practice (seit TASK-026): Workflow-Dokumentation wird referenziert, nicht inline eingebettet.

"❌ Don't: @-file docs (embeds entire file on every run)" "✅ Do: 'For complex usage, see path/to/docs.md'" — Claude Code Best Practices

Vorher (Inline, ~10KB):

## Session-Continuous Workflow
[246 Zeilen vollständige Dokumentation]

Nachher (Reference, ~1.5KB):

## Session-Continuous Workflow
**Detaillierte Workflow-Dokumentation:** `${CLAUDE_PLUGIN_ROOT}/skills/project-init/references/WORKFLOW.md`
[Quick-Reference Tabellen]

Migration bestehender Projekte:

python3 scripts/externalize_workflow.py CLAUDE.md --dry-run
python3 scripts/externalize_workflow.py CLAUDE.md

Why: Claude liest die externe Datei nur bei Bedarf (via Read-Tool), nicht bei jedem Session-Start.

2. No HTML <details> Blocks

Anti-Pattern: <details> tags hide content inline instead of migrating it to separate files. This keeps file size high while giving the illusion of "Progressive Disclosure". Use Modular Disclosure (file migration with links) instead.

3. Modular Disclosure

Outsource historical/resolved content to separate files:

• Resolved Open Questions → eigene Datei oder entfernen
• Solved Challenges → docs/ oder entfernen
• Reference sections → separate Datei mit Link
• Large tables (>8 rows) → auslagern oder kuerzen

Detailed Workflows

Analysis Workflow

python3 scripts/analyze_claude_md.py CLAUDE.md

Output includes:

• Total size in bytes
• Section breakdown with visual bars
• Decision Log entry count
• Workflow injection status
• Specific recommendations

Exit codes:

• 0: Healthy (<8KB)
• 1: Needs optimization (8-15KB)
• 2: Critical (>15KB)

Decision Log Migration

# Preview changes:
python3 scripts/migrate_decision_log.py CLAUDE.md --dry-run

# Execute migration:
python3 scripts/migrate_decision_log.py CLAUDE.md

Creates:

• docs/DECISION-LOG.md with full history
• Backup: CLAUDE.md.pre-decision-migration.backup

Updates CLAUDE.md:

• Replaces inline table with link
• Keeps last 3 decisions as summary

Modular Disclosure

# Preview:
python3 scripts/apply_progressive_disclosure.py CLAUDE.md --dry-run

# Apply:
python3 scripts/apply_progressive_disclosure.py CLAUDE.md

Outsources to separate files or removes:

• Resolved Open Questions → entfernen oder auslagern
• Solved Challenges → entfernen oder auslagern
• Reference sections → separate Datei mit Link
• Large tables (>8 rows) → kuerzen oder auslagern

Template Reference

See assets/claude-md-template.txt for the optimized CLAUDE.md structure with:

• Size-targeted sections
• Injection markers
• Decision Log link pattern
• Placeholder variables

Variables:

• {{PROJECT_NAME}}, {{PROJECT_PURPOSE}}
• {{TECH_STACK}}, {{ARCHITECTURE_OVERVIEW}}
• {{WORKFLOW_BLOCK}} - workflow-block.txt content
• {{RECENT_DECISIONS}} - last 3 decisions
• {{DATE}}

Common Scenarios

Scenario 1: CLAUDE.md Over 15KB

User says: "My CLAUDE.md is 18KB, Claude loses focus"

Workflow:

1. Analyze: python3 scripts/analyze_claude_md.py CLAUDE.md
2. Migrate Decision Log (saves ~3-5KB)
3. Apply Modular Disclosure (outsource sections)
4. Verify: Exit code 0

Scenario 2: Many Decision Log Entries

User says: "Decision Log has 25 entries"

Workflow:

1. Migrate: python3 scripts/migrate_decision_log.py CLAUDE.md
2. Result: docs/DECISION-LOG.md created, CLAUDE.md reduced

Scenario 3: After project-init

User says: "Just ran /project-init, CLAUDE.md already 10KB"

Workflow:

1. This is expected (workflow-block.txt is ~8KB)
2. Check Decision Log size
3. If Decision Log empty: No action needed
4. Monitor as project grows

Scenario 4: Workflow Injection Missing

User says: "Session-Continuous Workflow section missing"

Workflow:

1. Check for injection markers in CLAUDE.md
2. If missing: Re-run /project-init or manually inject
3. Source: ${CLAUDE_PLUGIN_ROOT}/skills/project-init/assets/workflow-block.txt

Scenario 5: Old Workflow Block → Vault-First Compact Block

User says: "Migrate my project to Vault-First" or detected automatically

Detects three patterns:

1. Full Inline Injection (~10KB, <!-- BEGIN:WORKFLOW-INJECTION --> markers)
2. Old Reference-Only Block (~1.5KB, references WORKFLOW.md but no Vault-First)
3. Old Reference Block without Feature Detection (no obsidian.com version)

Workflow:

python3 scripts/externalize_workflow.py CLAUDE.md --dry-run
python3 scripts/externalize_workflow.py CLAUDE.md

Result: Replaces any old pattern with Vault-First Compact Block (~4KB) that includes:

• Feature Detection (obsidian.com version)
• Dual-path: Vault-First + Local Fallback
• session-workflow skill reference for details
• Compact enough to stay inline in CLAUDE.md

Guardrails

Integration

With project-init

• project-init injects workflow-block.txt
• This skill preserves injection markers
• Re-injection safe after optimization

With session-refresh

• session-refresh triggers context optimization
• Consider running this skill when CLAUDE.md > 8KB
• Not auto-triggered (manual decision)

With project-doc-restructure

• project-doc-restructure handles PROJEKT.md
• This skill handles CLAUDE.md
• Different algorithms for different content types

Size Targets

Mit Vault-First Compact Block: Das 8KB-Ziel ist realistisch:

• Compact Block: ~4KB (statt ~10KB Full Injection oder ~1.5KB old reference)
• Compact Block enthaelt: Feature Detection, Vault-First/Local Fallback, Session Lifecycle
• Detail-Referenz: session-workflow Skill (on-demand, nicht inline)

Troubleshooting

Issue: "Exit code 2 after optimization" Cause: workflow-block.txt alone is ~8KB Fix: Accept 10-12KB as realistic target for projects with full workflow injection

Issue: "Decision Log not found" Cause: Non-standard heading format Fix: Ensure heading is ## Decision Log (exact)

Issue: "Injection markers missing after optimization" Cause: Manual editing removed markers Fix: Re-add markers around Session-Continuous Workflow section

Issue: "/project-init fails after optimization" Cause: "Session-Continuous Workflow" string removed Fix: Ensure this exact string exists in CLAUDE.md (in heading or content)

Success Criteria

After optimization:

• Size < 12KB (realistic) or < 8KB (ideal)
• Decision Log externalized to docs/DECISION-LOG.md
• Workflow injection markers present
• "Session-Continuous Workflow" string exists
• Modular Disclosure applied (resolved sections outsourced or removed)
• /run-next-tasks still works