impeccable clarify 实操指南：为 AI 生成的界面做一次高质量的 UX 文案改写

导读

本文围绕开源仓库 impeccable 的 /impeccable clarify 指令（clarify.md）展开，系统讲解如何把界面中含糊不清的文案，改写成让用户一眼看懂"发生了什么、什么重要、接下来做什么"的清晰表达。你将掌握一条可复用的审读—分层—逐功能区重写—无障碍与本地化—验证的五段式 UX Writing 工作流，并了解它与 /impeccable polish 的交接关系，可直接应用在任何 AI 辅助产出的 Web 界面、表单、错误页与空状态上。

clarify 是什么：定位与触发方式

/impeccable clarify 是 impeccable 设计技能体系中 Fix（修复）类 指令，定位为"改进 UX 文案、标签与错误消息"。在 SKILL.md 的 Commands 表中可以看到它的完整注册信息：

命令	类别	作用	参考文档
clarify [target]	Fix	Improve UX copy, labels, and error messages	reference/clarify.md

命令元数据（command-metadata.json 中的 clarify 项）给出了它被召唤的判定条件：

"Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing."

换句话说，当用户抱怨"这行字看不懂""错误提示莫名其妙""按钮不知道点了会怎样""说明文字读不下去"时，就应路由到 clarify，其参数提示为 [target]，即支持像 clarify pricing、clarify checkout 这样指向具体界面/文件的目标参数。用户未带参数召唤任何指令时，走 routing.md 的上下文菜单分发；clarify 是需要用户"额外提供背景"的一类任务——在 clarify.md 开头明确写着：Additional context needed: audience knowledge and emotional state（还需要补充的背景：受众知识水平与情绪状态），这提示在正式改写前应优先理解"读者是谁、彼时处于什么心境"。

一句话定义与不可逾越的边界

clarify 的核心任务定义只有一句话，但它同时划出了边界：

Rewrite unclear interface text so users understand what happened, what matters, and what to do next.（改写含糊的界面文本，让用户明白发生了什么、什么重要、接下来该做什么。）

三条红线必须同时守住（详见 clarify.md）：

• Preserve factual meaning：保留事实含义，不得因"顺口"而改变内容真实语义；
• Preserve product terminology：保留产品术语，不得用同义词替换用户已认知的专有名词；
• Preserve brand voice：保留品牌语气基线，只做清晰度修复，不做风格重构。

而在审计/改写阶段，凡是涉及事实主张、法律含义或可能是领域专属的术语的改动，文档要求先向用户提问确认（"Ask before changing…"），而不是自作主张下笔。

第一步：先审计整条交互路径的语言，而不是挑单个字符串

clarify 的首要原则是通读整条交互路径（entire interaction path），而非孤立地看某一句文案。界面状态之间彼此承接，一句在 A 状态正确的文案可能在 B 状态造成歧义。审计时需要逐项排查 clarify.md 列出的问题清单：

• 歧义的名词、动词与动作：例如 "Report" 到底指"报告文件"还是"举报"；
• 内部行话或假设性知识：默认读者懂产品内部缩写、技术黑话；
• 含糊的标签、结果与系统状态："已保存""处理中"这类不说明后果的状态描述；
• 缺失的后果、恢复方式与时机：报错后不说如何补救、何时会恢复；
• 不一致的术语与大小写：同一概念在页面不同位置叫法不一、大小写风格漂移；
• 冗余的标题、引言、辅助说明与确认弹窗：头重脚轻、车轱辘话重复；
• 在真实宽度或翻译后会断裂的文本：硬拼接、超长单词、无法换行/无法被 i18n 处理的句式；
• 忽略情绪基调的措辞：在紧张、风险、成功或紧急场景下用错了语气。

同时要 从产品上下文与周边 UI 推断受众与任务（Infer audience and task from product context and surrounding UI）。判断依据包括：这个界面是面向首次使用的新手还是高频老手？操作风险等级如何？如果上下文不足以判断，就用前面的"附加上下文"提示向用户求证。

第二步：为每个界面状态建立消息层级

审计完成后，逐个状态回答四个问题（clarify.md）：

1. 此刻用户唯一需要的那条事实（the one fact the user needs now）；
2. 接下来可执行的下一步动作（the action available next）；
3. 会改变决策的支撑性上下文（supporting context that changes the decision）；
4. 适合这一刻的语气（the appropriate tone for this moment）。

写作纪律是 "一个想法只说一遍"（Say each idea once）：如果标题已经把状态说清楚了，那么引言要么补充新信息，要么直接删除。冗余的"双重说明"不是保险，而是认知负担。

第三步：按功能分区逐类重写

clarify 不是给一套模板让你套，而是按界面功能的五种形态给出各自的改写准则（clarify.md）。

操作与导航：动词+宾语要说清结果

• 当结果并非不言自明时，用具体的"动词+宾语"，例如把 Submit 改为 Send feedback、把 OK 改为有意义的动作词；
• 标签描述的是将要发生的事，而不是触发它的手势/交互方式（不要写"点击此处"这类描述手势而非结果的文案）；
• 同一概念在整个产品中始终使用相同的名词与动词，禁止为追求文采换词。

破坏性操作（destructive actions）是最敏感的场合，规则最硬：

• 必须同时点名操作对象与后果，例如 "Delete 12 emails permanently"，而不是孤零零的 "Delete"；
• 当恢复是安全的，优先提供撤销（undo），而不是确认弹窗——撤销比确认更能降低用户摩擦；
• 当确认确有必要时，消息与按钮上都要写清楚动作，而不是只用 Yes、No、OK、Submit 这类无信息量的词。按钮应回显动作本身，如 "Delete project" / "Keep project"。

表单：标签常驻、前置校验、错误不指责用户

• 使用常驻标签（persistent labels）：placeholder 只是示例，不是标签的替代品——用户输入后 placeholder 消失，字段含义就没了；
• 格式与资格要求放在提交之前给出，而不是等用户提交后报错再补说明；
• 仅在信息用途不明显时才解释"为什么收集这项数据"；
• 必填/选填的处理必须全产品一致，不要这个表单用 *、那个表单用颜色区分；
• 校验消息要做到两点：指出哪里需要关注 + 给出如何修正，且语气上不得指责用户（不写 "you forgot"、"invalid" 这类归罪式表达）；
• 相关说明要靠近对应输入框，错误要以无障碍可感知的方式播报（如通过 aria-live / role="alert" 等技术让读屏器能宣布状态变化）。

错误与权限：可行动的三段式回答

一条"可行动的"错误消息必须回答 clarify.md 的三个问题：

1. 什么失败了（what failed）；
2. 为什么失败——仅当系统确实知道且讲出来有用时才说；
3. 如何恢复，或还有哪些替代路径（how to recover or what alternative remains）。

两条禁止项：不要把内部错误码当作主消息展示给用户（错误码可放次要位置供支持诊断，但不能充当人话）；不要承诺系统无法确知的原因或解决方式（例如不要写 "The server crashed" 如果系统并不知道）。

同时明确情绪边界：涉及隐私、支付、删除、访问丢失、工作被阻断的场景要严肃对待（Treat privacy, payment, deletion, access loss, and blocked work seriously）——温暖可以，玩笑绝对不行。

加载、空状态与成功状态：诚实、分型、简短

• 加载文案要点名真实操作，并在等待确有意义时给出诚实预期（"Optimizing your video…" 好过 "Please wait"）；有确定性进度就展示确定性进度条，但绝不虚构进度（never invent progress）；
• 空状态要区分五种成因：首次使用（first use）、无搜索结果（no results）、筛选条件下无数据（filters）、权限不足（permissions）、系统失败（failure）——这五种的引导动作完全不同；然后解释当前状态并给出下一步有用动作；
• 成功消息要确认已完成的结果，只有在"后果会改变用户接下来该做什么"时才顺带提一句后续影响；日常性的成功应当极简（例如保存成功的 toast，一句 "Saved" 即可，不必重复整页状态）。

帮助与说明文字：回答隐含问题，而不是复述控件

• Helper text 的职责是回答用户没说出口的隐含问题，而不是把控件标签再念一遍；
• 不常见的细节用**渐进式披露（progressive disclosure）**收纳（"Learn more" 折叠展开）；
• 链接文本脱离上下文必须仍然可读：不要写裸 "click here"，要写 "See the refund policy" 这类自含描述；
• 纯图标控件必须有无障碍名称（accessible name），不能只有视觉形状。

第四步：语气、无障碍与本地化的底层规则

clarify 的长期质量取决于写作层约定（clarify.md）：

• Voice 保持一致，tone 随场景应变：品牌 Voice 是稳定的说话方式，而语气要根据用户当下处境调整（成功时轻快、错误时克制）；
• 使用平实语言，但不把受众真正懂的专业术语"稀释"成大白话；
• 可本地化的硬性工程约束：
  • 写完整可翻译的句子，而不是拼接碎片（不要把 "You have " + count + " messages" 拆成片段让译者猜语序）；
  • 把变量与数字保持结构化，使译者能够自由重排（用带占位符的完整模板，如 You have {count} unread messages.，而非字符串拼装）；
  • 允许文本扩展，不要过早缩写——德语/法语通常比英文长 30% 以上，UI 要留出余量；
  • alt 文本要传达图片承载的信息，纯装饰性图片用空 alt（alt=""）让读屏器跳过；
  • 读屏器名称要与可见标签/结果保持一致，避免视觉文字与无障碍名称对不上；
  • 不得让消息仅靠标点、颜色或图标承载——色盲与纯文本/读屏场景下信息必须仍完整。
• 当术语不一致横跨整个产品时，维护一份简短术语表（terminology glossary）；不要为了文学效果在界面里换词。

第五步：放到上下文里验证

改写完成后必须回到真实流程上下文中检验（clarify.md），逐项测试：

• 不依赖隐藏的产品知识也能读懂（comprehension without hidden product knowledge）——找不熟悉产品的人试读；
• 在错误、空状态与决策点上有可行动性（actionability）——每一步用户都知道下一步做什么；
• 事实准确、术语一致——与产品真实行为逐字核对；
• 在目标宽度与 200% 缩放下可扫读（scanability at target widths and 200% zoom）；
• 长名称、本地化扩展、复数规则与动态值的边界情况——例如多语言下 "1 item(s)" 必须能正确复数化；
• 无障碍名称与状态变化播报——验证读屏器读到的是人话；
• 语气与后果、情绪语境匹配——紧急场景读起来是否冷静克制。

最终交付标准是一句可执行判据："最终文案要短到不能再短——在既不丢失意义、也不丢失恢复路径的前提下"（The final copy is as short as it can be without removing meaning or recovery）。

交接：干净的文案交给 polish 做收尾

clarify 的工作到"语言层面读起来干净"为止。当文案已经通顺无歧义后，应交给 /impeccable polish 做最后一轮质量收尾（When the language reads cleanly, hand off to /impeccable polish for the final pass）。polish.md 侧重的是 shipping 前的整体质量门槛（视觉对比、术语与事实一致性、缺陷清零），clarify 解决"用户看得懂吗"，polish 解决"这版界面能发吗"，两者在标准流水线上顺序衔接，避免任何一环节被跳过。

仓库内相关的落点与阅读路径

本文档以 .cursor/skills/impeccable/reference/clarify.md 为蓝本，该文件在仓库中面向多套 Agent 运行时做了同步镜像：.agent、.claude、.github、plugin/skills/impeccable/reference/ 等目录下的同名 clarify.md 与其内容完全一致（可用 md5 校验验证），而 skill/reference/clarify.md 是带 {{command_prefix}} 模板占位符的源版本，用于渲染各运行时的实际指令前缀。

想要进一步下钻的读者可以沿以下路径继续：

• 指令注册与路由：SKILL.md（Commands 表）与 routing.md；
• 触发词元数据：command-metadata.json 中的 clarify 条目；
• 上游审计入口：UX 问题可能先由 audit.md / critique.md 发现，其"建议命令"清单会把文案类问题映射到 clarify；
• 下游收尾：polish.md。

总体来看，clarify 的价值不在于"帮你把句子改漂亮"，而在于建立一套可审计、可重复、有明确完成标准的文案改写流程：先看清整条路径的歧义，再为每个状态排定消息优先级，然后按操作、表单、错误、状态、帮助五类功能分别套用规则，最后回到真实上下文里验证可读性、可行动性与无障碍表现。这套方法既可以由 Agent 在 /impeccable clarify 触发时严格照做，也可以作为前端工程师与内容设计师日常自查的 check-list 直接使用。