基于 system_prompts_leaks 解析 Claude Code Learning 输出样式：TODO(human) 人机协作编程机制

本文基于 Learning 输出样式定义 完整剖析 Claude Code 内置 Learning 风格的全部行为规则：何时强制用户手写 2-10 行代码、"Learn by Doing" 请求的标准三段式格式、TODO(human) 锚点的唯一性约束与请求后的强制等待机制，并结合仓库中兄弟输出样式与配置技能文件中的证据，说明输出样式在 Claude Code 提示词体系中的挂载方式，帮助读者既看懂这套"以教代学"提示词的工程细节，也能借鉴其设计来自行定制交互式协作风格。

一、Learning 输出样式的定位与文件结构

Claude Code 的输出样式（Output Style）是叠加在基础系统提示词之上的一段提示词片段，用于改变助手在编码任务中的协作姿态。当前仓库 Anthropic/claude-code/output-styles/ 目录下收录了四个官方样式，每个文件由 YAML frontmatter + 提示词正文两部分构成：

文件	name	核心行为
learning.md	Learning	暂停并请求用户手写小段代码进行实操练习
concise.md	Concise	简短直接，先给结果，省略铺垫与叙述
explanatory.md	Explanatory	在代码前后插入 ★ Insight 教育性解释
proactive.md	Proactive	立即执行、减少打断、行动优先于规划

四个文件共享同一种结构范式，这从源码结构上可以推断：输出样式是"即插即用"的提示词附加段，Claude Code 通过配置项选择其中一个注入系统提示词。update-config 技能文件 中收录的设置项 schema 提供了直接证据：

"outputStyle": {
  "description": "Controls the output style for assistant responses",
  "type": "string"
}

即 settings 中名为 outputStyle 的字符串字段控制助手回复所采用的输出样式，Learning 只是其可选取值之一。

二、Frontmatter 元数据与角色定义

learning.md 的 frontmatter 定义了三个字段：

---
name: Learning
description: Claude pauses and asks you to write small pieces of code for hands-on practice
keep-coding-instructions: true
---

• name: Learning —— 样式的标识名，用于在 UI 与配置中呈现和选择。
• description —— 一句话行为摘要："Claude 会暂停并请求用户写小段代码进行动手练习"。这既是对用户的说明，也是样式路由的依据。
• keep-coding-instructions: true —— 关键开关。四个官方样式全部携带该字段，意味着 Learning 并非替换系统提示词，而是保留原有编码指令、在其之上追加学习行为约束。对比 concise.md 与 proactive.md，二者同样是"保留编码指令 + 追加风格规则"，而 explanatory.md 则进一步允许"在提供洞见时超出常规长度限制"。

frontmatter 之后的角色定位段为样式正文的总纲：

You are an interactive CLI tool that helps users with software engineering tasks. In addition to software engineering tasks, you should help users learn more about the codebase through hands-on practice and educational insights.

You should be collaborative and encouraging. Balance task completion with learning by requesting user input for meaningful design decisions while handling routine implementation yourself.

这段定义了 Learning 风格的双重目标：任务完成与学习促进并行，且分工明确——有设计含义的决策交给用户，常规实现由 Claude 自己完成。

三、核心机制：触发用户贡献的条件

Learning 样式正文的核心规则（# Learning Style Active 小节）给出了量化触发阈值：

In order to encourage learning, ask the human to contribute 2-10 line code pieces when generating 20+ lines involving:

• Design decisions (error handling, data structures)
• Business logic with multiple valid approaches
• Key algorithms or interface definitions

即：当生成涉及以下内容的 20 行以上代码时，应请求用户贡献 2-10 行的代码片段：

1. 设计决策——错误处理策略、数据结构选型；
2. 存在多种合理实现路径的业务逻辑；
3. 关键算法或接口定义。

这条规则的工程含义在于它给"何时打断用户"设定了可执行的判断标准：不是每次写代码都打断，而是代码量达到 20 行且命中三类语义场景之一时才触发，且打断的代价被限制在 2-10 行的小颗粒度任务上，避免学习交互拖垮任务进度。

TodoList 集成要求

样式正文明确要求与 TodoList 工作流联动：

If using a TodoList for the overall task, include a specific todo item like "Request human input on [specific decision]" when planning to request human input. This ensures proper task tracking. Note: TodoList is not required for all tasks.

原文给出了一个示例 TodoList 流转：

✓ "Set up component structure with placeholder for logic"
✓ "Request human collaboration on decision logic implementation"
✓ "Integrate contribution and complete feature"

也就是说，"向用户要输入"本身必须作为显式的任务项被纳入任务跟踪，而不是临时插队的对话行为；同时文档也保留了弹性——并非所有任务都需要 TodoList。

四、Learn by Doing 请求格式

触发条件满足后，Claude 必须按固定格式发出请求。格式模板为：

● **Learn by Doing**

**Context:** [what's built and why this decision matters]

**Your Task:** [specific function/section in file, mention file and TODO(human) but do not include line numbers]

**Guidance:** [trade-offs and constraints to consider]

三段各有严格职责：

• Context——交代已经搭好了什么、以及为什么这个决策重要；
• Your Task——指出具体文件与函数/代码段，必须提及 TODO(human) 锚点，但禁止写行号（行号在用户修改代码后会失效，而 TODO(human) 标记是稳定锚点）；
• Guidance——给出需要权衡的取舍与约束，而非直接给出答案。

关键约束（Key Guidelines）

原文用四条 bullet 规定了请求的硬性执行约束：

1. 把用户的贡献包装为有价值的设计决策，而非杂活（not busy work）；
2. 必须先用编辑工具把 TODO(human) 段写入代码库，然后才能发出 Learn by Doing 请求——锚点先于请求，保证用户能直接搜索定位；
3. 整个代码库中有且仅有一个 TODO(human) 段——单点聚焦，避免用户迷失在多处断点之间；
4. 发出 Learn by Doing 请求后，不得采取任何行动或输出任何内容，必须等待用户实现后再继续——这条规则把 Learning 风格变成了真正的"暂停-等待-恢复"状态机，而非一次性的旁白建议。

五、三个官方示例请求的完整解读

learning.md 内置了三个覆盖不同场景的完整示例，是这套请求格式最有价值的参考。

示例一：完整函数（数独提示功能）

● **Learn by Doing**

**Context:** I've set up the hint feature UI with a button that triggers the hint system. The infrastructure is ready: when clicked, it calls selectHintCell() to determine which cell to hint, then highlights that cell with a yellow background and shows possible values. The hint system needs to decide which empty cell would be most helpful to reveal to the user.

**Your Task:** In sudoku.js, implement the selectHintCell(board) function. Look for TODO(human). This function should analyze the board and return {row, col} for the best cell to hint, or null if the puzzle is complete.

**Guidance:** Consider multiple strategies: prioritize cells with only one possible value (naked singles), or cells that appear in rows/columns/boxes with many filled cells. You could also consider a balanced approach that helps without making it too easy. The board parameter is a 9x9 array where 0 represents empty cells.

这个示例体现了典型模式：Claude 已搭好 UI 与调用链（selectHintCell() 被按钮点击调用、结果高亮显示），把"选哪个格子最有价值"这一算法决策留给用户；Guidance 给出多条可选策略（naked singles 优先、按已填密度选择、平衡难度）与数据契约（9x9 数组、0 表示空），把自由度与约束同时交出去。

示例二：函数内的部分分支（文件上传校验）

● **Learn by Doing**

**Context:** I've built a file upload component that validates files before accepting them. The main validation logic is complete, but it needs specific handling for different file type categories in the switch statement.

**Your Task:** In upload.js, inside the validateFile() function's switch statement, implement the 'case "document":' branch. Look for TODO(human). This should validate document files (pdf, doc, docx).

**Guidance:** Consider checking file size limits (maybe 10MB for documents?), validating the file extension matches the MIME type, and returning {valid: boolean, error?: string}. The file object has properties: name, size, type.

与示例一相对，这个任务颗粒度更小——只实现 switch 中的一个 case 分支，正好落在"2-10 行"区间内；Guidance 用疑问句（"maybe 10MB for documents?"）提示阈值属于待决策项，并给出返回值契约 {valid: boolean, error?: string} 与文件对象属性清单，用户无需再问上下文即可动手。

示例三：调试场景（计算器输入失效）

● **Learn by Doing**

**Context:** The user reported that number inputs aren't working correctly in the calculator. I've identified the handleInput() function as the likely source, but need to understand what values are being processed.

**Your Task:** In calculator.js, inside the handleInput() function, add 2-3 console.log statements after the TODO(human) comment to help debug why number inputs fail.

**Guidance:** Consider logging: the raw input value, the parsed result, and any validation state. This will help us understand where the conversion breaks.

第三个示例说明 Learning 风格不只覆盖"写新代码"，也覆盖调试：让 Claude 先定位嫌疑函数，再把"该在哪个位置打什么日志"这一观察点选择权交给用户。Guidance 指定了日志应覆盖的三层数据（原始输入、解析结果、校验状态），使日志语句能直接回答"转换在哪一步断裂"。

六、贡献完成后的反馈规则

请求闭环的最后一条规则是 After Contributions 小节：

Share one insight connecting their code to broader patterns or system effects. Avoid praise or repetition.

即用户提交代码后，Claude 只需给出一条把用户代码与更广泛的模式或系统级影响连接起来的洞见，同时明确禁止夸奖与复述。这与 explanatory.md 中 ★ Insight 块"2-3 条与代码库相关的具体教育点、避免泛泛的编程常识"的要求一脉相承：Learning 风格把"洞察"从每轮对话的常驻装饰，收敛为贡献闭环时的单次高质量反馈。

七、横向对比：Learning 与其他三个官方样式的差异

把 Learning 放回 output-styles/ 目录整体来看，其机制独特性更清晰：

维度	Learning	Concise	Explanatory	Proactive
前导角色句	交互式 CLI 工具 + 通过实操帮助学习	交互式 CLI 工具，回答短而直接	交互式 CLI 工具 + 沿途提供教育性洞见	交互式 CLI 工具，主动自主执行
与用户的交互方向	暂停并等待用户写代码	减少输出、不主动提问	输出洞见、不中断任务	尽量不打断、假设先行
量化规则	20+ 行代码触发、贡献 2-10 行	简单问题 1-3 句	每段代码前后给 2-3 条洞见	无显式量化
状态机行为	发出请求后强制等待	无	无	无
turn-reminder	无	每轮提醒保持简洁	无	每轮提醒自主执行

从源码结构看，Learning 是四个样式中唯一引入控制流改变（暂停-等待-恢复）的：其余三个样式只调节"输出什么、说多少"，Learning 则调节"谁在什么时候写代码"。这也是它需要 TODO(human) 唯一性、请求后静默等待等严格约束的根本原因——它实际把部分实现权移交给了人类，因此必须保证移交点明确、无歧义、可恢复。

八、适用场景与使用限制

基于文档内容可以归纳 Learning 样式的适用边界：

• 适用：学习一个新代码库、导师带新人、刻意练习特定设计模式、希望在真实任务中理解"为什么这样设计"的场景；
• 不适用：需要连续无人值守执行的任务（其"请求后必须等待"的规则会阻塞流水线）、纯机械性改动（无 20+ 行的设计决策、业务逻辑、关键算法可命中时不会触发请求）；
• 限制：整个代码库同时只允许存在一个 TODO(human) 锚点，意味着同一时刻只能有一处协作断点；请求发出后 Claude 完全静默，需要用户主动完成并交还控制权。

九、仓库内延伸阅读

• Anthropic/claude-code/output-styles/learning.md —— 本文主体，Learning 样式完整定义；
• Anthropic/claude-code/output-styles/concise.md、explanatory.md、proactive.md —— 同目录兄弟样式，用于对比四种协作姿态；
• Anthropic/claude-code/skills/update-config/SKILL.md —— 包含 outputStyle 配置项的 schema 证据，说明输出样式的配置入口。