token-efficiency

Token 效率专家

此技能提供 Token 优化策略，帮助你在所有项目中以较低成本使用 Claude Code。这些指南有助于在保持高质量协助的同时，尽量减少 Token 消耗。

核心原则

默认始终遵循这些优化指南，除非用户明确要求详细输出或完整文件内容。

默认假设：用户更喜欢高效且经济的协助。

---

模型选择策略

为任务选择合适的模型，以优化成本和性能：

Opus — 用于学习和深入理解

以下情况使用 Opus：

• 学习新的代码库——理解架构、代码结构和设计模式
• 广泛探索——识别关键文件，了解仓库组织方式
• 深入分析——分析复杂算法、优化性能
• 阅读和理解——在修改前需要理解现有代码时
• 极其复杂的调试——仅在 Sonnet 无法解决问题或问题涉及架构时

Sonnet — 用于常规开发任务（默认）

以下情况使用 Sonnet（默认）：

• 编写代码、编辑和修复、调试、测试、文档、部署和一般问题

典型会话模式：

1. 从 Opus 开始——花 10-15 分钟理解代码库（一次性投入）
2. 切换到 Sonnet——将其用于所有实现、调试和常规工作
3. 返回 Opus——仅在明确需要深入理解架构时使用

相比全程使用 Opus，可节省约 50% 的 Token 成本。

---

技能与 Token 效率

误区： 在 .claude/skills/ 中添加许多技能会增加 Token 用量。

事实： 技能采用渐进式披露——会话开始时 Claude 只会看到技能描述（4 个技能约 155 个 Token）。只有激活技能后，才会加载其完整内容。

将多个技能符号链接到项目中是安全的。 浪费 Token 的原因是无谓地读取大型文件，而不是技能可供使用。

---

Token 优化规则（速查）

1. 使用安静／精简输出模式

默认使用 --quiet、-q、--silent 标志。只有用户明确要求时才使用详细模式。

2. 绝不读取整个日志文件

读取前始终先过滤：tail -100、grep -i "error"、指定时间范围。

3. 先检查轻量级来源

读取大型文件之前，先检查 git status --short、package.json、requirements.txt。

4. 使用 Grep 代替读取文件

使用 Grep 工具搜索特定内容，而不是读取整个文件。

5. 限制文件读取范围

使用 offset 和 limit 参数。先用 wc -l 检查文件大小。

6. 使用 Bash 命令代替读取文件

**重要优化：**适用于纯转换和检查操作。读取文件会消耗 Token；Bash 命令不会。

操作	低效	高效
复制文件	读取 + 写入	cp source dest
替换文本	读取 + 编辑	sed -i '' 's/old/new/g' file
追加内容	读取 + 写入	echo "text" >> file
删除行	读取 + 写入	sed -i '' '/pattern/d' file
合并文件	读取 + 读取 + 写入	cat file1 file2 > combined
统计行数	读取文件	wc -l file
检查内容	读取文件	grep -q "term" file
检查 JSON	读取 + 凭思维解析	python3 -c "import json; ..." 或 jq

以下情况可不遵循此规则——优先选择读取 + 编辑：

• 代码编辑（.py、.js、.xml、.ga、.tsx 等），因为用户可以查看便于审阅的差异。为便于审阅而读取小型文件是值得的。
• 需要验证——语法错误可能会损坏文件时（工作流 JSON、配置架构）。
• 交互式审阅——用户明确希望查看修改内容时。

正确的思路是基于范围（见下一节），而不是“一律使用 Bash”或“一律读取 + 编辑”。更多策略和模式请参阅 strategies.md。

7. 筛选命令输出

限制范围：head -50、find . -maxdepth 2、tree -L 2。

8. 总结，而不是倾倒内容

以结构化方式总结目录内容、代码结构和命令输出。

9. 对大型输出使用 Head/Tail

使用 head -100、tail -50，或从中间抽样：head -500 | tail -100。

10. 高效使用 JSON/数据工具

提取指定字段：jq '.metadata'、jq 'keys'。对于 CSV：使用 head -20、wc -l。

11. 优化代码阅读

先了解概况（使用 find、grep 查找类/函数），只阅读结构，搜索特定代码，仅阅读相关部分。

12. 使用 Task 工具进行探索性搜索

使用 Task/Explore 子 Agent 广泛探索代码库。与直接探索多个文件相比，可节省 70-80% 的 Token。

13. 高效搜索科学文献

并行批量执行 3-5 个相关搜索。立即保存结果。记录“未找到”的项目。

详细策略、bash 模式和大量示例，请参阅 strategies.md。

---

根据范围选择工具

在 bash 和 Read+Edit 之间做选择，不只是考虑 Token 成本，还要看用户是否能从查看更改中受益。根据工作范围选择合适的工具：

范围	首选工具	原因
只读检查结构化数据（JSON、YAML、JSONL、大型日志）	python3 -c、jq、grep、awk	bash 输出可筛选；不会误改源文件。使用内联 python3 -c 检查 JSON，比 Read+解析更快、成本更低。
原地编辑代码（.py、.js、.xml、.ga、.tsx）	Read + Edit	用户可以查看差异；能及早发现语法错误。
转换大型数据文件（CSV、大型 JSON、BAM 派生的 TSV）	sed、awk、python3 脚本	读取整个文件会消耗数千个 Token。
从头创建新文件	Write 工具	一次往返即可；bash heredoc 没有额外价值，也无法供用户审查。

快速规则：如果用户希望查看并批准更改，请使用 Read+Edit。如果只是处理或检查数据，请使用 bash/python。

文件操作决策树

请问自己：

1. 要创建新文件？ -> 使用 Write 工具
2. 低成本操作（输出少于 100 行）？-> 直接使用 Claude 上下文
3. 要修改代码文件（.py、.js、.xml）？-> 使用 Read + Edit（始终如此）
4. 要修改小型数据文件（少于 100 行）？-> 使用 Read + Edit 即可
5. 要修改关键数据（基因组统计数据、富集表）？-> 使用 bash + 日志文件
6. 要修改大型数据文件？ -> 使用 sed/awk
7. 要复制/移动文件？ -> 使用 cp/mv

---

何时不遵循这些指南

以下情况可不遵循效率规则：

1. 用户明确要求完整输出（“给我看整个日志文件”）
2. 筛选后的输出缺少必要上下文（错误引用了缺失的行号）
3. 已知文件较小（少于 200 行）
4. 学习代码结构和架构——优先理解，而不是追求效率

学习模式下：

• 完整阅读 2-5 个关键文件，建立整体认识
• 使用 grep 查找其他相关示例
• 总结多个文件中发现的模式
• 学习阶段结束后，在实现时回到高效模式
• 有关学习模式的详细策略，请参阅 learning-mode.md

对于情况 1-3，向用户说明 Token 成本，并先提供筛选视图。

---

快速参考卡

模型选择（优先级最高）：

• 学习／理解 -> 使用 Opus
• 开发／调试／实现 -> 使用 Sonnet（默认）

执行任何文件操作前，请先问自己：

1. 我是在创建新文件吗？ -> 直接使用 Write 工具
2. 这是低成本操作吗？（< 100 行） -> 直接使用 Claude 上下文
3. 我是在修改代码文件吗？ -> Read + Edit（始终如此）
4. 我是在修改小型数据文件吗？（< 100 行） -> 使用 Read + Edit 即可
5. 我是在修改关键数据吗？ -> 使用 bash + 日志文件
6. 我是在修改大型数据文件吗？ -> 使用 bash 命令（节省 99% 以上）
7. 我是在复制／合并文件吗？ -> 使用 cp/cat，而不是 Read/Write
8. 我能否先检查元数据？（文件大小、行数）
9. 我能否在读取前先筛选？（grep、head、tail）
10. 我能否只读取结构？（前 50 行、函数名）
11. 我能否用摘要代替原始数据？
12. 用户真的需要完整内容吗？

---

成本影响

方式	每周 Token 数	备注
浪费（对所有内容执行 Read/Edit/Write）	500K	不必要地读取文件
适度（仅筛选后读取）	200K	使用 Grep/head/tail
高效（bash 命令 + 筛选）	30-50K	使用 cp/sed/awk 代替 Read

应用这些规则，平均可降低 90-95% 的成本。

---

实施

此技能会自动在以下情况下应用这些优化：

• 读取日志文件时
• 执行输出量很大的命令时
• 浏览代码库时
• 调试错误时
• 检查系统状态时

你可以随时说以下内容来覆盖这些设置：

• “显示完整输出”
• “读取整个文件”
• “我想使用详细模式”
• “不用担心 Token 数量”

---

支持文件

文件	内容	何时加载
strategies.md	详细的 bash 命令策略、文件操作模式、sed/awk 示例、Jupyter 笔记本操作、安全的 glob 模式、macOS/Linux 兼容性	执行特定文件操作或需要详细 bash 模式时
learning-mode.md	策略性文件选择、定向模式学习工作流、广泛的代码库探索策略、代码库类型识别	进入学习模式或探索新代码库时
examples.md	丰富的 Token 节省示例，含前后对比、定向学习示例（Galaxy 封装器、API 模式）、成本计算	展示 Token 节省效果或通过示例学习时
project-patterns.md	分析文件组织、使用 TodoWrite 进行任务管理、后台进程管理、代码库组织、MANIFEST 系统、高效文件操作	组织项目、管理长时间运行的任务或设置导航模式时

---

总结

核心准则：选对模型。选对工具。先筛选。选择性读取。智能总结。

模型选择（影响最大）：

• 学习／理解时使用 Opus（一次性投入）
• 开发／调试／实现时使用 Sonnet（默认）

工具选择（主要优化项）：

• 创建新文件 -> 直接使用 Write 工具
• 低成本操作（< 100 行） -> 直接使用 Claude 上下文
• 修改代码文件 -> Read + Edit（始终如此）
• 修改小型数据文件（< 100 行） -> 使用 Read + Edit 即可
• 修改大型数据文件 -> 使用 bash 命令（sed、awk、grep）
• 修改关键数据 -> 使用 bash 命令 + 日志文件
• 复杂编辑 -> 使用 Read + Edit 工具

次要规则：

• 读取前先筛选（grep、head、tail）
• 必要时限制读取范围
• 用摘要代替原始输出
• 使用命令的静默模式
• 学习时策略性地选择文件

遵循这些指南，用户可以从 Claude 订阅中获得 5-10 倍的价值，同时保持高质量的协助。