Strategic compaction skill: suggests context compression at logical breakpoints. Use to suggest compaction at logical intervals during development sessions.
本技能用于在合适的时机建议上下文压缩，优化会话效率。
⚠️ 重要提示：Claude Code 官方的 auto-compact 有已知 bug（见下文），建议主动在 70% 时手动压缩。
Claude Code 官方的自动压缩功能存在已知问题：
| Issue | 版本 | 状态 | 问题描述 |
|---|---|---|---|
| #18211 | v2.1.7+ | 已关闭 | /cc-best:compact-context 和 auto-compact 同时损坏 |
| #21853 | v2.1.23+ | 开放 | /cc-best:compact-context 始终失败（回归 bug） |
| #16349 | - | - | 警告和错误阈值相同，无预警 |
问题根因：
本插件的 Workaround：
suggest-compact.js 钩子1. 探索/研究完成，准备开始实现
2. 计划已确定，准备执行
3. 完成一个功能模块
4. 解决一个复杂问题后
5. 代码审查反馈处理完
6. 上下文使用率 > 70%
1. 调试进行中
2. 多文件修改未完成
3. 测试失败修复中
4. 重要决策讨论中
5. 复杂逻辑实现中途
管线阶段切换是最佳压缩时机。除了基于工具调用计数的提醒，系统还会在检测到阶段切换时主动建议压缩。
| 阶段切换 | 压缩建议 | 原因 |
|---|---|---|
| 研究/探索 → 架构设计 | ✅ 强烈 | 搜索上下文占用大量 token |
| 架构设计 → 任务分解 | ✅ 推荐 | 设计文本较长 |
| 任务分解 → 代码实现 | ✅ 推荐 | 设计和实现上下文差异大 |
| 代码实现 → 测试验证 | ⚠️ 视情况 | 测试可能需要代码细节 |
| 测试验证 → 下一任务 | ✅ 推荐 | 清除 bug trace 噪音 |
| 失败方案 → 新方案 | ✅ 强烈 | 清除死路思路 |
memory-bank/progress.md 的最近状态变化## 压缩前确认
- [ ] 当前任务状态已记录到 progress.md
- [ ] 重要决策已记录
- [ ] 待确认假设已标注
- [ ] 未完成的代码变更已保存
- [ ] 下一步明确
## 压缩内容
- 当前进度
- 关键决策及原因
- 待处理项
- 下一步任务
/cc-best:compact-context
当达到以下条件时，系统会提示考虑压缩：
# 环境变量
export COMPACT_THRESHOLD=40 # 首次提醒的工具调用数
export COMPACT_INTERVAL=20 # 后续提醒间隔
已在 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 → 恢复上下文继续工作
记住：好的压缩时机比压缩本身更重要。在逻辑断点压缩，保持思维连贯性。
| 阶段 | Token 占比 | 说明 |
|---|---|---|
| 上下文注入 | <=15% | memory-bank + context 模板 |
| 探索/研究 | <=25% | 文件搜索、阅读、理解 |
| 实现 | <=40% | 编码、测试、调试 |
| 审查/验证 | <=15% | 代码审查、安全扫描 |
| 缓冲 | >=5% | 预留给意外情况 |
技术限制: Claude Code 不向 hooks 暴露 token 计数，只能基于工具调用次数粗略估算。 调试循环中（检测到 fix_retry 模式时），compact 建议会自动抑制，避免中断修复流程。
