/compact

name: compact
description: "Strategic compaction skill: suggests context compression at logical breakpoints. Use to suggest compaction at logical intervals during development sessions."
allowed-tools: Read, Bash
parent: session

策略性压缩技能

本技能用于在合适的时机建议上下文压缩，优化会话效率。

> ⚠️ **重要提示**：Claude Code 官方的 auto-compact 有已知 bug（见下文），建议主动在 **70%** 时手动压缩。

官方 Auto-Compact Bug

Claude Code 官方的自动压缩功能存在已知问题：

| Issue | 版本 | 状态 | 问题描述 | | ---------------------------------------------------------------- | -------- | -------- | --------------------------------------------------- | | [#18211](https://github.com/anthropics/claude-code/issues/18211) | v2.1.7+ | 已关闭 | `/cc-best:compact-context` 和 auto-compact 同时损坏 | | [#21853](https://github.com/anthropics/claude-code/issues/21853) | v2.1.23+ | **开放** | `/cc-best:compact-context` 始终失败（回归 bug） | | [#16349](https://github.com/anthropics/claude-code/issues/16349) | - | - | 警告和错误阈值相同，无预警 |

**问题根因**：

• 官方 auto-compact 设计在 **95%** 时触发，但压缩本身需要空间
• 当上下文超过 **~85%** 时，压缩可能因空间不足而失败
• 警告阈值和错误阈值相同，用户无预警就触发硬限制

**本插件的 Workaround**：

• 默认启用 `suggest-compact.js` 钩子
• 每 40 次工具调用提醒一次
• 建议在 **70%** 时主动压缩

触发条件

• 工具调用次数达到阈值（默认 40 次）
• 从研究/探索阶段转向实现阶段
• 完成一个里程碑后
• 计划已最终确定
• **上下文使用率 > 60%**（建议主动压缩）

为什么需要策略性压缩

自动压缩的问题

• 发生在任意点，经常在任务中途
• 可能丢失重要上下文
• 打断思维连贯性
• **官方有 bug，可能失败**

策略性压缩的优势

• 在逻辑阶段边界压缩
• 保留关键决策和上下文
• 探索后、执行前压缩
• 里程碑完成后压缩
• **避免触发官方 bug**

压缩时机

适合压缩的时机

1. 探索/研究完成，准备开始实现
2. 计划已确定，准备执行
3. 完成一个功能模块
4. 解决一个复杂问题后
5. 代码审查反馈处理完
6. 上下文使用率 > 70%

不适合压缩的时机

1. 调试进行中
2. 多文件修改未完成
3. 测试失败修复中
4. 重要决策讨论中
5. 复杂逻辑实现中途

阶段感知压缩 | Phase-Aware Compaction

管线阶段切换是最佳压缩时机。除了基于工具调用计数的提醒，系统还会在检测到阶段切换时主动建议压缩。

阶段切换压缩矩阵

| 阶段切换 | 压缩建议 | 原因 | | -------------------- | --------- | ------------------------ | | 研究/探索 → 架构设计 | ✅ 强烈 | 搜索上下文占用大量 token | | 架构设计 → 任务分解 | ✅ 推荐 | 设计文本较长 | | 任务分解 → 代码实现 | ✅ 推荐 | 设计和实现上下文差异大 | | 代码实现 → 测试验证 | ⚠️ 视情况 | 测试可能需要代码细节 | | 测试验证 → 下一任务 | ✅ 推荐 | 清除 bug trace 噪音 | | 失败方案 → 新方案 | ✅ 强烈 | 清除死路思路 |

检测方式

• 读取 `memory-bank/progress.md` 的最近状态变化
• 管线角色切换（PM→Lead、Lead→Dev、Dev→QA）触发建议
• 阶段检测为**补充建议**，不替换现有计数器逻辑

压缩前检查清单

## 压缩前确认

- [ ] 当前任务状态已记录到 progress.md
- [ ] 重要决策已记录
- [ ] 待确认假设已标注
- [ ] 未完成的代码变更已保存
- [ ] 下一步明确

## 压缩内容

- 当前进度
- 关键决策及原因
- 待处理项
- 下一步任务

使用方式

手动触发

/cc-best:compact-context

自动建议

当达到以下条件时，系统会提示考虑压缩：

1. **工具调用数达到阈值**（默认 40 次） 2. **每隔一定间隔**（默认每 20 次工具调用后提醒）

配置

阈值配置

# 环境变量
export COMPACT_THRESHOLD=40  # 首次提醒的工具调用数
export COMPACT_INTERVAL=20   # 后续提醒间隔

Hook 配置

已在 `hooks/hooks.json` 中默认启用：

{
  "matcher": ".*",
  "hooks": [
    {
      "type": "command",
      "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/node/hooks/suggest-compact.js\"",
      "timeout": 3
    }
  ],
  "description": "压缩提醒: 工具调用达到阈值时提醒压缩上下文"
}

压缩摘要模板

压缩时，确保包含以下信息：

## 会话摘要

### 完成的任务

1. [任务1描述]
2. [任务2描述]

### 关键决策

| 决策    | 原因   | 置信度   |
| ------- | ------ | -------- |
| [决策1] | [原因] | 高/中/低 |

### 当前状态

- 进度: [百分比或阶段]
- 阻塞: [如有]

### 待处理

- [ ] [待处理项1]
- [ ] [待处理项2]

### 下一步

[明确的下一步任务]

与其他命令配合

/cc-best:compact-context     # 保存状态 + 生成摘要
/cc-best:checkpoint  # 创建检查点
/cc-best:catchup     # 恢复上下文
/cc-best:status      # 查看当前状态
/clear               # 官方命令：清除上下文

推荐流程

1. /cc-best:compact-context    → 保存状态、生成摘要
2. /clear              → 官方命令清除上下文
3. /cc-best:catchup    → 恢复上下文继续工作

最佳实践

1. **阶段边界压缩** - 探索→实现，设计→编码 2. **记录再压缩** - 先更新 progress.md 3. **明确下一步** - 压缩摘要包含下一步 4. **不要中途压缩** - 避免在复杂任务中途 5. **关注上下文率** - 超过 70% 考虑压缩 6. **保留关键决策** - 重要决策带入新上下文 7. **标注待确认项** - 不确定的内容明确标注

---

> **记住**：好的压缩时机比压缩本身更重要。在逻辑断点压缩，保持思维连贯性。

Token 预算策略

| 阶段 | Token 占比 | 说明 | | ---------- | ---------- | -------------------------- | | 上下文注入 | <=15% | memory-bank + context 模板 | | 探索/研究 | <=25% | 文件搜索、阅读、理解 | | 实现 | <=40% | 编码、测试、调试 | | 审查/验证 | <=15% | 代码审查、安全扫描 | | 缓冲 | >=5% | 预留给意外情况 |

> 技术限制: Claude Code 不向 hooks 暴露 token 计数，只能基于工具调用次数粗略估算。 > 调试循环中（检测到 fix_retry 模式时），compact 建议会自动抑制，避免中断修复流程。