strategic-compact

name	strategic-compact
description	在逻辑间隔建议手动上下文压缩，通过任务阶段保留上下文而非任意自动压缩。

Strategic Compact Skill

策略压缩技能

在工作流的策略点建议手动 /compact，而不是依赖任意的自动压缩。

何时激活

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

什么是上下文限制？ Claude 有一个"记忆窗口"（200K tokens），超过后会忘记旧内容。

为什么需要策略性压缩？

自动压缩在任意点触发：

• 经常在任务中途，丢失重要上下文
• 不感知逻辑任务边界
• 可能中断复杂的多步操作

示例问题：

你在实现一个功能：
1. 研究 API 文档（1000 tokens）
2. 计划实现（500 tokens）
3. 开始编写代码...
   → 自动压缩触发！ ← 错误时间
   → 丢失了 API 研究和计划

在逻辑边界的策略性压缩：

• 探索后、执行前 ——压缩研究上下文，保留实现计划
• 完成里程碑后 ——为下一阶段重新开始
• 重大上下文切换前 ——在不同任务前清理探索上下文

示例解决方案：

1. 研究 API 文档（1000 tokens）
2. 计划实现（500 tokens）
3. 保存计划到文件 ← 策略点
4. 手动 /compact ← 保留计划，清理研究
5. 继续实现 ✅

工作原理

suggest-compact.js 脚本在 PreToolUse（Edit/Write）时运行，并且：

1. 追踪工具调用 ——计算会话中的工具调用次数
2. 阈值检测 ——在可配置阈值（默认：50 次调用）时建议
3. 定期提醒 ——阈值后每 25 次调用提醒一次

为什么追踪工具调用？ 工具调用次数是上下文使用的代理指标。

示例流程：

会话开始：
- 第 10 次工具调用：正常
- 第 30 次工具调用：正常
- 第 50 次工具调用：⚠️ 建议压缩
- 第 75 次工具调用：⚠️ 再次建议
- 第 100 次工具调用：⚠️ 强烈建议

Hook 设置

添加到你的 ~/.claude/settings.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" }]
      }
    ]
  }
}

什么是 PreToolUse？ 在工具执行前触发的 hook。

配置

环境变量：

• COMPACT_THRESHOLD ——首次建议前的工具调用次数（默认：50）

设置阈值：

# 默认：50 次调用
# 保守：100 次调用（更少建议）
# 激进：25 次调用（更频繁建议）

压缩决策指南

使用此表决定何时压缩：

阶段转换	压缩？	为什么
研究 → 计划	✅ 是	研究上下文庞大；计划是提炼的输出
计划 → 实现	✅ 是	计划在 TodoWrite 或文件中；释放上下文给代码
实现 → 测试	⚠️ 可能	如果测试引用最近代码则保留；切换焦点则压缩
调试 → 下一功能	✅ 是	调试痕迹污染不相关工作的上下文
实现中途	❌ 否	丢失变量名、文件路径和部分状态代价高昂
失败方法后	✅ 是	在尝试新方法前清理死胡同推理

详细说明：

研究 → 计划（压缩）

你花了 30 分钟研究 API 文档。
现在你有详细的计划在 TodoWrite 中。

压缩：
✅ 保留：TodoWrite 任务列表
✅ 保留：计划文档
❌ 丢弃：30 分钟的阅读记录

计划 → 实现（压缩）

你有完整的功能计划。
现在开始编写代码。

压缩：
✅ 保留：计划（在文件或 TodoWrite 中）
✅ 释放上下文给代码
❌ 丢弃：规划讨论

实现中途（不压缩）

你正在实现功能的一半。
变量名、函数名、文件路径都很重要。

不压缩：
❌ 丢失：当前上下文
❌ 丢失：变量名
❌ 丢失：部分状态

调试后（压缩）

你花了 20 分钟调试一个错误。
现在错误已修复，继续下一个功能。

压缩：
✅ 清理调试痕迹
✅ 释放上下文给新功能
❌ 丢弃：调试对话

压缩后保留什么

理解什么持续存在有助于你有信心地压缩：

持续存在	丢失
CLAUDE.md 指令	中间推理和分析
TodoWrite 任务列表	你之前读取的文件内容
内存文件 (~/.claude/memory/)	多步对话上下文
Git 状态（提交、分支）	工具调用历史和计数
磁盘上的文件	口头表达的细微用户偏好

关键点：

• ✅ 磁盘上的文件安全 ——所有已保存的文件都存在
• ✅ TodoWrite 安全 ——任务列表保留
• ✅ Git 状态安全 ——提交和分支保留
• ❌ 上下文中的内容丢失 ——未保存的分析、对话历史

压缩前做什么：

# 1. 保存重要上下文到文件
echo "重要的 API 端点：/api/v1/users" > context-notes.md

# 2. 确保 TodoWrite 是最新的
/todowrite  # 检查任务列表

# 3. 提交 Git 更改
git add .
git commit -m "实现用户认证"

# 4. 现在压缩
/compact 保存任务列表，清理研究上下文

最佳实践

1. 计划后压缩 ——计划在 TodoWrite 中确定后，压缩以重新开始
2. 调试后压缩 ——继续前清理错误解决上下文
3. 不要在实现中途压缩 ——保留相关更改的上下文
4. 阅读建议 ——Hook 告诉你何时，你决定是否
5. 压缩前写入 ——压缩前将重要上下文保存到文件或内存
6. 使用带摘要的 /compact ——添加自定义消息

示例压缩命令：

# 基本压缩
/compact

# 带自定义消息
/compact 专注于实现身份验证中间件

# 带阶段标记
/compact [阶段：研究 → 实现] 保留任务列表

常见问题

Q: 压缩会删除文件吗？

A: 不会。压缩只清除 AI 的上下文（记忆），不删除任何文件。

Q: 我会丢失我的工作吗？

A: 如果你保存了文件（Edit/Write），不会。工作在磁盘上，不是在上下文中。

Q: 应该多久压缩一次？

A: 取决于工作流：

• 短任务（< 30 分钟）：从不
• 中等任务（30-60 分钟）：1-2 次
• 长任务（> 60 分钟）：每 30-40 分钟

Q: 如何知道何时压缩？

A:

• Hook 会建议（50 次工具调用）
• 响应变慢时
• 切换任务时
• 完成阶段时

Q: 压缩会破坏 TodoWrite 吗？

A: 不会。TodoWrite 任务列表在压缩后保留。

实际示例

示例 1：研究 → 实现

阶段 1：研究（40 分钟）
- 阅读 API 文档
- 尝试不同的方法
- 找到最佳方案

阶段 2：计划（10 分钟）
- 在 TodoWrite 中创建任务列表
- 写计划文档

阶段 3：压缩 ← 策略点
/compact [研究 → 实现] 保留任务列表和计划文档

阶段 4：实现（清洁 slate）
- 使用任务列表
- 参考计划文档
- 编写代码

示例 2：调试后清理

阶段 1：正常工作
- 实现功能 A
- 实现功能 B

阶段 2：调试（20 分钟）
- 功能 C 有错误
- 尝试修复 1：失败
- 尝试修复 2：失败
- 尝试修复 3：成功 ✓

阶段 3：压缩 ← 策略点
/compact 清理调试痕迹，开始功能 D

阶段 4：下一个功能
- 清洁的上下文
- 没有调试噪音

示例 3：实现中途（不压缩）

阶段 1：实现开始
- 编写函数 getUser()
- 编写函数 validateUser()
- 编写函数 saveUser()

← Hook 建议压缩
→ 决定：不压缩 ←

原因：
- 函数名称在上下文中
- 变量名很重要
- 部分状态

阶段 2：继续实现
- 完成 saveUser()
- 编写测试
- 提交代码

阶段 3：现在压缩 ✓
/compact 功能完成，清理上下文

相关资源

• The Longform Guide ——Token 优化章节
• 内存持久化 hooks ——压缩后幸存的状态
• continuous-learning 技能——会话结束前提取模式

---

记住：策略压缩是在正确时间手动触发——不是自动触发，也不是从不触发。关键是理解何时压缩是安全的。