strategic-compact

# 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 脚本在 Edit/Write 时运行。 --> `suggest-compact.js` 脚本在 PreToolUse（Edit/Write）时运行，并且： 1. **追踪工具调用** ——计算会话中的工具调用次数 2. **阈值检测** ——在可配置阈值（默认：50 次调用）时建议 3. **定期提醒** ——阈值后每 25 次调用提醒一次 **为什么追踪工具调用？** 工具调用次数是上下文使用的代理指标。 **示例流程：** ``` 会话开始： - 第 10 次工具调用：正常 - 第 30 次工具调用：正常 - 第 50 次工具调用：⚠️ 建议压缩 - 第 75 次工具调用：⚠️ 再次建议 - 第 100 次工具调用：⚠️ 强烈建议 ``` ## Hook 设置 <!-- 【教学说明】 添加到 settings.json 启用自动建议。 --> 添加到你的 `~/.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" }] } ] } } ``` **什么是 PreToolUse？** 在工具执行**前**触发的 hook。 ## 配置 环境变量： - `COMPACT_THRESHOLD` ——首次建议前的工具调用次数（默认：50） **设置阈值：** ```bash # 默认：50 次调用 # 保守：100 次调用（更少建议） # 激进：25 次调用（更频繁建议） ``` ## 压缩决策指南 <!-- 【教学说明】 使用此表决定何时压缩。 --> 使用此表决定何时压缩： | 阶段转换 | 压缩？ | 为什么 | |---------|--------|------| | 研究 → 计划 | ✅ 是 | 研究上下文庞大；计划是提炼的输出 | | 计划 → 实现 | ✅ 是 | 计划在 TodoWrite 或文件中；释放上下文给代码 | | 实现 → 测试 | ⚠️ 可能 | 如果测试引用最近代码则保留；切换焦点则压缩 | | 调试 → 下一功能 | ✅ 是 | 调试痕迹污染不相关工作的上下文 | | 实现中途 | ❌ 否 | 丢失变量名、文件路径和部分状态代价高昂 | | 失败方法后 | ✅ 是 | 在尝试新方法前清理死胡同推理 | **详细说明：** ### 研究 → 计划（压缩） ``` 你花了 30 分钟研究 API 文档。 现在你有详细的计划在 TodoWrite 中。 压缩： ✅ 保留：TodoWrite 任务列表 ✅ 保留：计划文档 ❌ 丢弃：30 分钟的阅读记录 ``` ### 计划 → 实现（压缩） ``` 你有完整的功能计划。 现在开始编写代码。 压缩： ✅ 保留：计划（在文件或 TodoWrite 中） ✅ 释放上下文给代码 ❌ 丢弃：规划讨论 ``` ### 实现中途（不压缩） ``` 你正在实现功能的一半。 变量名、函数名、文件路径都很重要。 不压缩： ❌ 丢失：当前上下文 ❌ 丢失：变量名 ❌ 丢失：部分状态 ``` ### 调试后（压缩） ``` 你花了 20 分钟调试一个错误。 现在错误已修复，继续下一个功能。 压缩： ✅ 清理调试痕迹 ✅ 释放上下文给新功能 ❌ 丢弃：调试对话 ``` ## 压缩后保留什么 <!-- 【教学说明】 理解什么持续存在有助于你有信心地压缩。 --> 理解什么持续存在有助于你有信心地压缩： | 持续存在 | 丢失 | |----------|------| | CLAUDE.md 指令 | 中间推理和分析 | | TodoWrite 任务列表 | 你之前读取的文件内容 | | 内存文件 (`~/.claude/memory/`) | 多步对话上下文 | | Git 状态（提交、分支） | 工具调用历史和计数 | | 磁盘上的文件 | 口头表达的细微用户偏好 | **关键点：** - ✅ **磁盘上的文件安全** ——所有已保存的文件都存在 - ✅ **TodoWrite 安全** ——任务列表保留 - ✅ **Git 状态安全** ——提交和分支保留 - ❌ **上下文中的内容丢失** ——未保存的分析、对话历史 **压缩前做什么：** ```bash # 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`** ——添加自定义消息 **示例压缩命令：** ```bash # 基本压缩 /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](https://x.com/affaanmustafa/status/2014040193557471352) ——Token 优化章节 - 内存持久化 hooks ——压缩后幸存的状态 - `continuous-learning` 技能——会话结束前提取模式 --- **记住**：策略压缩是在正确时间手动触发——不是自动触发，也不是从不触发。关键是理解**何时**压缩是安全的。