Output Styles

结论

Output styles 是 CC 独有的"system prompt 主段替换"机制：一个 markdown 文件就能把 Claude Code 从软件工程助手改写成任何角色，keep-coding-instructions 决定是否保留内建编码指令。机制本身没有废弃——废弃的只是独立的 /output-style 命令（v2.1.73 弃用、v2.1.91 移除，入口并入 /config），文件格式、三层目录、插件分发（loadPluginOutputStyles.ts）都健在。Codex 没有等价物：最接近的是 personality 配置——一个只有 None/Friendly/Pragmatic 三档的枚举，不可自定义内容。深层原因 [推断]：Codex 的人格化走"产品内置档位"路线（/personality 命令、个性迁移逻辑），CC 走"用户可编程"路线；对 harness 而言 output style 是单 runtime 能力，跨 runtime 的等价物只能用 AGENTS.md/CLAUDE.md 指令近似。

研究问题

• CC output styles 的机制（system prompt 如何被改）与现状（是否废弃）？
• Codex 有无等价物？替代方案是什么？

各 Agent 设计与实现

Claude Code

机制：替换 system prompt 的身份段 + 追加风格段。 [一手源码] src_2026-03-31/constants/prompts.ts：

• :152-157——非空 style 渲染为 # Output Style: ${name}\n${prompt} 段落注入 system prompt；
• :180——身份句按 style 切换：有 style 时是 "You are an interactive agent that helps users according to your 'Output Style' below..."，无 style 时才是 "...with software engineering tasks"；
• :562-565——keepCodingInstructions === true 或无 style 时保留内建软件工程指令段，否则剔除。

即 output style 不是 append-only：它能摘除 CC 的默认工程指令，这是它与 CLAUDE.md（纯追加上下文）的本质区别。[一手文档] docs/output-styles.md 同样强调 "use CLAUDE.md instead" 的分工，并指出 style 变更需 /clear 或新会话生效（system prompt 只在会话开始读一次，且影响 prompt cache）。

内建四档。 [一手文档+一手源码] Default（即原生 prompt）、Proactive、Explanatory、Learning；后两者源码可见 keepCodingInstructions: true + 教学型 prompt（constants/outputStyles.ts:48-62）。

一个完整的自定义 style（[一手文档] output-styles.md 示例语义 + [一手源码] loader 字段集）：

---
name: diagram-first
description: Lead every explanation with an ASCII diagram
keep-coding-instructions: true   # 仍保留软件工程指令，只改表达方式
---
Before any prose explanation, draw an ASCII diagram of the
structure or flow being discussed, then explain it.

// .claude/settings.local.json — /config 菜单写入的就是这个字段
{ "outputStyle": "diagram-first" }

自定义与作用域。 [一手源码] outputStyles/loadOutputStylesDir.ts:14-30：扫 user ~/.claude/output-styles 与 project .claude/output-styles（project 覆盖 user 同名），managed 目录见文档；frontmatter 仅 name / description / keep-coding-instructions（布尔或字符串均接受，:52-60），文件名兜底为 style 名。插件也可分发（utils/plugins/loadPluginOutputStyles.ts，plugin.json outputStyles 组件位，schemas.ts:507）。

现状与入口。 [一手文档] docs/output-styles.md："The standalone /output-style command was deprecated in v2.1.73 and removed in v2.1.91. Use /config or edit the outputStyle setting directly."——选择经 /config 菜单，落盘 .claude/settings.local.json 的 outputStyle 字段。机制活着，入口收编。

与相邻机制的分界（写 harness 文案时常被混淆）：

• vs CLAUDE.md：CLAUDE.md 是追加型用户上下文，永远不能摘除内建指令；output style 能（keep-coding-instructions 缺省即不保留）；
• vs --append-system-prompt / SDK 的 system prompt 定制（[一手文档] agent-sdk__modifying-system-prompts.md）：那是调用方编程接口，不进配置文件、不入 /config 菜单；
• vs subagent 的 getSystemPrompt：agent 定义携带完整 system prompt（见 subagents 章），output style 只作用于主 agent。
• 源码注释还点明了一个设计决策 [一手源码] prompts.ts:349："outputStyleConfig intentionally NOT moved here — identity framing lives"——身份框定句被刻意保留在主装配路径里，说明 style 注入点是经过位置敏感性考量的（prompt cache 前缀稳定性）。

Codex CLI

无 output styles，等价物是 personality 三档枚举。 [一手源码]

• protocol/src/config_types.rs:293：pub enum Personality { None, Friendly, Pragmatic }——封闭枚举，无自定义 prompt 载体；
• config/src/config_toml.rs:350-351：顶层配置 personality: Option<Personality>（注释 "Optionally specify a personality for the model"）；
• core/src/client_common.rs:32：personality 进入请求侧 Prompt 构造；存在 personality_migration.rs 做档位迁移；
• TUI /personality 命令在内建 slash 枚举中（tui/src/slash_command.rs:67）。

用户级风格定制的实际出口 [推断+一手文档]：AGENTS.md 指令（每轮注入的用户指令，可写"always answer in French"类风格要求）——但它无法移除 Codex 的内建 instructions（protocol/src/prompts/base_instructions/default.md 是基线），等价于 CC 的 keep-coding-instructions: true 模式，做不到 false 模式。

为什么 Codex 不开放 [推断]：personality 存在迁移逻辑（personality_migration.rs）说明档位语义由官方维护、随版本演进——开放自由文本会破坏这种可迁移性；且 Codex 的统一可编程载体已经压在 skills 上（interface 元数据连 default_prompt 都有），再开一个 prompt 替换面与其"配置层叠 + requirements 管控"的企业治理模型冲突。这与 CC "一切皆 markdown 文件" 的开放路线是路线级分歧，不是功能滞后。

差异矩阵

最小复现

# CC：自定义 style 并验证身份段切换
mkdir -p .claude/output-styles && cat > .claude/output-styles/poet.md <<'EOF'
---
description: answers as a poet
---
Respond to every request as a short poem.
EOF
claude --dump-system-prompt   # 设置 outputStyle:"poet" 后应出现 "# Output Style: poet" 段，
                              # 且身份句变为 according-to-output-style 版（prompts.ts:156,180；未在本机重测）

# Codex：确认只有三档
codex   # /personality → 仅 none/friendly/pragmatic 可选（config_types.rs:293）

Harness 接入建议（Yoda 实践）

1. 按单 runtime 能力建模：output style 不要进 Yoda 的跨 runtime 公共资产模型；在 claude runtime 的 surface spec 里加 outputStyleDirs: ['.claude/output-styles'] 即可，codex 侧映射为 config.toml personality 只读展示。
2. 检测与校验：扫 user/project 两层目录 + settings 的 outputStyle 值是否指向存在的 style（典型故障：style 文件被删但 settings 残留）；frontmatter 校验只需三字段，重点提示 keep-coding-instructions 缺省为"不保留"——用户最常见的误用是写了纯风格 style 却丢了编码能力。
3. 变更提示：harness 修改 outputStyle 后要提醒"需要新会话/clear 才生效，且会打断 prompt cache"（[一手文档] output-styles.md + prompt-caching.md）——否则用户会以为没生效。
4. 跨 runtime 近似：用户想要"两个 runtime 同一风格"时，引导写进 AGENTS.md/CLAUDE.md 共同维护的风格段，并明示 Codex 侧无法摘除内建指令的差异。

失效条件

• CC 把 output styles 整体并入 skills/agents 体系（出现迁移公告或 loadOutputStylesDir 被移除）
• Codex Personality 枚举扩展或改为自由文本（config_types.rs:293 变更即矩阵过期）
• CC outputStyle 落盘位置变更（当前 .claude/settings.local.json）
• keep-coding-instructions 语义或缺省值变化

参考资料

• CC 源码：src_2026-03-31/constants/prompts.ts:152-157,180,562-565、constants/outputStyles.ts、outputStyles/loadOutputStylesDir.ts、utils/plugins/loadPluginOutputStyles.ts
• Codex 源码：codex/codex-rs/protocol/src/config_types.rs:293、config/src/config_toml.rs:350、core/src/client_common.rs:32、core/src/personality_migration.rs
• 文档：claude-code-docs/docs/output-styles.md（含 /output-style 弃用时间线）、prompt-caching.md