Impeccable shape 命令详解:写代码之前,先用设计简报锁定该做什么

2026-09-04 22:08:49作者：卓艾滢Kingsley

在 AI 驱动的前端开发中,"先动手写代码、再回头修方向"是设计质量流失的主要来源。本文基于 Impeccable 技能中的 shape 命令参考文档(reference/shape.md),完整解析这套"先规划、后实现"的工作流:如何通过受控的发现访谈(Discovery interview)澄清目标、受众与边界,如何借用 new-work 流程解析视觉方向,以及如何产出一份"最小可用但信息完整"的经确认设计简报(Design Brief)——并在确认后立即停止、绝不越界写代码。读完后你可以复现这套流程,理解 shape 与 init、new-work、visualize 等相邻命令的职责切分,并知道每个阶段在仓库源码与测试中的落点。

shape 在 Impeccable 中的定位:计划,而不实现

Impeccable 是一个面向前端界面的设计技能集合,核心目标是让 AI harness 产出更高水准的 UI。其命令体系定义在 SKILL.src.md 的 Commands 表中,shape 被归入 Build 类别:

命令	类别	描述	参考文档
`shape [feature]`	Build	Plan UX/UI before writing code(写代码前规划 UX/UI)	reference/shape.md

命令的元数据描述(command-metadata.json)进一步补全了它的行为契约:

"Plan UX and UI before code. Runs a required multi-round discovery interview, uses visual probes when available, and produces a user-confirmed design brief for implementation."

即 shape 有三条硬性承诺:

运行多轮发现访谈是必需步骤,不是可选礼貌;
在可用时使用结构化视觉探针(visual probes,见后文 new-work 阶段);
产出物是一份经用户确认的设计简报,而不是代码。

shape 的一句话使命(原文):"Discover what should be made and how it should work, then return a confirmed design brief without code."(弄清该做什么、以及它应如何工作,然后返回一份已确认的设计简报,不写任何代码。)

路由规则(SKILL.src.md)明确了它与其它 Build 命令的分工:

"shape owns task discovery, then enters new-work only for visual-world and surface-concept decisions."(shape 拥有任务发现阶段,之后仅为视觉世界与表面概念的决策进入 new-work。)

也就是说:shape 负责"问对问题",而视觉世界(visual world)与构图概念(concept)的选择权归属 new-work.md。这种职责切分是理解后文 Phase 2 边界的前提。

Phase 1:发现访谈(Discovery interview)

shape 的第一阶段有一条铁律:此时不写代码,也不选视觉方向(Do not write code or choose visual direction yet)。这个阶段唯一的任务是把"做什么"和"为谁做"问清楚。

节奏规则(Cadence)

原文对访谈节奏的规定直接决定了 shape 的交互质量,四条规则如下:

优先使用结构化提问工具(structured question tool);不可用时退化为"提问后停下等待"。仓库中 skill/scripts/ 下的 serve-question.mjs 提供了基于本地决策页的提问/等待机制(--start 启动、--wait --key 收集 JSON 答案),即文档所指的"structured question tool"实现载体。
每轮只问 2~3 个相互关联的问题,然后等待回答。默认一轮即可;只有当回答暴露出实质性缺口(material gap)时才追加第二轮。
禁止倾倒问卷:不重复已确认的事实,不把显而易见的事实做成菜单选项。正确做法是"断言你的理解,邀请用户纠正"(Assert the likely reading and invite correction)。
按提示信息量决定轮数:稀疏的提示(sparse prompt)至少需要一轮正式回答;精确的提示(precise prompt)可能只需要一次紧凑确认。

第一轮:目的、受众与结果(purpose, people, and outcome)

第一轮从以下四个问题中挑选最能改变最终结果的 2~3 个发问:

这个界面(surface)或功能是做什么用的?它必须解决什么问题?
具体是谁会到达这里?在什么场景、什么心态下?
他们必须理解或完成的首要事项是什么?成功是什么样子?
这里有什么是邻近产品或通用模板无法声称的独特真实性?

第四个问题是关键差异点:它迫使需求方给出"产品独有真相"(product-specific truth),这正是简报第 2 块 "Outcome and proof" 的原料,也是后续构建中"不可虚构"的事实边界。

第二轮:素材、行为与边界(material, behavior, and boundaries)

第二轮仅在存在实质性未决决策时才运行,候选问题包括:

体验必须承载哪些真实内容、证据、数据与素材?现实的最小/典型/最大范围各是多少?
哪些状态与过渡重要:首次运行、空状态、加载中、错误、成功、权限、溢出、专家使用?
预期的保真度、广度与交互深度是什么:探索性草图、生产级单屏、完整流程,还是更广阔的表面?
什么必须保持不动?即使看起来很精致,什么会让结果"感觉不对"?
哪些平台、框架、性能、无障碍、本地化或交付约束是硬约束?

第二轮之后,原文设有一条明确的越界禁令:绝不询问 CSS 数值或现成的美学赛道(canned aesthetic lanes)——视觉世界与概念选择是 new-work 的专属领地。这条规则防止 shape 访谈从"任务发现"滑向"风格投票",保证第 3 块简报(Selected direction)的内容来自 Phase 2 的方向解析过程,而不是用户在问答中随口点选的形容词。

Phase 2:解析设计方向(Resolve the design direction)

Phase 2 处理"视觉方向该从哪来"。原文的规则很精炼:

新表面、品牌扩展或整体替换的情况:遵循 new-work.md 走完 visual authority(视觉权威判定)、world workshop(世界工坊)与概念选择,但复用 Phase 1 的发现结果,并在 new-work 的契约(contract)、持久化(persistence)与实现(implementation)之前返回 shape。
在既有视觉世界(established world)内部:仅当构图或交互仍有实质性开放问题时,才使用 new-work 的概念过程。

结合 new-work.md 的对应内容,可以补全这条路径的具体形态:

视觉权威四判定(new-work 第 1 节):读取 DESIGN.md、代表性代码、tokens、组件与素材后,把项目归入四种情况之一——Redesign(保留产品真相,替换旧视觉世界)、Established world(继承既有身份,缺失 DESIGN.md 并不抹去代码中已成型的身份)、Incomplete brand(保留已确认资产并共同扩展)、No visual authority(与用户共同创造新世界)。shape 的访谈结果正是这四种判定的输入:第一轮问出的"产品独有真相"决定了哪些承诺必须保留,第二轮问出的"不可触碰项"划定了继承边界。

概念掷骰机制(new-work 第 3 节):当需要在既有世界中创建全新表面时,new-work 要求运行 node <scripts_path>/concept-seed.mjs --scope surface --mode <mode>,由脚本从候选构图中"发牌"三张,避免每次运行都收敛到品类默认构图;决策页由 serve-question.mjs 托管,用户锁定其中一张。concept-seed.mjs 与 serve-question.mjs 均位于 skill/scripts/ 目录,与参考文档中 {{scripts_path}} 占位符指向一致。

关键边界条款:new-work 第 5 节末尾对 shape 专门写了一句合同条款——

"For shape, return the selected direction to shape.md and stop before persistence or implementation."(对 shape,把选定的方向交还给 shape.md,并在持久化或实现之前停止。)

这意味着 shape 借用了 new-work 的方向选择能力(视觉权威、世界工坊、概念掷骰),但 new-work 的后半段动作——把方向契约(direction contract)写入 surface brief、更新 DESIGN.md、调用 visualize 生成 comp——全部不在 shape 的执行范围内。"shape never writes code or a direction contract"(shape 从不写代码,也不写方向契约)是贯穿两篇文档的一致约束。

Phase 3:撰写简报(Write the brief)

Phase 3 的产出是 shape 的唯一交付物。原文的原则是"写最小的有用简报"(the smallest useful brief),并给出七个标准块。完整结构如下:

Job and audience(任务与受众):谁会到达、他们的上下文、需求,以及 visitor mode(访客模式)。四种模式——Persuade(说服转化)、Operate(操作任务)、Read(阅读理解)、Experience(体验作品)——定义于 SKILL.src.md 的 Modes 一节,shape 访谈第一轮的答案直接决定模式归属,并应只持久化在该表面的 brief 中。
Outcome and proof(结果与证据):首要任务/动作、成功标准、真实证据,以及产品特有真相。
Selected direction(选定方向):视觉权威来源、结构/交互论点(thesis)、序列、焦点时刻(focal moment),以及它对实现的后果。
Scope and boundaries(范围与边界):保真度、广度、交互深度、具名目标、保持不动的部分,以及明确的反目标(anti-goals)。
States and ranges(状态与范围):现实的内容/数据范围与关键状态。
Interaction and layout(交互与布局):层级、拓扑、响应式、可供性(affordances)、反馈与过渡——注意原文强调"intent, not CSS"(写意图,不写 CSS),与 Phase 1 的"绝问 CSS 数值"禁令首尾呼应。
Constraints and open decisions(约束与未决决策):平台、交付、无障碍、本地化、可复用组件,以及"构建者不得自行发明"的选择。

长度有明确的伸缩规则:任务已经清楚时,3~5 条要点即可;只有在任务含糊、跨多屏或独立规划(standalone planning)时才展开完整七块结构。同时原文要求"不要复述对话"(Do not restate the conversation)——简报是决策的凝练,不是聊天记录的转录。

对照 new-work 的持久化格式要求,可以理解这份简报与"方向契约"的差异:new-work 要求把方向契约压缩为六块、150 词以内并写入 surface brief(surface-brief.mjs 的 read/write 子命令管理);而 shape 的简报只作为会话内交付物呈现给用户确认,不落盘、不成为后续会话的契约输入。

确认即停止(Confirm and stop)

流程的最后一步是交付纪律:

把简报呈现给用户,接受一次明确确认或一轮修改,然后停止。
停止的含义是终止:不补写代码,不补写方向契约,不进入构建。
当环境中既没有人类应答、也没有结构化应答机制时(例如无人值守运行),shape 必须"把假设明文标注、返回简报、然后停止"——用显式假设代替默认猜测,保证下游流程能识别哪些字段是推断出来的。

源码与测试佐证:边界是如何被执行的

仓库中有多处证据表明 shape 的边界不是文档修辞,而是被测试锁定的行为契约:

行为测试场景 11:scenarios.test.mjs 中定义了 SHAPE_PROMPT = '/impeccable shape a landing page for the project in this workspace',并断言"当不存在视觉世界时,shape 应在实现之前先解析 init.md"。这与 SKILL.src.md 的路由规则一致:缺失 PRODUCT.md 的新表面请求会经 init 路由到 new-work,shape 发现阶段的答案是这条路由的输入。
会话上下文装载:Setup 一节要求每个会话先运行 context.mjs 装载 PRODUCT.md、DESIGN.md 与匹配的 surface brief。从源码结构看,shape 的"断言你的理解,邀请纠正"之所以可行,正因为它启动时已持有这些项目级事实,不必重复询问已确认内容。
结构化提问基础设施:serve-question.mjs 的 --start / --wait / --update 参数与 command-metadata.json 中 shape "uses visual probes when available" 的描述对应,说明"structured question tool"在 Impeccable 中是具体的脚本能力而非抽象要求。