如何推进大型任务：上下文与可验证的阶段

大型任务通常始于一个听起来很合理的请求："做一个地区语言目录：列出条目，支持搜索、按国家筛选，再把页面做得像样些。"一小时后，您面前的页面列表只完成了一半，搜索并未覆盖所有字段，样式已经改了两次，对话也变得太长，您甚至分不清哪些结果已经验证，哪些只是说过的承诺。

一个可能的原因是，任务没有拆分成结果明确的部分。这并不代表代码里没有错误，但知道当前应当有哪些功能后，排查错误会容易得多。下面来看看如何把大型工作拆成可验证的阶段，在当前阶段向智能体提供哪些信息，以及应该记录什么，才能明天回到任务时，无论继续原对话还是另开新对话，都不必从记忆里重新拼凑一切。

目录最终就该是这个样子：带搜索功能的列表，每行显示地区语言代码、语言、国家、货币和域名。记住这个样例，后面的练习中它不只是张图，也能作为样式参考。

大型任务与冗长对话

大型任务可能在代码出错之前就停滞：整个过程失去了章法。上下文不断膨胀，假设和已作出的决定混在一起，原本只想加搜索，却不知不觉又开始重做样式。上下文窗口确实有限，但更要紧的是，您会搞不清现在在做什么、哪些部分已经完成。

TASK_SPEC 用来明确整个任务的目标、边界和验证方式。然后根据这份说明，把工作拆成可验证的阶段，也就是 milestones。每个阶段都有自己的结果和边界，例如添加搜索，同时保留数据和样式。这样 Claude 能专注于当前工作，您也能看清任务进展到了哪里。

如果任务还不够明确，第一个阶段可以先做调查：阅读两三个关键文件，列出可选方案和风险，然后完善任务描述和后续阶段。

每个阶段结束时都要运行检查，并写一份简短总结（summary）：完成了什么、如何验证、下一步是什么。如果项目使用 Git，就把已验证的改动保存为一个小型 commit。总结记录决定，commit 保存代码版本；两者结合，便于核对结果，也方便暂停后继续工作。

什么才算一个阶段

Milestone（里程碑）是任务取得一个可验证的中间成果时所到达的节点。下文把到达这个节点之前的工作称为一个阶段。

一个阶段有三个必不可少的部分：

• 结果 - 具体会有什么功能开始正常工作；
• 边界 - 这次哪些内容不动；
• 验证 - 您要检查什么，才能确认结果。

看表述就能看出区别。"改进搜索功能"没有明确的结束点：可以一直改下去，谁都能随意宣布"完成"。而"搜索能按地区语言代码找到条目，查询为空时显示整个列表"就有明确的节点，打开浏览器，半分钟就能验证。

阶段没有通用的时间或文件数量上限。不过规模仍然重要：如果一个阶段里混进了几项互不相关的改动，导致您无法通过一轮清晰的检查来验证结果，就该把它拆小一些。参考标准是：离当前最近、有用，并且能单独取得、单独验证的成果。

把成果拆成可运行的部分

以一个练习用的地区语言目录为例。每条记录的字段与上面的样例相同：地区语言代码、语言、国家、货币和域名。为简单起见，现成的数组直接放在 app.js 中，并由 index.html 引入。页面不会通过单独的请求加载数据，因此无需服务器，直接在浏览器中打开即可。数据如下：

[
  { "code": "en-US", "language": "English", "country": "United States", "currency": "USD", "tld": ".us" },
  { "code": "de-DE", "language": "German", "country": "Germany", "currency": "EUR", "tld": ".de" },
  { "code": "fr-CA", "language": "French", "country": "Canada", "currency": "CAD", "tld": ".ca" },
  { "code": "ja-JP", "language": "Japanese", "country": "Japan", "currency": "JPY", "tld": ".jp" }
]

完整需求是：列表、搜索和按国家筛选。开头提到的"像样的样式"不单独设为一个阶段：页面在 M1 展示列表时就会有基本样式，只有新的样式，也就是更换主题，才列入"暂缓事项"。我们把需求拆成三个阶段。

首先要有一个能正常运行的列表：有了它，检查条目筛选会更方便。搜索和筛选可以按不同顺序添加；这里先做搜索，再在 M3 验证两者能否协同工作。阶段之间的箭头表示前一个结果已经验证，而绿色的 M3 表示需求已全部完成。

这里是按结果拆分工作。每个阶段都包含阅读代码、修改和验证。"先写完所有 HTML，再写完所有 JS，最后统一检查"这样的计划，会把功能验证推迟到最后。写好的 HTML 结构也可能是有用的中间成果，但它还不能说明搜索是否正常。

请留意，智能体很容易按层来制定计划：先完成全部 HTML 结构，再完成全部逻辑。经常使用 AI 智能体的人也提到过这一点，例如 Matt Pocock 在介绍自己工作流程的工作坊中就谈到过：即使您明确要求按结果拆分，智能体仍可能给出这种计划。因此，检查智能体提出的阶段时，只需关注一点：每个阶段结束后，能否打开某个东西并看到它正常运行。

这里的三个阶段只是示例，并非固定规则。也可能拆成两个，或者六个。

为当前阶段提供上下文

选定阶段后，智能体需要的是与该阶段相关的信息，而不是整个项目的所有内容。练习目录的 M2 请求可以这样写：

为地区语言列表添加搜索功能。
四条记录的列表已经可以正常运行。保留字段和样式，
不要更改原始数组的内容。只添加搜索所需的元素。

阅读 @index.html 和 @app.js。

要求：
- 在列表上方添加搜索框；
- 按地区语言代码和语言名称搜索；
- 查询 de-DE 和 German 都能找到 de-DE 记录；
- 查询 zzz 时列表中不显示任何行；
- 查询为空时显示整个列表。

这次先不添加按国家筛选。
如果还需要其他文件，请指出并阅读。
先说明本阶段的结果和边界，暂时不要修改文件。

如果您认可这些边界，可以在下一条消息中要求执行 M2，并列出要在浏览器中进行的检查。同时，请智能体区分哪些内容是它自己验证过的，哪些还需要您来检查。

示例中的路径只是占位符，您的文件会有所不同。如果工作需要请求中未提及的资料，智能体应先指出并阅读它：根据文件名猜测内容并不可靠，也不应该要求智能体这样做。

样式在这里属于单独的一类信息，而这个阶段正是要保留它。有时情况相反，外观本身就是阶段成果的一部分，例如页面第一次出现时。光用文字很难描述清楚："做得好看些"这个要求无法验证，决定权也就留给了智能体。这种情况下，请附上参考资料：设计稿、截图，或一个列出颜色和类名的小文件。

还要记住，这类表述并不是什么。"这次不添加筛选功能"是一条指示，而非技术屏障。它能说明方向，却不会阻止任何操作，所以结果仍然要由您亲自检查。

何时应该缩小阶段范围

阶段往往会在工作过程中越变越大。您从搜索开始，后来发现最好顺便调整数据结构、更新样式，再加个顶部导航。是不是很熟悉？

逐项确认每个新需求是否为当前选定的结果所必需。新配色主题和导航可以稍后再做，但搜索输入框是必要的。如果记录中缺少搜索所需的信息，先明确边界：可以在当前阶段补充数据，也可以把准备数据单独列为一个可验证阶段。不能在工作过程中悄悄取消不修改数据的限制。

补充说明可以很简短：

这次不改数据、样式和导航，
把这些内容分别记下来，以后再做。
保留按代码和语言搜索：输入框、匹配结果、空查询。

阶段在约定的成果已经取得、验证也已完成后才算结束。如果验证未通过，先解决当前阶段的问题；进入下一阶段只会增加不确定性。

有时阶段就是推进不下去：您指出智能体的问题，它重做了，结果还是不对。失败的尝试不会消失，而是留在对话中，下一次尝试也会以它们为基础。Claude Code 文档给出了一个简单的判断标准：如果同一件事需要纠正两次以上，就另开一个干净的对话，并在请求中写明您目前了解到的全部信息。例如："单独建立搜索数组的做法不合适，因为它会与原始数据脱节；请直接在主数组中搜索。"这样的请求通常比连续第三次修改更有效。如果仍然没有改善，这个阶段可能太大了，应该继续拆分。

保存继续工作的起点

左侧分支会回到同一阶段继续修改，因为结果尚未确认。右侧分支则会记录状态并进入下一阶段。在笔记中既要记下通过的检查，也要记录检查范围之外的内容。

验证完结果后，就把当前状态记录下来。写笔记不是为了汇报，而是为了避免隔天或换个对话时，还得翻遍聊天记录来还原经过。

文件名随意，也可以使用已有的工作笔记。这里就叫它 PROGRESS.md。下面是验证 M1 后的练习示例；您自己的笔记只记录实际做过、实际观察到的内容：

# 地区语言目录

## 已完成
M1：页面显示 app.js 数组中的地区语言列表。

## 已验证
在浏览器中打开 index.html：共 4 条记录，每行的五个字段
都与 app.js 中的原始数组一致。

## 未验证
数据集为空时页面会显示什么。
这项检查不属于 M1 的标准；空数组时的行为尚不明确。

## 决定
数据保存在 app.js 的数组中，不单独加载数据。
添加搜索功能时，保留记录内容和样式。

## 已舍弃
从单独的 JSON 文件加载数据：没有服务器时，浏览器
无法读取该文件，而页面必须能作为文件直接打开。

## 文件
index.html, app.js

## 剩余阶段
M2：支持按地区语言代码或语言名称搜索。
验证：de-DE 和 German 都能找到 de-DE 记录；
zzz 找不到任何记录；查询为空时显示全部四条。

M3：按国家筛选可与搜索同时使用。
验证：Canada + French 筛出 fr-CA；
Canada + German 显示空列表；
清除两个条件后恢复四条记录。

## 下一步
执行 M2。暂时不要添加按国家筛选功能。

关键在于"已验证"这一节。一周后，"一切正常"毫无意义，而"在浏览器中打开，4 条记录，字段都一致"则清楚得多。单独列出未验证内容，正是因为明天您可能就记不起这些区别了。

"已舍弃"这一节很容易被当成多余的，毕竟里面写的是项目中没有的东西。但在新对话里，智能体并不知道之前尝试过什么，可能会再次诚恳地建议走同一条路。写下一句原因，就能省掉一整轮返工。

您可以让智能体来写笔记，但要根据最新文件和验证结果进行核对。它可能会依赖对话历史，而那里计划和实际完成的操作混在一起。如果是在浏览器中观察到的结果，请注明是谁检查的；不要把智能体没有执行过的验证算到它头上。

有两点限制。任务的临时进展不该写进 CLAUDE.md，那里记录的是项目的长期规则，而不是您今天正在做什么。笔记也不会保存代码版本：它只是状态说明，并非文件副本。

带上所需信息继续工作

阶段边界是个合适的节点，可以用来决定接下来在哪个对话中工作。问题很简单：当前对话对下一步有帮助，还是已经开始碍事？

如果对话还有帮助，就继续使用，不必特意做什么。没有"每个阶段结束后都要清空对话"这条规则，也不存在一个百分比阈值，超过后就必须重新开始。

如果不确定历史记录占用了多少上下文，可以运行 /context 查看窗口使用情况。再结合工作进展想一想：哪些冗长的输出和讨论对下一阶段仍有用？这个命令能帮您估算上下文规模，但哪些信息有用仍要由您自己判断。

如果对话里累积了无关内容，而您决定另开一个干净的对话，请先保存笔记。/clear 命令会开始一段新对话：旧历史不会进入新对话的工作上下文，源文件仍保存在磁盘上，项目指令也会继续加载。这并不意味着旧对话被永久删除：您可以用 /resume 回到已保存的对话。不过，如果要在新会话中继续工作，最好明确传递所需的决定。

两条箭头在继续工作前汇合。笔记记录决定和验证结果，文件则展示当前代码。智能体会读取这两类资料并复述当前状态；在交给它 M2 之前，您要核对它的回答。

开启新对话的开场很简单：

阅读 @PROGRESS.md、@index.html 和 @app.js。
请用自己的话说明哪些内容已经完成并验证，哪些还没完成。
暂时不要修改文件。

请仔细阅读回答。如果智能体把您没做过的事情说成已完成，就将它的说法与笔记、文件和验证结果对照。问题可能出在记录不准确、代码过时，也可能是智能体自身出错。开始新的修改之前先解决这些差异：开启一段干净的对话，本身并不能修正错误的任务说明，也不能保证智能体正确理解。

从头到尾完成这个目录

讲解到此结束，接下来请您亲自完成同一个目录：从空文件夹开始，做到 M2 通过验证，并留下继续工作的起点。四个步骤按照本文的顺序展开。每一步都先自己写 prompt，再把我们的版本作为第二种参考：重点是判断智能体需要哪些信息，而不是照抄一句话。

步骤 1：先做计划，不写代码

项目还不存在，您最先想到的可能是请求"做一个目录"。这样文件就会在作出相关决定之前出现。本步骤的目标正好相反：先拿到计划，一个文件也不创建。动手输入之前，先想好四件事：

• 如何避免智能体立即开始写代码；
• 如何提供信息，替代目前还不存在的文件；
• 要说明哪些技术约束，才能避免引入多余的工具；
• 如果暂时没有东西要创建，应该要求智能体输出什么。

参考写法：

我想做一个练习用的地区语言目录：记录列表、搜索和按国家筛选。目前还没有项目。

页面必须能作为文件直接在浏览器中打开，不需要服务器或构建：
只用 index.html、styles.css 和 app.js。每条记录包含这些字段：地区语言代码（en-US）、
语言、国家、货币和域名。

请先制定计划：
- 说明整个任务的目标、边界和验证方式；
- 将工作拆成三个阶段；
- 为每个阶段说明结果，以及我验证时会看到什么；
- 告诉我还需要提供哪些信息；
- 列出你会创建的文件。

暂时不要创建任何文件。

将得到的阶段与上面的 M1-M3 表格对照一下；顺序不同也没关系。如果智能体把工作拆成"先完成所有 HTML，再完成全部 JS"，就要求它重新制定计划，让页面在每个阶段结束后都具备一些功能。如果某个阶段没有说明可观察到的行为，现在就完善表述：在写第一行代码之前，只需多发一条消息。

步骤 2：只做 M1，并一开始就提供样例

范围很明确：页面只显示四条记录，不做搜索，也不做筛选。不过，外观无法留到以后再说，因为页面首次出现时总得有个样子。因此请附上样例：在项目文件夹中保存 mockup.html，只包含静态 HTML，不写 JavaScript，仅列出颜色和类名。

<style>
  body   { background:#0f172a; color:#e2e8f0; font-family:system-ui, sans-serif; padding:24px }
  .search{ width:100%; margin-bottom:12px; padding:10px 14px; border-radius:10px;
           background:#1e293b; color:#e2e8f0; border:1px solid #334155 }
  table  { width:100%; border-collapse:collapse }
  th, td { padding:10px 12px; text-align:left; border-bottom:1px solid #334155 }
  th     { color:#8b98b1; font-size:13px }
  .code  { font-family:ui-monospace, monospace; font-weight:700; color:#818cf8 }
</style>

<input class="search" placeholder="Search by code or language">
<table>
  <tr><th>Code</th><th>Language</th><th>Country</th><th>Currency</th><th>TLD</th></tr>
  <!-- 示例行；实际行由 app.js 渲染 -->
  <tr><td class="code">en-US</td><td>English</td><td>United States</td><td>USD</td><td>.us</td></tr>
</table>

样例中已经画出了搜索框，但 M1 不会把它放到页面上：一个什么也做不了的空输入框，很难验证。它的样式保存在 .search 类中，M2 会用到。

还有一点：必须明确给智能体提供数据。否则它可能自己编造一组数据，表格中的验证条件也就对不上了：四行、de-DE、Canada。现在来写 prompt：想想如何让智能体只处理一个阶段、修改前需要它展示什么，以及您将如何验证结果。

只执行 M1：页面显示 app.js 数组中的地区语言列表。
这次不做搜索和筛选，
也先不要添加样例里的搜索框。

数据就是这四条记录组成的数组，请勿更改内容：
[插入本文中的数组]

外观参考 @mockup.html：使用其中的颜色和类名，
不要自己另编新的。

先展示文件计划，并说明会在哪一步停下。
在我确认计划之前，不要创建文件。
修改后告诉我应该打开什么，以及要与什么内容核对。

完成 M1 后就停下，未经我同意不要继续做 M2。

如果计划越写越大，先别确认；把阶段缩小到一个可验证的结果后再说。计划没有问题，就允许修改，然后打开页面，将四行数据与数组核对。从现在开始，基本样式就定下来了：之后继续保留，全面更换主题仍然是暂缓事项。

步骤 3：M2 与如实记录

M2 的 prompt 已在"为当前阶段提供上下文"一节中说明；请回到那里，并换成您自己的路径。示例中有两个文件，而完成 M1 后您有三个：除了 index.html 和 app.js，还多了 styles.css，也要把它列进去。再补充一句：现在是保留现有外观，而不是重新设计。

M1 已按 @mockup.html 设置好样式，请保持不变，
并使用其中的 .search 类为搜索框设置样式。

智能体正确说明了边界，就允许它开始修改。如果它动了筛选功能或数据结构，先在工作开始前问清楚。搜索的三项验证都通过后，参照上面的样例把状态记录到 PROGRESS.md；这次要记录 M2 完成后的情况，并填入您自己的文件列表。

再检查一下您的笔记是否经得起时间考验。想象一下，如果"已验证"一节只写着"差不多都好了，就差一点"，一周后这句话毫无用处。把它补充到足以继续工作：具体打开了什么、看到了什么、哪些内容没有验证、下一步是什么。可以参考："M2：查询 de-DE 和 German 都能找到 de-DE，zzz 找不到任何记录，空查询返回四条记录"；"未验证数据集为空时的行为"；"下一步：M3，按国家筛选"。

步骤 4：在新的对话中继续

最后一步验证的不是代码，而是笔记。开启一段新对话，让智能体根据 PROGRESS.md 和全部三个最新文件复述当前状态，包括 styles.css，然后将复述内容与您的实际操作对照。如果智能体把您没验证的内容说成已完成，笔记很可能写得太笼统；应当修改笔记，而不是再开一段新对话。不过，也要核对文件：问题可能出在代码，也可能是智能体本身出错。如果信息一致，您就有了通过验证的 M1、通过验证的 M2，以及开始 M3 的起点。

如何进入下一阶段

最后的流程很简短：

1. 选择近期一个可验证的成果；
2. 向智能体提供本阶段所需的资料，并说明边界；
3. 完成当前阶段；把新需求单独记录下来；
4. 执行约定的验证；在本文示例中，就是检查页面在浏览器中的表现；
5. 记录状态：已完成、已验证、未验证、已舍弃的内容和下一步；
6. 决定继续当前对话，还是开启一段干净的新对话。

一个阶段不等于一条消息。可能要发三条，也可能要发十五条，都很正常。阶段数量也不等于对话数量：几个相邻阶段完全可以在同一段对话中完成，而一个较难的阶段有时会占用两段对话。

这样一来，无论处于哪个步骤，您都能说清楚哪些功能已经正常运行，以及是如何验证的。对于大型任务来说，这大概是最重要的。