managarten/docs/archive/RESTRUCTURE_2025-12-16.md

Documentation Restructure - December 16, 2025

Summary

Restructured documentation based on industry best practices from HackerNews discussion and HumanLayer blog post on writing effective CLAUDE.md files.

Changes Made

Root CLAUDE.md

• Before: 678 lines, 22 KB
• After: 176 lines, 5.7 KB
• Reduction: 74% smaller

What Was Removed

• Detailed project tables (moved conceptually to docs/)
• Extensive authentication code examples (kept brief examples, reference .claude/guidelines/)
• Object storage implementation details
• Landing page deployment procedures
• Detailed environment variable setup
• Archived projects list (13 projects)
• Code quality infrastructure TODO section

What Was Added

• Critical Gotchas section (5 key issues Claude frequently gets wrong)
• Verification signature (🏗️ ManaCore Monorepo) to confirm Claude read the file
• Clearer signposting to detailed documentation
• Focus on universally applicable patterns only

Documentation Organization

New Structure

docs/
├── README.md                 # Navigation index (NEW)
├── getting-started/          # (NEW - empty for now)
├── architecture/             # (NEW - empty for now)
├── development/              # (NEW - empty for now)
├── deployment/               # (NEW - empty for now)
├── operations/               # (NEW - empty for now)
├── reference/                # (NEW - empty for now)
└── archive/                  # (NEW)

Files Deleted

• ENV_AUDIT_SUMMARY.md - Outdated audit (Dec 1, 2024)
• ENV_BACKEND_MATRIX.md - Outdated audit
• ENV_CONFIGURATION_AUDIT.md - Outdated audit
• README_ENV_AUDIT.md - Outdated audit
• DEPENDENCY_ALIGNMENT.md - Point-in-time snapshot

Files Archived

Moved to docs/archive/:

• DOCKER_SETUP_ANALYSIS.md - Analysis document
• BACKEND_ARCHITECTURE.md - Possibly outdated (25 KB)
• PROJECT_OVERVIEW.md - Possibly outdated (41 KB)
• TESTING_SUMMARY.md - Outdated test count
• TESTING_IMPLEMENTATION_GUIDE.md - Superseded
• CHANGELOG_2025-11-24.md - Historical
• HETZNER_DEPLOYMENT_SUMMARY.md - Redundant with other deployment docs

Best Practices Applied

1. Instruction Budget Management

   • Kept only high-signal, universally applicable information
   • Reduced from 678 lines to 176 lines
   • AI instruction budget is ~150-200 total; we now use ~176

2. Progressive Disclosure

   • Main CLAUDE.md is concise entry point
   • Links to detailed .claude/guidelines/ for code patterns
   • Links to docs/ for operational procedures

3. Critical Gotchas

   • Turborepo infinite loops
   • Svelte 5 runes only
   • Auth integration requirements
   • Go-style error handling
   • Environment variable prefixes

4. Verification Mechanism

   • Added project signature requirement (🏗️ ManaCore Monorepo)
   • Helps detect when Claude stops following instructions

Backup

Original CLAUDE.md saved as CLAUDE.md.backup (22 KB, 678 lines).

Metrics

Metric	Before	After	Change
CLAUDE.md lines	678	176	-74%
CLAUDE.md size	22 KB	5.7 KB	-74%
docs/ files	50+	43	-7 deleted, -7 archived
Documented projects	18 (active + archived)	6 (active only)	-67%

Next Steps (Phase 2)

Future improvements to consider:

1. Consolidate Environment Docs

   • Merge remaining env docs into single docs/reference/environment-matrix.md

2. Split DEPLOYMENT_ARCHITECTURE.md

   • Currently 2,814 lines (81 KB)
   • Should be 6-8 separate documents

3. Reorganize docs/

   • Move files into logical subdirectories
   • Create topic-based navigation

4. Consolidate Authentication Docs

   • Keep .claude/guidelines/authentication.md (code patterns)
   • Keep separate (already exists in .claude/guidelines/)

References

• HN Discussion on CLAUDE.md
• HumanLayer: Writing a Good CLAUDE.md

Key Insights

1. Length matters - Shorter files = better AI performance
2. Universal over specific - Only include broadly applicable patterns
3. Verification is critical - Add canary instructions to detect compliance
4. Progressive disclosure - Link to details rather than inline everything
5. Information density - Every line should justify its inclusion