# Claude Code 输出风格

> Claude Code output styles 的内置风格、自定义 output-styles、keep-coding-instructions、插件分发和 prompt caching 影响。

URL: https://docs.passion8.cc/docs/claude-code/output-styles
Language: zh-CN
Publisher: Passion8

Output style 改变 Claude Code 的回答方式。它修改 system prompt,用于固定角色、语气、输出格式或教学方式。项目规则、代码约定和长期上下文仍应该放在 [记忆与规则](https://docs.passion8.cc/docs/claude-code/memory),不是放进 output style。




一句话判断:如果你每轮都在重复“用某种格式回答”,用 output style。如果你在告诉 Claude 这个仓库怎么构建、怎么测试、哪些目录不能碰,用 `CLAUDE.md` 或 rules。




## 内置风格

| 风格 | 行为 | 适合 |
| --- | --- | --- |
| Default | 默认软件工程 agent 行为 | 大多数编码任务 |
| Proactive | 更主动执行,少问常规决策 | 明确要自动推进的任务 |
| Explanatory | 在完成任务时穿插解释和洞察 | 学习代码库、带新人 |
| Learning | 协作学习,会留下 `TODO(human)` 让人参与 | 教学和练习 |

Proactive 不是权限模式。它会更主动,但工具执行仍受 permissions 约束。

## 切换方式

推荐用 `/config`:

```text
/config
```

然后选择 Output style。选择结果通常写入 `.claude/settings.local.json`:

```json title=".claude/settings.local.json"
{
  "outputStyle": "Explanatory"
}
```

`outputStyle` 会影响 system prompt,当前会话中途改了不立即替换已经加载的系统提示。用 `/clear` 或新开会话后生效。




旧的 `/output-style` 命令已经被官方废弃并移除。现在用 `/config` 或直接改 `outputStyle` 设置。




## 自定义 output style

自定义风格是一个 Markdown 文件。文件名默认就是风格名,也可以用 frontmatter 的 `name` 覆盖。

| 作用域 | 位置 |
| --- | --- |
| User | `~/.claude/output-styles/` |
| Project | `.claude/output-styles/` |
| Managed | 管理员下发目录中的 `.claude/output-styles/` |

示例:

```markdown title=".claude/output-styles/diagrams-first.md"
---
name: Diagrams first
description: 解释代码时先给 Mermaid 图
keep-coding-instructions: true
---

解释代码、架构或数据流时,先给一个 Mermaid 图,再用短段落说明。
图保持在 15 个节点以内。
```

如果只是改变表达方式,但仍然希望 Claude 按软件工程 agent 行为做事,设置 `keep-coding-instructions: true`。如果你要把 Claude 变成写作助手、数据分析助手或非编码角色,可以不保留。

## Frontmatter

| 字段 | 作用 |
| --- | --- |
| `name` | 显示名称,省略时使用文件名 |
| `description` | `/config` picker 里的说明 |
| `keep-coding-instructions` | 是否保留 Claude Code 默认编码指令 |
| `force-for-plugin` | 插件分发时强制启用该 style |

插件也可以在 `output-styles/` 目录里分发风格。启用插件后,用户可以在 `/config` 中选择。

## 和其他机制的边界

| 机制 | 改什么 | 典型用途 |
| --- | --- | --- |
| Output styles | system prompt | 固定角色、语气、默认输出格式 |
| `CLAUDE.md` | 用户消息层上下文 | 项目规则、架构、命令 |
| `--append-system-prompt` | 本次启动追加系统提示 | 一次性脚本或 CI |
| 子代理 | 独立 agent 的系统提示、模型、工具 | 专项任务隔离 |
| Skills | 相关时加载的任务说明 | 可复用工作流 |

## 成本和缓存

| 动作 | 对 5m / 1h 缓存的影响 |
| --- | --- |
| 切换 `outputStyle` 后继续当前会话 | 已加载 system prompt 通常不立刻变化 |
| `/clear` 或新会话后应用新 style | system prompt 改变,下一轮通常全量 miss |
| 使用 Explanatory / Learning | 输出更长,output token 增加 |
| 自定义 style 内容很长 | input token 增加,首轮写缓存更贵 |
| 频繁切 style | cache key 和系统提示反复变化,不利于命中 |

建议按任务开始前确定 output style。中途为了“换口吻”频繁切换,通常不划算。

## Passion8 使用建议

| 场景 | 建议 |
| --- | --- |
| 日常写代码 | Default |
| 希望 Claude 少问多做 | Proactive + 明确 permissions |
| 学习大项目 | Explanatory |
| 教团队成员 | Learning |
| 固定交付格式 | 自定义 style,尽量短 |

接入 Passion8 不改变 output style 机制。模型可用性、计费和缓存表现仍以当前 Claude Code 请求和 Passion8 网关行为为准。

## 官方参考

- [Output styles](https://code.claude.com/docs/en/output-styles.md)
- [Settings](https://code.claude.com/docs/en/settings.md)
- [Prompt caching](https://code.claude.com/docs/en/prompt-caching.md)
- [Plugins](https://code.claude.com/docs/en/plugins.md)