Claude Code 深度学习手册

主题

Output Styles（输出风格） ​

Output Styles 通过直接改写 Claude Code 的 system prompt，调整 Claude 回复的角色、语气和默认输出格式（改"怎么答"而非"知道什么"）。

你的真实情况 ​

你装的插件里就有输出风格相关的（explanatory-output-style、learning-output-style 在你的插件 hooks 目录里出现过）。Output style 改的是 Claude 回复的"语气/结构"——通过替换/追加 system prompt 实现。

去真实体验 ​

想验证什么这样做
切换输出风格/output-style（或在 /config 里）
看当前风格/config
注意改了风格要 /clear 或重启才重建 system prompt 生效

对你的实际意义 ​

  • 你 CLAUDE.md 已经规定了"中文回复、简短优于详细、表格代替长段落"——这其实就是用 CLAUDE.md 做了轻量的风格约束。要更彻底（每次回答都带教学解释）可叠加 explanatory 风格。
  • 风格是 system prompt 级，比 CLAUDE.md（user message 级）更强、更难被对话内容冲淡。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

Output styles 改变的是 Claude 如何回复（role、tone、output format），而不是 Claude 知道什么。它通过修改 system prompt 来设定角色、语气和输出格式。当你每一轮都在为同一种语气或格式反复 re-prompt，或者想让 Claude 扮演软件工程师以外的角色（如写作助手、数据分析师）时使用。自定义 output style 会把你的指令加到 system prompt，并可选择是否保留 Claude Code 内置的软件工程指令。关于项目/约定/代码库的信息应改用 CLAUDE.md。

怎么工作 ​

  • Output styles 直接修改 Claude Code 的 system prompt。
  • 所有 output style 都会把各自的自定义指令追加到 system prompt 的末尾（added to the end of the system prompt）。
  • 所有 output style 都会在对话过程中触发 reminders，提醒 Claude 持续遵守该 output style 指令。
  • 自定义 output style 默认会丢弃 Claude Code 内置的软件工程指令（如何 scope changes、写注释、verify work 等），除非在 frontmatter 设 keep-coding-instructions: true。
  • Output style 是 system prompt 的一部分，Claude Code 在 session 启动时读取一次（reads once at session start）；更改后需 /clear 或开新 session 才生效。
  • Token 影响：往 system prompt 加指令会增加 input tokens，但首次请求后 prompt caching 会降低成本；内置 Explanatory 和 Learning 风格按设计会产生比 Default 更长的回复，从而增加 output tokens。

怎么配置 / 用法 ​

切换风格：运行 /config 选择 Output style 从菜单挑选；选择保存到 .claude/settings.local.json（local project level）。不用菜单时，可直接在 settings 文件里编辑 outputStyle 字段：

json
{
  "outputStyle": "Explanatory"
}

独立的 /output-style 命令已在 v2.1.73 deprecated、v2.1.91 removed，改用 /config 或直接编辑 outputStyle 设置。

创建自定义风格：写一个 Markdown 文件（frontmatter + 指令正文），保存到三个层级之一：

  • User：~/.claude/output-styles
  • Project：.claude/output-styles
  • Managed policy：managed settings directory 里的 .claude/output-styles 文件名即风格名，除非在 frontmatter 设 name。示例：
markdown
---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---

When explaining code, architecture, or data flow, start with a Mermaid diagram showing the structure, then explain in prose.

Plugins 也可在 output-styles/ 目录里携带 output styles。

什么时候用 ​

  • 当你每一轮都在为同一种 voice 或 format 反复 re-prompt 时用。
  • 当你想让 Claude 扮演软件工程师以外的角色（writing assistant、data analyst）时用，此时留空 keep-coding-instructions（即 false）。
  • 当你想改变 Claude 的沟通方式但仍在写代码（如总是用 diagram 回答）时用，并设 keep-coding-instructions: true。
  • 对比表给出的判断：想要每一轮都有不同的 role/tone/默认响应格式 → 用 Output styles。
  • 别用来记项目约定/代码库上下文 → 改用 CLAUDE.md（它是在 system prompt 之后追加一条 user message）。
  • 别用来做一次性追加 → 用 --append-system-prompt（单次调用追加到 system prompt 且不删除任何东西）。
  • 别用来做单独 scope 的专项助手 → 用 Agents（subagent 有自己的 system prompt、model、tools）。
  • 别用来做可复用工作流 → 用 Skills（按需或相关时加载任务指令）。

限制 / 坑 ​

  • 更改 output style 不会立即生效：因为它是 session 启动时读取一次的 system prompt 一部分，必须 /clear 或新开 session 后才生效。
  • 独立 /output-style 命令已在 v2.1.73 弃用、v2.1.91 移除（文档标注 max-version 2.1.90）；现在必须用 /config 或直接编辑 outputStyle。
  • 自定义 output style 默认会丢掉内置软件工程指令；若忘记设 keep-coding-instructions: true，Claude 在编码任务上的行为可能退化。
  • Explanatory 和 Learning 按设计产生更长回复，增加 output token 成本。
  • force-for-plugin 仅对 plugin output styles 有效；若多个启用的 plugin 都设了它，Claude Code 用第一个加载的（first one loaded），且会覆盖用户的 outputStyle 设置。
  • Proactive 风格虽提供比 auto mode 更强的自主执行引导，但不改变 permission mode，工具运行前你仍会看到 permission prompts。

硬事实速查（19 条） ​

  • 内置 Default 风格 = 现有 system prompt，为高效完成软件工程任务而设计。
  • 另有三个内置风格：Proactive、Explanatory、Learning。
  • Proactive：立即执行、对常规决策做合理假设而非停下来、偏向行动而非规划；比 auto mode 的自主执行引导更强，且不改 permission mode，工具运行前仍有 permission prompts。
  • Explanatory：在帮你完成软件工程任务的同时穿插教育性的 "Insights"，帮你理解实现选择和代码库模式。
  • Learning：协作式 learn-by-doing 模式，不仅分享 "Insights"，还会让你亲手贡献小而关键的代码片段；Claude Code 会在代码里加 TODO(human) 标记供你实现。
  • 切换方式：/config → 选 Output style。
  • 选择保存到 .claude/settings.local.json（local project level）。
  • 设置字段名为 outputStyle，值如 "Explanatory"。
  • 独立 /output-style 命令：v2.1.73 deprecated，v2.1.91 removed。
  • 自定义风格文件三个保存层级：User ~/.claude/output-styles、Project .claude/output-styles、Managed policy（managed settings directory 内的 .claude/output-styles）。
  • 文件名即风格名，除非 frontmatter 设 name。
  • frontmatter 字段 name：风格名（不设则继承文件名）。
  • frontmatter 字段 description：在 /config picker 中显示的描述（默认 None）。
  • frontmatter 字段 keep-coding-instructions：保留内置软件工程指令，默认 false。
  • frontmatter 字段 force-for-plugin：仅 plugin output styles，启用插件即自动应用该风格、覆盖用户 outputStyle，多个时用第一个加载的，默认 false。
  • Plugins 可在 output-styles/ 目录里携带 output styles。
  • 机制：自定义指令加到 system prompt 末尾；触发 reminders 让 Claude 持续遵守；自定义风格默认丢弃内置软件工程指令（除非 keep-coding-instructions: true）。
  • 对比：CLAUDE.md 在 system prompt 之后加一条 user message；--append-system-prompt 追加到 system prompt 且不删任何内容（单次调用）；Agents 跑带独立 system prompt/model/tools 的 subagent；Skills 按需加载任务指令。
  • 示例 frontmatter 用 name: Diagrams first / description: Lead every explanation with a diagram / keep-coding-instructions: true，正文要求先给 Mermaid diagram，用 flowchart TD 表控制流、sequenceDiagram 表请求路径，diagram 节点保持在 15 个以内。

官方出处：https://code.claude.com/docs/en/output-styles