impeccable：给 AI 补上它最缺的那门课

介绍

先说个我自己的感受。

这一年我用 AI 写了不少前端，Claude Code、Gemini、Kimi 换着来，效率是真高，想到啥页面几分钟就出来了。但用久了你会发现一件怪事：相同模型生成的东西，总是差不多长一个样。

Inter 字体，紫到蓝的渐变，卡片里再套一层卡片，彩色背景上压一行灰字，每个标题上面还要摆一个圆角方块的小图标。你换个项目，换个人,甚至换个模型——出来的还是这套。像是所有 AI 都上过同一所培训班，学的还是同一套 SaaS 落地页模板。

impeccable 就是来治这个病的。

它是 Paul Bakaus（pbakaus）做的一个开源项目，一句话概括自己："The missing design vocabulary for agents"——给 AI agent 补上它缺的那套设计词汇。说白了，它不是又一个组件库，也不是又一个 UI 框架，而是一层"设计规矩"，装在你的 AI 编码工具上，让它别一张嘴就是那股 AI 味。

为什么使用

想想 AI 为什么会做成一个样。

因为它们喂的是同一批数据。全世界的 SaaS 模板就那么多，模型学来学去，学到的就是那几个"安全牌"。项目文档里有句话我印象很深，大意是：跳过设计引导，你每次拿到的就是同一小撮破绽——到处都是 Inter，紫蓝渐变，卡片套卡片，彩字上的灰字。这些东西单拎出来都不算错，但凑在一起，就是一眼假的"AI 生成感"。

问题是，你光靠一句"帮我做得好看点"是没用的。这话太虚，AI 接不住。它需要的是确定性的、能被执行的指令，而不是形容词。

impeccable 干的就是这件事：把"做得好看点"这种废话，拆成一条条 AI 能听懂、能落地的命令。polish、audit、distill、typeset……每个词背后都是一套具体的检查项和改法。它还带一个不依赖 API、纯规则跑的检测器，专门揪那些"AI 破绽"，59 条确定性规则，改完 CI 里都能跑。

所以它适合谁？我的判断是：用 AI 写前端、但又受不了那股塑料味的人。 如果你是设计师，它帮你把品味翻译给 AI；如果你像我一样是个独立开发、设计是短板，它更是直接帮你兜底。

安装

环境要求 Node 22.12+，一行命令搞定：

npx impeccable install

在项目根目录跑，它会问你用的是哪个 AI 工具，然后把对应的东西装进去。支持的面很广：Cursor、Claude Code、GitHub Copilot、Gemini CLI、Codex、Grok Build、OpenCode、Pi、Trae 都行。

如果你和我一样主力是 Claude Code，还可以直接走 marketplace 的插件安装，更省事。

装完之后，进到 AI 对话里跑一次初始化：

/impeccable init

这一步很关键，别跳。它会问你这个东西是品牌向（marketing、落地页、作品集）还是产品向（app 界面、后台、工具），然后把这些上下文——受众、品牌调性、声音、你不想要的"反面参考"、配色、字体、组件——写进 PRODUCT.md，需要的话再给你一份 DESIGN.md。

写一次，后面所有命令都读它。这是它比"每次重新描述需求"聪明的地方。

核心

理解 impeccable，抓住三样东西就够了。

一，单一入口。 所有功能都从 /impeccable <命令> <目标> 走。比如：

/impeccable audit the header
/impeccable polish the checkout form

前面是动作，后面是你要它动手的地方。目标是可选的，不写就默认整个当前上下文。

二，上下文持久化。 前面 init 写的那些文件，加上 .impeccable/ 目录下的一堆配置，构成了 AI 的"记忆"。它不会每次都从零猜你的品味，而是有据可依。团队配置放 .impeccable/config.json，你自己机器上的个人偏好放 config.local.json（这个 gitignore 掉），设计规范放 design.json，review 报告落在 .impeccable/critique/*.md。

三，检测器（detector）。 这是我觉得最实在的部分。它不靠调 API，纯规则，能扫目录、扫单个 HTML、甚至扫一个线上 URL，把 AI 破绽给你列出来。在 Claude Code、Copilot、Codex、Cursor、Grok Build 上，装的时候还会顺手配好钩子（hook），你每次改文件它自动跑一遍，问题直接反馈回 agent。等于有个人在你背后盯着，不让那股 AI 味溜上线。

还有个细节值得一提：buildPath 这个设置，让你在comp-first（先出高保真效果图，慢但准）和code-first（直接写代码，快但赌一把）之间选。团队用 init 定一次，个人想改就本地覆盖。

命令详解

一共 23 个命令。别被数量吓到，其实是按"你想干嘛"分好类的。我按用途归了一下，找起来快。

起步与上下文

从零做一个东西

审查与打磨

调性微调（这几个特别顺手）

专项修理

上线前的硬骨头

实时迭代

用得多的命令嫌名字长？可以钉起来：

/impeccable pin audit

钉完 /audit 就能直接用了。我一般会把 audit、polish、critique 这仨钉上。

实战指南

光看命令表没感觉，我说说真实场景里怎么串起来用。

场景一：从零做一个落地页

/impeccable init          # 先说清楚这是品牌向落地页，定好调性
/impeccable craft the hero section   # 让它先规划再做，带迭代
/impeccable critique      # 做完先自我 review 一遍 UX
/impeccable polish        # 最后对齐、检查上线就绪

关键在于别一步到位。先 craft 出来，再 critique 挑毛病，再 polish 收尾。这个节奏，比你一句"做个漂亮的落地页"然后祈祷靠谱得多。

场景二：手里已经有个项目，想改造它

这是我最想细说的一个。因为大多数人不是从零开始，而是手里已经有一坨跑了半年、自己看着都嫌"AI 味"重的东西，想收拾又不知道从哪下手。

我拿自己一个记账工具的后台举例，一步步说这条路怎么走。

第一步，先让它读懂现状，别急着改。

/impeccable document      # 从现有代码反向生成 DESIGN.md
/impeccable extract       # 把已有的组件、token 抽进设计系统

这一步是整条路径的地基。document 让 impeccable 把你现在的设计——用了哪些颜色、字体、间距、组件——反向读成一份 DESIGN.md；extract 再把里面能复用的东西沉淀成设计系统的 token。

为什么非要先做这步？因为项目反复强调一件事：尊重现有设计系统，而不是覆盖它。 你不先告诉它"我现在长这样、哪些是我想留的"，它一动手就是推倒重来，那你改造个啥，等于重做。多少工具是不管三七二十一先给你换一套的？impeccable 至少给了你保留自己东西的机会，但前提是你得先把家底交给它。

第二步，量化问题，看清楚烂在哪。

npx impeccable detect src/        # 纯规则扫一遍，列出所有 AI 破绽

不进 AI 对话，直接命令行跑检测器。它会把那些 Inter 满天飞、彩字压灰字、卡片套卡片的地方一条条列出来。这一步的意义是把"感觉不好看"变成"具体哪几处不对"。有了清单，你才知道改造的工作量有多大，也才有个基准——改完再扫一遍，数字掉下去了，就是实打实的进步。

第三步，深度 review，分 UX 和技术两条线。

/impeccable critique      # UX 层：层级、清晰度、情绪
/impeccable audit         # 技术层：无障碍、性能、响应式

critique 管"好不好用、顺不顺眼"，audit 管"合不合格、有没有硬伤"。两条线分开跑，问题看得更清楚。跑完你手里就有两份报告，落在 .impeccable/critique/ 下，改造清单基本就齐了。

第四步，按清单针对性修理。别一把梭，一个一个来。

/impeccable distill the dashboard   # 后台信息太挤？剥到本质
/impeccable typeset                 # 字体层级乱，先理顺
/impeccable layout the settings     # 设置页间距节奏不对
/impeccable colorize                # 配色太单调，有策略地加色

这一步是改造的主体，也是最考验节奏的地方。impeccable 的哲学就是一个命令干一件事，你想要的效果是一层层叠出来的。先做减法（distill）把冗余砍掉，再修字（typeset）、修布局（layout）、调色（colorize），一步一个脚印。急着一句话喊出个完美结果，反而容易翻车。

第五步，上线前把硬骨头啃了。

/impeccable harden        # 错误处理、国际化、文字溢出、边界
/impeccable adapt         # 适配移动端等不同设备
/impeccable optimize      # 性能
/impeccable polish        # 最后一道，对齐设计系统，检查上线就绪

改造不是"看着好看"就完了。harden 管那些平时想不到的边界情况——文字溢出、空数据、超长内容；adapt 管跨设备；最后 polish 收尾。

第六步，装上防线，别让它退回去。

改完最要命的是什么？是过两个月又慢慢长回那股 AI 味。所以把检测器接进 hook 和 CI：

npx impeccable detect --json .    # 接进 CI，作为 PR 检查

Claude Code、Cursor 这些工具装的时候会顺手配好 hook，你每次改文件它自动扫。等于给改造成果上了把锁。

一句话总结这条路径：读懂现状 → 量化问题 → 分线 review → 针对性修 → 硬化上线 → 锁住成果。 六步里我觉得最容易被跳过、也最不该跳过的，是第一步和第六步——一头一尾。中间的修修补补谁都会想到，但"先让它认识你"和"改完别让它变回去"，才是改造和重做的区别。

场景三：把检测器塞进 CI

这个我觉得是团队协作里最值的用法。不进 AI 对话，纯命令行：

npx impeccable detect src/                    # 扫整个目录
npx impeccable detect index.html              # 扫单个文件
npx impeccable detect https://example.com     # 扫线上页面
npx impeccable detect --json .                # 机器可读，接 CI

有些破绽是历史遗留、暂时改不动的，加白名单：

npx impeccable ignores list                   # 看当前忽略了啥
npx impeccable ignores add-file "src/legacy/**"   # 忽略某些文件
npx impeccable ignores add-value              # 忽略某个具体值（要写原因）

注意 add-value 要求你写原因。这个设计我很喜欢——它逼着你对每一次"网开一面"留个交代，而不是无脑跳过。

场景四：从零做一个完整的多模块项目

这是最接近真实开发的一个场景。一个正经产品不是一个落地页，它有登录、有列表、有详情、有设置、有仪表盘……一堆模块。怎么把 impeccable 揉进"一个模块一个模块往下推"的节奏里，我说说我的走法。

先把全局定死，只做一次。

/impeccable init          # 定产品定位、品牌调性、配色、字体、组件、buildPath

这一步是给整个项目立规矩。它写出来的 PRODUCT.md 和 DESIGN.md，是后面每个模块都要遵守的"宪法"。全局只做一次，别每个模块重来一遍——那样每个模块各长各的，一致性就没了。

然后进入单模块循环。 每个模块都走同一套流程：

# 以「仪表盘」这个模块为例
/impeccable shape the dashboard     # ① 先规划：信息怎么组织、流程怎么走，先不写代码
# ——② 这里停下来，人来审一遍 shape 的产出——
/impeccable craft the dashboard     # ③ 落成代码，带可视化迭代
/impeccable typeset / layout / colorize   # ④ 按需专项调
/impeccable onboard / harden        # ⑤ 补空状态、边界情况
/impeccable critique + audit        # ⑥ 模块级 review，UX 和技术两条线
/impeccable polish                  # ⑦ 收尾，对齐设计系统
/impeccable extract                 # ⑧ 把这个模块产出的可复用组件、token 抽回设计系统

八步里，第①步和第⑧步是灵魂，中间是干活。

第①步 shape 先规划不写码，给了你一个"改思路成本还很低"的窗口——这时候发现信息架构不对，一句话就改了，等代码写完再改就贵了。

第⑧步 extract 是模块间一致性的命门。第一个模块做完，把它产出的按钮、卡片、表单这些沉淀成设计系统的 token 和组件；第二个模块直接复用。这样推到第五个模块，它们还是一家人，而不是五个人各画各的。少了这步，你会发现越往后越乱。

最后全局收一次。

npx impeccable detect --json .    # 全项目扫一遍，接进 CI

模块都拼齐了，整体再扫一遍破绽，接进 CI 和 hook 锁住。

它到底管到哪？——顺便说清楚"能不能审需求"

你这个问题问得很准：它是不是主要负责样式？能不能负责需求的审批和审计？

我得诚实说：impeccable 不负责需求审批，也不该负责。 这不是它的短板，是它的边界。

它叫"design vocabulary for agents"——设计语言。它管的是"怎么把一个需求做成好用好看的界面"，不管"这个需求该不该做、优先级排哪、业务逻辑对不对"。你看它那两个带"审"字的命令：audit 是技术审计（无障碍、性能、响应式），critique 是 UX 审查（层级、清晰度、情绪共鸣）——全是体验和质量层面的，没一个是业务需求层面的。

所以说它"主要负责样式"其实小看它了。它比纯样式广：信息架构、交互流程、UX 文案（clarify）、空状态和引导（onboard）、边界情况（harden）这些"体验"它都管。但再往上一层——需求本身对不对——它不碰。那是产品判断，得你自己或产品经理来定。

一句话划清边界：impeccable 管"怎么把需求做成好界面"，不管"这个需求该不该做"。

那我本身有需求文档（PRD），怎么结合它做设计？

这恰恰是它最顺的用法。PRD 和 impeccable 是上下游关系，不是二选一：PRD 是"要做什么"，impeccable 负责把它翻译成"界面长什么样、体验怎么走"。桥就搭在两个地方：

一，init 阶段喂产品上下文。 把 PRD 里的受众、产品定位、品牌调性这些提炼出来，喂给 init，让它写进 PRODUCT.md。这样后面每个命令都知道"我在给谁做、做的是个什么调性的东西"。

二，shape 阶段喂功能需求。 做每个模块前，把 PRD 里对应章节的功能点贴给它、或让它读，然后跑 shape。它会把"这个模块要实现 A、B、C 功能"翻译成"界面该怎么布局、信息怎么分层、用户走哪条流程"。

# 手里有 PRD 的话，单模块起手式变成这样
# 先把 PRD 里「订单管理」这一节的需求给到 AI，然后：
/impeccable shape the order management page

说白了，PRD 定"做什么和为什么"，impeccable 定"长什么样、怎么用"。前者是你（或产品）的活，需求的审批审计也在这一层由人来把关；后者才是 impeccable 上场的地方。别指望它替你审需求，但它能保证你审过的需求，落地成一个不那么"AI"的好界面。

各司其职，这才是舒服的配合。

最佳实践

用下来，几条我自己踩过或者想明白的：

init 一定要认真填。 后面所有命令的效果，都建立在这一步给的上下文上。你敷衍它，它就敷衍你。填"反面参考"（你不想要的样子）尤其有用，比正面描述好使——告诉 AI"别搞成那样"，往往比"要搞成这样"更准。

小步走，别憋大招。 一个命令干一件事，是 impeccable 的设计哲学。bolder 就是放大，quieter 就是收敛，distill 就是做减法。你想要的最终效果，是靠这些小命令一层层叠出来的，不是一句话喊出来的。

把检测器接进 hook 和 CI，让它自动跑。 人是会偷懒的，尤其赶进度的时候。让机器在每次改动和每次提交时替你把关，比靠自觉可靠得多。这也是它不依赖 API、纯规则的好处——快、稳、不花钱。

document 先行，别让它覆盖你。 接手老项目，先让它读懂现状。尊重现有系统这件事，impeccable 是认真的，你也得配合它。

个人偏好走 config.local.json。 团队共享的配置和你自己机器上的习惯分开放，别把个人设置提交到仓库里污染别人。

说到底，impeccable 帮你解决的不是"AI 不会做设计"，而是"AI 太会做那种烂大街的设计"。它给的不是审美，是把审美翻译成 AI 能执行的语言的那套词汇。

工具再好，也替不了你知道自己想要什么。

参考资料

• 项目主页：impeccable.style
• GitHub 仓库：github.com/pbakaus/impeccable
• 作者：Paul Bakaus（pbakaus）
• 许可证：Apache 2.0