refactor: reduce CLAUDE.md size by 80% for better performance

[markturansky]

Summary

Reduces CLAUDE.md from 1,168 to 237 lines (80% reduction) by eliminating content duplication and replacing inlined sections with pointers to existing documentation in the memory system.

Benefits

🚀 Performance Improvements

• Faster Claude Code context loading — 80% smaller primary instruction file
• Reduced token usage — Less redundant content across instruction files
• Improved readability — CLAUDE.md is now a focused index rather than a kitchen sink

📚 Better Documentation Architecture

• Eliminates duplication — Content exists in one canonical location
• Leverages existing memory system — Uses .claude/context/ and .claude/patterns/ as intended
• Maintains complete coverage — All information still accessible via pointers
• No new files created — Works within established documentation structure

🎯 Specific Improvements

• Backend/operator patterns → .claude/context/backend-development.md (extended)
• Frontend standards → .claude/context/frontend-development.md
• Security patterns → .claude/context/security-standards.md
• Error handling → .claude/patterns/error-handling.md
• Testing guides → docs/testing/ (existing files)
• Local development → docs/developer/local-development/ (existing files)

Changes Made

Files Modified (2 total)

1. CLAUDE.md: 1,168 → 237 lines

   • Kept: Project overview, core architecture, memory system index, essential commands, configuration standards
   • Replaced: Detailed implementation patterns with → Load file.md pointers

2. .claude/context/backend-development.md: 129 → 397 lines

   • Added: Operator patterns, API design, package organization, common mistakes (content that was unique to CLAUDE.md)

Content Organization

• Essential info kept inline: Project overview, architecture flow, quick commands
• Detailed patterns externalized: Implementation specifics moved to specialized context files
• Clear navigation: → pointer syntax for easy file loading
• No content lost: Everything accessible via existing memory system

Validation

✅ All content from original CLAUDE.md is preserved
✅ No new files created — uses existing documentation structure
✅ Pointers reference valid existing files
✅ Essential quick-reference info remains in CLAUDE.md
✅ Memory system table updated with comprehensive coverage

Example Usage

Before (everything inlined):

• CLAUDE.md contained 535 lines of backend patterns, 79 lines of Langfuse config, etc.

After (pointer-based):

## Backend and Operator Development Standards

**IMPORTANT**: When working on backend or operator code, you MUST load the detailed context files:

- **→ `.claude/context/backend-development.md`** — Critical rules, operator patterns, API design, common mistakes
- **→ `.claude/patterns/k8s-client-usage.md`** — User-scoped vs service account client patterns  
- **→ `.claude/patterns/error-handling.md`** — Handler and operator error patterns

This maintains the same guidance quality while dramatically improving load performance and eliminating maintenance burden from duplicate content.

🤖 Generated with Claude Code

[github-actions]

Claude Code Review

Summary

This PR successfully refactors CLAUDE.md to reduce duplication and improve maintainability by consolidating content into the existing memory system. The refactoring is well-executed with clear benefits for performance and documentation architecture.

Overall Assessment: ✅ APPROVED - This is a high-quality refactoring that improves the codebase architecture.

Issues by Severity

🚫 Blocker Issues

None - No blocking issues found.

🔴 Critical Issues

None - No critical issues found.

🟡 Major Issues

None - No major issues found.

🔵 Minor Issues

None - No minor issues found.

Positive Highlights

✅ Architecture & Design

1. Excellent DRY Principle Application

   • Eliminates 931 lines of duplicated content (80% reduction)
   • Content now exists in a single canonical location
   • Leverages existing memory system as intended

2. Clear Navigation Pattern

   • Consistent → pointer syntax makes file loading explicit
   • Quick reference table provides excellent overview
   • Memory system index is well-organized and comprehensive

3. No Information Loss

   • All content from original CLAUDE.md preserved
   • Better organized by moving detailed patterns to specialized files
   • Maintains complete coverage through pointer system

✅ Code Quality

1. Smart Content Organization

   • .claude/context/backend-development.md now comprehensively covers backend/operator patterns (129 → 397 lines)
   • Appropriate separation: essential info inline, detailed patterns externalized
   • Backend development context now includes operator patterns, API design, package organization, and common mistakes

2. Consistent with Project Standards

   • Follows the documented pattern of colocating docs with code
   • Aligns with "default to improving existing documentation" standard
   • No new files created - works within established structure

3. Improved Readability

   • CLAUDE.md transformed from "kitchen sink" to focused index
   • Easier to scan and find relevant information
   • Clear separation of concerns

✅ Performance Benefits

1. Faster Context Loading

   • 80% smaller primary instruction file
   • Reduced token usage when loading base context
   • Targeted loading of only relevant context files

2. Better Scalability

   • Future additions can go to specialized files
   • Reduces risk of CLAUDE.md growing unwieldy again
   • Easier maintenance with single source of truth

✅ Testing & Validation

1. Thorough Verification

   • All pointers reference valid existing files
   • Essential quick-reference info remains accessible
   • Memory system table updated comprehensively

2. No Breaking Changes

   • All referenced files exist
   • No functional changes to code
   • Pure documentation refactoring

Technical Review

Files Modified

1. CLAUDE.md (1,168 → 237 lines)

• ✅ Retained essential project overview and architecture
• ✅ Maintained critical quick-reference commands
• ✅ Preserved configuration standards
• ✅ Clear pointers to detailed documentation
• ✅ No content removed, only relocated

2. .claude/context/backend-development.md (129 → 397 lines)

• ✅ Added comprehensive operator patterns
• ✅ Included API design patterns
• ✅ Added package organization guidance
• ✅ Expanded common mistakes section
• ✅ Added reference files listing
• ✅ All additions follow established code patterns

Alignment with Memory System Standards

✅ backend-development.md: Now comprehensive single source for backend/operator work
✅ frontend-development.md: Already loaded, referenced correctly
✅ security-standards.md: Already loaded, referenced correctly
✅ k8s-client-usage.md: Pattern file correctly referenced
✅ error-handling.md: Pattern file correctly referenced
✅ react-query-usage.md: Pattern file correctly referenced

Documentation Standards Compliance

✅ Follows "default to improving existing documentation" principle
✅ Uses existing memory system structure
✅ Colocates detailed patterns with relevant context
✅ Maintains clear navigation
✅ No unnecessary file proliferation

Recommendations

1. Consider Adding a Migration Note (Optional)

If developers have bookmarked specific sections of CLAUDE.md, consider adding a brief comment at the top like:

> **Note:** As of [date], detailed implementation patterns have been consolidated into the memory system files referenced below. This improves load performance while maintaining complete coverage.

Priority: Low - Nice to have but not required

2. Update Any CI/CD Documentation References (Optional)

Verify that no CI/CD workflows or scripts explicitly reference line numbers or sections in CLAUDE.md that have been relocated.

# Quick check
git grep -n "CLAUDE.md" .github/workflows/

Priority: Low - Likely not an issue, but worth a quick verification

3. Consider a Follow-up PR for Consistency (Future)

The memory system pattern is now well-established. Consider a follow-up to apply similar treatment to other potentially duplicated content across the codebase.

Priority: Low - Future enhancement, not blocking

Final Assessment

Verdict: ✅ LGTM - Excellent Refactoring

This PR demonstrates:

• Strong understanding of DRY principles
• Thoughtful documentation architecture
• Careful execution with no information loss
• Clear performance benefits
• Alignment with project standards

The refactoring successfully achieves its goals:

• ✅ 80% reduction in CLAUDE.md size
• ✅ Eliminates content duplication
• ✅ Leverages existing memory system
• ✅ Maintains complete coverage
• ✅ Improves readability and navigation
• ✅ No new files created

Recommendation: Approve and merge. This is a model refactoring that improves the codebase quality.

---

🤖 Generated by Claude Code (Sonnet 4.5)

---

🔍 View AI decision process (logs available for 90 days)

📋 View memory system files loaded (click to expand)

What Amber Loaded for Code Review

Amber automatically loaded these repository standards from the memory system:

1. CLAUDE.md - Master project instructions, development standards
2. backend-development.md - Go backend, K8s integration patterns
3. frontend-development.md - NextJS, Shadcn UI, React Query patterns
4. security-standards.md - Auth, RBAC, token handling
5. k8s-client-usage.md - User token vs service account patterns
6. error-handling.md - Consistent error patterns
7. react-query-usage.md - Data fetching patterns

Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines.

[markturansky]

see also #643

[ktdreyer]

I checked out this branch, asked claude to review it, and did some light examination.

Before this PR, I see the following warning in claude:

Large CLAUDE.md will impact performance (40.8k chars > 40.0k) • /memory to edit

After this change, the warning goes away.