token-discipline

Token Discipline

你的上下文窗口有限。用户直接（通过 API）或间接（通过套餐限制和速率上限）为 Token 付费。你的工作是完整地完成任务，同时尽量减少对话开销。大多数上下文都浪费在复述文件内容、反复读取相同文件、用文字记录计划，以及倾倒未经筛选的工具输出上。这些都不是工作，只是消耗。

把上下文当作预算。把它花在思考、决策和差异上，不要浪费在噪声上。

七个习惯（默认应用，而不只是“快用完时”才应用）

1. 用 offset 和 limit 读取文件——绝不一口气读完整个文件

Read 工具默认读取约 2000 行。大多数文件不需要读这么多。大多数任务只涉及 10-50 行。

• 文件少于 100 行：整份读取。
• 文件有 100-500 行：先扫描结构（用 grep -n 查找符号），然后仅用 offset 和 limit 读取相关片段。
• 文件超过 500 行：绝不整份读取。先定位，再读取一个窗口。

刚编辑完就重新读取文件，几乎总是错误的。执行环境已经跟踪了更改。

2. 把研究委派给子 Agent——保护主上下文

回答需要读取 3 个或更多文件的问题时，应交给子 Agent（只读查找用 Explore，多步骤研究用 general-purpose）。子 Agent 消耗自己的上下文，并返回一段简述。

以下情况应交给子 Agent，而不是自己直接读取：

• “X 在哪里定义，哪些地方调用了它？”
• “找出所有处理 Y 的位置。”
• “是否已有用于 Z 的辅助函数？”
• 任何开放式的“在代码库中，在哪里／如何实现……”问题。

之后不要自己重复相同的搜索。相信子 Agent 的报告。

3. 用管道过滤长输出——绝不让原始 bash 输出涌入上下文

对所有可能很长的输出，默认使用 tail/head。

• 构建和测试：... | tail -50
• 查找（find、ls -R、grep -r）：... | head -50
• 长日志：... | tail -200，或先用 grep <pattern>
• 不要把整个 JSON 负载格式化输出；用 jq '.field' 提取所需内容。

如果完整输出滚过了实际有用的信息，就没有价值。在源头过滤。

4. 使用 TodoWrite（或同等任务跟踪工具）——不要用文字记录计划

用对话文本写出的多步骤计划，会在之后的每一轮中再次出现。同一计划若用 TodoWrite 跟踪，就能保存在一个精简结构中，并原位更新。

规则：如果你打算在消息中写一个“我会先做 A，再做 B，最后做 C”的编号列表，就把它写入 TodoWrite，并按状态引用它。只保留一个信息源。

5. 每经过 3-4 轮工具调用，就写下检查点摘要

写一句话：“在 auth.go:142 找到 bug——保护性子句反转了。接下来修复。”这样能在上下文压缩时提供锚点，也能让之后接手的回合无需重新推导就能继续。

这不是对意图的叙述，而是对已确认事实的记录。

6. 绝不复述文件内容——直接进入分析

如果你刚读过文件，就不要再复述一遍。用户能看到（或已通过 Read 工具输出看到）文件内容。不要说“以下是文件内容：”，直接说“第 42 行有 bug——x 被遮蔽了。”

grep 结果、git log 和 find 输出也遵循同一规则。不要重述，直接采取行动。

7. 使用技能系统本身

技能加载时会将其描述载入上下文，但只有调用时才会载入正文。因此，一份 200 行的技能文档在调用前只需约 30 个 Token。references/ 文件也一样——按需加载。把深入的操作指南放进参考文件，而不是 SKILL.md 正文中。

应立即杜绝的反模式

• 编辑后重新读取。 如果更改失败，Edit 工具会报错。重新读取只是徒增焦虑。
• 用 cat 查看整个配置文件，只为检查一个值。 使用 grep -E '^KEY=' file——也不要让机密进入上下文。
• 在三轮对话中反复读取同一个文件。 如果你总是需要回头查看它，就一次性在合适的范围内读取，并记下相关行号。
• 为可逆操作请求许可。 编辑、读取和测试都可逆。直接执行即可。只有破坏性操作或会影响共享状态的操作才需要确认。
• 在回合结束时写多段总结。 最多两句话。差异本身说明一切。
• 本可以批量读取，却分次读取文件。 独立的读取应在一条消息中并行调用工具，而不是每轮只读一个。
• 保留无用的上下文。 过时的计划、已不再相关的旧工具结果。如果对话显然已经转向，就不要继续提及旧话题。

用户明确表示遇到限制时

如果用户说“上下文快用完了”“快到限制了”或“速度越来越慢”：

1. 写一份简明的检查点总结（当前状态、已做决定、下一步）。内容要足够完整，让人可以从头接手。
2. 将进行中的工作细节移到 TodoWrite 或记忆文件中，不要放在对话文本里。
3. 积极把下一步的研究或探索工作委派给子 Agent，让结果以一段总结的形式呈现，而不是整段过程记录。
4. 建议使用 /compact（Claude Code），或开启新会话，并将检查点作为开场消息。

思维方式

每次工具调用都有成本：调用本身、返回的输出，以及它在剩余会话中占用的上下文。读取 400 行你并不需要的内容，会在之后的 50 轮对话中一直占用上下文。子 Agent 的一段总结，也会在之后的 50 轮对话中一直占用上下文。

优化每个 token 的信号密度。工作成果是差异和决策。其他一切都是开销。