Impeccable polish 精修实战指南：发布前最后一个质量关卡

Impeccable polish 精修实战指南发布前最后一个质量关卡【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccableImpeccable 的polish是 Refine精修类别下的收尾命令定位是发布前的最终质量检查见 SKILL.md 命令表 与 command-metadata.json 中对 polish 的描述fixing alignment, spacing, consistency, and micro-detail issues before shipping。它接管 critique 留下的优先问题、harden 加固后的成品沿完整用户路径把布局、排版、色彩、交互、状态与代码逐项打磨到一致的质量水准。读完本文你将掌握 polish 的精修原则、漂移分类、证据收集与分诊方法、五维打磨清单、快照关闭流程以及它和 critique、harden、hooks、craft-floor 之间的协作边界。1. 先立规矩精修refine永远不等于换皮redesignpolish 参考文档reference/polish.md开宗明义给出三条铁律任何打磨动作都必须在此框架内进行Polish is refinement, never concealed redesign.精修必须保留现有的视觉世界、内容、行为以及范围之外的一切。如果概念本身错了应当直说并推荐 redesign 或bolder而不是夹带一个替换方案偷偷上线。这与 SKILL.md 的如何设计 完全一致refinement 保留现有身份、行为、文案与范围外的一切redesign 才允许更换视觉世界。检测器结果只是缺陷证据不是质量证明。检测器detector能机械地发现对比度不足、内容溢出、设计系统漂移等问题但干净不代表体验好。真正的判断必须落到渲染后的实际体验与真实交互路径上。不要为打磨而打磨。不要在已经一致的系统里为单一局部例外硬造一套抽象也不要为了让打磨看得见而添加动画。2. 建立系统先认清现状再给漂移分类打磨的第一步不是改代码而是建立判断基准。打开 DESIGN.md仓库根目录即存在此文件与代表性的 token、共享组件、模式和相邻流程如果项目没有正式的视觉系统就采用项目中一致的自有约定。这里隐含了 impeccable 的上下文机制会话开始时应先运行impeccable context加载 PRODUCT.md、DESIGN.md、surface brief 等上下文并遵循其指令见 SKILL.md Setup 段。面对每一个漂移先分类再动手polish 文档给出了四类分类含义修复方向missing token缺失 token系统需要一个可复用的值提升为设计系统 tokenone-off implementation一次性实现已有共享组件或模式可以取代它改用共享组件/模式conceptual mismatch概念错位流程、信息架构或层级与同类产品区域不一致修正概念层级而非局部贴补丁local defect局部缺陷实现本身不完整或不一致补全实现修复原则是在最窄的正确层级修根因fix the cause at the narrowest correct level而不是在同一层级反复打补丁当无法从现有资料推断出系统级原则时应当询问用户而不是擅自决定。这与 craft-floor 的从已确定的提交世界出发而非自己的习惯reference/craft-floor.md互为表里。3. 收集证据亲身体验 读取 critique 快照在动手前必须用产品本身在代表性尺寸上走一遍Web 端覆盖桌面与移动端原生平台ios/android/adaptive则在模拟器、仿真器或真机上按平台参考文档ios.md 的Verifying the build、android.md 的Verifying the build所描述的方式截图。需要确认四件事路径功能是否完整预期质量门槛与可用时间已知约束或刻意未完成的工作用户实际会遇到的状态、内容长度、角色与输入方式。3.1 用 critique-storage 读取既有评审如果之前有过 critique 评审polish应当把它作为输入之一而不是无视它.claude/skills/impeccable/scripts/impeccable critique-storage latest resolved target --json退出码 0返回 JSON包含最新快照的body与精确的snapshot_file标识。必须把snapshot_file保留到本轮结束因为收尾时关闭快照需要它。本地文件目标helper 会把文件当前精确内容指纹SHA-256与 critique 记录时的指纹比对。未改动的已暂存、未暂存或未跟踪内容视为仍为当前任何字节变化、删除或替换为非文件都会关闭它此前识别的 backlog同时保留趋势历史并退出码 2。URL 目标没有本地指纹会一直保持当前直到被显式关闭。退出码 2表示不存在快照或目标已变更。无论哪种情况都要独立执行一轮精修不能依赖旧快照直接改。这套语义在源码中有完整实现见 crates/context/src/critique_storage.rs指纹为sha256:hexL229-L238目标身份为file:解析后的绝对路径或url:origin pathnameL214-L227latest在本地指纹不一致时会先关闭该快照再返回 2L580-L597。快照文件命名形如2026-05-12T18-30-00Z__slug.md同一秒内的并发写入用~NNNN四位定宽后缀防碰撞L509-L525这一行为在测试 close_verb_round_trip_and_ownership 中有完整覆盖。快照体存在.impeccable/critique/目录下由slug对目标路径/URL 派生的稳定标识组织。当快照仍然有效时把其中的P0/P1 优先问题纳入本轮并在最终报告中注明读取了哪个快照。4. 分诊先修功能再修观感把功能缺陷与观感问题分开按以下顺序修复断裂或阻塞的任务、数据丢失、误导性状态、不可达路径——这是 P0优先于一切缺失的 loading、空、错误、成功、禁用、权限状态——状态不全会让用户误判流程、层级、响应式与设计系统漂移——结构性一致性问题视觉与动效不一致——观感层代码与资源清理——死代码、重复值、临时产物。关键约束是不要把一个角落打磨到完美而让其余部分低于同一质量门槛Do not perfect one corner while leaving the rest below the same quality bar。严重度分级P0–P3的定义可参照 reference/critique.md 的 Issue Severity 一节P0 阻止任务完成、P1 造成显著困难、P2 有绕行方案、P3 锦上添花。5. 全路径打磨五个维度逐一过检polish 的核心章节把打磨拆成五个维度每个维度都是一份可直接执行的检查清单。5.1 流程与层级Flow and hierarchy匹配相邻区域的心智模型、术语、披露方式、路由、保存行为以及乐观/悲观更新模式让主任务与当前状态显而易见但不要把所有元素压成同等权重到达路径、过渡、空状态与恢复路径必须互相衔接而不是各自孤立的屏。5.2 布局与排版Layout and type对齐项目的网格与间距尺度同时修正光学对齐与数学对齐视觉重心对齐往往比像素对齐更重要相关内容紧凑成组、不同分组慷慨分隔同角色的排版保持一致测试 measure行长、换行、本地化扩展、缩放与字体加载逐个验证所有支持的视口而不是只修正当前这张截图。5.3 色彩、图像与图标Color, imagery, and icons使用语义化 token让颜色含义跨主题稳定在每个状态下验证文本、控件与焦点对比度保持图标家族、描边/字重、尺寸与光学对齐的连贯防止图片布局偏移layout shift正确的宽高比、响应式图片来源、有意义的 alt 文本。5.4 交互与状态Interaction and state每个控件都要有恰当的默认、hover、focus、active、disabled、loading、error、success 行为保留可见的键盘焦点、逻辑 tab 顺序、标签与平台适配的触控目标动效保持连贯、可中断、性能良好——不要为了让打磨看得见而加动画在产品可能遇到的场景中验证长内容、缺失内容、本地化内容、离线、慢速与权限受限内容。5.5 内容与代码Content and code保持术语、大小写、标点与事实性文案一致修改事实声明前先询问移除调试输出、死代码、未用 import、过时样式与打磨引入的重复系统已拥有该模式时用共享组件替换自定义实现真正可复用的值才提升为 token不要为单一局部例外创建系统抽象。6. 验证与收尾三通道走查 源码 diff 关闭快照6.1 完整路径的三通道走查用鼠标、键盘、触控如适用重新走完整条路径检查布局Web 端覆盖移动、中间与宽屏原生端覆盖手机与平板两种尺寸类别、两个支持方向状态loading、空、错误、成功、禁用、长内容、缺失内容可达性缩放、对比度、焦点、语义、屏幕阅读器可读名称运行时控制台错误、布局偏移、交互延迟、图片加载——Web 端覆盖支持浏览器原生端覆盖支持 OS 版本、运行时警告与掉帧一致性与 DESIGN.md、相邻功能、用户既定范围是否一致。6.2 遵循质量指引与 hooks遵循impeccable context与 hooks 提供的质量指引再运行其他相关 QA 命令。这里有一条明确的边界只有当没有自动检测器在运行时context 才要求手动扫描一次绝不额外增加一次检测器扫描。这与 hooks 的设计吻合reference/hooks.md每条编辑触发 per-edit 层、Stop 事件触发全量深度扫描无自动 hook 的会话会收到一条MANUAL_DETECTOR_REQUIRED指令。此外要记住干净的扫描结果不能替代视觉判断A clean scan does not replace visual judgment。6.3 源码 diff 与交付标准收尾时做一次源码 diff清除意外改动、孤立代码、冗余值与临时产物。只有功能完整、且整条路径一致地达到同一完成度时才能交付。6.4 关闭快照critique-storage close当本轮把从快照接手的所有 Priority Issue 全部清除后关闭该快照.claude/skills/impeccable/scripts/impeccable critique-storage close resolved target snapshot_file returned by latest关闭语义源码见 close_snapshot 实现 与 close verb只关闭本轮实际处理过的那个快照若期间落入了更新的 critique它的 backlog 保持存活未读取任何快照、未保留snapshot_file、或仍有 Priority Issue 未清时不得关闭close会在快照 frontmatter 中写入closed: trueinsert_closed_flag二次关闭是静默 no-op错误目标身份会被拒绝退出码 2这一所有权校验在测试 close_verb_round_trip_and_ownership 中得到验证。7. 与相邻能力的协作边界polish不是孤立的命令它处于一条完整工作流的末端正确使用它需要理解与周围能力的边界critique → polish 的数据链路critique 通过critique-storage write持久化快照记录total_score、max_score、P0/P1 计数与目标指纹见 reference/critique.mdpolish 通过latest --json无缝接管 Priority Issues完成后用close归还。趋势可通过critique-storage trend target 5查看最近 5 次的分数演变。harden → polish 的移交harden 参考文档reference/harden.md明确写道当边缘情况覆盖完毕后移交/impeccable polish做最终打磨——即 polish 站在加固之后的成品上做一致性与细节收尾。craft-floor 的机械底线打磨时的对比度正文与占位文本 ≥4.5:1、大文本 ≥3:1、行长65–75ch、间距、动效与状态检查都已有机械化的检查清单见 reference/craft-floor.mdhook 激活时这些检查由 hook 强制执行打磨时应处理其发现而非重新审计每条规则。bolder / redesign 的分流当问题不是细节不精而是概念本身错了polish 的纪律要求停止精修、明确建议 redesign 或bolder——这保证了 polish 始终服务于既有视觉世界而不是悄悄替换它。结语一次合格的 polish 是克制的它不改文案事实、不重建系统、不为局部例外发明抽象而是把整条用户路径提升到同一质量线。判断依据永远是渲染后的真实体验与真实交互路径检测器与快照只是证据最终交付标准是功能完整 全路径一致 无临时痕迹并以关闭快照、留下干净的源码 diff 作为收尾标志。把 polish 放在 critique、harden 与 hooks 的协作链末端使用时它就是你发布前最后一道、也是最值得信赖的一道质量关卡。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考