Skill1.2k repo starsupdated 3mo ago

strategic-compact

Strategic Compact is a Claude Code skill that recommends manually executing the `/compact` command at logical workflow boundaries rather than relying on automatic context compression. Use this when running long sessions approaching context limits, transitioning between multistage tasks, switching to unrelated work, completing major milestones, or detecting slow responses from context pressure. The skill tracks tool calls via a PreToolUse hook and suggests compression at configurable thresholds to preserve important context while clearing exploration data at optimal task boundaries.

View source Repository: everything-claude-code-zh

Install in Claude Code

Copy

git clone --depth 1 https://github.com/xu-xiang/everything-claude-code-zh /tmp/strategic-compact && cp -r /tmp/strategic-compact/.agents/skills/strategic-compact ~/.claude/skills/strategic-compact

Then start a new Claude Code session; the skill loads automatically.

Definition

SKILL.md

# 策略性压缩（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 Longform Guide）](https://x.com/affaanmustafa/status/2014040193557471352) —— 令牌（Token）优化章节
- 记忆持久化钩子（Memory persistence hooks） —— 用于压缩后仍保留的状态
- `continuous-learning` 技能 —— 在会话结束前提取模式