1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
# Context Maintenance Guide
Keep AI context focused on **actionable, current information** while archiving **historical details** for reference.
**Principle**: Answer "What am I working on **now**?" not "What did we do 6 months ago?"
---
## File Organization Hierarchy
### Tier 1: Critical (Always Loaded)
Essential for every session, remain lean:
- **CLAUDE.md** / **GEMINI.md** - Agent configuration (~30 lines)
- **PROJECT_CONTEXT.md** - High-level overview (~200 lines)
- **TODO.md** - Active tasks only (~300 lines)
- **README.md** - Quick start guide
### Tier 2: Technical Reference (Always Loaded)
Essential for daily work:
- **doc/HOWTO.md** - Usage instructions
- **doc/CONTRIBUTING.md** - Coding guidelines
- **doc/AI_RULES.md** - Agent rules
### Tier 3: Design Docs (Load On-Demand)
Load when working on specific subsystems:
- **doc/ASSET_SYSTEM.md**, **doc/BUILD.md**, **doc/3D.md**
- **doc/SPEC_EDITOR.md**, **doc/TRACKER.md**, **doc/PROCEDURAL.md**
### Tier 4: Historical Archive (Load Rarely)
Reference for past decisions:
- **doc/COMPLETED.md**, **doc/HANDOFF*.md**
- **doc/*_ANALYSIS.md**, **doc/*_SUMMARY.md**
---
## Maintenance Schedule
### After Major Milestone
1. Move completion notes from TODO.md to COMPLETED.md
2. Update PROJECT_CONTEXT.md "Current Status"
3. Archive detailed plans from TODO.md
4. Update "Next Up" section
### Monthly Review
1. Archive tasks completed >30 days ago
2. Remove old "Recently Completed" items
3. Move temp analysis docs to doc/
4. Verify agent configs load only Tier 1-2
### On-Demand (Context Bloat)
1. Run: `wc -w CLAUDE.md PROJECT_CONTEXT.md TODO.md`
2. Check for oversized files (>500 lines in Tier 1-2)
3. Archive verbose sections
4. Split large design docs
---
## Decision Matrix: What to Archive?
| Content Type | Action | Keep in Main Docs |
|--------------|--------|------------------|
| Completed tasks (>30 days) | ✅ Archive | 2-line summary |
| Detailed plans (>100 lines) | ✅ Archive | Goal + approach |
| Analysis of resolved issues | ✅ Archive | Root cause + solution |
| Deprecated designs | ✅ Archive | Pointer to archive |
| Major architectural decisions | ⚠️ Summarize | 3-line summary |
| Performance optimizations | ⚠️ Summarize | Before/after metrics |
| Current priorities | ❌ Keep | Full details |
| Coding guidelines | ❌ Keep | Full details |
| Active constraints | ❌ Keep | Full details |
**Quick rule**: If >30 days old AND >50 lines of detail → Archive with 2-line summary.
---
## Red Flags (Clean Up Now)
### File Size
- PROJECT_CONTEXT.md >500 lines (critical: >800)
- TODO.md >800 lines (critical: >1200)
- Any Tier 1-2 file >1000 lines
### Content
- "Recently Completed" >100 lines in PROJECT_CONTEXT.md
- TODO.md has tasks marked `[DONE]` >30 days ago
- Detailed plans (>50 lines) for completed tasks
- Analysis docs in root directory (move to doc/)
### Performance
- AI responses noticeably slower
- Token usage >50K on initial load
- Repeated "let me read..." for basic info
---
## Archiving Workflow
**Quick steps:**
1. Find content: `grep -n "\[x\].*202[0-9]" TODO.md`
2. Move to COMPLETED.md with format:
```markdown
- [x] **Task Name**: Brief summary (2-3 bullets max, one-line result)
```
3. Replace verbose sections: `**Note**: See doc/COMPLETED.md`
4. Update agent configs if files moved
5. Verify: `grep -r "@doc/" CLAUDE.md GEMINI.md`
**File moves:**
```bash
git mv OLDFILE.md doc/OLDFILE.md
# Update CLAUDE.md/GEMINI.md references
# Update cross-references: grep -r "OLDFILE.md" *.md doc/*.md
git commit -m "docs: Move OLDFILE.md to doc/"
```
---
## Context Size Targets
| File | Optimal | Warning | Critical |
|------|---------|---------|----------|
| CLAUDE.md | <30 lines | - | - |
| PROJECT_CONTEXT.md | <300 lines | >500 | >800 |
| TODO.md | <500 lines | >800 | >1200 |
| Total Tier 1-2 | <10K words | >15K | >20K |
---
## Examples
### Good: Lean TODO.md
```markdown
- [ ] **Task #72: Audio Compression**
- Goal: Reduce .spec sizes by 50%
- Approach: uint16_t quantization, RLE
- See: doc/AUDIO_COMPRESSION_PLAN.md
```
### Bad: Verbose TODO.md
```markdown
- [ ] **Task #72: Audio Compression**
- Goal: Reduce .spec sizes by 50%
- Background: float32 wasteful... [20 lines]
- Step 1: Create interface
- Define CompressorBase [100+ lines]
```
### Good: Lean PROJECT_CONTEXT.md
```markdown
### Current Status
- Audio: Stable, 93% test coverage, variable tempo
- 3D: Hybrid SDF/raster, BVH acceleration
```
### Bad: Verbose PROJECT_CONTEXT.md
```markdown
### Recently Completed
#### Audio Peak Fix (Feb 7)
- Real-Time Peak: Fixed bug where... [20 lines]
- Decay Optimization: Changed 0.95 to 0.7... [15 lines]
[200+ lines of milestones]
```
---
## Common Mistakes
### ❌ Don't:
- Archive active tasks or priorities
- Remove essential architectural context
- Break cross-references without updating
- Delete content (archive instead)
- Keep "Recently Completed" >3 months
### ✅ Do:
- Preserve key insights in summaries
- Update file references after moves
- Keep audit trail (note where moved)
- Regular small cleanups (not big purges)
---
## Quick Decision Test
If unsure whether to archive:
1. Completed >30 days ago? → Archive
2. Detailed plan (>50 lines)? → Archive (keep 2-line summary)
3. Needed next week? → Keep
4. New contributor needs immediately? → Keep
When in doubt, **archive with pointer**. Better clean context than bloat.
---
*Last updated: February 9, 2026*
|
