Claude Code 输出风格怎么设:Concise / Explanatory / Learning

Claude Code 默认按软件工程系统提示答话,有时太长、有时你想先听结论。官方 Output styles 用一套会话级指令改角色、语气和篇幅:内置 Concise / Explanatory / Learning / Proactive,也支持自定义 Markdown。本文按 code.claude.com 输出风格文档 与 settings 参考整理怎么切、怎么写、和 CLAUDE.md / hooks 怎么分工;配置步骤未在本机逐条实测,以你本机 Claude Code 版本为准。
Output style 改什么、不改什么
Output style 是一组指令,挂在整段会话的每条回复上,省得你每轮重复「短一点 / 解释一下」。文档写明:它是指令,不保证某事一定发生或绝不发生。项目约定、目录结构、常用命令,仍放 CLAUDE.md;每次编辑后必须格式化、某条命令必须拦,用 hook。风格只管语气、长度、角色。
Claude Code 从 Default 起步:未选任何风格时,不加额外风格指令,沿用标准软件工程系统提示。/output-style 列表里也能选回 default。
| 风格 | 相对 Default 多了什么 | 适合 |
|---|---|---|
| Proactive | 立刻动手,常规决策自行假设;删数据或动共享/生产前仍应在对话里确认(与权限弹窗分开) | 你想少被例行问题打断,错了再纠偏 |
| Concise | 首句给结果;去掉开场白、过程旁白、收尾复述;简单问题 1–3 句。工程做得与 Default 一样细。需 Claude Code v2.1.237+ | 默认回复比你需要的长 |
| Explanatory | 任务照做,另加短 Insight 块说明代码选择(不写进仓库注释) | 摸代码库,或要「改了什么 + 为什么」 |
| Learning | 同样有 Insight;在有设计分叉处留 TODO(human),让你补几行再继续 | 边做边练,任务仍要做完 |
Concise 把回复写短,不把工程做薄;你要解释、或安全相关输出,它仍会写全。
Concise:短在哪,何时仍长
文档对 Concise 的约定很具体:回复第一句就要说发生了什么或答案是什么;去掉铺垫、逐步旁白和结尾复盘。简单事实题压到一两句到三句。实现质量不打折。
下面几类仍保持完整篇幅:
- 你明确要解释或要更多细节时;
- 你需要据此安全行动时:错误报告、失败测试输出、安全警告、破坏性操作确认等。
实践上:日常改代码、问「测过了吗」用 Concise 很省扫读时间;做设计评审或排障时,直接说「展开讲」或临时切回 Default / Explanatory,比抱怨「Concise 太短」有效。
怎么切换
命令与菜单会把选择写到项目本地 .claude/settings.local.json:
/output-style:/output-style concise直接切;不带参数则列出可选风格并标当前。非交互模式、Agent SDK、以及经 Remote Control 的手机/网页也可列/选内置风格(需 v2.1.269+)。- 终端菜单:
/config→ Output style。 - VS Code 扩展:命令菜单
/→ Output styles(含自定义;需 v2.1.257+)。 - 桌面端:在 settings 文件里写
outputStyle(终端菜单在桌面会打开设置页而不是同一套菜单)。
手改示例:
{
"outputStyle": "Concise"
}
大小写:settings 里内置名必须写成 Proactive、Concise、Explanatory、Learning。写成 explanatory 这种不精确匹配会落到 Default。/output-style 命令则忽略大小写。跨项目默认写在 ~/.claude/settings.json;项目级 settings 优先。会话中途切换后,下一条消息起生效(v2.1.251 前要 /clear 或新开会话)。权限模式不会因切到 Proactive 而改变——谁自动跑工具仍看 权限与 settings。
自定义风格
自定义 = 一个 Markdown:YAML frontmatter + 正文指令。路径三选一(同名时离工作目录近的项目级优先):
- 用户:
~/.claude/output-styles/ - 项目:
.claude/output-styles/(从工作目录到仓库根之间的嵌套目录都会加载) - 托管策略目录下的
.claude/output-styles/
常见字段:name、description、keep-coding-instructions(true 时保留 Claude Code 内置软件工程说明;默认 false——自定义风格在完整系统提示下会拿掉那一段,除非你显式保留)。插件也可在 output-styles/ 里附带风格;force-for-plugin: true 可在启用插件时强制套用并覆盖用户的 outputStyle。
---
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.
终端里风格文件在启动时读取;会话中新建或改文件后,需重启 Claude Code 才生效。VS Code 可用菜单创建文件(v2.1.261+)。
和别的扩展怎么选
| 你想要 | 用 | 原因 |
|---|---|---|
| 整段会话统一语气/长度/角色 | Output style | 一条命令切换,作用于每条回复 |
| 项目约定、命令、结构常驻 | CLAUDE.md | 与风格无关,换风格仍在 |
| 某一类任务的清单/流程 | Skill | 按需加载,不污染无关回复 |
| 每次编辑后必跑、某命令必拦 | Hook | 由 Claude Code 执行,不靠模型「记得住」 |
| 独立上下文的帮手 | Subagent | 自有系统提示;风格不传到普通子代理(fork 会继承父会话) |
Token:风格指令增加输入;同会话后续有 prompt cache。Explanatory / Learning 故意更长(输出 token↑);Concise 相反。自定义风格的输出量取决于你写的指令。
建议怎么试
同一仓库开两次会话对比最清楚:一次 Default 让它「给这个函数加测试并说明取舍」;一次 /output-style concise 发同一句。再试一次 Explanatory,看 Insight 块是否出现在对话里而不是写进文件。若 Concise 下你仍觉得某次回复过长,先检查是不是触发了「你要细节」或安全类全文保留。
团队默认可把 outputStyle 写进 ~/.claude/settings.json;单个仓若要更啰嗦的 onboarding,用项目 .claude/settings.json 覆盖为 Explanatory。和 effort 档位 正交:effort 调推理深浅,style 调说话方式。
常见坑
- settings 写成小写
concise。落到 Default,看起来像「设置没生效」。 - 用 Concise 当「禁止解释」。你一问细节或遇安全相关输出,它仍会写长——这是文档约定,不是 bug。
- 把必须执行的检查塞进风格。风格不被强制;门禁用 hook,权限用 settings。
- 自定义风格忘了
keep-coding-instructions: true。若你仍要它按软件工程默认方式改代码,保留那段说明;若角色根本不是工程师,可保持默认 false。 - Proactive ≠ 绕过权限。切换风格不改 permission mode;删库级操作仍受权限与风格内「先问你」指令双重约束,二者不是一回事。
完成标准
- 能说出 Concise / Explanatory / Learning / Proactive 各解决什么问题。
- 能在 settings 里写出大小写正确的
"outputStyle": "Concise",并用/output-style验证当前风格。 - 能举一例:项目知识 → CLAUDE.md;必须发生 → hook;说话方式 → output style。
- 若写自定义风格:文件落在约定目录,需要保留工程指令时打开
keep-coding-instructions。
最后
先试 Concise 压日常噪音;要讲清楚设计时切 Explanatory。项目事实继续写在 CLAUDE.md,别塞进风格文件。版本与字段以下方官方文档为准。