Optimize CLAUDE.md as Routing Layer for Memory System

[jeremyeder]

Overview

Optimize CLAUDE.md to work as a "routing layer" that points to the memory system files rather than containing all context inline. This reduces the file from ~2000+ lines to ~1200-1500 lines while making deep context available on-demand.

Prerequisite: Memory system implementation complete (issue #357)

Problem

Current CLAUDE.md is monolithic:

• ❌ ~2000+ lines loaded every session
• ❌ Detailed examples inline (100+ line code blocks)
• ❌ Historical decision context mixed with rules
• ❌ Difficult to find critical rules among examples

Solution

Transform CLAUDE.md into a routing layer:

• ✅ ~1200-1500 lines focused on essentials
• ✅ Memory System Guide (what to load when)
• ✅ Universal rules inline (always apply)
• ✅ Deep patterns in memory files (load on-demand)

Coldstartable Implementation Prompt

File: docs/implementation-plans/claude-md-optimization.md

Execute with:

Claude, optimize CLAUDE.md using the coldstartable plan in:
docs/implementation-plans/claude-md-optimization.md

This plan transforms CLAUDE.md from a monolithic context file into a 
routing layer that points to memory system files (.claude/context/, 
.claude/patterns/, docs/adr/). Follow the plan exactly:

1. Add Memory System Guide section (complete content provided)
2. Slim down Backend/Frontend sections with links to context files
3. Update security/testing sections with memory file references
4. Remove detailed examples now in memory files
5. Validate with checklist

Goal: Reduce CLAUDE.md to ~1200-1500 lines while keeping all critical 
rules and adding navigation to deep context.

What Changes

Stays in CLAUDE.md

• ✅ Universal rules (NEVER violate, ALWAYS apply)
• ✅ Build/deploy commands
• ✅ Project structure overview
• ✅ Critical backend/frontend rules (5-10 per component)
• ✅ Memory System Guide (NEW)

Moves to Memory Files

• ❌ Detailed code examples (>20 lines) → context/pattern files
• ❌ "How to" step-by-step guides → context files
• ❌ Historical decision context → ADRs
• ❌ Anti-patterns with explanations → pattern files
• ❌ Component-specific deep patterns → context files

Example Transformation

Before (Current)

### Kubernetes Client Patterns

**User-Scoped Clients** (for API operations):

[100+ lines of detailed examples, anti-patterns, decision trees...]

After (Optimized)

### Kubernetes Client Patterns

**CRITICAL RULE:** Always use user-scoped clients for API operations.

**For detailed patterns:** Load `.claude/patterns/k8s-client-usage.md`

**Quick reference:**
- User-scoped: All user operations
- Service account: ONLY privileged ops after validation

**See also:** ADR-0002 (User Token Authentication)

Changes by Section

Section	Action	New Reference
Memory System Guide	➕ Add new section	Links to all memory files
Backend Standards	⚠️ Slim down	.claude/context/backend-development.md
Frontend Standards	⚠️ Slim down	.claude/context/frontend-development.md
K8s Client Patterns	⚠️ Slim down	.claude/patterns/k8s-client-usage.md
Error Handling	⚠️ Slim down	.claude/patterns/error-handling.md
React Query	⚠️ Slim down	.claude/patterns/react-query-usage.md
Security Patterns	⚠️ Slim down	.claude/context/security-standards.md
Architecture Decisions	❌ Remove	docs/adr/*.md

Success Criteria

• Memory System Guide section added after Table of Contents
• Backend section reduced with links to .claude/context/backend-development.md
• Frontend section reduced with links to .claude/context/frontend-development.md
• All detailed examples (>20 lines) moved to memory files
• File size reduced by 30-40% (2000+ → 1200-1500 lines)
• All critical rules still present and easy to find
• Table of Contents updated
• Test with Claude: "Claude, load backend-development context and help me add an endpoint"

Implementation Steps

Full step-by-step instructions: docs/implementation-plans/claude-md-optimization.md

1. Add Memory System Guide section (complete content in plan)
2. Update Backend Development Standards section
3. Update Frontend Development Standards section
4. Add quick links to other sections (security, testing)
5. Update Table of Contents
6. Validate changes with checklist

Validation

After implementation:

# Verify memory system section exists
grep -A 50 "## Memory System Guide" CLAUDE.md

# Verify context file links present
grep "\.claude/context/" CLAUDE.md

# Verify file size reduced
wc -l CLAUDE.md
# Target: 1200-1500 lines (down from 2000+)

# Test with Claude
# "Claude, load the backend-development context file and help me 
#  understand K8s client usage patterns"

Dependencies

Blocked by: Issue #357 (Memory System Implementation)

• Must complete memory system first (context files, patterns, ADRs)
• This issue optimizes CLAUDE.md to reference those files

Rollback Plan

If optimization causes issues:

git checkout HEAD -- CLAUDE.md

Memory files are additive, so they don't need rollback.

Benefits

1. Faster context loading: Claude loads ~1200 lines instead of 2000+
2. Better discoverability: Clear signposts to deep context
3. Easier maintenance: Update patterns in one place (memory files)
4. On-demand depth: Load deep context only when needed
5. Clearer rules: Critical rules stand out without noise

Related

• Implementation plan: docs/implementation-plans/claude-md-optimization.md
• Prerequisite: Issue Implement Memory System for Better Claude Code Context #357 (Memory System Implementation)
• Related files: .claude/context/*.md, .claude/patterns/*.md, docs/adr/*.md

---

Ready to execute once issue #357 is complete.

[jeremyeder]

Coldstart Execution Prompt

Copy-paste this prompt to execute the CLAUDE.md optimization:

---

Claude, optimize CLAUDE.md using the coldstartable plan in docs/implementation-plans/claude-md-optimization.md

Context: This plan transforms CLAUDE.md from a monolithic ~2000+ line context file into a ~1200-1500 line routing layer that points to memory system files (.claude/context/, .claude/patterns/, docs/adr/).

Your task:

1. Add Memory System Guide section (after Table of Contents)

   • Complete content provided in the plan
   • Includes table of memory types, available context files, patterns, ADRs
   • Example prompts for common scenarios
   • Quick reference mapping tasks to memory files

2. Slim down Backend Development Standards section

   • Keep critical rules (5 rules that never have exceptions)
   • Add links to .claude/context/backend-development.md
   • Replace detailed examples with brief patterns + links
   • Remove anti-patterns (now in pattern files)

3. Slim down Frontend Development Standards section

   • Keep critical rules (zero any, Shadcn only, React Query only, etc.)
   • Add links to .claude/context/frontend-development.md
   • Replace detailed examples with links to pattern files

4. Update other sections with memory file references

   • Security section → link to .claude/context/security-standards.md
   • Testing section → link to E2E guide
   • Error handling → link to .claude/patterns/error-handling.md

5. Update Table of Contents to include Memory System Guide

6. Validate changes:

   # Verify memory system section exists
   grep -A 50 "## Memory System Guide" CLAUDE.md
   
   # Verify file size reduced
   wc -l CLAUDE.md
   # Target: 1200-1500 lines (down from 2000+)
   
   # Verify links are correct
   grep "\.claude/context/" CLAUDE.md
   grep "\.claude/patterns/" CLAUDE.md
   grep "docs/adr/" CLAUDE.md

Goal: Reduce CLAUDE.md to ~1200-1500 lines while keeping all critical rules and adding clear navigation to deep context in memory files.

All content and exact changes are specified in the plan - no decisions needed during execution.

---

[cgwalters]

#360 should close this right? Except that's also mixing in the "repomix" stuff.

There's an inbound textual (partial semantic) conflict with #366 to reconcile. Also I have a design-level question in #360 (comment)