mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-21 04:06:43 +02:00
ad495b2044
Optimize CLAUDE.md based on industry best practices from HN and HumanLayer:
Changes:
- Trim CLAUDE.md from 678 to 176 lines (74% reduction, 5.7KB)
- Add "Critical Gotchas" section for common AI mistakes
- Add verification signature (🏗️ ManaCore Monorepo)
- Create docs/README.md navigation hub with "I want to..." index
- Delete 5 outdated audit files (ENV_AUDIT_*, DEPENDENCY_ALIGNMENT)
- Archive 7 analysis/historical docs to docs/archive/
- Keep authentication docs separate per request (.claude/guidelines/)
Benefits:
- Better AI instruction adherence (within ~150-200 line budget)
- Progressive disclosure via signposting to detailed docs
- Cleaner navigation with topic-based organization
- Reduced maintenance burden (stale docs archived)
Backup: CLAUDE.md.backup preserves original 678-line version
Change log: docs/archive/RESTRUCTURE_2025-12-16.md
127 lines
4.3 KiB
Markdown
127 lines
4.3 KiB
Markdown
# 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](https://news.ycombinator.com/item?id=46098838)
|
|
- [HumanLayer: Writing a Good CLAUDE.md](https://www.humanlayer.dev/blog/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
|