Mingyu's Library主页
2026年8月27日

第 20 课:Output Styles —— 换掉 Claude 的「说话方式」

2026-08-27 · 主题:output styles(内置风格、outputStyle 设置、自定义风格、与 CLAUDE.md / skills 的分界)

前 19 课几乎都在解决「Claude 做什么、能做什么、别做什么」——CLAUDE.md 管项目常识,权限管边界,hooks 管护栏,skills 管可复用工作流。今天这一课解决的是另一个正交问题:Claude 用什么身份、什么语气、什么默认格式跟你说话。

如果你发现自己每一轮都在打「别啰嗦,直接说结论」「先画个图再解释」「你现在是数据分析师不是工程师」——那就是 output style 该出场的信号。官方对它的定义很干脆:output style 改变 Claude 怎么回应,不改变 Claude 知道什么。它直接修改系统提示词(system prompt),对每一轮都生效。

本课 4 条,由浅入深。

技巧 1(入门):先把内置的 5 种风格试一遍,尤其是新出的 Concise

Claude Code 的 Default 就是内置的软件工程系统提示词。另有 4 种内置风格:

风格 行为
Proactive 立即执行,对常规决策自行做合理假设,倾向行动而非规划。比 auto mode 的自主执行引导更强,且不改变你的权限模式——什么能免确认跑,依然由权限模式说了算
Concise 先给结果,跳过铺垫和旁白,默认简短;但工程做得和 Default 一样扎实。你要解释时它会完整展开。错误报告、安全告警、破坏性操作的确认信息永远保留完整内容。需要 v2.1.237+
Explanatory 干活的同时穿插教学性的 "Insights",讲清实现取舍和代码库模式
Learning 边做边学模式,除了 Insights,还会在代码里插 TODO(human) 标记,让你自己实现一小段关键逻辑

终端里切换:

/config
# → 选 Output style → 选一个

Claude Code 会把选择写进项目本地的 .claude/settings.local.json。

⚠️ 独立的 /output-style 命令已在 v2.1.73 弃用、v2.1.91 移除。现在只能用 /config 或直接改设置文件。

上手建议:日常 code review / 修 bug 用 Concise,读陌生代码库用 Explanatory,想真学会某个模块用 Learning。Concise 是 8 月新增的,值得优先试——它是「省 output token」和「少读废话」两件事一次解决。

技巧 2(进阶):写进 settings.json,并记住它「什么时候才生效」

不想每次开会话都点菜单,就把它固化到设置文件里:

// .claude/settings.local.json(项目本地,不进 git)
// 或 .claude/settings.json(项目级,团队共享)
// 或 ~/.claude/settings.json(用户级)
{
  "outputStyle": "Concise"
}

桌面 app 里没有终端那套菜单——/config 会直接打开 Settings > Claude Code,所以桌面端就是直接改 outputStyle 字段。

这条最容易踩的坑是生效时机:

Output style 是系统提示词的一部分,而系统提示词 Claude Code 只在会话启动时读一次。改完之后,要 /clear 或开新会话才生效。

顺带一个成本细节:切换 output style 会让 prompt cache 失效(系统提示词变了,缓存前缀就不匹配了)。所以别在一个长会话里反复横跳切风格——那等于每切一次就重付一遍系统提示词的 input token。选定一个,/clear 一次,跑完这一段活。

技巧 3(实操):自定义风格,关键只有一个开关 keep-coding-instructions

自定义 output style 就是一个 Markdown 文件:frontmatter 写元数据,正文写要追加进系统提示词的指令。放三个位置之一:

文件名即风格名(除非在 frontmatter 里写 name)。

<!-- .claude/output-styles/diagrams-first.md -->
---
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.

## Diagram conventions

Use `flowchart TD` for control flow and `sequenceDiagram` for request paths.
Keep diagrams under 15 nodes.

整个自定义机制里最重要的一个字段是 keep-coding-instructions,默认 false。

默认值是 false 这件事值得单独记一下:如果你写了个自定义风格只是想让它说话客气点,却忘了加 keep-coding-instructions: true,你会连带把 Claude 的整套工程纪律一起关掉——然后困惑「它怎么突然不验证自己的改动了」。

完整 frontmatter 字段:

字段 作用 默认
name 风格名(不写则用文件名) 文件名
description 在 /config 选择器里显示的说明 无
keep-coding-instructions 保留内置软件工程指令 false
force-for-plugin 仅插件风格:插件启用时自动应用,覆盖用户的 outputStyle 设置。多个插件都设了就用最先加载的那个 false

项目级风格会从工作目录一路加载到仓库根目录的每一个 .claude/output-styles/;同名冲突时,离工作目录最近的那个赢——monorepo 里给不同子包配不同风格就靠这条。

插件也能通过 output-styles/ 目录分发风格(呼应第 17 课的插件与 Marketplace)。

技巧 4(选型):别拿 output style 当 CLAUDE.md 用——五个机制的分界线

这是最容易混淆的地方。官方给了一张对照表,值得背下来:

机制 工作方式 什么时候用
Output styles 修改系统提示词 你想要每一轮都不同的角色、语气或默认回应格式
CLAUDE.md 在系统提示词之后追加一条 user message Claude 应该永远知道你的项目约定和代码库上下文
--append-system-prompt 追加到系统提示词,不删任何东西 单次调用的一次性补充
Agents(subagent) 跑一个有独立系统提示词、模型、工具的子代理 你要一个作用域独立的助手干一件专注的事
Skills 被调用或判定相关时才加载任务专属指令 你有一个可复用的工作流

三条实践推论:

  1. 项目约定写 CLAUDE.md,不要写进 output style。 官方明确说了:关于你的项目、约定、代码库的内容,用 CLAUDE.md。output style 是给「角色和语气」用的,把项目知识塞进去会让风格没法在项目间复用。

  2. Output style 只对主会话生效,subagent 不继承。 subagent 跑的是它自己的系统提示词——所以你设了 Concise,派出去的 subagent 依然按它自己的方式回答。唯一例外是 fork,因为 fork 继承父会话的完整系统提示词(呼应第 10 课的会话管理)。

  3. 注意 token 的两个方向。 加指令进系统提示词 → input token 上升(但会话内第一次请求之后,prompt caching 会把这部分成本压下去,呼应第 21 篇深度文档提过的缓存命中率);而 Explanatory 和 Learning 按设计就会产出更长的回答 → output token 上升,Concise 则相反。自定义风格的 output 开销,完全取决于你的指令让 Claude 产出什么。

一次性试某个风格、不想改配置?用无头模式配合(呼应第 12 课):

claude -p "review this diff" --append-system-prompt "Lead with the verdict. No preamble."

排查「风格没生效」:先确认你 /clear 过或开了新会话,再用官方的配置调试页逐层看设置优先级。

一句话总结

Output style 管「怎么说」,CLAUDE.md 管「知道什么」,skills 管「怎么干一类活」,权限管「能干什么」——四个抽屉别互相塞。 自定义时先想清楚 keep-coding-instructions 该不该开,改完记得 /clear。

相关阅读