企业官网建设流程全解析

Impeccable 的 clarify 命令详解：把含糊的界面文案改写成用户看得懂的 UX 文本

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

impeccable 是一个面向 AI 编码代理的设计语言技能包，其clarify命令专门解决“界面文案让用户看不懂”的问题：识别含糊的标签、报错与提示，按功能类型（导航、表单、错误、状态、帮助文本）系统性改写，并输出可验证的验收清单。读完本文，你将完整掌握clarify的审计方法、消息层级设定、五类界面文本的改写规则、本地化与无障碍约束，以及它与audit、polish等命令在 impeccable 工作流中的衔接方式。

1. clarify 在 impeccable 命令体系中的定位

impeccable 技能通过一张命令表组织全部能力，clarify被归类在Fix（修复）类别中：

这是 SKILL.md 中 Commands 表对clarify的完整定义。命令的参数提示为[target]，即指定要改写的界面区域（功能、页面或组件）；在 command-metadata.json 中，它的触发描述进一步细化为：当用户提到“文案令人困惑、标签不清晰、错误信息差、说明难以跟随，或想要更好的 UX 写作”时使用。

使用方式遵循 impeccable 的标准 Setup 流程：每个会话先运行一次

.agents/skills/impeccable/scripts/impeccable context

该启动器会加载 PRODUCT.md、DESIGN.md、对应的界面简报以及（如适用）原生平台指引，随后再加载clarify的参考文档执行改写。如果想为clarify建立独立快捷方式，可以用 SKILL.md 中描述的 Pin 机制：

.agents/skills/impeccable/scripts/impeccable pin pin clarify

生成独立的$clarify命令。若用户不带参数调用$impeccable，技能会转入 routing.md 的上下文感知菜单，只推荐不自动执行命令。

值得注意的是，impeccable 各 reference 文档的第一行都会声明该命令所需的“额外上下文”。clarify.md 开头即声明：

Additional context needed: audience knowledge and emotional state.（额外所需上下文：受众的知识水平与情绪状态。）

这意味着执行clarify时，代理必须先弄清“读这些文案的人懂多少、处于什么情绪状态”，再动手改写——这是整份 playbook 的第一性前提。

2. 审计语言：读整条交互路径，而非孤立的字符串

clarify的第一步不是改字，而是审计。文档明确要求“读整条交互路径，而不是孤立的字符串”（Read the entire interaction path, not isolated strings），并逐一识别以下八类语言问题：

• 含糊的名词、动词与动作（ambiguous nouns, verbs, and actions）；
• 内部黑话或默认用户已知的假设知识（internal jargon or assumed knowledge）；
• 含糊的标签、结果描述与系统状态（vague labels, outcomes, and system states）；
• 缺失的后果说明、恢复途径或时间预期（missing consequences, recovery, or timing）；
• 不一致的术语与大小写（inconsistent terminology and capitalization）；
• 冗余的标题、引言、辅助文本与确认提示（redundant headings, intros, helper text, and confirmations）；
• 在真实宽度下会断裂、或翻译后会出问题的文本（text that breaks at realistic widths or in translation）；
• 无视用户所处压力、风险、成功或紧迫情境的语气（tone that ignores stress, risk, success, or urgency）。

完成审计后，代理需要从产品上下文与周边 UI 推断受众与任务。同时有一条明确的边界：在改动事实性声明、法律含义或可能是领域专用术语的词之前，必须先向用户提问。这条规则防止 UX 改写越权改动产品语义——文案润色不能悄悄改变事实。

3. 设定消息层级：每个界面状态只回答四个问题

审计完成后，对每一个界面状态（一个弹窗、一个错误页、一个空列表……）依次决定四件事：

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）。

配套的写作纪律只有一条但极其严格：每个观点只说一次。如果标题已经把状态解释清楚了，引言要么补充新信息，要么直接删掉。这条规则直接对应审计清单中“冗余的标题、引言、辅助文本”这一项，把“删冗余”从感觉变成可执行的判定标准。

4. 按功能类型改写：五类界面文本各自的规则

clarify的核心是把改写规则按 UI 功能切分为五个子域。以下完整继承原文档的每类规则。

4.1 动作与导航（Actions and navigation）

• 当结果不显然时，使用具体的动词 + 宾语；标签应描述“会发生什么”，而不是描述“触发它的手势”（例如描述保存结果，而不是写“点击此处”）。
• 全产品内同一概念保持同一套名词与动词，禁止同义漂移。
• 对破坏性操作，文案必须点名操作对象与后果；在恢复安全的前提下，优先使用undo（撤销）代替确认对话框。
• 确实需要确认时，消息与按钮上都要写明动作本身，而不是用Yes、No、OK、Submit这类无信息量的词。

4.2 表单（Forms）

• 使用持久标签；placeholder 只是示例，不能充当标签。
• 把格式要求与资格限制放在提交之前呈现，而不是让用户提交后才撞墙。
• 只有当“为什么要这个信息”不显然时才解释原因。
• 必填与选填的视觉处理必须全产品一致。
• 校验文案只说哪里需要注意、如何纠正，不指责用户。
• 相关说明紧贴对应字段放置，并通过可访问的方式播报错误（对应无障碍的 live region 播报）。

4.3 错误与权限（Errors and permissions）

一条可执行的错误信息必须回答三个问题：

1. 什么失败了（what failed）；
2. 为什么——在已知且有用的前提下（why, when known and useful）；
3. 如何恢复，或还剩什么替代路径（how to recover or what alternative remains）。

同时有两条禁令：不要把内部错误码作为主消息暴露给用户；不要承诺系统实际上无法知晓的原因或解决方案。对涉及隐私、支付、删除、权限丢失、工作被阻塞的场景要严肃对待——可以有温度，但不可以有玩笑。

4.4 加载、空态与成功状态（Loading, empty, and success states）

• 加载文本要说出真实正在执行的操作，并在等待有意义时给出诚实的预期；能显示确定性进度就显示，永远不要伪造进度。
• 空态要区分四种本质不同的空：首次使用、无搜索结果、被过滤器筛空、权限不足、失败——原文档列出的是 first use, no results, filters, permissions, and failure——并解释状态、提供下一个有用动作。
• 成功态确认已完成的成果，只有当“下一步后果”会改变用户该做什么时才提及其后影响；例行成功应保持简短。

4.5 帮助与指导性文本（Help and instructional text）

• 辅助文本应回答一个隐含的问题，而不是复述控件本身。
• 不常用的细节使用渐进披露（progressive disclosure），不要平铺。
• 链接文本必须脱离上下文也能看懂（因为屏幕阅读器会单独朗读链接）；仅有图标的控件必须有可访问名称。

5. 语气、无障碍与本地化

clarify把语言质量拆成两层：Voice（语气底色）保持一致，tone（语气）随情境调节。用平实语言，但不要抹平受众真正熟悉的术语。原文档给出的六条硬性约束是：

1. 写完整可翻译的消息，而不是靠运行时拼接碎片（concatenated fragments）；
2. 变量与数字保持结构化，让翻译者可以调整语序；
3. 预留扩展空间，不要过早缩写；
4. alt 文本要传达图片的信息，装饰性图片用空 alt；
5. 屏幕阅读器名称与可见标签、结果保持一致；
6. 不要依赖标点、颜色或图标单独承载消息。

最后一条配套建议：当术语不一致跨产品存在时，维护一份简短的术语表；在界面里禁止为了文学效果而变化措辞——界面的语言稳定性优先于修辞。

6. 验证：改写完成的验收清单

改写完不等于结束。clarify的 Verify 章节要求在上下文里通读整条流程，并逐项测试八个维度：

• 不依赖隐藏产品知识即可理解（comprehension without hidden product knowledge）；
• 在错误、空态与决策点上的可执行性（actionability）；
• 事实准确性与术语一致性；
• 在目标宽度与 200% 缩放下的可扫读性（scanability）；
• 长名称、本地化扩展、复数变化与动态值；
• 可访问名称与状态变更的播报；
• 语气与后果及情绪情境相称。

验收的收尾标准是一句话：“最终文案要在不丢失含义或恢复路径的前提下尽可能短”（as short as it can be without removing meaning or recovery）。

7. 与 audit、polish 的上下游衔接

clarify在 impeccable 工作流中不是孤岛，从源码结构看它与评测类、收尾类命令形成了明确的接力关系：

• 上游：audit.md 与 critique 的报告格式都规定，每条发现应给出“Suggested command”，且允许的命令白名单中明确包含$impeccable clarify——即技术/UX 审计在发现文案问题时，标准出口就是clarify。
• 下游：clarify.md 的最后一行规定：当语言读起来干净了，交接给$impeccable polish做最终一遍。polish.md 本身则定义了如何建立系统上下文、按优先级分诊并在整条路径上收尾，是 impeccable “Fix → Refine” 两段式流程的收口。
• 类似地，harden.md（负责错误处理、i18n 与边界情况的工程加固）也以同样的 polish 交接收尾，可以推断 impeccable 把“文案层”（clarify）与“工程层”（harden）视为互补的修复面，二者最终都汇入同一个质量关口。

8. 小结：clarify 的方法论骨架

把 clarify.md 的完整流程压缩成一句话：先读整条路径做语言审计，再为每个状态定四个问题（事实、动作、上下文、语气），然后按五种功能类型套用改写规则，用本地化与无障碍六条约束守住语言质量底线，最后用八项验证清单验收，并交接给 polish。它把“UX 写作”从一种品味问题，变成了一份可执行、可验收、可复用的工程规程——这也是 impeccable 作为“让 AI 代理更懂设计的语言包”在文案维度上的核心贡献。

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable