cpr-compress-preserve-resume：AI Agent 工具实践指南

团队讨论cpr-compress-preserve-resume时，我会先把用途说清楚：克劳德代码的持久内存，跨会话保存、搜索和恢复对话上下文。一旦进入网页与浏览器自动化环节，登录状态、页面变化和失败恢复往往不稳定会直接影响交付，这也是我最关心的风险。试跑可以从选择一个权限清楚的网页流程做端到端短测开始，并把会话保持、元素定位、错误恢复和工件留存写进验收记录。编辑判断上，需要可观测网页自动化流程的开发者可以优先研究它；其他团队不必为了热门标签勉强接入。

CPR 克劳德 Code

Compress，保留 & Resume

Persistent 跨会话内存。永远不会丢失上下文 again.

Estimated 会话重启令牌成本降低约 55%（分析模型，范围 24-68%）。

  Save key learnings to CLAUDE.md

  

三种自定义技能可保存、搜索和恢复您的对话上下文，以便您可以准确地从上次中断的地方继续。

Problem • Solution • Why 它节省了 Tokens • Installation • Usage • Workflow • Scaling • FAQ

什么是技能？

技能是 Claude Code 的自定义斜杠命令。您在对话中键入 /preserve、/compress 或 /resume，Claude 就会按照 Markdown 文件中定义的说明进行操作。没有代码，没有插件，只有正确文件夹中的 .md 文件。

克劳德代码从两个位置加载技能：

每个 .md 文件都会成为您可以运行的 /command。就是这样。 CPR 是其中三个文件。

问题

克劳德·代码在会话之间没有记忆。当你结束对话时，一切都消失了：决策、解决方案、背景，所有这些。

情况变得更糟：

解决方案

三种技能共同作用，让 Claude Code 具有记忆力：

Session Work ──> /preserve  ──> CLAUDE.md updated
                 /compress  ──> Session Log saved
                      |
                 /compact   ──> Context compressed (always LAST)
                      |
New Session  ──> /resume   ──> Loads CLAUDE.md + recent logs ──> Full context restored

运行 /preserve 和 /compress（按任意顺序） BEFORE /compact。 /compact 会清除整个上下文窗口，因此始终最后运行它。

关键：禁用自动压缩

当上下文窗口填满时，Claude Code 的自动压缩功能会自动压缩您的对话。这是敌人，在你保存细节之前就把它们扔掉。

禁用它：

1. 在 Claude 代码中输入 /config
2. 将 Auto-Compact 设置为 false （这是第一个选项）

或通过 CLI：

claude config set --global autoCompact false

关闭自动压缩后，您可以控制何时发生压缩：

1. /preserve：使用关键知识更新 CLAUDE.md
2. /compress：保存会话日志（保留所有内容）
3. /compact：压缩上下文（总是最后，因为你已经保存了）

这为您提供了一个干净、明确的工作流程，而不是无声的数据丢失。

为什么它可以节省代币

在每次会话开始时重新建立上下文的成本很高。用户重新解释项目，克劳德重新阅读文件，重新得出先前的决策，并且从头开始重建对话。 CPR 将其替换为重要内容的紧凑日志。

在整个建模范围内，会话重启令牌成本在低情况下下降 24%，在中值情况下下降 55%，在高情况下下降 68%。在一个包含 10 个会话的项目中，中位数大约节省了 ~83,250 个代币。在一个 20 个会话的高上下文项目中，它节省了 ~535,800 个令牌。

这些是分析估计，而不是遥测。 CPR 对于具有跨会话上下文的多会话项目是净正值，对于一次性错误修复或单会话工作是净负值。当下一个会话重复大约 3,700 个上下文重建工作时，就达到了收支平衡，大多数多会话项目都会在会话 #2 中交叉。

完整的方法、基准情景和每个组件的成本细分：docs/token-savings-analysis.md。

会话日志系统

每个 /compress 都会在项目根目录下的 CC-Session-Logs/ 中创建一个结构化 Markdown 文件。

文件名格式： DD-MM-YYYY-HH_MM-topic-name.md

Log结构（点击展开）

# Session Log: 05-03-2026 14:20 - api-auth-refactor

## Quick Reference (for AI scanning)
**Confidence keywords:** auth, JWT, refresh-tokens, middleware
**Projects:** my-saas-app
**Outcome:** Replaced cookie-based auth with JWT + refresh tokens

## Decisions Made
- JWT over session cookies, stateless scales better

## Key Learnings
- Redis EX flag is cleaner than separate EXPIRE calls

## Solutions & Fixes
- Login race condition fixed with SETNX

## Files Modified
- `src/middleware/auth.ts`: JWT verification

## Pending Tasks
- [ ] Add refresh token rotation

---
## Quick Resume Context
2-3 sentence summary for fast loading in /resume.

---
## Raw Session Log
{Full conversation archive, searchable but never loaded by /resume}

关键见解： /resume 仅读取摘要部分（“原始会话日志”上方的所有内容）。原始对话是为了可搜索性而存在，但它在上下文加载期间绝不会浪费令牌。

有关完整示例，请参阅 examples/session-log-example.md。

安装

先决条件

• 克劳德代码 CLI

1. 获取文件

git clone https://github.com/eliaalberti/cpr-compress-preserve-resume.git
cd cpr-compress-preserve-resume

2.安装技能

技能是位于 commands/ 文件夹中的 .md 文件。选择一项：

全局安装（在所有项目中可用）：

mkdir -p ~/.claude/commands
cp commands/*.md ~/.claude/commands/

按项目安装（仅在该项目中可用）：

mkdir -p /path/to/your/project/.claude/commands
cp commands/*.md /path/to/your/project/.claude/commands/

3.重启克劳德代码

技能在启动时加载。重新启动以显示新的 /preserve、/compress 和 /resume 命令。

4. 型号

所有这三种技能都默认为Claude Opus（frontmatter 中的 model: opus），以实现最大程度的上下文理解和输出质量。如果您没有 Opus 访问权限，请在每个文件的 frontmatter 中将 model: opus 更改为 model: sonnet。 Sonnet 4.6 作为后备版本效果很好。

5.禁用自动压缩

在 Claude Code 中输入 /config 并将 Auto-Compact 设置为 false （第一个选项）。

或通过 CLI：

claude config set --global autoCompact false

此步骤至关重要。 如果没有它，Claude Code 将在您有机会使用 /preserve 或 /compress 保存上下文之前默默地压缩您的上下文。

6. 测试

You: /compress

如果您看到保存问题，则说明它正在起作用。

用途

更新CLAUDE.md：保留关键知识

You: /preserve
Claude: What should be preserved? [multi-select]
You: 2, 6 (Key Decisions, Next Steps)
Claude: CLAUDE.md Updated
        Preserved:
        - Added JWT auth decision rationale
        - Updated next steps with token rotation
        CLAUDE.md is now 185 lines (target: <280)

会话结束：保存您的工作

You: /compress
Claude: What would you like to preserve? [multi-select]
  1. Key Learnings
  2. Solutions & Fixes
  3. Decisions Made
  4. Files Modified
  ...
You: 1, 2, 3, 4
Claude: Anything specific to highlight? (Type 'skip' to continue)
You: skip
Claude: Suggested topic: api-auth-refactor. Accept or type your own:
You: ok
Claude: Session saved to CC-Session-Logs/05-03-2026-17_30-api-auth-refactor.md
        Run /compact to compress context.

开始新会话：恢复上下文

You: /resume
Claude:
══════════════════════════════════════════════
 RESUMING: my-saas-app
══════════════════════════════════════════════

CONTEXT:
- JWT auth flow implemented, tests passing
- Redis used for refresh token storage

MOST RECENT SESSION: 05-03-2026 17:30
Topic: api-auth-refactor
...

READY TO:
- Add refresh token rotation
- Set up token blacklist for logout
══════════════════════════════════════════════

按主题搜索过去的会议

You: /resume auth
Claude: [Shows recent sessions + RELATED SESSIONS matching "auth"]

══════════════════════════════════════════════
 RELATED SESSIONS (Topic: "auth")
══════════════════════════════════════════════

- 05-03-2026: api-auth-refactor, JWT + refresh tokens
- 28-02-2026: oauth-google-setup, Google OAuth integration
══════════════════════════════════════════════

推荐工作流程

┌──────────────────────────────────────────────────────┐
│  1. Start session                                    │
│     └── /resume          Load context                │
│                                                      │
│  2. Do work...                                       │
│     └── (normal Claude Code usage)                   │
│                                                      │
│  3. Before ending or when context is filling up      │
│     ├── /preserve        Update CLAUDE.md (optional) │
│     ├── /compress        Save session log            │
│     └── /compact         Compress context (LAST)     │
└──────────────────────────────────────────────────────┘

何时 /preserve：

• 做出重要的架构决策后
• 当您发现未来课程中需要的模式时
• 当项目 phase/status 发生变化时

何时 /compress：

• 结束会话之前
• 在上下文填满之前（如果您发现回复变得不太具体）
• 完成大量工作后

定制化

Session 日志存储 path

默认情况下，日志转到 {project_root}/CC-Session-Logs/。通过从当前目录向上查找 CLAUDE.md 或 .git 来检测项目根目录。

要更改此设置，请编辑 commands/compress.md 和 commands/resume.md 中的路径检测逻辑（分别为步骤 5/步骤 3）。

CLAUDE.md 线 target

默认目标是 280 行。通过修改阈值在 commands/preserve.md（步骤 6）中更改此设置。

Protected sections

将 CLAUDE.md 中的任何部分标记为不受存档影响：

## My Important Section (PROTECTED)
This will never be suggested for archiving.

或者将部分标记为可以安全存档：

## Old Notes (ARCHIVABLE)
This will be auto-suggested for archiving when CLAUDE.md gets too long.

Core sections

编辑 commands/preserve.md 中的“CORE 部分”列表以匹配您的 CLAUDE.md 结构。从来不建议对这些部分进行存档。

如何扩展

原始会话日志可能会变得很大（完整的对话存档），但 /resume 永远不会读取超过 ## Raw Session Log 标记。仅加载结构化摘要标头。

FAQ

Do 我需要全部三个技能？

/compress + /resume 是最小可行设置。 /preserve 是可选的，但推荐使用。它使您的 CLAUDE.md 保持最新状态，无需手动编辑。

Where 是否存储日志？

{project_root}/CC-Session-Logs/。项目根目录是包含 CLAUDE.md 或 .git 的最近的父目录。如果两者都没有找到，它将回退到当前工作目录。

Will 这适用于任何项目吗？

是的。该技能会在首次使用时自动检测您的项目根目录并创建 CC-Session-Logs/ 文件夹。无需配置。

How 大日志得到了吗？

包含原始对话的完整会话日志可能有数百个 KB。但 /resume 仅读取摘要标头（通常为 30-80 行），因此无论日志大小如何，令牌使用率都保持较低水平。

Should 我将会话日志提交到 git？

由你决定。它们对于团队知识共享很有用，但可能很大。如果您希望将它们保留在本地，请考虑将 CC-Session-Logs/ 添加到 .gitignore。

What 如果我在 /compact 之前忘记 /preserve 或 /compress？

压缩的上下文仍然有效，但您将丢失详细的会话日志和 CLAUDE.md 更新。始终在 /compact 之前运行 /preserve和/或/compress，因为 /compact 会清除整个上下文窗口。

Can 我将其与子目录中的 CLAUDE.md 文件一起使用？

这些技能在项目根目录中查找 CLAUDE.md。如果您有多个 CLAUDE.md 文件（e.g.、monorepo），请从相关子目录运行。