Context Awareness and Compaction

---

What compaction is

When a Claude Code session gets long, Claude Code automatically summarises the earlier parts of the conversation to make room for new content. This summary replaces the original messages — some details may not survive.

This process is called compaction. You do not trigger it and you do not control when it happens. It fires when the conversation reaches a certain length. Once it fires, the original messages are gone from the active context. What remains is the summary that was generated from them.

Most AI users do not know this happens. Knowing it — and knowing what survives and what does not — is one of the things that separates an advanced practitioner from a capable beginner.

---

What compaction preserves

Compaction is not random. It is a structured summarisation that prioritises certain things:

• Your explicit requests and stated intentions
• Key concepts, frameworks, and decisions that were named clearly
• Specific file names, function names, and other named items
• Errors that were encountered and how they were resolved
• Corrections you made ("do it this way, not that way")
• Your messages, when they were written as clean standalone statements
• The task in progress at the moment compaction fired
• The confirmed next step

---

What compaction loses

• Raw tool output — file reads, search results, shell command output
• Intermediate reasoning Claude Code generated along the way
• Context that was established through example rather than stated explicitly ("you can see from this file that we use...")
• Constraints expressed conversationally ("yeah, probably don't do that") rather than as clear rules
• Nuance buried inside long paragraphs
• Anything that was implied but never stated directly

The pattern is consistent: explicit beats implicit, standalone beats buried, named beats described.

---

Recognising context rot

Context rot is the gradual degradation of Claude Code's working state as a session runs long. It surfaces as re-asked questions, constraint drift, wrong terminology, or responses that were precise earlier becoming vague.

Compaction is the main cause. The session summary is generated by a model — it inherits the limitations of any summarisation. Implicit context, naming conventions established by example, and nuanced constraints expressed conversationally are the most likely things to compress poorly.

Symptoms of context rot

Signal	What it means
Claude Code re-asks a question you already answered	That answer did not survive compaction
Claude Code violates a constraint you set earlier	The constraint drifted out of active context
Claude Code uses a different name for something	The terminology anchor was lost in summarisation
Responses become more hedged and general	Claude Code is working from a summary, not the original specifics
Claude Code repeats work it already did	It has lost track of completed state

Without / With: Coding

Without: A developer builds a form validation library. They established early in the session that all validation errors must use error codes (REQUIRED_FIELD, INVALID_EMAIL) rather than human-readable strings. After a long session and compaction, Claude Code starts returning { error: "This field is required" } instead of { code: "REQUIRED_FIELD" }. The developer does not notice until they are writing tests.

With: The developer notices the format changed. They recognise this as context rot and respond:

Stop — you are using human-readable error strings. We established at the start of this session that all validation errors use error codes (REQUIRED_FIELD, INVALID_EMAIL, etc.), not strings. Rewrite the last output using the code format.

Reminder: all validation errors for this entire session must use the code format.

They restate the constraint and continue.

Without / With: Content and research

Without: A researcher builds a competitive intelligence report. Early in the session the responses were precise and sourced. After compaction, responses become hedged and general: "it appears that", "generally speaking", "their strategy seems to focus on." The researcher accepts the vaguer output without recognising it as a symptom.

With: The researcher notices the shift in register. They respond:

Your last few responses have been significantly more vague than earlier in this session — using phrases like "it appears" and "seems to."

Do not hedge on claims that can be verified from the source material. If something cannot be verified, say so explicitly rather than softening it with language that implies speculation about a fact that can be checked.

---

Writing for compaction

The most durable elements in compaction are standalone user messages with clear structure. The most volatile are conversational replies, tool output, and implicit context.

Writing for compaction means structuring your important messages so they survive.

What to do:

• State constraints as standalone messages, not as replies embedded in a longer exchange
• Name things explicitly — do not establish terminology only through example
• Use phrases like "confirmed finding:" or "decision for this session:" to signal a message that should survive
• Reference specific names (files, concepts, decisions) in your messages, not just in the context of tool results

Without / With: Coding

Without: A developer establishes a rule by commenting on Claude Code's output: "Don't hardcode that — it should be configurable." This is a conversational reply. During compaction the nuance may not survive. Later the rule is violated.

With: The developer writes the constraint as a standalone message:

Architecture constraint for this entire session:

Configuration values must never be hardcoded in source files. All configurable values must be read from environment variables or configuration files at runtime.

This applies to everything we build today. If you are about to hardcode a value, stop and ask me for the configuration key name instead.

Without / With: Content and research

Without: A writer and Claude Code work through several rounds deciding to frame a report around three themes rather than five. The decision was reached through dialogue and exists in the conversation flow, but was never stated as a clean decision. After compaction, Claude Code might return to proposing the five-theme structure.

With: The writer writes a consolidating message:

Decision for this document — confirmed:

We are using three themes, not five:

1. Speed to value
2. Integration simplicity
3. Compliance without complexity

The original five-theme structure has been rejected. Do not propose adding other themes. If a point belongs in the document, fit it into one of the three existing themes.

---

Manual checkpointing

A checkpoint is a message you send before compaction happens automatically — asking Claude Code to summarise the current state, then verifying that summary is accurate before you continue.

Automatic compaction happens when the context reaches a certain length. You have no control over when it fires or what it preserves. Manual checkpointing gives you both: you choose the moment, and you can correct the summary before it becomes the working context for the rest of the session.

A corrected checkpoint costs one turn. Uncorrected drift can cost many.

When to checkpoint:

• Before switching from one phase of work to another
• Halfway through a long task, when the session is getting long
• Before starting on the most complex or highest-stakes part of a task
• When you notice any of the context rot symptoms above

---

The compaction survival checklist

Use this before starting any long Claude Code session where you care about consistency across many turns:

1. State your key constraints in standalone messages before work begins — not buried in the opening paragraph.
2. Name things explicitly. Use the term you want used, not a description that the model has to infer a label from.
3. When a decision is made through dialogue, confirm it as a clean standalone statement: "Decision confirmed: [the decision]."
4. Checkpoint before long or complex phases. Verify the summary. Correct it before continuing.
5. Watch for context rot symptoms. When you see them, restate the relevant constraint immediately — as a standalone message, not as a conversational aside.

---

Copy, Personalise, Use

Use this starter to send a manual checkpoint at any point in a long session.

Checkpoint before we continue.

Please summarise:

1. What we have completed so far in this session, and the key decisions made
2. What constraints and rules are active for this session
3. What is the agreed next step

I will confirm the summary is accurate before we continue. If you are uncertain about any item, say so rather than guessing.

How to edit this:

• You can replace the three numbered items with whatever you need confirmed. Common additions: "What is the grain or structure of the data/document we are building?" "What have we decided NOT to include?" "What was the last completed step?"
• The phrase "I will confirm the summary is accurate before we continue" is load-bearing — it signals that this is a checkpoint and that you expect to verify the output rather than treat it as final.
• The phrase "say so rather than guessing" reduces the risk that Claude Code fills in gaps with plausible-sounding but invented details.

---

Next

A-06 covers output engineering — specifically the plan-before-execute pattern and how to control the format and structure of Claude Code's responses.