Claude Code compaction strategy for long coding tasks

A good Claude Code compaction strategy treats compaction as a handoff boundary, not as durable memory. That distinction matters when a coding task spans hours, restarts, or multiple context windows. If the task state lives only in the chat transcript, compaction can drop details that still matter: file paths, numeric constraints, rejected approaches, test status, and the reason behind a decision. If the task state is written into project artifacts, compaction becomes less risky because the next turn can re-read the facts.

The practical goal is simple: keep Claude useful after the conversation has been compressed. For a platform engineer or engineering lead, that means making the work inspectable in ordinary files, choosing compaction moments deliberately, and verifying the post-compact state before more code changes happen.

Anthropic's docs describe compaction as a way to keep active context smaller in long conversations and agentic workflows. The same docs also give you the tools to manage it: /context, /compact, /clear, /resume, project memory through CLAUDE.md, context-aware status lines, and PreCompact and PostCompact hooks. The useful operating model is not "trust compaction" or "avoid compaction." It is "externalize state before compaction, then verify what survived."

Internal link suggestion: Link "Claude Code context management" to a related article about keeping coding-agent context small and inspectable.

Why compaction is a risky moment in real coding work

Claude Code auto-compaction summarizes conversation history as the context limit approaches. Official cost and platform docs frame this as a way to reduce token pressure and keep active context smaller, because response quality can degrade as a conversation grows. That is useful. It also creates a boundary where detail can be transformed, shortened, or lost.

Community reports in the brief point to the same failure pattern from different angles. Users report dropped numbers, conditionals, unresolved questions, cross-document relationships, and decision rationale. One Hacker News case involved pasting about 8K of DOM markup into the prompt. After compaction, Claude retained only a vague reference and started guessing selectors. The safer pattern is to put large source material in files and refer to focused line ranges or retrieval tools.

The problem is not that compaction is broken. The problem is that a coding task often depends on exact state. A refactor may require remembering that a compatibility path must stay until a migration finishes. A database change may depend on a destructive-operation caveat. A flaky test investigation may depend on which hypotheses already failed. Those details need a home outside the compressed transcript.

Use Claude Code's primitives as workflow controls

Claude Code gives you several controls that map well to a disciplined workflow.

• /context shows what is filling the context window. Use it before the session becomes unstable, especially after large file reads, pasted logs, or broad searches.
• /compact summarizes the conversation to free space. It can accept user instructions, so the compact can be focused on the plan, diff, blockers, decisions, and verification state.
• /clear starts fresh between tasks while retaining project memory. Use it when the current transcript is no longer the right workspace for the next task.
• /resume returns to earlier conversations. Use it for continuity, but do not treat it as a replacement for a written handoff.
• CLAUDE.md and auto memory load at session start. Anthropic warns that they are context, not enforcement, so critical rules still need verification through tests, code review, and tooling.
• Status lines can show context percentage continuously. This turns compaction from a surprise event into a checkpoint you can plan around.
• PreCompact and PostCompact hooks can support observability. PreCompact can see whether the trigger is manual or automatic and can receive custom instructions. PostCompact receives the generated summary, but Anthropic's hook docs say it cannot affect the compaction result.

The important detail is that these are controls, not guarantees. A hook can log a summary. A memory file can provide project conventions. A status line can warn that context is filling. None of those should be the only place where task-critical state lives.

A practical Claude Code compaction strategy

The strongest workflow is checkpoint-based. You decide when the task is ready to cross a compaction or restart boundary, then you write down the state that another engineer or a fresh agent session would need.

1. Monitor context before the task gets fragile

Use a status line or /context to watch context pressure. Do this after operations that tend to bloat the transcript: reading large files, pasting logs, asking for broad repository scans, or dumping tool output into the conversation.

Do not wait until auto-compaction happens in the middle of a delicate edit. Community workflows in the brief often recommend disabling auto-compact or at least compacting manually at natural stopping points. Treat that as a quality tactic. A natural stopping point is when the current diff is coherent, the next action is known, and verification state can be stated clearly.

2. Write the task state to disk

Before compaction, create or update a durable handoff file. The name can be simple: PLAN.md, handoff.md, an issue note, or a task-specific file in the repo's existing docs area. The point is not the filename. The point is that the next session can inspect the same facts a human would inspect.

Include the current goal, branch, files touched, decisions made, rejected paths, commands run, test results, blockers, open questions, and exact next action. If the task has constraints that would be dangerous to lose, write them as explicit bullets. Examples include "do not change the public API," "keep rollback path until migration finishes," or "do not run destructive database commands outside a disposable environment."

This matches the practitioner guidance in the brief: "sessions are ephemeral, but projects aren't" and "write state to disk, not conversation." Those are field reports, not controlled benchmarks, but they align with the official tool model. Claude can recover better when the source of truth is a file and a diff, not a compressed memory of the chat.

3. Keep the diff reviewable before crossing the boundary

Before compaction or restart, ask Claude to inspect git diff and summarize the actual changed files. This catches a common mismatch: the conversation says one thing, while the filesystem says another.

A good checkpoint has a diff that can be explained in a few sentences. If the diff mixes unrelated refactors, formatting churn, generated files, and half-finished behavior changes, compaction will make the next session harder. Split the work or document the reason the pieces must move together.

Internal link suggestion: Link "reviewable diff" to a related article about AI coding agent PR reviewability checklists.

4. Compact with explicit preservation instructions

When you run /compact, provide instructions about what must survive. Anthropic's troubleshooting docs include the pattern /compact keep only the plan and the diff for context thrashing recovery. For long coding tasks, use a slightly richer instruction:

/compact Preserve the current goal, files changed, decisions made, blockers, exact next action, commands already run, test status, and any constraints that must not be violated. Drop old exploration that is no longer relevant.

This does not guarantee perfect preservation. It does make the compression target clearer. More important, it reinforces that the compact summary should agree with the handoff file and the current diff.

5. Verify after compaction before editing again

After compaction, do not immediately ask for more code changes. Ask Claude to restate the task from the handoff file and the current diff:

Before making changes, read the handoff file and inspect git diff. Restate the goal, changed files, open questions, next action, and verification commands. Call out any mismatch between the handoff and the diff.

This turns compaction into a checkable transition. If the restatement drops a constraint or invents an assumption, fix the handoff before continuing. The small delay is cheaper than debugging a mistaken continuation later.

Use a handoff file schema that fits engineering work

A handoff file should be boring and complete. It should help a fresh Claude Code session, a teammate, or future you restart the task without reading the whole chat transcript.

# Handoff: <task name>

## Goal
- What the task is trying to accomplish.
- What is explicitly out of scope.

## Current branch and baseline
- Branch:
- Base commit or PR:
- Relevant issue or ticket:

## Files touched
- path/to/file: what changed and why
- path/to/test: what behavior it covers

## Decisions
- Decision:
- Rationale:
- Trade-off:

## Rejected paths
- Approach tried:
- Why it was rejected:

## Commands run
- command
- result summary
- important output snippet or log path

## Verification state
- Passing:
- Failing:
- Not run:
- Reason not run:

## Constraints
- Constraint that must survive compaction or restart.
- Security, migration, compatibility, or rollout caveat.

## Open questions
- Question:
- Who or what can answer it:

## Next action
- The exact next edit, command, or review step.

This format is intentionally plain. It avoids hiding important state inside hook side effects or chat-only summaries. If your team already works through issues, PR descriptions, or task docs, use those instead. The rule is that the handoff must be visible, versionable when appropriate, and easy to compare against the diff.

Common failure modes and how to avoid them

Mid-task auto-compaction

Auto-compaction protects the session from hard context failure, but it may fire at a poor moment. The mitigation is to watch context usage and compact manually at checkpoints. If your workflow allows it, close out before the last part of the context window rather than squeezing every token out of the session.

Large pasted output

Do not paste giant DOM snapshots, logs, generated files, or stack traces into the prompt when the repo can hold them as files. Put the material in a file, point Claude to the relevant path, and ask for focused line ranges. This keeps the transcript smaller and preserves exact source material after compaction.

Dropped numbers and conditionals

Numbers, thresholds, migration steps, feature flags, and conditional requirements should be copied into the handoff file. If a constraint is important enough to break production, it is important enough to write down outside the chat.

Compaction thrashing

Anthropic's troubleshooting docs describe an "Autocompact is thrashing" failure mode: compaction succeeds, but oversized file or tool output immediately refills context. Recovery options include smaller file chunks, a focused compact instruction, subagents for large-file work, or /clear. In practice, thrashing is a sign that the session is carrying too much raw material. Move source material into files and restart from a cleaner state.

Overgrown memory files

CLAUDE.md is useful for project conventions, architecture notes, and recurring workflow rules. It should not become a dumping ground for every task. Anthropic documents memory as context, not enforcement, and notes that MEMORY.md loads only the first 200 lines or 25KB at session start. Keep durable task state in task-specific handoffs, not in a global memory file that grows until it becomes noise.

Hook overreliance

PreCompact and PostCompact hooks are useful for logging and observability. They are not a substitute for a visible handoff. PostCompact receives the generated compact summary, but the docs say it cannot affect the compaction result. That makes it a good place to record what happened, not a place to enforce that Claude remembered everything correctly.

Choosing the right session strategy

There is no single best setting for every team. The right choice depends on task risk, repository size, and how much control you need over context transitions.

For platform teams, the conservative default is manual compaction at checkpoints plus fresh-session handoffs for work that crosses a major boundary. Keep auto-compaction as a fallback, not the primary continuity mechanism for fragile work.

Team checklist for compaction-safe Claude Code work

• Check context usage before the session is near the limit.
• Keep large logs, DOM dumps, generated files, and source material on disk, not pasted into chat.
• Write a task handoff before compaction, restart, or ownership transfer.
• Record files touched, decisions, rejected paths, commands run, test state, blockers, constraints, and next action.
• Make the diff coherent before crossing a compaction boundary.
• Use explicit /compact instructions that preserve the plan, diff, verification state, and constraints.
• After compaction, ask Claude to re-read the handoff and inspect git diff before making more edits.
• Treat CLAUDE.md as project context, not policy enforcement.
• Use PreCompact and PostCompact hooks for observability, not as the only recovery path.
• Use /clear when the transcript is too noisy for the next task.

Make compaction a checkpoint, not a gamble

Claude Code compaction is useful, but it is a lossy transition. The reliable strategy is to move important state out of the transcript before the transition happens. Plans, diffs, verification commands, blockers, and decisions should be visible in files that a fresh session can read and a human can review.

Use /context and status lines to see compaction coming. Use /compact with precise instructions when the task is at a natural checkpoint. Use /clear when a clean session is better than a compressed one. After any compaction, verify the restatement against the handoff and the actual diff before allowing more edits.

That is the working rule for long coding tasks: compact the conversation, not the source of truth.