Customize Context Compaction Instructions in Claude Code

You can customize context compaction instructions in Claude Code in two ways: add a focus after /compact for a particular compaction, or put a Compact Instructions section in your project's CLAUDE.md for recurring guidance. Tell Claude which decisions, constraints, changed files, and verification results matter to the next stage of work.

The important distinction is between giving the summary priorities and expecting it to preserve everything. Compaction compresses a conversation. A useful instruction helps retain information that would be costly to lose while allowing repetitive output and obsolete discussion to shrink.

Choose between a one-time focus and persistent instructions

Use the method that matches the lifetime of the instruction:

A useful combination is a stable project rule such as “keep test commands and their results,” plus a one-time focus naming the particular failing test you are investigating. Keep both consistent. Do not depend on contradictory instructions resolving in the way you intended.

1. Add instructions to a manual compaction

Enter the command inside Claude Code's interactive prompt, rather than at your normal operating-system shell:

/compact Preserve the current goal, agreed constraints, modified file paths, unresolved failures, test commands with results, and the next action. Condense repeated logs and obsolete discussion.

The words after the command describe the focus for that compaction. This is an action: Claude summarizes the conversation to free context space. It is not a preview of a future summary.

For a narrower task, be more specific. This illustrative example concerns an authentication change:

/compact Focus on the session-expiry fix. Preserve the decision to keep the existing cookie format, the files changed, the failing regression test, and what remains unverified.

Replace the example details with facts from your own session. A preservation instruction should not introduce a decision that was never agreed or label a test as failing when it has not run.

Use this approach when you reach a meaningful transition, such as finishing an investigation and preparing to implement its result. It gives you a chance to identify what the next phase needs. You do not need to compact after every response.

2. Add a Compact Instructions section to CLAUDE.md

For instructions you want available across project sessions, edit the existing project CLAUDE.md. Claude Code supports a file at the repository root or .claude/CLAUDE.md. Use your project's established location and preserve the rules already there.

You can open instruction files with /memory, or edit them directly in your text editor. Add a section like this:

## Compact Instructions

When compacting this conversation, prioritize:

- The current user goal and agreed acceptance criteria.
- Constraints that affect the next edit, including files or interfaces
  that must remain unchanged.
- Decisions already made, with a brief reason for rejected approaches
  when that reason is still relevant.
- Modified file paths and a short description of each change.
- Verification commands actually run and their observed results.
  Distinguish passed, failed, blocked, and not-run checks.
- Unresolved questions, blockers, and the next concrete action.

Condense repeated tool output and superseded discussion.
Keep exact error text only where it is needed to continue debugging.
Do not turn proposed work into completed work or guesses into facts.
If evidence is missing, state the uncertainty.

This template uses ordinary Markdown and natural language. Adapt its priorities to your work: an API migration may need compatibility decisions, while a visual change may need the approved layout and the screenshots still to check.

Keep the section focused on how to summarize. The current list of broken tests belongs in the task's working notes; a standing rule telling Claude to distinguish failed tests from unrun tests belongs here.

After saving, run /context and check the loaded memory files. If the edited file is missing, resolve its location or loading configuration before evaluating whether its instructions helped.

Write preservation priorities that are easy to verify

“Remember everything important” leaves the difficult decision to the summarizer. Describe information whose loss would change the next action.

For example, “preserve the test results” is weaker than “preserve the exact command, whether it completed, and the observed result.” A command that could not start because a service was unavailable should not become a successful check in the next summary.

The same distinction applies to decisions. “Use the existing parser because downstream clients depend on its error format” gives the next stage more useful information than “parser discussed.” The reason explains when the decision can be reconsidered.

When writing these rules, separating the objective, constraints, and requested output can help. Our guide to structured prompt writing covers that organizational approach. For compaction, keep the requested output centered on the information needed to resume work.

Specify what can be condensed

A summary becomes less useful if every line is declared essential. Identify expendable detail alongside preservation priorities:

• Keep the decisive error and where to find the full log; condense repeated copies of the same failure.
• Keep the chosen approach and relevant reasons; shorten alternatives that no longer affect the task.
• Keep changed paths and behavior; avoid reproducing whole files when the repository contains the current code.
• Keep blockers and open decisions; remove conversational repetition around them.

For a large change, ask for a grouped overview with the important paths identified. If an exact inventory is required, keep that inventory in a maintained file and have the summary point to it. A long list of filenames alone may explain less than a short account of which behavior changed.

Ars Technica's explanation of coding agent context provides background on why compression and external notes matter during long coding sessions.

Understand what reloads after compaction

Claude Code re-injects the project-root CLAUDE.md and unscoped rules from disk after compaction. Nested instruction files and rules limited to matching paths reload when Claude reads the relevant files. This distinction matters when a rule appears to disappear halfway through work.

Put a project-wide compaction rule in the project-root instructions. A rule placed only inside a component directory may not be present until work in that directory causes it to load.

If you are also dealing with forgotten project instructions, review how those instructions are stored and loaded alongside your compaction settings.

Also distinguish persistent instructions from conversation details. The former tell Claude how to work; the latter describe what happened in this task. Re-reading a rule such as “preserve test results” cannot reconstruct an earlier result that is no longer available.

Claude Code also restores its plan-mode plan from disk. An ordinary file you name HANDOFF.md is your own project note, however; its filename does not give it the same built-in behavior. Ask Claude to read it explicitly when you need its contents.

Keep changing task state in a separate note

For work spanning several compactions, a short task note can make review easier. Give it a descriptive path that fits your project, such as docs/work-notes/session-expiry.md, and decide whether it belongs in version control.

A practical note can use this structure:

# Current task

Goal:
Acceptance criteria:
Constraints:
Decisions and reasons:
Changes made:
Verification performed:
Still unverified:
Open questions:
Next action:
Relevant files or logs:

Fill it with current, checked information. Ask Claude to update it at a meaningful milestone and review the changes before relying on it. Keeping a note is useful only if it stays consistent with the repository and the task.

You can then request:

Read docs/work-notes/session-expiry.md and compare it with the current diff. Report any disagreement about completed work or test status before making more edits.

This gives you a recoverable account outside the conversation. Keep its purpose narrow: a short handoff is easier to inspect and maintain than another copy of every log and response.

Verify the result before continuing

Evaluate the setup on a real task at a sensible stopping point. Before compaction, identify a few facts you can check independently: one important restriction, one decision, a changed path, a verification result, and the next step.

After compaction finishes, ask:

Before making further changes, summarize the active goal, constraints,
decisions, changed files, verification results, and next action.
Mark anything you cannot establish from the available context as unknown.

This is a check of Claude's current understanding, not a direct export of the internal compaction summary. Compare its answer with the facts you recorded and the current files.

If it reports that a test passed, check the actual command output. If it proposes an approach you rejected, point it to the decision and its reason. Fix the specific discrepancy before continuing; repeated compaction alone is not a reliable way to recover missing evidence.

A useful correction is direct:

Correction: the integration test has not run because the test service
was unavailable. Only the unit test passed. Preserve that distinction
and keep integration verification listed as pending.

One successful check does not guarantee that every future summary will be complete. Use the same comparison when the task changes direction or a later response contradicts an earlier agreement.

If the assistant starts making unrelated file changes, pause the task and restate the permitted scope before allowing further edits.

Use hooks only when you need additional automation

The two instruction methods above are enough to begin. Hooks are useful for more specialized needs, such as recording summaries or adding a short reminder after each compaction.

Claude Code documents a SessionStart hook with a compact matcher for adding context after compaction. Text printed by that command is added to the compacted session. This can provide a concise reminder or current project information; it does not rewrite the summary that was just generated.

For inspecting the actual summary, the PostCompact event supplies a compact_summary input field. A hook can log that value for review. Check the hook support in your installed version before building automation around it.

Do not mistake the custom_instructions field in a PreCompact event for a setting you can add anywhere. It describes the instructions supplied to a manual compaction; automatic compaction reports null there. Use CLAUDE.md for recurring natural-language guidance.

Troubleshoot instructions that seem ineffective

Start by identifying whether the problem is loading, interpretation, or missing evidence:

• The file is absent from loaded context: Check the working directory, file location, and applicable configuration. A saved file is useful only when the session actually reads it.
• Two rules disagree: Remove the conflict. A demand to preserve complete logs competes with a demand for a very short summary.
• The summary sounds confident but lacks evidence: Strengthen the distinction between observed results, plans, and unknowns. Correct the current record as well as the standing instruction.
• The conversation fills again immediately: Inspect what is being loaded. A better summary cannot prevent a subsequent enormous file read from consuming context again.

Keep permanent instructions concise. Anthropic recommends trimming material that does not need to accompany every session and moving specialized workflows into on-demand skills. Adding several pages of repeated preservation rules creates more information to process without necessarily making the priority clearer.

For an unexpected command or interface difference, check /help inside Claude Code and record claude --version from your ordinary terminal. Avoid applying instructions intended for another coding assistant or a different interface.

Frequently asked questions

Do Compact Instructions also help automatic compaction?

A loaded CLAUDE.md is the documented place for recurring compaction guidance, including sessions that compact automatically. Text supplied after a manual /compact should be treated as guidance for that invocation.

Can I guarantee that Claude preserves every instruction?

No. Natural-language instructions guide model behavior but do not guarantee complete retention or compliance. Keep critical rules in the appropriate persistent file and verify important decisions after a context transition.

Does this change when automatic compaction starts?

No. Summary priorities and the automatic compaction threshold are separate controls. This setup tells Claude what matters during summarization; it does not set a context size or trigger point.

Do I need to disable automatic compaction?

No. You can add project guidance while leaving automatic compaction available. Use a manual focused compaction when you want to choose the transition yourself.

Add the short project template, confirm that its file is loaded, and try one focused compaction at the next natural milestone. Check the resulting understanding against your task record, then revise only the instruction that failed to preserve something necessary.