# Strategic Compact

建议在逻辑间隔进行手动上下文压缩（Context Compaction），以便在任务阶段中保留上下文，而不是依赖任意的自动压缩。

- Repository: https://github.com/xu-xiang/everything-claude-code-zh (2012 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-03-05
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add xu-xiang/everything-claude-code-zh --skill strategic-compact -g -a claude-code -y`
Codex: `npx skills add xu-xiang/everything-claude-code-zh --skill strategic-compact -g -a codex -y`
Cursor: `npx skills add xu-xiang/everything-claude-code-zh --skill strategic-compact -g -a cursor -y`
Gemini CLI: `npx skills add xu-xiang/everything-claude-code-zh --skill strategic-compact -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add xu-xiang/everything-claude-code-zh`

## Description

建议在逻辑间隔进行手动上下文压缩（Context Compaction），以便在任务阶段中保留上下文，而不是依赖任意的自动压缩。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 策略性压缩（Strategic Compact）技能

建议在工作流的策略点手动执行 `/compact` 命令，而不是依赖任意的自动压缩（Auto-compaction）。

## 何时启用

- 运行接近上下文限制（200K+ tokens）的长会话（Long Sessions）时
- 处理多阶段任务（研究 → 规划 → 实现 → 测试）时
- 在同一会话中切换到不相关的任务时
- 完成重大里程碑（Milestone）并开始新工作后
- 当响应变慢或连贯性下降（上下文压力）时

## 为什么要进行策略性压缩？

自动压缩在任意点触发：
- 通常在任务中间，导致重要上下文丢失
- 缺乏对逻辑任务边界的感知
- 可能会中断复杂的多步骤操作

逻辑边界处的策略性压缩：
- **在探索之后，执行之前**, , 压缩研究上下文，保留实现方案
- **完成里程碑之后**, , 为下一阶段提供全新的开始
- **重大上下文转移之前**, , 在开始不同任务前清除探索上下文

## 工作原理

`suggest-compact.js` 脚本在 `PreToolUse`（`Edit`/`Write`）钩子（Hook）上运行，并且：

1. **跟踪工具调用**, , 统计会话中的工具调用（Tool Calls）次数
2. **阈值检测**, , 在达到可配置的阈值（默认：50 次调用）时提出建议
3. **定期提醒**, , 达到阈值后，每隔 25 次调用提醒一次

## 钩子配置（Hook Setup）

添加到你的 `~/.claude/settings.json` 中：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
      },
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
      }
    ]
  }
}
```

## 配置

环境变量：
- `COMPACT_THRESHOLD`, , 第一次建议前的工具调用次数（默认：50）

## 压缩决策指南

使用下表来决定何时压缩：

| 阶段转换 | 是否压缩？ | 原因 |
|-----------------|----------|-----|
| 研究 → 规划 | 是 | 研究上下文很臃肿；方案是提炼后的产出 |
| 规划 → 实现 | 是 | 方案已在 `TodoWrite` 或文件中；为代码腾出上下文空间 |
| 实现 → 测试 | 可能 | 如果测试引用了近期代码则保留；如果切换关注点则压缩 |
| 调试 → 下一功能 | 是 | 调试追踪（Debug traces）会污染不相关工作的上下文 |
| 实现中 | 否 | 丢失变量名、文件路径和部分状态的代价很高 |
| 方案失败后 | 是 | 在尝试新方案前清除死胡同式的推理 |

## 压缩后保留的内容

了解哪些内容会持久化，有助于你充满信心地进行压缩：

| 保留 | 丢失 |
|----------|------|
| `CLAUDE.md` 指令 | 中间推理和分析 |
| `TodoWrite` 任务列表 | 之前读取过的文件内容 |
| 记忆文件（`~/.claude/memory/`）| 多步骤对话上下文 |
| Git 状态（提交、分支）| 工具调用历史和计数 |
| 磁盘上的文件 | 口头陈述的细微用户偏好 |

## 最佳实践

1. **规划完成后压缩**, , 一旦方案在 `TodoWrite` 中确定，就进行压缩以全新开始
2. **调试完成后压缩**, , 在继续之前清除错误解决上下文
3. **不要在实现过程中压缩**, , 保留相关更改的上下文
4. **阅读建议**, , 钩子告诉你*何时*，你决定*是否*
5. **压缩前写入**, , 在压缩前将重要上下文保存到文件或记忆中
6. **使用带有总结的 /compact**, , 添加自定义消息：`/compact 下一步重点实现认证中间件`

## 相关内容

The rest: https://github.com/xu-xiang/everything-claude-code-zh/blob/HEAD/.agents/skills/strategic-compact/SKILL.md