Document & Clear Pattern
A context management technique where you persist important state to external files, then explicitly clear the AI's context to start fresh with only relevant information.
The Document & Clear pattern is a practitioner-tested technique for maintaining high-quality AI output during long development sessions. It addresses the fundamental limitation of AI context windows: as conversations grow, quality degrades because older context gets compressed or dropped unpredictably.
The pattern has three phases: Document (save important state to external files), Clear (explicitly reset the AI's context), and Resume (start fresh by reading only the relevant files). This gives you explicit control over what the AI "remembers" instead of relying on automatic context compaction.
When to clear: Watch for symptoms of context bloat—the AI forgetting earlier decisions, giving inconsistent responses, asking questions you already answered, or producing noticeably lower-quality output. HumanLayer recommends keeping context utilization in the 40-60% range; Shankar recommends clearing aggressively when you shift to a new task.
Tool support: Both Claude Code and GitHub Copilot CLI now support the /clear command with identical behavior. Cursor users can start a new Composer session. The pattern is tool-agnostic because the documented state lives in your filesystem, not in any tool's memory.
Example workflow: Before ending a session, ask the AI to write a progress summary to docs/progress.md with completed work, key decisions, blockers, and next steps. Then use /clear to reset. When resuming, simply ask the AI to read the progress file and continue. The AI gets only relevant context with no accumulated noise.
This integrates naturally with git: your progress files become part of your version history, creating a trail of decisions and state changes that persist beyond any single AI session. For complex projects spanning multiple days, this external memory is more reliable than any context window.
Key Takeaways
- Keep context utilization in the 40-60% range; clear when switching tasks or quality degrades
- Document state to external files BEFORE clearing to create durable external memory
- Both Claude Code and GitHub Copilot support /clear - the tools have converged
- Auto-compaction is opaque and error-prone; explicit clearing gives you control
- Run /context mid-session to monitor token utilization
- Works naturally with git: progress files become part of your version history
Visual Overview
In This Platform
This platform uses a similar pattern: the build process captures state to build/copilot_survey.json and build/learning_platform.json. These artifacts are the 'documented state' that can be used by other tools without needing to understand the full source. Our CLAUDE.md file serves as persistent context that survives between sessions.
- CLAUDE.md
- build.js