1. 从impeccable说起一个被低估的前端设计约束工具第一次看到impeccable这个词是在一个前端项目的PRODUCT.md文件里。当时团队正在用 AI coding agents 做页面重构生成出来的代码功能上没毛病但视觉上总差那么一口气——间距忽大忽小、颜色搭配说不上丑但就是不对劲、组件之间的对齐关系全靠运气。后来有人提议在项目根目录放一个PRODUCT.md把设计规范、品牌调性、组件约束全部写清楚再配合一个叫 impeccable 的 CLI 工具做校验整个流程才算是真正跑通了。impeccable 本质上是一个前端设计质量约束工具它通过 CLI 的方式介入开发流程读取项目中的PRODUCT.md配置文件对 AI coding agents 生成的前端代码进行设计层面的检查和修正。它解决的核心问题是当 AI 帮你写代码时功能逻辑可以靠测试保证但设计一致性、视觉规范、交互细节这些软约束往往被忽略而 impeccable 就是把这些软约束变成硬性检查项。这个工具适合谁用如果你正在用 codex cli、zcode cli、minimax cli 这类 AI 编程助手做前端开发或者团队里有多人协作、需要统一设计语言再或者你单纯想让 AI 生成的页面看起来不那么AI 味那 impeccable 值得花时间研究一下。它不复杂但用好了能省掉大量返工和设计走查的时间。2. 核心设计思路为什么是 PRODUCT.md CLI 的组合2.1 设计约束为什么需要独立文件来承载大部分前端项目把设计规范散落在三个地方设计稿Figma/Sketch、代码里的 CSS 变量、以及口口相传的我们一般用 8px 间距。这三者之间没有强绑定关系AI coding agents 在生成代码时既读不到设计稿也未必会遵守 CSS 变量更不可能知道口口相传的规则。PRODUCT.md的设计思路很直接把设计规范写成 AI 能读懂的 Markdown 文件放在项目根目录作为 AI 生成代码时的上下文输入。这个文件里通常包含品牌色板主色、辅助色、语义色成功/警告/错误/信息的具体色值和使用场景间距系统基础间距单位通常是 4px 或 8px以及各层级间距的倍数关系字体层级标题、正文、辅助文字的字号、字重、行高组合组件规范按钮、输入框、卡片等核心组件的尺寸、圆角、阴影、状态样式布局规则栅格系统、断点设置、容器最大宽度交互约束过渡动画时长、缓动函数、悬停/聚焦/禁用状态的视觉反馈注意PRODUCT.md不是设计文档的替代品而是设计文档的可执行摘要。它不需要面面俱到但必须覆盖 AI 生成代码时最容易出错的那些点。2.2 CLI 介入的时机与价值impeccable 以 CLI 形式存在意味着它可以嵌入到任何开发流程中。常见的介入时机有三个AI 生成代码后立即校验codex cli 或 zcode cli 生成完组件代码马上跑一遍impeccable check把设计违规项列出来提交前钩子在 git pre-commit 阶段运行防止不合规的代码进入仓库CI 流水线在构建阶段做全量检查生成设计质量报告为什么不做成 IDE 插件或者 Web 服务因为 CLI 的组合性最强。你可以把它和 codex cli 的/compact、/model、/resume这些命令串起来用也可以写进 shell 脚本里批量处理多个项目。CLI 不挑环境不依赖特定编辑器对 AI coding agents 的工作流侵入性最小。2.3 与 AI coding agents 的协作模式impeccable 和 AI coding agents 的关系不是替代而是互补。AI 负责生成impeccable 负责约束。具体协作模式有两种模式一先约束后生成。在调用 codex cli 生成代码之前先把PRODUCT.md的内容作为 prompt 的一部分传进去让 AI 在生成时就遵守规范。这种方式对 AI 的理解能力要求较高适合PRODUCT.md写得足够清晰的情况。模式二先生成后校验。让 AI 自由生成然后用 impeccable 做检查把违规项反馈给 AI 让它修正。这种方式更稳妥因为 AI 对具体违规项的理解比抽象规范更准确。实际操作中我通常两种模式混用核心组件用模式一页面级布局用模式二。3. 环境准备与安装避开 node 安装 codex cli 很慢的坑3.1 基础环境要求impeccable 本身是一个 Node.js 工具安装前需要确认环境node -v # 建议 18.x 或 20.x LTS npm -v # 建议 9.x 以上如果你还没装 Node直接去官网下载 LTS 版本不要用系统包管理器装版本太旧。Windows 用户建议用 nvm-windows 管理版本macOS/Linux 用 nvm 或 fnm。3.2 安装 impeccablenpm install -g impeccable-cli # 或者用 npx 直接运行不全局安装 npx impeccable-cli init安装完成后验证impeccable --version impeccable --help如果提示命令找不到检查 npm 全局 bin 目录是否在 PATH 里。npm config get prefix可以看到全局安装路径。3.3 关于 node 安装 codex cli 很慢的解决方案很多人在安装 codex cli 时遇到下载慢的问题这通常是因为 npm 默认源在国外。解决办法是切换镜像源npm config set registry https://registry.npmmirror.com # 安装完 codex cli 后可以切回官方源 npm config set registry https://registry.npmjs.org如果还是慢可以试试用pnpm或yarn替代 npm它们的缓存机制更好。另外安装 codex cli 时如果卡在某个特定包上可以用--verbose看具体卡在哪一步有时候是某个依赖包的 postinstall 脚本在下载二进制文件。实操心得我习惯在项目里用.npmrc文件固定镜像源而不是改全局配置。这样不同项目可以用不同的源互不影响。.npmrc内容就一行registryhttps://registry.npmmirror.com。3.4 初始化项目配置在项目根目录运行impeccable init这个命令会做三件事创建PRODUCT.md模板文件、生成.impeccablerc配置文件、在package.json里添加impeccable相关的 scripts。如果你已经有PRODUCT.md它会提示你是否覆盖。.impeccablerc的默认内容大概长这样{ productFile: PRODUCT.md, ignore: [node_modules/**, dist/**, *.test.*], rules: { spacing: error, color: error, typography: warn, component: warn }, output: console }rules里的error和warn决定了检查不通过时的行为。error会导致命令返回非零退出码适合 CI 环境warn只提示不阻断适合本地开发。4. PRODUCT.md 怎么写从零搭建一份可执行的设计约束4.1 文件结构设计一份好的PRODUCT.md应该像一份给 AI 看的设计规范而不是给人看的设计文档。区别在于给人看的文档可以配图、可以模糊描述给 AI 看的必须精确、可量化、无歧义。我常用的结构是这样的# Product Design Spec ## Brand Colors - Primary: #2563EB (buttons, links, active states) - Secondary: #7C3AED (accents, highlights) - Success: #16A34A - Warning: #D97706 - Error: #DC2626 - Neutral: #6B7280 (secondary text, borders) ## Spacing Scale Base unit: 4px - xs: 4px - sm: 8px - md: 16px - lg: 24px - xl: 32px - 2xl: 48px ## Typography - H1: 32px / 1.25 / 700 - H2: 24px / 1.3 / 600 - H3: 20px / 1.4 / 600 - Body: 16px / 1.5 / 400 - Small: 14px / 1.5 / 400 - Caption: 12px / 1.4 / 400 ## Components ### Button - Height: 40px (default), 32px (small), 48px (large) - Padding: 0 16px - Border radius: 6px - Font weight: 500 ### Input - Height: 40px - Padding: 0 12px - Border: 1px solid #D1D5DB - Border radius: 6px - Focus: border-color #2563EB, box-shadow 0 0 0 3px rgba(37,99,235,0.1) ## Layout - Container max-width: 1200px - Grid: 12 columns, 24px gutter - Breakpoints: 640px, 768px, 1024px, 1280px ## Motion - Duration: 150ms (micro), 250ms (standard), 400ms (complex) - Easing: cubic-bezier(0.4, 0, 0.2, 1)4.2 关键细节让 AI 能读懂写PRODUCT.md有几个容易踩的坑坑一色值只写 hex不写用途。AI 看到#2563EB不知道什么时候该用。必须标注用于按钮、链接、激活状态。坑二间距只写数值不写场景。16px是卡片内边距还是卡片间距要写清楚卡片内边距用 md卡片之间用 lg。坑三组件规范不写状态。按钮的 hover、active、disabled 状态分别什么样输入框的 focus、error 状态呢这些不写AI 就会自己发挥。坑四用模糊词汇。适当、大概、差不多这类词对 AI 来说等于没说。全部换成具体数值。提示PRODUCT.md写完后可以拿一段 AI 生成的代码做测试看 impeccable 报出来的违规项是否符合预期。如果报了一堆你根本没在意的细节说明规范写得太细了如果什么都没报但页面明显不对说明规范漏了关键项。4.3 与现有设计系统的对接如果团队已经有设计系统比如基于 Tailwind 或 Ant DesignPRODUCT.md不需要从零写而是做映射## Design System Mapping - This project uses Tailwind CSS - Primary color maps to blue-600 - Spacing scale maps to Tailwinds default scale (4px base) - Border radius maps to rounded-md (6px) - Font family: Inter, system-ui, sans-serif这样 AI 生成代码时会优先用 Tailwind 的类名而不是硬编码样式值。impeccable 检查时也会把 Tailwind 类名解析成实际值再做比对。5. 实操流程从 AI 生成到 impeccable 校验的完整链路5.1 典型工作流演示假设我要用 codex cli 生成一个用户卡片组件完整流程如下第一步准备 prompt。把PRODUCT.md的核心内容附在 prompt 里codex cli generate --prompt 生成一个用户卡片组件包含头像、姓名、职位、关注按钮。参考 PRODUCT.md 中的设计规范。 --context PRODUCT.md第二步生成代码。codex cli 会输出组件代码通常是 React/Vue/Svelte 组件加样式。第三步运行 impeccable 检查。impeccable check src/components/UserCard.tsx输出可能是这样的src/components/UserCard.tsx ✗ Line 12: spacing value 20px not in scale (use 16px or 24px) ✗ Line 18: color #3B82F6 not in brand palette (did you mean #2563EB?) ⚠ Line 25: border-radius 8px differs from component spec (expected 6px) ⚠ Line 32: font-weight 600 used for body text (expected 400)第四步修正。把违规项反馈给 AIcodex cli fix --file src/components/UserCard.tsx --issues $(impeccable check src/components/UserCard.tsx --format json)或者手动改因为通常违规项不多。第五步再次校验。直到impeccable check通过。5.2 批量处理与 CI 集成单个文件检查只是开始真正省时间的是批量处理# 检查整个 src 目录 impeccable check src/ # 只检查有改动的文件配合 git impeccable check $(git diff --name-only --cached | grep -E \.(tsx|jsx|vue|svelte|css)$) # 生成 JSON 报告 impeccable check src/ --format json design-report.jsonCI 集成以 GitHub Actions 为例name: Design Check on: [pull_request] jobs: impeccable: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install -g impeccable-cli - run: impeccable check src/ --format json - run: impeccable report --input design-report.json --output comment.mdimpeccable report会生成一份人类可读的报告可以直接贴到 PR 评论里。5.3 参数配置与规则调优.impeccablerc里的规则可以按项目需求调整。比如{ rules: { spacing: { level: error, tolerance: 0 }, color: { level: error, allowNearMiss: true }, typography: { level: warn, checkLineHeight: false }, component: { level: warn, checkStates: true } } }tolerance控制间距的容差设为 0 表示必须严格匹配设为 2 表示允许 2px 以内的偏差。allowNearMiss允许颜色有轻微偏差比如#2563EB和#2564EC视为相同。checkLineHeight关掉行高检查可以避免一些误报。实操心得新项目建议先把所有规则设为warn跑一段时间看看误报率。误报太多就调规则误报少再逐步升级为error。一上来就全error会导致开发体验很差大家会想办法绕过检查。6. 常见问题与排查技巧实录6.1 安装与配置类问题问题impeccable命令找不到。检查 npm 全局 bin 目录是否在 PATH 中。npm config get prefix拿到路径然后确认该路径下的bin目录Windows 是根目录在 PATH 里。如果用的是 nvm每次切换 Node 版本后全局包会重新安装需要重新npm install -g impeccable-cli。问题impeccable init报错说 PRODUCT.md 已存在。加--force覆盖或者先备份再运行。我一般会先mv PRODUCT.md PRODUCT.md.bak初始化完再对比合并。问题检查结果全是误报。大概率是PRODUCT.md写得太模糊或者.impeccablerc的规则太严。先看PRODUCT.md里有没有适当、大概这类词全部换成具体数值。然后调低规则等级逐步收紧。6.2 与 AI coding agents 协作类问题问题AI 生成的代码完全不遵守 PRODUCT.md。检查 prompt 里有没有把PRODUCT.md的内容传进去。有些 AI coding agents 需要显式指定 context 文件比如 codex cli 的--context参数。另外PRODUCT.md太长的话AI 可能会忽略后面的内容建议控制在 200 行以内。问题AI 修正后引入了新的违规项。这是常见现象因为 AI 在修正一个问题的同时可能破坏另一个约束。解决办法是让 AI 一次性修正所有违规项而不是逐个修。用impeccable check --format json拿到完整违规列表一次性传给 AI。问题codex cli 的/compact命令和 impeccable 冲突。/compact会压缩上下文可能导致PRODUCT.md的内容被截断。建议在/compact之后重新加载PRODUCT.md或者用/resume恢复完整上下文后再跑 impeccable。6.3 性能与规模类问题问题大项目检查太慢。impeccable check默认会扫描所有文件。用--ignore排除node_modules、dist、coverage等目录。另外可以用--changed-only只检查 git 有改动的文件。问题CI 里 impeccable 报错但本地不报。检查 Node 版本是否一致以及.impeccablerc是否被正确加载。CI 环境可能没有安装某些依赖导致 impeccable 解析文件失败。加--verbose看详细日志。问题检查结果不稳定同样的代码有时报有时不报。这通常是缓存问题。impeccable会缓存解析结果缓存损坏时会导致不一致。运行impeccable cache clean清缓存后重试。6.4 常见问题速查表问题现象可能原因解决方法命令找不到PATH 未配置检查 npm prefix 并加入 PATH安装慢npm 源在国外切换镜像源或使用 pnpm全是误报PRODUCT.md 太模糊替换模糊词汇为具体数值AI 不遵守规范context 未传入检查 --context 参数修正引入新问题逐个修正导致一次性修正所有违规项检查太慢扫描范围太大用 --ignore 和 --changed-onlyCI 本地不一致环境差异统一 Node 版本清缓存结果不稳定缓存损坏impeccable cache clean7. 进阶用法把 impeccable 嵌入到更大的工作流里7.1 与 openspec cli 的配合openspec cli 是用来管理项目规格说明的工具它和 impeccable 的配合点在于openspec 管功能规格impeccable 管设计规格。两者可以共享同一个PRODUCT.md文件openspec 读取其中的功能描述部分impeccable 读取设计约束部分。具体做法是在PRODUCT.md里用注释标记分区!-- openspec:start -- ## Features - User can upload avatar - User can edit profile !-- openspec:end -- !-- impeccable:start -- ## Design Constraints - Avatar size: 40px - Profile card padding: 16px !-- impeccable:end --这样两个工具各取所需互不干扰。7.2 与 minimax cli 的协作minimax cli 如果用于生成 UI 代码可以在生成后直接管道传给 impeccableminimax cli generate --type component --name UserCard | impeccable check --stdin--stdin模式让 impeccable 从标准输入读取代码适合管道操作。检查结果可以用--format json输出再传给下一个工具做自动修正。7.3 自定义规则开发impeccable 支持自定义规则。在项目根目录创建impeccable-rules/文件夹里面放 JS 文件// impeccable-rules/no-hardcoded-color.js module.exports { name: no-hardcoded-color, level: error, check(node, context) { if (node.type color !context.isFromPalette(node.value)) { return { message: Color ${node.value} not in brand palette, line: node.line, suggestion: context.nearestPaletteColor(node.value) }; } } };然后在.impeccablerc里引用{ customRules: [./impeccable-rules/no-hardcoded-color.js] }自定义规则适合团队特有的约束比如禁止使用!important、所有动画必须用 CSS 变量控制时长等。7.4 生成设计质量报告impeccable report可以生成多种格式的报告# Markdown 报告适合贴 PR impeccable report --input design-report.json --format markdown # HTML 报告适合存档 impeccable report --input design-report.json --format html --output report.html # 趋势报告对比多次检查结果 impeccable report --history .impeccable-history/ --format trend趋势报告会显示设计质量随时间的变化适合在团队周会上展示。如果违规项数量持续下降说明规范在起作用如果突然上升可能是新成员加入或者规范被绕过。8. 一些踩坑之后的个人体会impeccable 这个工具本身不复杂但要用好关键不在工具而在PRODUCT.md的质量。我见过太多团队把PRODUCT.md写成一份设计规范大全几百行下去AI 读不完人也懒得维护。真正有效的PRODUCT.md应该像一份检查清单只写那些 AI 最容易出错、且对视觉一致性影响最大的约束。另一个体会是不要试图用 impeccable 替代设计走查。它能检查的是可量化的违规项——间距、颜色、字号、圆角这些。但这个按钮放在这里合不合适、这个页面的信息层级对不对这类问题它管不了。把它当成一个自动化的设计 lint 工具就好别指望它做设计决策。最后说一个实际效果我们团队用 impeccable 三个月后AI 生成代码的设计返工率大概下降了六成。剩下的四成里大部分是布局层面的问题这些确实需要人来看。但至少那些低级的、重复的、肉眼可见的间距和颜色错误基本被拦住了。对于用 AI coding agents 做前端开发的团队来说这个投入产出比是划算的。如果你刚开始用建议先在一个小项目上试把PRODUCT.md写到能覆盖 80% 的常见场景就行剩下的边用边补。别一上来就追求完美规范那样大概率会卡在写文档的阶段工具本身反而没用起来。