第 08 期 | /caveman:compress — 压缩你的 CLAUDE.md，每次省 46% 输入 Token

🎯 学习目标

学完本期你将掌握：

1. 输入 Token 与输出 Token 的区别，以及为什么压缩输入同样重要
2. /caveman:compress 的使用方法和文件处理机制
3. 压缩的安全规则——哪些内容会被压缩，哪些不会
4. 在不同平台上使用 compress 的最佳实践

📖 核心内容

8.1 被忽视的成本：输入 Token

前面几期我们一直在讲如何压缩 Agent 的输出。但实际上，还有一个更隐蔽的 Token 消耗来源：输入。

每次你启动一个 Claude Code 会话，Agent 会自动读取：

• CLAUDE.md (项目级规则)
• ~/.claude/CLAUDE.md (用户级规则)
• 各种 Skill 文件
• MCP 配置

graph TD
    A["会话启动"] --> B["读取 CLAUDE.md
~1200 tokens"]
    A --> C["读取 ~/.claude/CLAUDE.md
~800 tokens"]
    A --> D["读取 Skill 文件
~500 tokens"]
    A --> E["读取 MCP 配置
~300 tokens"]
    
    B --> F["总输入: ~2800 tokens
每次会话都要支付"]
    C --> F
    D --> F
    E --> F
    
    F --> G["一天 20 次会话
= 56,000 输入 tokens/天
= 仅上下文加载就花费 ~$0.84/天"]

这些文件在你的整个项目生命周期内很少改变，但每次会话启动都要重新读取和支付 Token。这就是 caveman-compress 要解决的问题。

8.2 Compress 的工作原理

graph LR
    A["CLAUDE.md
1200 tokens
人类可读版"] -->|"/caveman:compress CLAUDE.md"| B["处理流程"]
    
    B --> C["CLAUDE.md
648 tokens
压缩版 (Claude 读)"]
    B --> D["CLAUDE.original.md
1200 tokens
备份 (人类读)"]
    
    E["每次会话启动"] -->|"读取"| C
    F["开发者维护"] -->|"编辑"| D
    
    style C fill:#90EE90,stroke:#2E8B57
    style D fill:#87CEEB,stroke:#4169E1

核心设计：

1. 原始文件被备份为 .original.md（你继续编辑这个）
2. 原始文件被覆盖为压缩版（Claude 读这个，更少 Token）
3. 技术内容保持不动，只有散文描述被 Caveman 化

8.3 使用方法

基础用法

# 在 Claude Code 中
> /caveman:compress CLAUDE.md

# 输出:
# ✅ Compressed CLAUDE.md (1200 → 648 tokens, saved 46%)
# 📄 Original saved as CLAUDE.original.md

压缩其他文件

# 压缩用户级偏好
> /caveman:compress claude-md-preferences.md

# 压缩项目笔记
> /caveman:compress project-notes.md

# 压缩待办列表
> /caveman:compress todo-list.md

# 压缩任何 Markdown 上下文文件
> /caveman:compress any-context-file.md

在其他平台上

8.4 安全规则：什么不会被压缩

这是 compress 最重要的设计原则——技术内容永远不会被修改：

graph TB
    subgraph Safe["✅ 不会被压缩 (原样保留)"]
        A1["代码块
```python...```"]
        A2["URL 链接
https://..."]
        A3["文件路径
src/utils/auth.ts"]
        A4["命令行
npm install / git commit"]
        A5["标题 / Heading
# ## ###"]
        A6["日期 / 版本号
v2.3.0 / 2026-04-22"]
    end
    
    subgraph Compressed["🔧 会被压缩 (Caveman 化)"]
        B1["散文描述
'This project is a...'"]
        B2["解释性段落
'The reason we chose...'"]
        B3["冗余修饰
'Please make sure to always...'"]
    end
    
    style Safe fill:#E8F5E9,stroke:#4CAF50
    style Compressed fill:#FFF3E0,stroke:#FF9800

压缩前后对比

压缩前 (CLAUDE.md):

# Project Architecture

This project is built using a modern microservices architecture 
with TypeScript as the primary language. We chose this approach 
because it provides better scalability and allows independent 
deployment of each service.

## Important Rules

Please make sure to always follow these guidelines when making 
changes to the codebase:

1. Always run `npm test` before committing
2. Use the `src/utils/logger.ts` module for all logging
3. Database queries must go through `src/db/repository.ts`

压缩后 (CLAUDE.md → Claude 读这个):

# Project Architecture

Microservices, TypeScript primary. Independent deploy per service.

## Important Rules

1. Run `npm test` before commit
2. Log via `src/utils/logger.ts`
3. DB queries through `src/db/repository.ts`

备份 (CLAUDE.original.md → 你编辑这个):

保持原始完整内容不变。

8.5 日常维护工作流

graph TD
    A["需要更新项目规则"] --> B["编辑 CLAUDE.original.md"]
    B --> C["重新压缩"]
    C --> D["/caveman:compress CLAUDE.md"]
    D --> E["CLAUDE.md 更新为新的压缩版"]
    D --> F["CLAUDE.original.md 更新为新的备份"]
    
    G["⚠️ 不要直接编辑 CLAUDE.md！"] -->|"会被下次压缩覆盖"| B
    
    style G fill:#FFEBEE,stroke:#F44336

⚠️ 重要提醒：

• 编辑 → 修改 CLAUDE.original.md
• 压缩 → 运行 /caveman:compress CLAUDE.md
• 不要直接编辑压缩后的 CLAUDE.md，它会在下次压缩时被覆盖

8.6 各平台的上下文文件对应表

💻 实战练习

练习：压缩你的项目 CLAUDE.md

1. 查看当前 CLAUDE.md 的 Token 数（粗略估计：1 个英文单词 ≈ 1.3 token，1 个中文字 ≈ 2 token）
2. 运行 /caveman:compress CLAUDE.md
3. 对比压缩前后的 Token 数
4. 确认 CLAUDE.original.md 是否正确保存了原文
5. 启动一个新会话，确认 Agent 能正常读取压缩版

📊 压缩效果统计

根据 Caveman 官方基准测试，不同类型的文件压缩率：

💡 最佳实践：将 CLAUDE.md 中的"是什么"和"为什么"写在散文段落里（这些会被压缩），将"如何做"写在代码块和命令里（这些保持原样）。

📝 本期要点回顾

1. 输入 Token 是每次会话的隐性成本，CLAUDE.md 每次启动都要重新支付
2. /caveman:compress 将散文压缩为 Caveman 风格，平均节省 46% 输入 Token
3. 安全保证：代码块、URL、文件路径、命令行、标题、版本号永不压缩
4. 压缩后编辑 *.original.md，不要直接编辑压缩版
5. 各平台都有对应的上下文文件（CLAUDE.md / GEMINI.md / AGENTS.md），都可以压缩

🔗 参考资料

• Caveman Compress README
• Caveman Compress 安全说明
• CLAUDE.md 最佳实践