实战：给你的仓库配一份预算

11.1 现在轮到你的仓库了

shopfront 是编的，你的仓库是真的。这一章把前面所有东西搬过去，产出两样可交付的东西：一份写在仓库里的上下文预算方案，和一张用来打分的自检量规。

整章就是一个练习。分六步，每步都具体到能照做。做完你手上会有一个 .md 文件、一个改过的 CLAUDE.md、一个笔记文件、一个子代理配置，以及一次跑过的真实任务记录。

时间预算：六步做完大约三到四小时，其中第 6 步占一半以上，因为那一步是真的在干活。不要把六步压在一个下午囫囵跑完，第 2 到第 5 步做完隔一天再做第 6 步，效果更好——你需要一次不带练习心态的真实任务。

11.2 第 1 步：选一个真实仓库和一个够长的任务

**选仓库。**必须是你自己在维护、有真实历史包袱的那个。不要选刚起的玩具项目——玩具项目的上下文永远够用，练不出任何东西。判断标准：这个仓库里有你不敢随便改的地方，有至少一个「历史原因」，有别人写的代码。

**选任务。**必须至少 20 轮工具调用。太短的任务任何做法都能跑完，测不出差别。合格的任务长这样：

• 跨至少 5 个文件的重构或迁移
• 给一个已有模块补齐测试
• 升级一个牵动多处的依赖
• 把一个功能从 A 实现方式换成 B

不合格的：修一个 bug、加一个函数、改一段文案。这些是十分钟的活。

**写下来。**在纸上或者随便什么地方写清楚三件事，这是后面五步的输入：

仓库：
任务一句话描述：
预估涉及的目录/文件：
完成判据（3 条，都要能验证）：
1.
2.
3.

完成判据这三条，参照第 10 章的写法。「代码里不再出现 X」「测试 Y 全绿」「文档 Z 与实现一致」这类能跑能查的，才算判据。「代码更清晰了」不算。

11.3 第 2 步：填第 2 章那张上下文盘点表

不要凭感觉估。开一个新会话，什么都不做，先盘点一次静态占用；然后让它做三轮真实工作，再盘点一次。两个数字都要。

按第 2 章那张表的列填。至少要有这几行：系统提示、CLAUDE.md（含所有被引用的子文件）、工具定义（分别列出内置工具和每个 MCP 服务器）、对话历史、工具返回值。

填的时候有三个地方最容易低估，特意去看一眼：

**MCP 服务器。**如果你装了三四个，把每个的工具定义单独算一行。很多人第一次盘点最大的震惊在这里——一个用得不多的 MCP，工具定义可能比整个 CLAUDE.md 还大。

**CLAUDE.md 的引用链。**如果它 @ 引用了别的文件，那些文件也算进来。你以为的 800 字可能实际是 4000 字。

**单次工具返回值的峰值。**不是平均值，是最大的那次。一次全量测试输出、一次没加限制的 grep，可能一口气吃掉一成窗口。

填完，回答一个问题并写下来：**最大的三块分别是什么，占比多少？**这个答案决定第 3 步。

11.4 第 3 步：用第 3 章矩阵定位症状，选出首个动作

盘点告诉你 token 在哪。矩阵告诉你先动哪只手。

**先写症状，一句可观察的话。**参照第 3 章的要求：不能写「它有时候会跑偏」，要写「它第三次修改 src/api/client.ts 的 postOrder，每次都改回上一版」。如果你的仓库里有真实发生过的卡壳，用真的；没有的话，从第 2 步的盘点数字里推——占用最大的那块通常就是症状来源。

在矩阵里找到这一行，抄下「先做哪个动作」和「做完怎么验证」两列。

**只选一个动作。**这一步最容易犯的错是四个动作一起上。别。你现在需要知道的是「这一个动作有没有用」，四个一起上你什么都学不到。

**把验证方法先写下来，在做之前写。**做完再想验证方法，人会不自觉地把标准调到刚好能过。

写成这样，三行：

症状：
首个动作：
验证方法（做之前写好）：

11.5 第 4 步：按第 4 章三问改写 CLAUDE.md 里最长的三条

打开 CLAUDE.md，按字数排序，挑出最长的三条规则。长通常意味着两件事之一：要么它在讲一个本该由代码或文档承载的细节，要么它在防一个只发生过一次的意外。

对每一条问第 4 章那三个问题：

1. 它足够具体到能指导行为吗？「写好测试」不行——什么叫好，它猜不出来。
2. **它足够灵活到给模型强启发式吗？**如果它是一段 if-else 式的硬编码流程，一旦遇到没列举的情况就失效。
3. **它值这个 token 吗？**它每一轮都在场。用得上的场景有多大比例？

改写规则很简单：具体的判据留下，冗长的过程说明删掉，例外情况挪到文档里。

留一份改写前后的对照，格式随意，但两边的字数要标出来。你会想在第 6 步之后回头看它。

三条改完，再做一件顺手的事：把 CLAUDE.md 里所有「只在某类任务里才用得上」的内容标记出来。它们是渐进式披露的候选——按第 7 章的思路，这些内容更适合放进技能或独立文档，命中时才加载，而不是常驻。这一步不用现在就动手改造，标出来就行。

11.6 第 5 步：建笔记文件，写一个只读子代理

**笔记文件。**按第 6 章模板建，路径自己定，但要写进 CLAUDE.md 让 agent 知道它存在，比如「任务进行中请先读 docs/task-notes.md，并在每完成一步后追加一行」。

开局的笔记文件应该只有四个小节，且都很短：完成判据（第 1 步写好的三条直接抄进来）、已确认事实（空）、待办清单（空）、已做决定（空）。

**子代理。**照第 9 章那份 v1-usage-scanner 的结构，为你自己的任务写一个只读调查员。存进 .claude/agents/。

四项必填：name、description、tools（只给 Read, Grep, Glob 之类的只读工具）、disallowedTools（至少禁掉 Write, Edit）。

正文里花最多篇幅写回传格式。这是第 9 章反复强调的那一步：不规定格式，它就把原文倒回来，你隔离了个寂寞。至少写清三件事：产物的确切结构（几行、什么表、哪些列）、三条「不要输出什么」（不要贴源码、不要讲检索过程、不要给建议）、一条结果过多时的降级规则。

写完做一次冒烟测试：派它跑一次，看回传的东西是不是真的只有格式里那些。如果它还在贴代码片段，回去把约束写得更硬。

11.7 第 6 步：跑一次，在两个边界压实

前五步是准备，这一步是真跑。按第 10 章那六个阶段走一遍你自己那个任务。

硬性要求四条：

**一，全程不 /clear。**撑不住就按第 10 章 10.10 那三个信号判断该不该重开，并记录命中了哪个。

**二，至少在两个边界主动压实。**边界的定义是「一个切片刚做完、下一个还没开始」，不是「占用到多少了」。

三，每次压实前固化四类事实：已确认的接口或行为事实、已做的决定和理由、失败过的路径、当前进度与下一步。

四，每次压实后做三问：让它复述完成判据、说出下一个要处理的文件、随机抽一条已确认事实。三问都对才继续。

记录一张表，四列：时刻 / 当前占用 / 刚做了哪个动作 / 备注。至少记六行：开局基线、两次压实的前后各一次、收口一次。

跑完之后，回到第 3 步你写下的那个验证方法，执行它。这是整个练习唯一的判分点——不是「感觉顺畅多了」，是那个你在动手之前就写好的、可重复的验证。

11.8 上下文预算方案模板

跑完之后，把你学到的东西固化成一份方案，放进仓库。下面这份直接复制去改，路径建议 docs/context-budget.md。

方括号里是要你填的，括号里的数字是起步值，跑几次之后按实际调。

# 上下文预算方案 — [仓库名]

最后更新：[日期]　适用范围：[哪类任务]

## 一、常驻预算（每一轮都在场的部分）

| 项目 | 上限 | 当前实测 | 超了怎么办 |
|---|---|---|---|
| 系统提示（工具自带，不可控） | — | [填] | 只能观测，不能改 |
| 项目指令 `CLAUDE.md`（含引用链） | [1500] token | [填] | 按第 4 章三问砍最长的三条；只在某类任务用得上的内容挪进技能或独立文档 |
| 内置工具定义 | [不动] | [填] | — |
| MCP 工具定义（逐个列出） | 合计 [2000] token | [填] | 本次任务用不上的 MCP 直接关掉；同一职责的多个工具只留一个 |
| 子代理 description 合计 | [3000] token（官方建议上限 15000） | [填] | 删掉三个月没派过的；合并职责重叠的 |
| **常驻小计** | **不超过窗口的 [15%]** | [填] | 超了就先砍 MCP，再砍 CLAUDE.md |

## 二、每轮浮动预算

| 项目 | 上限 | 违反时的动作 |
|---|---|---|
| 单次工具返回值 | [2000] token | 加过滤：测试输出只留失败项，grep 加 `-l` 或限制行数，JSON 用 jq 取字段 |
| 单轮检索文件数 | [3] 个 | 超过就说明任务切片太大，拆开 |
| 单个文件读入 | 超过 [500] 行只读相关区间 | 用行号范围或符号检索，不整文件读 |
| 单轮总增量 | [5%] 窗口 | 停下来看这一轮到底在干什么 |

## 三、外部状态

- 笔记文件路径：`[docs/task-notes.md]`
- 更新规则：每完成一个切片追加一行，**只追加不改写**（改写会打断缓存前缀）
- 必须写进去的四类：已确认事实 / 已做决定与理由 / 失败过的路径 / 进度与下一步
- 谁来写：[agent 自动追加，你在检查点核对]
- 会话开始时：先读它，再干活

## 四、隔离规则

必须走子代理的任务：
- [ ] 全仓调查类（找出所有调用 X 的地方、盘点覆盖率）
- [ ] 会产生 [2000] token 以上原始输出的（全量测试、大 JSON、长日志）
- [ ] 需要硬性只读的操作
- [ ] [你自己的第四条]

不走子代理：连续编辑同一批文件、依赖对话共识的落地、十分钟以内的活、彼此强耦合的子任务。

已有子代理清单：
| 名称 | 用途 | 上次使用 |
|---|---|---|
| [填] | [填] | [填] |

## 五、压实规则

- 压的边界：[一个切片完成、下一个未开始]，不是「占用到了 X%」
- 触发阈值：占用达到 [50%] 且正好在边界上
- 压前必须固化的四类事实：见「三、外部状态」
- 压后三问：复述完成判据 / 说出下一个文件 / 随机抽一条已确认事实
- 三问不过：重读笔记文件再问；仍不过则补笔记，必要时重开

## 六、稳定前缀纪律

- 会话中途不改系统提示和 `CLAUDE.md`（要改等下次开局）
- 提示里不放时间戳、随机 ID、每轮变化的进度数字
- 上下文只追加不改写

## 七、重开信号（命中任意一条就重开，别硬撑）

1. 压实后三问答不对，读了笔记文件还是答不对
2. 出现上下文投毒，且已在同一会话里纠正过一次
3. 同一个坑第三次

这份方案有个用法上的提醒：它是给你自己看的，不是给 agent 看的。别把它整个塞进 CLAUDE.md——那正好是它自己反对的事。CLAUDE.md 里只需要一两行：笔记文件在哪、开工前先读它。

11.9 自检量规

跑完一次真实任务之后，用这张表给自己打分。六个维度，三档。

图 11.1：六行是维度，三列是不合格／及格／良好。看的时候不要横着看平均分，要竖着找那一行你落在最左列的维度——那是你下一次任务里唯一要改的东西。右上角标出的四个动作，说明每个维度分别由写／选／压／隔中的哪一个支撑。

给自己打完分，挑最低的那一个维度，只改它。六个维度一起改，一个都改不动。

一个提醒：这张表的「良好」档不是终点，是可持续的日常状态。如果你发现要维持良好得花很大力气，那多半是做过头了——下一节就是讲这个。

11.10 反面自检：五个说明你做过头了的信号

上下文工程是有边际的。过了那个点，它从省时间变成花时间。五个信号，出现任意一个就该往回收：

**一，笔记文件比它记录的代码还长。**你在 docs/task-notes.md 里写了三百行，而这次迁移一共改了两百行代码。笔记的作用是让状态能被便宜地取回来，不是给项目写第二份历史。笔记应该是索引和结论，不是过程实录。判断标准：如果一条笔记你三天后不会再读，它就不该被写下来。

**二，任何小事都开子代理。**读一个已知路径的文件也派个子代理去读。别忘了那个 15 倍——多 agent 架构的 token 用量约为单 agent 的 15 倍。这不是免费的整洁，这是一笔交易。交易的前提是中间产物够大，小事没有这个前提，纯亏。

**三，CLAUDE.md 变成了第二份文档站。**它开始有目录、有章节、有「术语表」。这个文件每一轮都在场，它不是文档，它是每次呼吸都要吸进去的空气。文档站该有的东西放 docs/，让 agent 需要时去读——那是选，不是常驻。

**四，你花在管理上下文上的时间超过了花在任务上的时间。**每两轮压实一次，每一步都在纠结要不要写进笔记，光是准备就用了一小时。上下文工程的收益是「同样的任务跑得更远更稳」，如果它反过来吃掉了任务时间，说明你在给一个不需要这么多结构的任务上重型装备。短任务就该直接干，这套方法是给长任务的。

**五，你在优化那些你没测过的东西。**你把 CLAUDE.md 从 1200 字压到 900 字，感觉很爽，但你从来没测过这 300 字有没有影响行为，也没量过它在总占用里占多少。这是最隐蔽的一种过度——它看起来完全像在做正事。每一次优化都该有一个先写好的验证方法，这条从第 3 章开始就在说，到这里应该已经变成习惯。

这五条的共同点是：手段变成了目的。上下文工程的目的只有一个——让任务在有限的注意力预算下跑完。任何不指向这个目的的整洁，都是成本。

11.11 接下来去哪

这本书讲的是判断：什么该进窗口、什么时候进、进来多大、进哪个窗口。它刻意没有深入具体机制的实现细节，因为那些细节随版本变，而判断不变。

如果你要补实现，两条路径：

站内《给 AI 写规矩》系列做子代理和技能的完整动手实现。第 9 章那份配置只是个起点，那个系列会带你把它写完、调通、跑起来，包括权限、技能预载这些本书一笔带过的部分。

《MCP、Skills、Subagent 到底该用哪个》做机制选型。第 5 章讲了工具集臃肿的代价，但同一件事到底该做成 MCP、技能还是子代理，那是一篇专门的选型文章的活。第 2 章盘点表里 MCP 那一行如果偏大，先去看它。

另外，《Claude Code 上手指南》第 5 章讲上下文管理、第 8 章讲技能/子代理/钩子的四选一，可以作为工具侧的补充；主站短文《什么是上下文窗口》适合转给团队里还不熟悉这个概念的同事。

最后说一句实在的。

这本书里没有一个技巧是复杂的：把状态写进文件、只读需要的文件、在合适的时候摘要、把脏活隔开。每一条你听完都会觉得理所当然。

难的不是理解，是在第 47 轮、你已经有点烦、只想赶紧跑完的时候，仍然停下来在切片边界压一次实，仍然把那条刚确认的事实追加进笔记文件。那三十秒的动作，决定了这个任务是在第 60 轮结束，还是在第 90 轮崩掉重来。

你现在有一份预算方案和一张量规了。挑量规里最低的那一维，下周的任务里只改它一个。