看不见的缰绳 — Claude Code 如何用 <system-reminder> 驾驭大模型

一、概述：被忽略的一块

一个 AI Agent 的落脚点只有一个——Claude API 的 messages 数组。API 只认三种 role：system、user、assistant。承载 Agent 的那层壳子（Harness），把花里胡哨的所有"状态、事件、上下文、提醒、约束"全都得塞进这三种 role 里，没有第四种。

Claude Code 通常被这么描述："Claude API + 工具调用 + MCP + skill + 上下文压缩"。这几项确实都在。而且从工程密度上看，Claude Code 上还有其它很多层设计：hook 机制、plan 模式、auto 模式、team 协同、上下文压缩策略、MCP 接入……每一层都值得单独讲。但如果只看表面那几项，你会漏掉它最精华、最能决定模型"好不好带"的一层东西：<system-reminder> 标签。

所谓 system-reminder，其实就是 Claude Code 给自己立下的一条约定：

• 把一段文本包进一对 <system-reminder>...</system-reminder> 标签里；
• 以 user 角色、带 meta 标记，插进 messages 数组；
• 在系统提示里告诉模型："见到这种标签，就知道是系统自动加的旁路信息，它跟前后那条 user 消息、tool result 没有因果关系。"

就这么一个约定，Claude Code 拿到了一条旁路通道：在不改变 API 角色语义、不自创新 role 的前提下，持续往模型脑子里灌注引导和约束。

它决定了模型在第 50 轮时还记不记得自己在 plan mode、知不知道今天是哪一天、要不要继续维护 todo 列表、是否该避开已经失效的 MCP 工具。大多数 system-reminder 用户永远看不到，但模型每一轮都在读。这篇文章就专门梳理这一层：定义、所有生产者（含类型、含义、注入时机和位置）、流水线后处理、消费与过滤；末尾两则附录顺带留一扇缝，看看大厂怎么做 prompt 工程的 A/B 实验。

二、定义与语法

2.1 标签本身

形如：

<system-reminder>
...任意文本...
</system-reminder>

包装函数固定在前后各加一个 \n，所以换行是标签的一部分、不是内容的一部分。批量包装时，字符串型 content 整个包一层；数组型 content 只给 type === 'text' 的 text 块包，image / tool_result 等其它块保持原样。

2.2 "鉴别前缀"

整个 Claude Code 系统共用一个判定条件：文本是否以 <system-reminder> 开头。后续的"合并回 tool_result"、"UI 剥离"、"transcript 搜索"、"telemetry 采样"都靠它分辨"这段是不是 reminder"。

为此 Claude Code 在所有附件类消息的尾段跑一次幂等包装——如果某路径忘了加 reminder，就在这步补上。保证没有"漏网之鱼"，否则会影响后续合并逻辑的正确性。

2.3 标签在消息里的形态

永远以 user-role 文本块的身份出现。形态有两种：

形态 A：整条 user 消息就是一条 reminder（最常见）

或数组写法：

这种消息在 Claude Code 内部带有 isMeta: true 标记，用于本地 UI 过滤，不影响发出去的 API 请求体。

形态 B：被合并到某个 tool_result 的 content 里（下文 §五详讲）

2.4 识别与剥离

识别用一个简单正则，用于 telemetry 等场景：

^<system-reminder>\n?([\s\S]*?)\n?<\/system-reminder>$

UI 侧的剥离分两种粒度：

• "只剥开头"：渲染聊天气泡、复制到剪贴板时用。因为 reminder 往往拼在用户消息最前面，剥掉开头就能露出用户真正打的字。
• "满文剥离"：transcript 搜索时用。因为用 claude -c（continue 子命令）恢复旧会话时，memory reminder 可能插在消息中段，只剥开头的版本不够用。

三、模型侧的"宪法"——系统提示中的声明

Claude Code 的系统提示里有两段声明，明确告诉模型"见到 <system-reminder> 怎么理解"。两段都是系统提示组成部分，一条给一般 agent，一条给自主工作型 agent。

第一段：

第二段（出现在另一份系统提示 items 清单里）：

两段声明里，有三个关键点：

1. 既可能出现在 user 消息里，也可能出现在 tool result 里 —— 对应 §二.3 的 A / B 两种形态。
2. "bear no direct relation to..." —— 明确告诉模型"这段话不是对前面那条 user 消息或 tool result 的回复，不要当因果关系来读"。
3. "automatically added by the system" —— 模型不应当面 echo、不应模仿、不应把这句话复述给用户。

此外，在具体模板里还有大量加强措辞："DO NOT mention this to the user explicitly because they are already aware"、"Make sure that you NEVER mention this reminder to the user"、"Don't tell the user this, since they are already aware"——反复提醒模型："这段话不要念出来。"

四、生产者分类：谁在往 messages 里塞 <system-reminder>

下文按语义分类，每一类先给一个表格，列出类型 / 含义 / 注入三项。"注入"这一列会分别讲清楚时机（什么时候触发）与位置（进入 messages 数组的哪个位置），因为这两者对理解 Harness 的行为同样重要。

"类型"列用的是代码中对应的 attachment.type 字符串；没有对应 type 字段、而是由函数/常量直接拼的，用函数名或常量名。模板里出现的 ${...} 都是代码里的运行时变量（比如 ${filename}、${planFilePath}），实际渲染时会被替换成具体值。

4.1 用户上下文预置

模板：

说明：

• context 字典里的字段并非硬编码固定，调用方（主对话 / forked agent / companion 等）可以各自决定塞哪些键。主对话里实际塞的是 claudeMd、currentDate。
• claudeMd 字段承担的是项目根 CLAUDE.md 的注入；但在填入这个字段之前会先跑一次 filterInjectedMemoryFiles，把本会话里已经作为 attachment 注入过的 memory 文件（比如下面 §4.4 的 nested_memory）从这里剔除，避免双重注入。换句话说：项目根 CLAUDE.md 走 prependUserContext.claudeMd，子目录 CLAUDE.md 走 nested_memory attachment——两条路径互斥分工。

4.2 @提及的文件与目录

模板：

edited_text_file：

file 子类型为 text 且被截断时，额外追加的第二条：

compact_file_reference：

Note: ${filename} was read before the last conversation was summarized, but the contents are too large to include. Use Read tool if you need to access it.

pdf_reference：

示例：@目录 / @file 的消息结构

这两种分支特别之处在于，它们不是单纯塞一段文字，而是构造两条 user-role 文本消息，分别对应"工具调用的描述"和"工具结果的描述"，整体再包进 reminder。注意这里的"工具调用/工具结果" 不是 API schema 定义的 tool_use / tool_result 结构化块——它们就是普通的 user-role 文本，字面写着：

Called the ${toolName} tool with the following input: ${input 的 JSON}

Result of calling the ${tool.name} tool:
${contentStr}

以 @src/ 为例，最终进入 messages 的大致是这样两条相邻消息（实际发出前还会经过第五节的合并流水线）：

效果：模型"以为"这次是用户要它看看 src/ 里有什么，并看到 ls 的文本结果。但整个过程并没有真的走一趟 Bash 工具——它完全是在文本层面伪造出来的一次调用叙事。

4.3 IDE 联动

模板：

selected_lines_in_ide：

The user selected the lines ${lineStart} to ${lineEnd} from ${filename}:
${content}

This may or may not be related to the current task.

opened_file_in_ide：

The user opened the file ${filename} in the IDE. This may or may not be related to the current task.

4.4 Memory（CLAUDE.md / 项目 memory / 个人 memory）

模板：

nested_memory：

Contents of ${attachment.content.path}:

${attachment.content.content}

relevant_memories 的每一条（header 在 attachment 创建时就算好并缓存住，不会每轮用当前时间重算——这是为了 prompt cache 稳定）：

${header}

${content}

memoryFreshnessNote（来自 memoryFreshnessText）：

4.5 Skills

模板：

skill_listing：

The following skills are available for use with the Skill tool:

${attachment.content}

invoked_skills：

The following skills were invoked in this session. Continue to follow these guidelines:

${skillsContent}

其中 skillsContent 是每个 skill 按下列格式拼接、以 \n\n---\n\n 连接：

### Skill: ${skill.name}
Path: ${skill.path}

${skill.content}

skill_discovery：

说明：

• Skill 的初次加载不是走 reminder 的——走的是 Skill 工具调用，调用后由 tool_result 把 skill 的完整内容返回给模型。之后该 skill 的内容就在 tool_result 里躺着，不需要任何重复注入。
• invoked_skills 这条 reminder 的真正作用是跨压缩事件的保活。正常不压缩的情况下，skill 的内容活在 tool_result 里；但一旦触发上下文压缩，summarizer 可能会把 tool_result 的细节汇总掉，使得后续的 turn 丢失 skill 指南。为此压缩流程会在生成压缩产物的同时，额外塞进一条 invoked_skills 把这些 skill 的完整 markdown 带过压缩边界；用 claude -c 恢复旧会话时，也由这条 attachment 把进程内的 skill 注册表恢复。
• skill_listing 的节制也类似——整条清单大约 4K tokens，所以代码里反复强调"只注入一次、不要重复铺"，宁可相信模型还记得 Skill 工具的 schema 和已用 skill 的 tool_result。
• skill_discovery 分支只给 name + description；完整 skill 内容要通过 Skill 工具自行拉取。

4.6 Todo / Task 软提醒

模板：

todo_reminder：

task_reminder：

说明：两段模板末尾的 "NEVER mention this reminder to the user" 是 reminder 类提示的固定收尾——对模型的压制是怕它把"系统让我用 TodoWrite"当真理念给用户听，变成一次无意义的无工具回合。

4.7 模式切换（Plan / Auto / Output Style / Brief）

这一类 reminder 在语义上最"重"——它们是运行时的模式开关，一注入就相当于给模型换上了一整套新的行为准则。

模板：

plan_mode（full，不含 interview phase 的版本）：

补充说明：整个 plan workflow 是 5 个 Phase，其中 Phase 4（写最终 plan 那一步）在代码里另做了一组 A/B 实验，共 4 个变体（CONTROL / TRIM / CUT / CAP），由服务端下发的 feature flag 分桶决定。上面展开的就是 CONTROL 对照组原文；完整的实验细节、动机、监测指标见附录 A。

plan_mode（sparse）：

其中 workflowDescription 在 interview phase 启用时为 Follow iterative workflow: explore codebase, interview user, write to plan incrementally.，否则为 Follow 5-phase workflow.。

plan_mode_reentry：

plan_mode_exit（planReference 在存在 plan 文件时为 The plan file is located at ${planFilePath} if you need to reference it.，否则为空）：

## Exited Plan Mode

You have exited plan mode. You can now make edits, run tools, and take actions.${planReference}

auto_mode（full）：

auto_mode（sparse）：

Auto mode still active (see full instructions earlier in conversation). Execute autonomously, minimize interruptions, prefer action over planning.

auto_mode_exit：

output_style：

${outputStyle.name} output style is active. Remember to follow the specific guidelines for this style.

brief 模式开启：

Brief mode is now enabled. Use the SendUserMessage tool for all user-facing output — plain text outside it is hidden from the user's view.

brief 模式关闭：

Brief mode is now disabled. The SendUserMessage tool is no longer available — reply with plain text.

4.8 子 Agent / 后台任务

模板：

agent_mention：

The user has expressed a desire to invoke the agent "${attachment.agentType}". Please invoke the agent appropriately, passing in the required context to it. 

task_status（killed）：

Task "${attachment.description}" (${attachment.taskId}) was stopped by the user.

task_status（running，带 outputFilePath）：

task_status（running，不带 outputFilePath）：

task_status（completed / failed，带 outputFilePath）：

（不带 outputFilePath 时，末句换成 You can check its output using the TaskOutput tool.。deltaSummary 为空时不附 Delta: 段。）

team_context（模板里内嵌一个 JSON 代码块，下面首行反引号做了转义以免破坏外层渲染）：

SHUTDOWN_TEAM_PROMPT（reminder 段 + 同一条 user 消息里 reminder 外的命令句，两段一起发）：

4.9 Hook 事件（用户自定义的 shell 钩子）

模板：

hook_blocking_error：

${attachment.hookName} hook blocking error from command: "${attachment.blockingError.command}": ${attachment.blockingError.blockingError}

hook_success：

${attachment.hookName} hook success: ${attachment.content}

hook_additional_context：

${attachment.hookName} hook additional context: ${attachment.content.join('\n')}

hook_stopped_continuation：

${attachment.hookName} hook stopped continuation: ${attachment.message}

异步 Stop Hook 阻塞：

Stop hook blocking error from command "${hookName}": ${stderr || stdout}

4.10 MCP / 动态工具与 Agent 注册

这几类 reminder 服务于一件事：运行时的动态工具/ agent 生态变化要让模型立刻得知。

模板：

deferred_tools_delta（增/删可以同时出现，多段之间用 \n\n 连接）：

The following deferred tools are now available via ToolSearch:
${addedLines.join('\n')}

agent_listing_delta（首次 vs 增量的 header 不同）：

Available agent types for the Agent tool:
${addedLines.join('\n')}

New agent types are now available for the Agent tool:
${addedLines.join('\n')}

The following agent types are no longer available:
${removedTypes.map(t => `- ${t}`).join('\n')}

Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses.

mcp_instructions_delta：

# MCP Server Instructions

The following MCP servers have provided instructions for how to use their tools and resources:

${addedBlocks.join('\n\n')}

The following MCP servers have disconnected. Their instructions above no longer apply:
${removedNames.join('\n')}

mcp_resource（有 text 内容时，item.text 前后加两段提示文本）：

Full contents of resource:

${item.text}

Do NOT read this resource again unless you think it may have changed, since you already have the full contents.

mcp_resource（空/二进制/无可显示内容时，从如下三种里挑一种）：

<mcp-resource server="${server}" uri="${uri}">(No content)</mcp-resource>

<mcp-resource server="${server}" uri="${uri}">(No displayable content)</mcp-resource>

[Binary content: ${mimeType}]

说明：deferred_tools_delta 的精妙之处在于和 ToolSearchTool 的配合——它只广播工具的名字，让模型知道"有这些工具"；真正的工具 schema 要通过 ToolSearch 工具按需查询。这是按需加载工具 schema 的一种经典做法，避免新增 MCP 工具就把 system prompt 撑爆。

4.11 会话生命周期与状态切换

模板：

compaction_reminder：

date_change：

The date has changed. Today's date is now ${attachment.newDate}. DO NOT mention this to the user explicitly because they are already aware.

ultrathink_effort：

The user has requested reasoning effort level: ${attachment.level}. Apply this to the current turn.

companion_intro（来自 companionIntroText(name, species)）：

queued_command 的 4 种前缀（由 wrapCommandText(raw, origin) 按 origin.kind 分支，外层再统一包 reminder）：

来源 human / undefined（普通用户打字）：

The user sent a new message while you were working:
${raw}

IMPORTANT: After completing your current task, you MUST address the user's message above. Do not ignore it.

来源 task-notification：

A background agent completed a task:
${raw}

来源 coordinator：

The coordinator sent a message while you were working:
${raw}

Address this before completing your current task.

来源 channel：

verify_plan_reminder（toolName 在 CLAUDE_CODE_VERIFY_PLAN === 'true' 时为 VerifyPlanExecution，否则为空字符串）：

plan_file_reference：

critical_system_reminder 的内容由 agent definition 自行定义，内置 verificationAgent 里的原文是：

4.12 Token / 预算统计

模板：

token_usage：

Token usage: ${attachment.used}/${attachment.total}; ${attachment.remaining} remaining

budget_usd：

USD budget: $${attachment.used}/$${attachment.total}; $${attachment.remaining} remaining

output_token_usage（budget !== null 时）：

Output tokens — turn: ${formatNumber(attachment.turn)} / ${formatNumber(attachment.budget)} · session: ${formatNumber(attachment.session)}

output_token_usage（budget === null 时）：

Output tokens — turn: ${formatNumber(attachment.turn)} · session: ${formatNumber(attachment.session)}

4.13 Diagnostics（IDE / LSP 诊断）

模板（reminder 内部再嵌一层 <new-diagnostics>，便于模型分辨）：

<new-diagnostics>The following new diagnostic issues were detected:

${diagnosticSummary}</new-diagnostics>

4.14 Side Question（不经 attachment，独立路径）

模板（reminder 闭合后紧跟一个换行 + 用户真实问题文本 ${question}）：

说明：本分支是全系统里 reminder 强度最高的地方之一——连"不要说 Let me try..."这种措辞层面的限制都写进了约束。原因是 side question 的 forked agent 没有任何工具可用，如果它说"我去查一下"就彻底卡死。

4.15 内嵌在 tool_result 里的 reminder

这些不是独立的 user 消息，而是在某个工具结果字符串里手工拼出来的 reminder——模型看到的是"工具结果末尾附带的注解"。

模板：

FileReadTool 空文件：

<system-reminder>Warning: the file exists but the contents are empty.</system-reminder>

FileReadTool 偏移越界：

CYBER_RISK_MITIGATION_REMINDER（前后有 \n\n 和 \n，完整原文如下）：

4.16 返回空的分支（声明了类型但在 API 层不产生 reminder）

为了穷尽列一下——这些 attachment.type 在代码里明确返回空数组，只在 UI 层有意义：

• already_read_file、command_permissions、edited_image_file
• hook_cancelled、hook_error_during_execution、hook_non_blocking_error、hook_system_message、hook_permission_decision
• structured_output
• dynamic_skill（仅 UI 用）
• 已移除的遗留类型：autocheckpointing、background_task_status、todo、task_progress、ultramemory 等

五、消息流水线后处理：Smoosh —— 把 reminder 折回 tool_result

到 §四为止，所有生产者产出的都是独立的 user 消息。但在真正发到 API 之前，Claude Code 会做一次关键的合并：把 <system-reminder>-前缀的文本块折进紧邻它的最后一个 tool_result 里。

5.1 为什么要折？

代码里对这件事的解释（翻译自注释原文）：

如果 toolresult 块后面直接接着一个 text 块（哪怕只是一条 reminder），在底层 prompt 序列化里会被渲染成 `</functionresults>\n\nHuman: 的形态。在对话中段反复出现这种 pattern，会让模型"学到"一个坏习惯：工具调用完之后自己吐一个空的 Human:` 前缀再结束回合——浪费 3 个 token 的无效回合。内部 A/B 实验显示：不合并时这种行为发生率约 92%，合并后降为 0%。

简单说：不合并，就会污染模型的输出习惯。

5.2 合并规则

• 紧挨着的 user 消息先被合并成同一条；
• 其中若同时包含 tool_result 块和 <system-reminder> 前缀的 text 块，就把这些 reminder text 折进最后一个 tool_result 的 content 字段里；
• tool_result.content 本来是字符串、待合并块又全是 text → 拼接成字符串，用 \n\n 连接；
• tool_result.content 含某种实验性的 tool_reference 块 → 不合并，跳过；
• 错误态（is_error: true）的 tool_result 受 API 约束只能含 text——先过滤掉非 text 块再拼；
• 其它情况规整成数组形态、相邻 text 块再合并。

5.3 合并前后对比

合并前（两条 user 消息已经被相邻合并成一条，但 reminder 仍是独立 text 块）：

合并后（reminder 折进 tool_result.content 字符串）：

5.4 相关的两个护栏

• tool_result 前置：user 消息里的 tool_result 块必须出现在最前面，否则 API 会报 "tool result must follow tool use"。合并过程中会做一次前置整理。
• 错误结果内容消毒：老会话里若把 image 等非 text 块塞进了 is_error: true 的 tool_result，恢复时会 API 400 崩溃。读端有一次无条件的消毒，过滤成纯 text。

5.5 为什么需要"鉴别前缀"幂等包装

合并逻辑靠"文本是否以 <system-reminder> 开头"判定该不该折进 tool_result。所以每个 attachment 分支都必须把自己的 text 内容包上 reminder 标签，否则就会漏网，变成那个会教坏模型的 sibling。在流水线尾段跑的幂等包装，就是兜底补齐的最后一步。

六、消费者：谁在读这些 reminder

6.1 模型（唯一"认真"的读者）

• 系统提示里已经告诉它"这是旁白"，别 echo、别把它当作用户原话。
• 绝大多数具体模板里，还额外写了 "DO NOT mention this to the user explicitly"、"NEVER mention this reminder to the user"、"Don't tell the user this" 反复强化。
• 模型读得不读得好，就是 Agent 工程的上限。

6.2 UI 渲染聊天气泡

Claude Code 的交互界面，每一条用户消息气泡、每一条 assistant 消息气泡都由前端组件根据 messages 数据源渲染出来。问题是：对"模型视角"的 messages 而言，一条用户消息的完整文本往往是形如：

直接把这种文本渲染到聊天气泡里，用户会看到一堆不知所云的英文旁白。所以 UI 组件在渲染前会把消息文本喂给 stripSystemReminders，把开头那些连续的 <system-reminder>...</system-reminder> 块依次剥掉，只保留尾部用户真实输入。仅剥开头即可——因为生产侧的约定就是"reminder 永远拼在用户消息最前面"。

6.3 复制到剪贴板

Claude Code 支持把某条消息复制到剪贴板（比如方便贴到别处分享）。复制走的是同一个剥离函数，规则和 UI 渲染一致：只剥消息开头的 reminder 块，把用户真正打的字复制出去。不是调试场景的话，用户不需要看到 reminder。

6.4 Transcript 搜索

Claude Code 把会话历史保留成 transcript（对话脚本），支持用户事后检索"我之前说过什么"、"Claude 之前说过什么"。搜索命中的是人类可读内容，因此在索引/匹配之前，同样要把 reminder 从文本里清掉。但 transcript 搜索用的版本比 UI 渲染更狠——它不是"只剥开头"而是"循环剥全文"。

原因是：当用户用 claude -c 恢复旧会话时，某些 reminder（比如 memory 更新）会被插在消息中段而不是开头；只剥开头会留下残骸。所以 transcript 搜索用的全文剥离版本在整段文本上迭代，找到一个 <system-reminder>...</system-reminder> 就切掉一个，直到没有为止。

6.5 Telemetry（遥测）

Telemetry 指 Claude Code 收集的使用行为与性能指标——比如"每一轮消息里 reminder 占了多少字节、哪类 reminder 最常注入、prompt 缓存命中率、各种 reminder 对输出 token 的影响"等等。这些指标通过匿名化的会话追踪上报给研发团队，用来支撑 A/B 实验和长期统计（文中多次出现的"A/B 实验代号"就是从这类遥测拉出来的证据）。

在这个场景下，Telemetry 需要把 reminder 的内容单独抽出来做分类统计——不抽出来就只能统计整条消息，无法区分"这轮有多少字节是用户原话、多少字节是系统注入"。因此 Telemetry 专用的辅助函数用一个简单正则：

^<system-reminder>\n?([\s\S]*?)\n?<\/system-reminder>$

把整段消息文本与之匹配：若整段恰好是一条 reminder，就提取内部文本、归类为"系统注入"；否则当作普通用户/模型内容计入另一桶。

七、设计哲学：引导与约束

<system-reminder> 从头到尾体现的都是同一件事——对大模型的引导与约束。把链路读一遍，可以归纳出四条具体做法：

1. 约定一条模型能辨认的旁路通道。API 只有三种 role，无法给"系统注入"开新 role，于是 Claude Code 用一对 XML 风格标签 + 系统提示里的两句声明，让模型学会"见到这种前缀就知道是旁白、不是因果"。
2. 在关键节点反复注入以维持状态。Plan 模式、Auto 模式、Output Style、skill 调用的指南——这些只讲一次模型会忘；每一轮都重新注入一次，才能让"现在在 plan mode"这件事真的持续 50 轮。
3. 让 reminder 的字节"可缓存"。模板里所有容易每轮抖动的字段都被主动冻结（例如 memory header 里的 "N days ago" 在 attachment 创建时就算好并缓存），避免 Date.now() 把 prompt cache 打穿——这让每轮注入的 reminder 成为 prompt cache 的友军，而不是对手。
4. 矫正副作用。reminder 放错位置（作 tool_result 的 sibling）会教坏模型、让它多吐一个空 Human: 回合。smoosh 合并机制把这种漂移从根本上消除掉，让"不停注入 reminder"这个动作本身不会累积毒性。

这四条放在一起，才是 <system-reminder> 真正做的事——它不只是一个标签，而是一整套"如何持续地引导和约束大模型"的工程实践。

结语

如果你之前对 Claude Code 的印象是"Claude API + 工具调用 + MCP + skill + 上下文压缩"那几件事，希望这篇文章让你多看到了一层：在每轮 API 请求真正发出去之前，messages 数组里早已被系统静悄悄填满了各种 <system-reminder>。它们是模型行为长期保持稳定的那条几乎看不见的骨架。

附录

A. Phase 4 的 A/B 实验

正文 §4.7 提到 Plan 模式 Phase 4（"写最终 plan"那一步）在代码里有 4 个 A/B 变体。这里把实验的具体细节整理一下，作为一扇看看"大厂怎么做 prompt 工程实验"的小窗。

实验代号：tengu_pewter_ledger，由 Anthropic 服务端的 feature flag 分桶下发。返回值为 null（走 CONTROL 对照组，也是默认/兜底）、'trim'、'cut'、'cap' 四种。所以一个用户具体看到哪一版 Phase 4 不取决于本地配置，而是服务端分配；null 是 fallback，意味着统计上多数用户看到 CONTROL。

4 个变体从宽到严：

• CONTROL：对照组原版（正文已展开），要求 Context 背景段、详细文件列表、端到端验证说明。
• TRIM：Context 压成一行，验证部分改成"一条验证命令"。
• CUT：直接禁止写 Context/Background 段，并加入"好 plan 通常少于 40 行，废话即是凑字数"。
• CAP：最严版——禁止散文段、每个文件只能一行说明、硬性 40 行上限。

实验动机（来自 CONTROL 组的 baseline）：代码注释里附了一段 14 天内约 2630 万个会话（截止 2026-03-02）的 baseline 统计：

• plan 文件长度：中位数 4,906 字符、p90 11,617 字符、均值 6,207 字符。
• 82% 会话走 Opus 4.6。
• 拒绝率随 plan 大小单调增长：plan 不到 2K 字符时用户拒绝率约 20%，plan 超过 20K 字符时拒绝率升到 50%。

这条单调关系就是 TRIM/CUT/CAP 实验的出发点——plan 越短，用户越容易接受。于是实验要回答的是"能不能把 Phase 4 的指令压缩到让模型主动写更短的 plan，同时又不损失质量"。

监测指标（来自代码注释）：

• 主指标：会话级平均成本（Anthropic 内部指标代号 fact__201omjcij85f）。用成本而不是直接用"plan 长度"当主指标，原因是 Opus 输出价格是输入的 5 倍——花多少钱等价于吐多少字节；这比 plan 长度更能反映整体开销。
• 机制变量：plan 退出时记录的 plan 文件字符数（planLengthChars）。注释里专门提醒："CAP 变体可能把 plan 文件压短了，但总输出反而因为 write→count→edit 的反复循环变多——所以光看 plan 长度会误判。"
• 护栏指标：用户点坏反馈（feedback-bad）的比率、每会话发起的请求数（plan 太薄 → 实现阶段补轮次变多）、工具错误率。三条护栏挡住"为压而压把质量压没了"。

到截稿为止实验还在跑——代码里 4 个变体的分支都还在线，服务端仍按配置做分桶，没有收敛为某个唯一胜者的迹象。

B. Interview Phase：Anthropic 员工走的另一条 Plan 链路

正文 §4.7 的 Plan 模式展开的是 5-phase workflow——面向外部用户的主流程。代码里还存在另一条完整的 Plan workflow，代号 interview phase。它不是 5-phase 的第几步，而是 5-phase 的替代：Plan 模式被激活后，Claude Code 要么走 5-phase、要么走 interview phase，二选一。

怎么决定走哪条：函数 isPlanModeInterviewPhaseEnabled() 按优先级判定：

1. Anthropic 员工（代码用环境变量 USER_TYPE === 'ant' 判定）——始终启用 interview phase。
2. 否则看环境变量 CLAUDE_CODE_PLAN_MODE_INTERVIEW_PHASE（用户显式开关）。
3. 否则查 feature flag tengu_plan_mode_interview_phase。

正是因为员工强制走 interview phase，而 Phase 4 的 A/B 实验（见附录 A）只跑在 5-phase 工作流上，interview phase 就天然被实验隔离，成了观测设计上的参照组。

完整模板（来自 getPlanModeInterviewInstructions，替换后占位符如 ${planFilePath} 等为运行时值；最外层再包一层 <system-reminder>）：

其中 ${planFileInfo} 与 5-phase 的同名占位符用的是同一套条件文案——plan 文件已存在时展开为"A plan file already exists at ${planFilePath}. You can read it and make incremental edits using the Edit tool."，不存在时展开为"No plan file exists yet. You should create your plan at ${planFilePath} using the Write tool."。