上下文压缩与 Token 控制指南 Context Compression & Token Control

给用户看的简明版：Claude Code 会在上下文过长时压缩历史，但最佳实践是主动监控、主动压缩、按任务拆会话，并把长期规则写入 CLAUDE.md 。 Short version: Claude Code can compact long sessions, but the reliable workflow is to monitor context, compact proactively, split unrelated tasks, and persist stable rules in CLAUDE.md .

⚡ Claude Code Guide / 中英双语

给用户看的简明版：Claude Code 会在上下文过长时压缩历史，但最佳实践是主动监控、主动压缩、按任务拆会话，并把长期规则写入 CLAUDE.md。
Short version: Claude Code can compact long sessions, but the reliable workflow is to monitor context, compact proactively, split unrelated tasks, and persist stable rules in CLAUDE.md.

1. Claude Code 怎么压缩上下文？

Claude Code 会维护当前会话历史，包括用户指令、读过的文件、工具调用结果、代码片段、TODO 和关键决策。

接近窗口上限

当上下文越来越大，系统会触发 auto compact，避免超过模型上下文窗口。

生成会话摘要

把前面的长聊天、日志、工具输出压成较短摘要，保留核心状态。

继续当前任务

后续使用“摘要 + 最近上下文”继续工作，而不是完整保留所有历史原文。

English:

Claude Code summarizes older conversation history, tool outputs, files read, decisions, and TODOs into a shorter state summary, then continues with that summary plus recent context.

会保留什么？

当前任务目标 / Goal
关键文件和修改点 / Files & changes
已做决策 / Decisions
剩余 TODO / Remaining TODOs
重要约束 / Constraints

2. Token 会不会成倍增加？

结论 / Bottom line不是严格成倍或指数增长，但会越来越贵、越来越慢。

每一轮通常都要携带当前上下文作为输入；上下文越长，每轮成本越高。

It is not strictly exponential, but every turn carries more input context, so long sessions become progressively slower and more expensive.

成本增长的直观理解 / Cost intuition

总成本 ≈ 每轮输入上下文长度 × 对话轮数 + 输出 token
Total cost ≈ input context per turn × number of turns + output tokens

Prompt caching 能降低一部分重复上下文成本，但不能完全抵消新增内容、长日志和工具输出。

3. 如何规避上下文过长？ / How to avoid context bloat?

<70% 正常 / Normal70%-85% 建议压缩 / Compact soon>85% 立即压缩 / Compact now

主动查看 / Inspect

/context

查看上下文占用和优化建议。Check context usage and optimization tips.

主动压缩 / Compact

/compact

比等自动压缩更稳。More reliable than waiting for auto compact.

换任务清空 / Clear

/clear

适合新任务，不适合做到一半的任务。Use for unrelated new tasks.

精准压缩示例 / Focused compact

/compact focus on current bug, modified files, failing tests, decisions made, and remaining TODOs

指定重点，减少关键信息丢失。Focus compaction on the state you cannot afford to lose.

长期规则写文件 / Persist rules

CLAUDE.md

项目规则不要靠聊天历史记。Do not rely on chat history for stable project rules.

4. Skills / Agents 能否一定触发自动压缩？

结论：没有一个 Claude Code skill 或 agent 能 100% 强制触发 auto compact。真正稳定可控的是手动 /compact、/context 监控、压缩前摘要和项目规则文件。

English: No Claude Code skill or agent can guarantee auto compaction. The reliable controls are manual /compact, context monitoring, handoff summaries, and persistent project rules.

不能保证的原因

auto compact 的触发阈值属于 Claude Code 内部机制，skill/agent 只能提醒、整理摘要、减少上下文膨胀，不能强制内部阈值立刻触发。

Auto compact is controlled internally. Skills and agents can guide behavior, but they cannot force the internal threshold.

最稳命令

/compact focus on current implementation state, modified files, failing tests, remaining TODOs, decisions made, and risks

Hook 的定位

PreCompact hook 是“压缩发生前做事”，不是“主动触发压缩”。适合备份、记录、审计。

PreCompact runs before compaction happens; it does not initiate compaction.

推荐 Agent：context-keeper

mkdir -p .claude/agents
nano .claude/agents/context-keeper.md

作用：在压缩前整理当前状态，生成 compact-safe handoff notes，然后再手动执行 /compact。

Use a context-keeper agent to produce compact-safe handoff notes before manually running /compact.

调用方式 / Usage

@context-keeper summarize the current session and prepare compact-safe handoff notes

context-keeper agent 模板 / Template

---
name: context-keeper
description: Summarizes current task state and prepares compact-safe handoff notes
model: sonnet
tools: [Read, Bash]
---

You are a context management assistant for Claude Code.

Your job:
1. Summarize the current implementation state.
2. Identify modified files.
3. Record commands already run.
4. Record test/build results.
5. List unresolved issues.
6. Produce compact-safe handoff notes.

Output format:
## Goal
## Current State
## Modified Files
## Commands Run
## Test Results
## Decisions Made
## Remaining TODOs
## Risks
## Recommended /compact Command

CLAUDE.md 上下文管理规则 / Project rules

# Claude Code Context Management Rules

When the session becomes long or context usage is above 70%:

1. Recommend running:
   /compact focus on current task, modified files, failing tests, decisions made, and remaining TODOs

2. Before any compact/summarization, preserve:
   - current goal
   - modified files
   - commands already run
   - test results
   - unresolved errors
   - next steps
   - important constraints

3. Do not load huge logs or full generated files unless necessary.
4. Prefer reading focused file sections instead of entire directories.
5. For unrelated new tasks, recommend /clear or a fresh session.

PreCompact Hook 示例 / Example

{
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "mkdir -p .claude/compact-backups && date >> .claude/compact-backups/precompact.log"
          }
        ]
      }
    ]
  }
}

5. 推荐命令 / Recommended commands

一次性审查 / One-shot review

claude -p "检查当前 git diff 是否有 bug，重点看逻辑回归和安全问题" --max-turns 3

限制轮数和预算 / Limit turns & budget

claude -p "Fix failing tests" --max-turns 10 --max-budget-usd 1

限制工具权限 / Restrict tools

claude -p "Review auth module" --allowedTools "Read" --max-turns 3

低成本简单任务 / Cheap simple tasks

claude -p "Summarize this file" --model haiku --max-turns 1

简单总结、解释类任务可以用便宜模型或低 effort；复杂重构和疑难 bug 再提高 effort。

清理日志输入 / Trim logs

tail -n 200 app.log
grep -i "error" app.log | tail -n 100

不要把几万行日志直接塞进上下文。Do not dump huge logs into context.

6. 推荐工作流 / Recommended workflow

一句话：新任务新会话，长任务勤 /context，超过 70% 主动让 context-keeper 整理，再执行 /compact，项目长期规则写入 CLAUDE.md。

One sentence: start fresh for unrelated tasks, check /context often, ask context-keeper for handoff notes above 70%, then run /compact, and keep stable rules in CLAUDE.md.

开始任务 / Start

claude
/context

先确认上下文状态。

任务中途 / Mid-task

@context-keeper summarize the current session and prepare compact-safe handoff notes

/compact focus on the handoff notes above, current task, modified files, failing tests, decisions made, and remaining TODOs

任务结束 / 换任务

/clear

避免一个会话混入太多无关任务。

CLAUDE.md 示例 / Example

# Project Context

## Commands
- npm run test
- npm run lint
- npm run build

## Rules
- Use TypeScript strict mode
- Do not modify generated files
- Prefer existing service patterns