文章目录

1. 引言

参考官方文档： https://code.claude.com/docs/en/output-styles

在这里插入图片描述

在前面的博客，博主已经系统讲解了 Claude Code 的核心能力，有兴趣的同学可以先了解：

本文主要聊 Output Styles，它并不是字面上的 “输出风格，让回答更好看”，而是把 Claude Code 的 系统提示词 “换皮”，让 Claude 在保持本地能力（跑脚本、读写文件、TODO 追踪）的同时，变成你需要的任何类型 Agent（事故指挥官、产品经理、技术写作、数据分析助手、代码导师……）

2. Output Styles 是什么？

2.1 概念

在这里插入图片描述

一句话总结：Output Styles 通过“修改 Claude Code 的 system prompt”，把 Claude Code 变成不同类型的 Agent。

官方定义里强调了两点：

  • Claude Code 的核心能力依然保留，例如：运行本地脚本、读写文件、追踪 TODO。
  • 输出/交互方式会被“风格化”，不局限于 软件工程师助手，也就是说不只是仅开发人员可以使用，其它人也能使用。

为了更好理解，可以把 Output Styles 当作：

  • “长期生效的输出契约”：要求它每次都按某种固定结构输出（标题/表格/清单/风险提示/确认口径）。
  • “默认工作方式的开关”：比如要不要先问问题、要不要先出计划、要不要教育性讲解、要不要把关键步骤留给你做。
  • “身份 + SOP 的最小集合”：它不替代 Skills 的完整流程，但能把 “每次都必须遵守的交互规则”固化下来。

2.2 三种内置风格

Claude Code 自带 3 种风格的 Output Styles：

  • Default（默认）：偏执行、偏高效、偏落地（默认 system prompt）的工程师风格。
  • Explanatory（讲解型）：会在干活过程中插入教育性 “Insights”，适合看懂代码库、理解实现选择、快速熟悉模式。
  • Learning（共学型）：不仅解释，还会让你“参与写几行关键代码”，会在代码里插入 TODO(human) 让你完成，适合带新人、结对编程、训练自己在项目里的手感。

在这里插入图片描述

2.3 如何理解？

这里举一个例子来加深对 Output Styles 的理解。例如：用同一个请求做 A/B 测试最直观，这个时候会对 Claude 说：

“请帮我把一个 POST /orders 接口补上幂等（Idempotency-Key），并告诉我为什么这样设计。”

如果选择不同的Output Styles，会看到如下的差异：

  • Default：倾向直接落地改动（要改哪里、怎么做、怎么验证），解释更少。
  • Explanatory：会在关键选择点插入解释（幂等键存哪里、冲突怎么返回、重试语义）。
  • Learning：会把关键一两处留 TODO(human)（例如“你来补：幂等键表的唯一索引/冲突处理分支”），并引导完成。

如果你“看不出差异”，通常不是你没理解，而是：你给的任务太小/太确定（比如“把变量名改一下”），任何风格都差不多。用这种更“有选择空间”的任务测试最有效。

2.4 易混淆点（统一对照）

下表从作用位置、影响范围、适用场景三个核心维度，对 Output Styles、CLAUDE.md、--append-system-prompt、Subagents 与自定义 Slash Commands 进行统一对照：

能力/机制 作用到哪里 影响范围 典型用途
Output Styles System Prompt（主对话） 主 agent 的整体角色、语气、输出契约 从“工程师助手”切换到产品、运维、写作、法务等身份
CLAUDE.md User Message（system 之后） 项目级约束与背景信息 项目规范、目录结构、流程约定、注意事项
--append-system-prompt System Prompt 当前会话的行为强化 临时试验、一次性强化、对比测试
Subagents（Agents） 子 agent（被调用） 具体任务的模型、工具、权限边界 任务分工、能力隔离、自动化流程
自定义 Slash Commands 触发指令 单次流程或模板化操作 快捷执行固定步骤或提示词

一句话理解以上易混淆的概念点:

  • Output Styles 决定“你在和谁对话”
  • CLAUDE.md 决定“这个项目有哪些约束”
  • Subagents 决定“任务怎么分工、用什么能力做”
  • Slash Commands 决定“什么时候快速跑一套流程”
  • --append-system-prompt 只是临时改一下脑回路

3. Output Styles 的工作原理

官方文档里有几条结论，我们把它当成“规则”记住：

  1. Output styles 直接修改 system prompt ；
  2. 所有 output styles 都会去掉“高效输出”的那部分指令（例如“尽量简洁”） ；
  3. 自定义 output style 默认也会去掉“编码相关指令”（例如“跑测试验证”），除非设置 keep-coding-instructions: true
  4. 风格指令会被追加到 system prompt 末尾，并在对话过程中反复提醒 Claude 遵守

用人话说就是：

如果想要 “简洁 / 固定格式 / 先问再做 / 先列计划 / 必须给检查清单”，都要在 Output Styles 里明确写出来；否则你以为的“默认行为”，可能已经被关掉了。

很多人看完文档还是懵，核心原因是：你以为 Output Style 只改“措辞”，但它可能连“工程化习惯”也一起改掉。

可以这样去理解：

  • keep-coding-instructions: true：更像“换一种表达/协作方式，但仍按工程师方式做事”
    典型表现：会主动建议/运行测试、会按改动范围做验证、会更谨慎处理写入操作。
  • keep-coding-instructions: false（默认）：更像“把它从工程师助手切到别的身份”
    典型表现：可能更偏文档产出/决策建议/模板填写；当我们让它改代码时，它仍能改，但更容易忽略 “跑测试/验证/边界检查/逐步确认” 这类习惯。

一个容易踩坑的场景，例如让 Claude 写了一个 “PRD Writer” 风格（false），同时让它顺手改个接口，它可能就“直接给你一段代码/建议”，但不再默认把验证步骤当成必须项。

解决方式：把 keep-coding-instructions 改 true，或者在风格里明确写：“涉及代码/配置变更时必须给验证清单、必须先确认风险点”。

4. Output Styles 用法

4.1 命令行使用

官方提供了两种方式使用Output Styles。

4.1.1 命令

运行/output-style 打开菜单选择或者直接 /output-style explanatory（举例）：
在这里插入图片描述

另外 /config 菜单里也能进到同一个入口。
在这里插入图片描述

4.1.2 配置文件

切换会保存到项目级别的 .claude/settings.local.json，也可以在不同层级 settings 文件里手动改 outputStyle 字段（比如想给整个项目默认一个风格）。

示例（节选）：

{
  "outputStyle": "explanatory"
}

4.2 自定义 Style

自定义 Output Style 本质是一个 Markdown 文件：

  • frontmatter（可选元数据）
  • 正文（会被追加到 system prompt）

存放位置两种（官方推荐）：

  • 用户级：~/.claude/output-styles
  • 项目级：.claude/output-styles（更适合团队共享，能进 Git）

4.2.1 官方推荐模板

---
name: My Custom Style
description:
  A brief description of what this style does, to be displayed to the user
keep-coding-instructions: false
---

# Custom Style Instructions

[你的风格指令写在这里]

## Specific Behaviors

[具体行为约束写在这里]

frontmatter 字段要点（官方表格）：

  • name：显示名（不写就继承文件名）
  • description：仅用于 /output-style UI 展示
  • keep-coding-instructions：是否保留“编码相关 system prompt 指令”（默认 false）

4.2.2 如何写 Style

写 Output Style 时，建议按下面 5 件事组织（缺了就容易“感觉没变化”或“容易跑偏”）：

  1. 目标：一句话说明它要把对话变成什么（例如“可发群的纪要”“可执行的事故处置清单”）。
  2. 输入澄清规则：先问几个问题？不足时必须先问而不是瞎编？
  3. 输出结构（最关键）：固定小节标题/表格字段/清单项（最好“严格包含”，没有就写“暂无”）。
  4. 行动边界：什么情况必须先征求确认？什么情况禁止执行？要不要提供回滚/风险？
  5. 简洁度/语气：要短句、要表格、要不讲科普、还是要教学式解释？

可以把它理解为：把“你每次都要反复提醒 Claude 的话”，搬进 Output Style 里，让它自动记住。

4.3 案例模板

下面举例三个Output Style案例，这些案例可以放到 .claude/output-styles/。

4.3.1 事故分诊风格

建议配合 MCP使用，incident-triage.md 模板如下：

---
name: Incident Triage
description: 用于线上事故分诊与处置建议（先证据后结论）
keep-coding-instructions: true
---

# Custom Style Instructions

你是“线上事故分诊官”。目标：快速收敛问题、降低影响面、推动可执行动作。
默认保持回答简洁，避免长篇科普。

## Specific Behaviors

- 永远先问清楚：时间范围、影响面、是否可回滚、当前缓解措施。
- 永远先给出“你还缺哪些关键证据”，并给出最小可行的获取方式。
- 输出必须严格包含以下小节（没有也要写“暂无”）：
  1) Incident Summary（现象 & 影响）
  2) Evidence（证据）
  3) Hypotheses（按可能性排序）
  4) Actions（可执行动作清单，标注风险/可逆性）
  5) Rollback & Mitigation（回滚/缓解方案）
  6) Next Check（下一步验证点）
- 涉及写入/破坏性操作时，必须先征求确认，并给出回滚预案。

这里建议 keep-coding-instructions: true，因为事故处理中往往仍需要 Claude 保持“工程化习惯”（验证、检查、谨慎执行）。

4.3.2 PRD 写作风格

prd-writer.md模板如下：

---
name: PRD Writer
description: 用于需求分析与 PRD 产出（结构化、可评审）
keep-coding-instructions: false
---

# Custom Style Instructions

你是资深产品经理 + 技术合作者，负责把需求写成“可评审、可落地”的 PRD。

## Specific Behaviors

- 先问 3~7 个澄清问题（不足就不要直接写 PRD）。
- PRD 必须包含：背景、目标、非目标、用户故事、范围、交互/流程、埋点、验收标准、风险与灰度方案、里程碑。
- 每个验收标准必须可测试、可观察，避免空话。
- 输出尽量短句，表格优先。

4.3.3 会议纪要风格

meeting-notes.md 模板风格如下：

---
name: Meeting Notes
description: 会议纪要与行动项提炼（可直接发群）
keep-coding-instructions: false
---

# Custom Style Instructions

你是会议记录员。目标：把讨论变成对齐材料与行动项。

## Specific Behaviors

- 输出必须包含：
  - 结论（Decisions）
  - 待办（Action Items：Owner / Due / 内容）
  - 风险与未决（Risks & Open Questions）
- 不要复述过程；只保留对齐需要的信息。
- 行动项不超过 10 条，超过就合并/聚类。

5. 文末

通过阅读本文，相信大家已经系统理解了 Claude Code 中 Output Styles 的设计初衷与工程意义：它并不是简单的“回答风格切换”，也不是为了让输出更好看，而是通过 修改 system prompt，在不影响 Claude Code 本地能力的前提下，重新定义 Claude 的角色身份、默认行为与交互契约。

Output Styles 的核心价值在于：把“你希望 AI 如何工作”这件事，从一次次临时提示，固化为长期生效的系统级规则。通过合理设计 Output Style，Claude 可以稳定地扮演事故分诊官、产品经理、技术写作助手或协作型代码导师，在不同场景下遵循固定结构、明确边界，并保持一致的工程习惯。

希望本文能帮助大家正确理解 Output Styles 的工作机制与使用边界，避免将其误用为单纯的表达层配置。也欢迎在实践中结合 CLAUDE.md、Subagents 与 Skills，构建更符合团队协作方式的 Agent 体系。感谢阅读，本文完！

# AI
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

零成本在终端里搭建 AI 编程智能体（Open Interpreter + 智谱免费模型）

作为嵌入式开发者，我一直在寻找一种能的 AI 工具。Claude Code 虽然强大，但需要付费 API 且国内网络不稳定；GitHub Copilot 依赖 IDE，不够灵活。后来我发现了——一个开源的终端 AI Agent，支持多种大模型后端。配合智谱 AI 的免费模型，我实现了，能读写文件、执行 Shell 命令、管理 QEMU 虚拟机，极大提升了内核和驱动学习效率。这篇文章记录完整的搭建过

avatar AI Agent技术社区

如何成为一名 AI Agent 工程师：从入门到精通的完整指南

AI Agent 工程师是专注于设计、开发和部署智能代理（Intelligent Agent）的专业技术人员。AI Agent 是一种能够感知环境、自主决策并执行行动以实现特定目标的软件实体。与传统的 AI 模型（如分类器、生成器）不同，AI Agent 强调在动态环境中的持续交互、规划与学习能力。自动化工作流：构建能够处理复杂、多步骤任务的自动化助手，如数据分析、报告生成、客户服务等。游戏与模拟

avatar AI Agent技术社区
cover

AI Agent 多角色协作总是重复问需求？用单一事实源串起文档、代码和测试

avatar AI Agent技术社区