108 lines
4.2 KiB
Markdown
108 lines
4.2 KiB
Markdown
# Context Management
|
|
|
|
Context is the most critical resource in a Claude Code session. Manage it actively.
|
|
|
|
## File-Backed State (Primary Strategy)
|
|
|
|
**The file is the memory, not the conversation.** Conversations are ephemeral and
|
|
will be compacted or lost. Files on disk persist across compactions and session crashes.
|
|
|
|
### Session State File
|
|
|
|
Maintain `production/session-state/active.md` as a living checkpoint. Update it
|
|
after each significant milestone:
|
|
|
|
- Design section approved and written to file
|
|
- Architecture decision made
|
|
- Implementation milestone reached
|
|
- Test results obtained
|
|
|
|
The state file should contain: current task, progress checklist, key decisions
|
|
made, files being worked on, and open questions.
|
|
|
|
### Status Line Block (Production+ only)
|
|
|
|
When the project is in Production, Polish, or Release stage, include a structured
|
|
status block in `active.md` that the status line script can parse:
|
|
|
|
```markdown
|
|
<!-- STATUS -->
|
|
Epic: Combat System
|
|
Feature: Melee Combat
|
|
Task: Implement hitbox detection
|
|
<!-- /STATUS -->
|
|
```
|
|
|
|
- All three fields (Epic, Feature, Task) are optional — include only what applies
|
|
- Update this block when switching focus areas
|
|
- The status line displays it as a breadcrumb: `Combat System > Melee Combat > Hitboxes`
|
|
- Remove or empty the block when no active work focus exists
|
|
|
|
After any disruption (compaction, crash, `/clear`), read the state file first.
|
|
|
|
### Incremental File Writing
|
|
|
|
When creating multi-section documents (design docs, architecture docs, lore entries):
|
|
|
|
1. Create the file immediately with a skeleton (all section headers, empty bodies)
|
|
2. Discuss and draft one section at a time in conversation
|
|
3. Write each section to the file as soon as it's approved
|
|
4. Update the session state file after each section
|
|
5. After writing a section, previous discussion about that section can be safely
|
|
compacted — the decisions are in the file
|
|
|
|
This keeps the context window holding only the *current* section's discussion
|
|
(~3-5k tokens) instead of the entire document's conversation history (~30-50k tokens).
|
|
|
|
## Proactive Compaction
|
|
|
|
- **Compact proactively** at ~60-70% context usage, not reactively at the limit
|
|
- **Use `/clear`** between unrelated tasks, or after 2+ failed correction attempts
|
|
- **Natural compaction points:** after writing a section to file, after committing,
|
|
after completing a task, before starting a new topic
|
|
- **Focused compaction:** `/compact Focus on [current task] — sections 1-3 are
|
|
written to file, working on section 4`
|
|
|
|
## Context Budgets by Task Type
|
|
|
|
- Light (read/review): ~3k tokens startup
|
|
- Medium (implement feature): ~8k tokens
|
|
- Heavy (multi-system refactor): ~15k tokens
|
|
|
|
## Subagent Delegation
|
|
|
|
Use subagents for research and exploration to keep the main session clean.
|
|
Subagents run in their own context window and return only summaries:
|
|
|
|
- **Use subagents** when investigating across multiple files, exploring unfamiliar code,
|
|
or doing research that would consume >5k tokens of file reads
|
|
- **Use direct reads** when you know exactly which 1-2 files to check
|
|
- Subagents do not inherit conversation history — provide full context in the prompt
|
|
|
|
## Compaction Instructions
|
|
|
|
When context is compacted, preserve the following in the summary:
|
|
|
|
- Reference to `production/session-state/active.md` (read it to recover state)
|
|
- List of files modified in this session and their purpose
|
|
- Any architectural decisions made and their rationale
|
|
- Active sprint tasks and their current status
|
|
- Agent invocations and their outcomes (success/failure/blocked)
|
|
- Test results (pass/fail counts, specific failures)
|
|
- Unresolved blockers or questions awaiting user input
|
|
- The current task and what step we are on
|
|
- Which sections of the current document are written to file vs. still in progress
|
|
|
|
**After compaction:** Read `production/session-state/active.md` and any files being
|
|
actively worked on to recover full context. The files contain the decisions; the
|
|
conversation history is secondary.
|
|
|
|
## Recovery After Session Crash
|
|
|
|
If a session dies ("prompt too long") or you start a new session to continue work:
|
|
|
|
1. The `session-start.sh` hook will detect and preview `active.md` automatically
|
|
2. Read the full state file for context
|
|
3. Read the partially-completed file(s) listed in the state
|
|
4. Continue from the next incomplete section or task
|