Claude Code 系统提示解读：AskUserQuestion 选项的 preview 预览字段与并排对比布局-育师

文档
提示工程
人工智能

【免费下载链接】claude-code-system-prompts

All parts of Claude Code's system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.

项目地址：https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts

点击查看免费下载

本篇技术指南聚焦于 Claude Code 系统提示中system-prompt-option-previewer.md所定义的 Option Previewer 行为——即AskUserQuestion工具选项上的可选preview字段。文章将说明该字段的适用场景（ASCII 线框图、代码片段、图表变体、配置示例）、渲染与布局规则（等宽 Markdown 预览框、左列表右预览的并排 UI）、以及使用边界（禁止用于简单偏好问题、仅支持单选），并辅以仓库中同主题的 HTML 变体提示与 AskUserQuestion 系列提示作为实现依据。

背景：preview 字段在 AskUserQuestion 工具中的定位

Claude Code 通过AskUserQuestion工具在用户面临真正需要用户决策的节点时提问。该工具的基础描述（见 tool-description-askuserquestion.md）规定了使用门槛：仅在「确实需要用户拍板、且无法从请求、代码或合理默认值中自行解决」的决策点使用；用户永远可以通过 "Other" 选项输入自定义文本；若你推荐某一选项，应将其放在首位并在标签末尾追加 "(Recommended)"。

在此基础上，Option Previewer（即 system-prompt-option-previewer.md）补充了一条关键能力：每个选项可以附带一个可选的preview字段，用于把「需要用户肉眼对比的具体产物」直接呈现给用户。它解决的是纯文字选项（label + description）难以表达视觉差异的问题——例如两个 UI 方案、三段不同的实现代码，仅靠文字描述很难让用户高效决策。

仓库 README.md 将本文件收录为 System Prompt 类别下的独立条目，注明约 151 tokens，属于主系统提示中条件注入的组成部分。

什么时候应该使用 preview：四类典型内容

根据 system-prompt-option-previewer.md 的明确列举，当选项呈现的是**需要用户视觉对比的具体产物（concrete artifacts）**时，应使用preview字段。原提示给出四类推荐用途：

内容类型	说明
UI 布局或组件的 ASCII 线框图	用字符画（ASCII mockup）勾勒界面布局、组件结构，让用户在提问前直观看到两种布局长什么样
展示不同实现的代码片段	同一需求的不同实现方案，直接把代码片段放进预览，用户可逐行对比差异
图表变体	例如不同的图表示例、示意图方案，供用户挑选方向
配置示例	不同配置参数的完整示例，用户可直接比对配置差异后拍板

这四类内容的共同点是：信息高度视觉化、难以用一行标签概括、且用户需要「看」而不是「听」才能决策。这正是 preview 字段存在的意义。

仓库中还提供了对应的 HTML 变体说明 tool-description-askuserquestion-preview-field.md，其适用场景清单与之呼应（HTML mockups of UI layouts or components、Formatted code snippets showing different implementations、Visual comparisons or diagrams），可视为同一预览能力在「终端侧（Markdown 等宽框）」与「宿主侧（HTML fragment）」的两种渲染形态。

渲染与布局规则：等宽 Markdown 预览框 + 并排布局

关于 preview 内容如何展示，system-prompt-option-previewer.md 给出两条明确的渲染契约：

预览内容以 Markdown 形式渲染在等宽字体（monospace）盒子中。这意味着预览适合呈现对排版有要求的字符画、代码、配置，多行文本与换行（newlines）均被支持——即预览内容不是一行摘要，而是可以承载完整的多行产物。
布局联动：当任意一个选项带有 preview 时，UI 自动从普通提问布局切换为并排（side-by-side）布局——左侧是垂直排列的选项列表，右侧是对应选项的预览区。用户上下切换选项，右侧预览随之更新，形成「列表 + 详情」的对比体验。

值得强调的是，并排布局是全局行为而非逐项行为：只要有一个选项带 preview，整个问题就会进入并排模式。因此在设计问题时，要么所有需要对比的选项都带上同规格的预览，要么都不要带，避免布局与信息量不一致造成误导。

使用边界：两条硬约束

原提示对 preview 的使用边界约束非常明确，违反会直接造成体验退化：

禁止用于简单偏好问题：当选项的标签（label）和描述（description）已经足以表达含义时，不要使用 preview。例如「你喜欢深色还是浅色主题」这类偏好问题，纯文字足以决策，强行加预览只会放大界面、增加认知负担。仓库中 skill-init-claude-md-and-skill-setup-new-version.md 第 104 行还给出了一个反例用法：在 /init 流程中询问 "Does this look right?" 时明确注明Don't use thepreviewfield——因为提案内容已经显示在滚动记录中，用户不需要在提问框里再看一遍，这印证了「预览只服务于需要视觉对比的产物」这一原则。
仅支持单选（single-select）：preview 只对单选问题生效，不支持 multiSelect（多选）。原因是多选场景下用户需要同时勾选多个选项，并排预览的「当前选中项」语义无法与之兼容。设计多选问题时不要携带 preview 字段。

此外，结合同族的校验规则，选项数量本身也有限制：系统提示 system-reminder-askuserquestion-minimum-options-validation.md 说明，少于 2 个选项的问题会被拒绝且不显示——单个选项的问题不存在决策可言，也不允许通过编造第二个填充选项来绕过。因此带 preview 的问题同样应保证至少有 2 个真实、标签互异的选项，并且每个选项都应当是用户真正需要对比的候选方案。

与 AskUserQuestion 决策体系的协同

preview 字段并不是孤立的功能，它嵌套在 AskUserQuestion 一整套「何时问、怎么问」的决策体系中：

只在答案会改变下一步行动时才提问：tool-description-askuserquestion-decision-guidance.md 强调，如果存在常规默认值或可在代码库中自行核实的事实，就直接选择显然的选项、在回复中说明并继续，而不是提问。preview 只是「提问时」的增强手段，不能反过来降低提问门槛。
问题组织与字段设计：tool-description-askuserquestion-extended-host-guidance.md 规定扩展宿主下的提问顺序（最重要的放最前）、kind字段（普通选择题可省略，text为开放式文本框，number配合min/max表达数量）、多选默认开启（除非选项互斥）、可选的title/description辅助行。preview 字段正是在这样的结构化选项模型之上叠加的展示层。
推荐选项的优先级：tool-description-askuserquestion.md 要求推荐项置顶并标注 "(Recommended)"——当该推荐项同时携带 preview 时，用户既能一眼看到推荐结论，又能通过右侧预览直观理解推荐方案长什么样。

从源码结构看（这些提示均从 Claude Code npm 包编译产物中按版本提取，见 README.md 的 Extraction 说明），preview 属于选项对象上的一个可选字段，由宿主端负责渲染；本仓库记录了其行为契约，供使用 AskUserQuestion 的 Agent 与宿主实现共同参考。

小结

Option Previewer 是 Claude Code 提问体系中的一个精巧的展示层：在「确需提问」的前提下，把需要视觉对比的具体产物通过preview字段以等宽 Markdown 框呈现在并排布局中，让用户在 30 秒内完成本可能需要一整段描述才能完成的方案对比。使用时请牢记三条要点——只用于视觉化产物、不用于简单偏好问题、仅限单选；并结合 AskUserQuestion 的决策纪律（只在答案改变行动时提问、推荐项置顶标注），才能让预览能力真正提升决策效率而非徒增界面噪音。