Context Management

Context is a working set, not a storage layer. Keep durable knowledge in files and keep the active session focused on the decision being made now.

Durable Context

Use files for information that must survive sessions:

• CLAUDE.md for project rules.
• ADRs for architectural decisions.
• Test files for expected behavior.
• Issue or PR descriptions for task goals.
• Changelogs for release facts.

Do not rely on a long chat transcript as the only place where decisions live.

Compaction

Before compaction, ask for a concise state summary:

Summarize current goal, files changed, commands run, unresolved risks, and exact next step.

After resuming, sanity-check the summary against the worktree:

git status --short
git diff --stat

Recap Discipline

Good recaps are factual:

• Current user request.
• Assumptions.
• Files touched.
• Tests passed or failed.
• Known blockers.

They should not include every exploratory detail.

Token Discipline

• Read only the file ranges needed for the next decision.
• Prefer rg over broad file dumps.
• Summarize long docs instead of pasting them into the prompt.
• Move stable instructions into repository files.
• Close loops by updating tests or docs when behavior changes.