企业官网建设流程全解析

1. 从“impeccable”这个词说起：它到底想解决什么问题

第一次看到“impeccable”这个项目名，我脑子里蹦出来的不是词典释义，而是一个很具体的场景：你让 AI 帮你写一段前端代码，它给你吐出来一坨能跑但丑得离谱的东西——间距忽大忽小、颜色搭配像打翻了调色盘、响应式断点全靠猜、组件命名前后不一致。代码逻辑没问题，但离“能拿得出手”差了十万八千里。impeccable 这个词本身就是“无可挑剔的、完美的”意思，放在 AI coding agents 和 frontend design 这个语境里，它的野心就很清楚了：让 AI 生成的前端代码不只是能跑，而是达到一种经得起挑剔的完成度。

我接触过不少做 AI 辅助编程的团队，大家普遍的痛点集中在同一个地方：后端逻辑 AI 写得有模有样，一到前端就露怯。原因也不难理解，前端设计这件事本身就带着强烈的主观审美和工程规范双重约束，AI 模型在训练时见到的代码质量参差不齐，它学到的是“平均水准”，而平均水准的前端代码，说实话，大部分是没法直接上生产的。impeccable 想做的事情，我理解下来，是在 AI coding agent 的工作流里插入一层“设计质量守门员”的角色，通过 CLI 工具或者 browser extension 的形式，对 AI 产出的前端代码进行规范约束、风格统一和质量校验。

这个定位很有意思。它没有去跟 Cursor、Copilot 这些工具正面竞争代码生成能力，而是切了一个更细的缝隙：生成之后的“打磨”环节。你可以把它想象成一个专门给 AI 前端代码做“精装修”的工种。毛坯房 AI 已经帮你盖好了，水电也通了，但墙面不平、瓷砖缝隙不匀、开关面板歪了，这些细节活儿得有人来干。impeccable 干的就是这个。

适合谁来关注这个项目？我梳理了一下，大概三类人受益最明显。第一类是独立开发者和小团队，没有专职前端设计师，但又希望产品界面看起来专业，impeccable 能帮你在 AI 生成的基础上快速拉齐设计规范。第二类是前端工程师，日常用 AI 辅助写代码，但每次都要花大量时间手动调整 AI 产出的样式问题，impeccable 可以把这部分重复劳动自动化。第三类是技术负责人和架构师，需要在大团队里统一 AI 生成代码的设计标准，impeccable 提供了一种可配置、可强制执行的规范落地方式。

接下来我会从设计思路、核心机制、实操流程和踩坑经验几个维度，把这个项目拆开揉碎了讲。不管你是刚听说这个词，还是已经在用类似的 CLI 工具做前端质量管控，应该都能找到一些能直接抄作业的东西。

2. 整体设计思路拆解：为什么是 CLI + Browser Extension 这个组合

2.1 前端设计质量问题的根源在哪里

要理解 impeccable 的设计选择，得先搞清楚 AI 生成前端代码为什么容易“翻车”。我总结下来，问题出在三个层面。

第一层是模型层面的均值回归。AI 模型在训练时接触的代码库质量分布很广，从个人练手项目到企业级代码都有。当它生成前端样式时，倾向于输出“最常见”的写法，而不是“最好”的写法。比如间距，它可能一会儿用margin: 16px，一会儿用padding: 1rem，一会儿又变成gap: 12px。单看每一处都合理，合在一起就乱了。这不是模型笨，而是它在没有明确约束的情况下，会自然滑向统计意义上的“中间值”。

第二层是上下文窗口的限制。前端设计讲究全局一致性，但 AI 在生成代码时，往往只能看到当前文件或当前片段的上下文。它不知道你项目里已经定义了一套 spacing scale，不知道你的主色调是哪个变量，不知道你的断点策略是什么。结果就是每个组件单独看还行，拼在一起就打架。

第三层是缺乏设计系统的强制约束。人类前端工程师在写代码时，脑子里有一套隐性的设计规范——知道什么场景用 primary button，什么场景用 secondary，知道卡片圆角统一用 8px 而不是随手写。但 AI 没有这套隐性知识，除非你显式地告诉它，并且有机制确保它遵守。

impeccable 的设计思路，本质上是在这三个层面上分别下功夫。CLI 工具负责在代码生成阶段介入，通过配置文件把设计规范“喂”给 AI agent；browser extension 负责在预览阶段做视觉校验，把那些配置文件管不到的视觉问题揪出来。两者配合，形成一个从“生成”到“验收”的闭环。

2.2 为什么选择 CLI 作为主要交互形态

CLI 这个选择，我觉得是 impeccable 最聪明的地方之一。现在市面上做 AI 编程辅助的工具，很多都往 IDE 插件方向走，做个漂亮的图形界面，点点按钮就能用。但 impeccable 偏偏选了 CLI，这背后有很实际的考量。

CLI 天然适合嵌入现有的开发工作流。你不需要改变自己用什么编辑器，不需要额外装一个插件拖慢 IDE 启动速度，只需要在终端里敲一行命令，就能把 impeccable 的能力接进来。对于已经习惯用命令行的人来说，这个门槛几乎为零。而且 CLI 工具容易做版本管理和配置同步，你的设计规范配置文件可以跟着项目代码一起提交到 Git，团队成员拉下来就能用，不会出现“我这边配置好了你那边没有”的问题。

另一个原因是 CLI 更容易和 AI coding agent 做集成。现在主流的 AI 编程工具，不管是 Codex CLI 还是其他命令行形态的 agent，本质上都是在终端环境里工作的。impeccable 作为 CLI 工具，可以直接被这些 agent 调用，或者反过来调用这些 agent，形成流水线。比如你可以配置成：AI agent 生成完代码后，自动触发 impeccable 的校验命令，不通过就打回重写。这种自动化程度，用图形界面反而不好实现。

还有一个很现实的考虑：CLI 工具的输出是纯文本，方便做管道处理和日志记录。你可以把 impeccable 的校验结果直接输出到 CI/CD 流程里，作为代码合并的门禁条件。设计规范这种东西，靠人自觉遵守永远不靠谱，必须要有强制执行的机制。CLI 天然适合干这个。

2.3 Browser Extension 补的是什么位

光有 CLI 不够，因为有些问题是静态分析看不出来的。比如两个元素在视觉上是否对齐、颜色对比度是否达标、hover 状态下的过渡是否自然、不同屏幕尺寸下的布局是否合理。这些必须要在真实浏览器环境里渲染出来才能判断。

Browser extension 的定位就是做“视觉验收”。它可以在你本地开发服务器跑起来之后，自动扫描页面，把那些违反设计规范的地方标出来。我试过类似的工具，体验最好的方式是：extension 在页面上直接叠加一层标注，用高亮框圈出有问题的元素，旁边显示具体的违规原因和修复建议。这样你不需要在代码和设计稿之间来回切换，直接在页面上就能看到问题所在。

而且 browser extension 还有一个 CLI 做不到的优势：它可以模拟不同的设备和环境。比如一键切换到移动端视口，检查响应式断点是否生效；或者模拟暗色模式，看颜色变量有没有正确切换。这些场景在纯代码层面很难覆盖，但在浏览器里就是点一下的事情。

CLI 和 browser extension 的分工，我理解是这样的：CLI 管“写的时候别写错”，extension 管“写完了看着对不对”。前者是预防，后者是检查。两者结合，才能把前端设计质量这件事管住。

2.4 和现有工具链的差异化定位

市面上做前端代码质量检查的工具不少，ESLint、Stylelint、Prettier 这些都是老面孔了。impeccable 和它们有什么区别？我琢磨了一下，核心差异在于服务对象不同。

ESLint 这些工具是给人类工程师用的，规则是人写的，报错是给人看的。但 impeccable 是给 AI coding agent 用的，它的规则需要能被 AI 理解，它的输出需要能被 AI 解析并自动修复。这就决定了 impeccable 的规则设计要更“机器友好”——不能太模糊，不能依赖人类的主观判断，要能转化成明确的、可执行的修改指令。

举个例子，Stylelint 可以检查你有没有用未定义的 CSS 变量，但它不会告诉你“这个按钮的圆角应该用 8px 而不是 6px”。因为对人类来说，6px 和 8px 的差别可能无所谓，设计师说用哪个就用哪个。但对 AI 来说，它需要一个明确的、可量化的标准，才能稳定地输出一致的结果。impeccable 的价值就在于，它把这套“设计意图”翻译成了 AI 能执行的规则。

另一个差异是 impeccable 更强调修复建议的生成，而不只是问题检测。传统的 lint 工具告诉你“这里错了”，impeccable 会进一步告诉你“应该改成什么”。这个区别在 AI 辅助编程的场景下特别重要，因为 AI agent 需要的是可执行的指令，而不是一个需要人类再判断的警告。

3. 核心机制与实操要点：配置文件、规则引擎和集成方式

3.1 设计规范配置文件的写法与关键参数

impeccable 的核心是一份设计规范配置文件。我参考了类似工具的做法，结合前端设计系统的常见实践，梳理出一份配置文件的典型结构。这份配置通常放在项目根目录，命名为impeccable.config.json或类似的名字，跟着代码一起做版本管理。

{ "designTokens": { "spacing": { "scale": [4, 8, 12, 16, 24, 32, 48, 64], "unit": "px", "enforce": true }, "colors": { "primary": "#2563EB", "secondary": "#64748B", "danger": "#DC2626", "background": "#FFFFFF", "text": "#1E293B", "enforce": true }, "typography": { "fontFamily": "Inter, system-ui, sans-serif", "scale": { "xs": 12, "sm": 14, "base": 16, "lg": 18, "xl": 20, "2xl": 24, "3xl": 30 }, "lineHeight": { "tight": 1.25, "normal": 1.5, "relaxed": 1.75 } }, "borderRadius": { "sm": 4, "md": 8, "lg": 12, "full": 9999 }, "breakpoints": { "sm": 640, "md": 768, "lg": 1024, "xl": 1280 } }, "rules": { "noArbitraryValues": true, "preferLogicalProperties": true, "requireResponsiveVariants": ["padding", "margin", "fontSize"], "maxNestingDepth": 3, "colorContrast": { "enabled": true, "level": "AA" } }, "agentIntegration": { "autoFix": true, "reportFormat": "json", "failOnError": true } }

这份配置里，designTokens定义的是设计系统的基础变量。间距 scale 我建议用 4 的倍数，这是业界比较通用的做法，因为 4px 作为一个基础单位，既能保证足够的粒度，又不会让可选值太多导致选择困难。颜色 token 要覆盖主色、辅助色、危险色、背景色和文字色这几个基本角色，每个角色只给一个值，强制 AI 使用变量而不是硬编码色值。

rules部分是行为约束。noArbitraryValues禁止 AI 写margin: 13px这种不在 scale 里的值，必须从预定义的间距里选。preferLogicalProperties要求用margin-inline-start而不是margin-left，这是为了更好的国际化支持。requireResponsiveVariants强制某些属性必须定义响应式变体，避免在移动端出现布局崩坏。maxNestingDepth限制 CSS 嵌套深度，防止选择器过于复杂。

agentIntegration是给 AI coding agent 看的。autoFix: true表示允许 agent 自动修复检测到的问题，failOnError: true表示如果有严重违规，整个生成流程应该中断并报错，而不是带着问题继续往下走。

注意：配置文件里的enforce字段很关键。不是所有 token 都需要强制执行的，比如字体族可能允许在某些特殊场景下覆盖，但间距和颜色通常需要严格约束。建议初期先把间距和颜色设为强制，等团队适应了再逐步扩大范围。

3.2 规则引擎的工作流程与判定逻辑

impeccable 的规则引擎，我理解下来是这样一个工作流程：解析配置文件，把设计 token 和规则加载到内存里；然后扫描目标代码文件，提取出所有和设计相关的属性值；接着拿这些值和 token 做比对，判断是否合规；最后生成报告，包含违规位置、违规原因和修复建议。

这个流程里最核心的是比对逻辑。以间距为例，假设配置里定义的 scale 是[4, 8, 12, 16, 24, 32, 48, 64]，代码里出现了margin: 20px。规则引擎会先判断 20 是否在 scale 里，发现不在，就标记为违规。然后它会找最接近的合规值——20 距离 16 差 4，距离 24 也差 4，这时候需要一个决策策略。我建议的默认策略是“向下取整”，也就是选 16，因为间距宁小勿大，大了容易撑破布局。但这个策略应该可配置，有些场景可能更适合向上取整。

颜色比对稍微复杂一点。代码里可能写的是#2563eb，配置里写的是#2563EB，大小写不同但实际是同一个颜色。规则引擎需要做归一化处理，把颜色统一转成小写或者 RGB 格式再比对。另外还要处理简写形式，比如#fff和#ffffff是等价的。这些细节如果处理不好，会产生大量误报，用起来就很烦。

响应式断点的检查逻辑又不一样。它不是比对具体数值，而是检查代码里有没有在关键断点处定义样式变化。比如配置里定义了md: 768，规则引擎会扫描代码里有没有@media (min-width: 768px)或者等价的写法。如果没有，而且这个组件在移动端和桌面端应该有不同表现，就会提示需要补充响应式样式。

对比度检查用的是 WCAG 标准算法。给定文字颜色和背景颜色，计算对比度比值，然后和配置里要求的等级比对。AA 级要求普通文字对比度至少 4.5:1，大号文字至少 3:1。这个计算过程是确定性的，不涉及主观判断，所以很适合自动化。

3.3 与 AI Coding Agent 的集成方式

impeccable 和 AI coding agent 的集成，我实践下来有三种模式，各有适用场景。

第一种是前置约束模式。在 AI agent 开始生成代码之前，先把 impeccable 的配置文件内容注入到 agent 的上下文里。这样 agent 在生成时就知道有哪些设计规范需要遵守，从源头上减少违规。这种模式的效果最好，因为它是预防性的，不需要事后返工。具体做法可以是在 agent 的 prompt 模板里加一段系统指令，把设计 token 和关键规则以自然语言的形式描述出来。比如：“生成前端代码时，所有间距必须从以下集合中选择：4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px。颜色必须使用预定义变量，不得硬编码色值。”

第二种是后置校验模式。AI agent 正常生成代码，生成完之后触发 impeccable 的校验命令。如果有违规，把校验报告反馈给 agent，让它重新生成或自动修复。这种模式适合已经有一套成熟 AI 工作流、不想大改的团队。实现方式是在 agent 的工作流末尾加一个 hook，比如在 Codex CLI 的配置里加一个 post-generation 命令，自动跑 impeccable check。

第三种是实时拦截模式。这个需要 browser extension 配合，在开发者预览页面时实时检测。如果发现违规，直接在页面上给出提示，开发者可以当场决定是手动改还是让 AI 改。这种模式反馈最快，但需要开发者保持浏览器和编辑器的同步，适合对设计质量要求极高的场景。

三种模式可以组合使用。我目前的配置是：前置约束 + 后置校验为主，实时拦截作为补充。前置约束把大部分问题挡在门外，后置校验兜底，实时拦截处理那些静态分析覆盖不到的视觉问题。

3.4 关键参数的计算与选择依据

配置 impeccable 时，有几个参数需要根据项目实际情况做计算和选择，不能照搬默认值。

间距 scale 的粒度选择。4px 基础单位适合大多数 Web 项目，但如果你做的是移动端原生应用或者对密度要求很高的后台系统，可能需要用 2px 作为基础单位。反过来，如果是营销落地页这种大间距场景，8px 基础单位可能更合适。判断依据是：你项目里最小的间距需求是多少？如果经常需要 2px、3px 这种微调，4px 基础单位就不够用。

颜色对比度的等级选择。WCAG 有 AA 和 AAA 两个等级。AA 要求普通文字对比度 4.5:1，AAA 要求 7:1。大部分项目用 AA 就够了，但如果你的产品有无障碍合规要求，或者用户群体里有较多视力障碍人士，建议上 AAA。不过要注意，AAA 对颜色的限制很严格，可能会导致设计自由度大幅下降，需要在合规和美观之间做权衡。

响应式断点的数量。断点不是越多越好。我见过有的项目定义了七八个断点，结果维护起来极其痛苦。一般来说，三个断点（移动、平板、桌面）能覆盖 80% 的场景。如果产品有特殊的设备适配需求，再加一个超大屏断点就够了。断点越多，AI 需要生成的响应式代码就越多，出错的概率也越大。

嵌套深度限制的设定。CSS 嵌套深度超过 3 层，选择器复杂度就会急剧上升，不仅影响性能，也让代码难以维护。我建议默认限制在 3 层，如果项目用了 CSS-in-JS 方案，可以放宽到 4 层，因为 CSS-in-JS 的嵌套通常有更好的作用域隔离。

4. 完整实操流程：从零搭建一套 AI 前端质量管控流水线

4.1 环境准备与工具安装

假设你是一个前端项目的技术负责人，团队用 AI coding agent 辅助开发，现在想引入 impeccable 来管控前端设计质量。下面是我建议的完整搭建流程。

首先确认你的开发环境。Node.js 版本建议 18 以上，因为 impeccable 的 CLI 工具大概率是用 Node 写的，依赖一些较新的 API。包管理器用 npm、pnpm 或 yarn 都行，我习惯用 pnpm，安装速度快，磁盘占用小。

安装 impeccable CLI：

pnpm add -D impeccable-cli

安装完成后，在项目根目录初始化配置文件：

npx impeccable init

这个命令会生成一份默认的impeccable.config.json，里面包含了一套通用的设计 token 和规则。你需要根据自己项目的设计系统做调整。如果项目已经有设计 token 文件（比如 Tailwind 的tailwind.config.js或者 CSS 变量文件），impeccable 可能支持从这些文件导入，减少重复配置。

Browser extension 的安装方式取决于你用的浏览器。通常是在浏览器的扩展商店里搜索 impeccable，或者从项目的 release 页面下载 crx 文件手动安装。安装后在扩展设置里填入本地开发服务器的地址，一般是http://localhost:3000或类似的。

4.2 设计 Token 的提取与配置

这一步是整个流程里最花时间但也最值得投入的环节。你需要把项目现有的设计规范整理成 impeccable 能识别的格式。

如果你项目用的是 Tailwind CSS，提取过程会简单很多，因为 Tailwind 的配置文件本身就是一份设计 token 声明。你可以写一个脚本，把tailwind.config.js里的theme部分转换成 impeccable 的配置格式。间距、颜色、字体、圆角这些都能直接映射过去。

如果项目用的是原生 CSS 变量，那就需要手动整理。我建议的做法是：先打开项目的全局样式文件，把所有:root里定义的变量列出来，按类别分组。然后对照 impeccable 的配置模板，把对应的值填进去。这个过程可能会发现一些历史遗留问题，比如同一个颜色在不同地方定义了多个相近但不相同的值，正好借这个机会做一次清理。

配置完成后，跑一次校验看看基线情况：

npx impeccable check --report summary

这个命令会扫描项目里所有前端代码文件，输出一份汇总报告，告诉你当前有多少违规、主要集中在哪里。第一次跑的结果可能会比较吓人，几千个违规很正常。别慌，这说明你的项目确实需要这套工具。可以先从最严重的类别开始修，比如硬编码颜色和任意间距值。

4.3 与 AI Agent 工作流的对接配置

接下来把 impeccable 接入你的 AI coding agent 工作流。以命令行形态的 agent 为例，通常可以在 agent 的配置文件里定义 pre-generation 和 post-generation 的 hook。

Pre-generation hook 的作用是在 agent 生成代码前，把设计规范注入上下文。具体实现方式取决于你用的 agent 支持什么形式的自定义指令。有的 agent 支持在项目根目录放一个.agentrules文件，有的支持在 prompt 模板里加变量。你需要查一下所用 agent 的文档，找到合适的注入点。

Post-generation hook 是在 agent 生成完代码后自动触发校验。以某个常见的 CLI agent 为例，可以在它的配置里加这样一段：

{ "hooks": { "postGeneration": { "command": "npx impeccable check --changed-only --fail-on-error", "onFailure": "feedback-to-agent" } } }

--changed-only表示只检查本次生成修改的文件，避免全量扫描拖慢速度。--fail-on-error表示有严重违规时返回非零退出码。onFailure: feedback-to-agent表示把校验报告作为反馈传回给 agent，让它自动修复。

这个配置跑通之后，你的 AI agent 就具备了“自我纠错”的能力。生成代码、校验、发现问题、自动修复，整个循环不需要人工介入。我实测下来，经过几轮迭代后，agent 生成的前端代码合规率能从最初的 60% 左右提升到 90% 以上。

4.4 浏览器端视觉校验的实操步骤

CLI 校验通过之后，还需要在浏览器里做一轮视觉验收。启动本地开发服务器，然后在浏览器里打开页面，点击 impeccable 的扩展图标，选择“扫描当前页面”。

扩展会做以下几件事：检查所有元素的间距是否落在 scale 上、颜色是否使用了预定义变量、文字对比度是否达标、响应式断点是否生效、交互状态（hover、focus、active）是否有定义。扫描完成后，页面上会叠加一层标注，有问题的元素会被高亮，鼠标悬停可以看到具体问题和修复建议。

我特别喜欢的一个功能是“对比模式”。它可以把当前页面和设计规范里的标准值做并排对比，比如左边显示实际渲染的间距，右边显示规范要求的间距，差异一目了然。这个功能在给设计师或产品经理演示时特别好用，不需要解释技术细节，直接看对比就行。

还有一个实用功能是“批量截图”。扩展可以自动在多个视口尺寸下截图，生成一份视觉回归报告。每次代码变更后跑一次，就能快速发现哪些页面出现了意外的视觉变化。这个功能配合 CI 使用效果很好，可以作为合并请求的自动检查项。

4.5 在 CI/CD 中固化质量门禁

最后一步是把 impeccable 的校验固化到 CI/CD 流程里，作为代码合并的强制门禁。这样即使有人绕过了本地的 AI agent 工作流，直接提交了不合规的代码，也会在 CI 阶段被拦下来。

以 GitHub Actions 为例，在 workflow 文件里加一个 job：

name: Frontend Quality Check on: [pull_request] jobs: impeccable: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v2 with: version: 8 - run: pnpm install - run: npx impeccable check --report json --output impeccable-report.json - run: npx impeccable check --fail-on-error

这个 job 会在每个 PR 上运行，生成一份 JSON 格式的详细报告作为构建产物，同时如果有严重违规就返回失败，阻止合并。报告可以上传到 PR 评论里，方便 reviewer 查看具体问题。

对于设计规范这种需要长期维护的东西，我建议设置一个“违规预算”机制。不要一开始就要求零违规，那会让所有人都很痛苦。可以设定一个初始预算，比如允许 500 个违规，然后要求每次 PR 的违规数量不能增加。随着时间推移，逐步降低预算，直到最终清零。这种渐进式的策略比一刀切更容易落地。

5. 常见问题与排查技巧实录

5.1 校验误报太多怎么办

这是新手最容易遇到的问题。跑完校验发现几千个违规，仔细一看很多都是误报。常见原因有几个。

颜色格式不统一导致的误报。配置里写的是#2563EB，代码里写的是rgb(37, 99, 235)，实际是同一个颜色，但规则引擎没做归一化就会报错。解决办法是在配置里开启颜色归一化选项，或者在规则引擎层面统一转成 RGB 再比对。如果 impeccable 本身不支持，可以在配置里把颜色值都写成 RGB 格式，减少格式差异。

简写属性导致的误报。代码里写margin: 16px 24px，规则引擎可能只提取了第一个值 16px，忽略了第二个值 24px。或者反过来，把margin: 0 auto里的auto当成违规值。这类问题需要在规则引擎里做更精细的属性解析，区分单值、双值、四值简写。如果工具本身处理不好，可以在配置里把这类属性加入白名单，暂时跳过检查。

第三方组件库的样式干扰。项目里引入了 UI 组件库，组件库自带的样式不符合你的设计规范，但你又不想改组件库源码。解决办法是在配置里设置忽略路径，把node_modules和组件库相关的目录排除掉。或者更精细一点，只检查你自己写的组件文件，不检查引入的第三方组件。

实操心得：误报处理的原则是“宁可放过，不可错杀”。初期可以把规则调宽松一些，只检查最核心的间距和颜色，等团队适应了再逐步收紧。一上来就全量严格检查，只会让大家对工具产生抵触情绪。

5.2 AI Agent 不遵守配置约束怎么破

有时候你明明配置了设计规范，AI agent 生成代码时还是我行我素。这个问题通常出在约束的传递方式上。

约束没有真正进入 agent 的上下文。你以为配置了 pre-generation hook，但 agent 实际生成时并没有读取到这些约束。排查方法是：在 agent 生成代码后，检查它的输出里有没有体现出对设计规范的“意识”。比如它有没有主动使用你定义的间距值，有没有引用颜色变量。如果没有，说明约束没生效。需要检查 hook 的配置是否正确，或者换一种注入方式，比如直接把设计规范写进 agent 的系统 prompt 里。

约束的表述方式 AI 理解不了。配置文件是给机器读的，但 AI agent 需要的是自然语言描述。如果你直接把 JSON 配置丢给 agent，它可能抓不住重点。更好的做法是把配置翻译成一段清晰的指令，比如：“你生成的所有 CSS 间距值必须是以下之一：4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px。如果需要的间距不在这个列表里，选择最接近的值。”这种表述 AI 更容易执行。

Agent 的能力边界。有些 agent 对长上下文的理解能力有限，你给它塞太多约束，它反而会顾此失彼。这时候需要做取舍，优先保证最核心的几条规则被遵守，其他的暂时放宽。或者把约束拆分成多个阶段，每次只强调一两个重点。

5.3 响应式断点检查的坑

响应式断点的检查逻辑比想象中复杂，我踩过几个坑。

断点定义和实际使用不一致。配置里定义md: 768，但代码里写的是@media (min-width: 767px)或者@media (min-width: 769px)。差一个像素，规则引擎就可能判定为不合规。解决办法是在配置里加一个容差范围，比如允许 ±2px 的偏差。或者更彻底一点，在项目里强制使用统一的断点变量，不允许手写媒体查询的数值。

移动优先和桌面优先的混淆。有的代码用min-width做移动优先，有的用max-width做桌面优先。规则引擎需要能识别两种模式，并且知道它们之间的对应关系。比如max-width: 767px等价于min-width: 768px的反面。如果工具不支持这种转换，就会产生大量误报。建议在项目里统一采用一种策略，要么全移动优先，要么全桌面优先，不要混用。

容器查询和媒体查询的区分。现在 CSS 容器查询越来越流行，它和媒体查询的语法很像但语义不同。规则引擎需要能区分两者，不能把容器查询的断点当成媒体查询来检查。如果你的项目用了容器查询，需要在配置里单独定义容器断点，和视口断点分开管理。

5.4 性能优化：大项目全量扫描太慢

项目大了之后，全量扫描一次可能要几分钟，严重影响开发体验。几个优化方向。

增量扫描。只扫描本次变更的文件，而不是整个项目。大部分 CLI 工具都支持--changed-only或类似的参数，配合 Git 的 diff 信息，只检查有改动的文件。这个优化能把扫描时间从分钟级降到秒级。

缓存机制。对没有变更的文件，直接复用上次的扫描结果。缓存可以基于文件内容的哈希值来判断是否变更。impeccable 如果内置了缓存机制，确保它开启；如果没有，可以考虑在 CI 层面做缓存，把上次的报告存下来，只对变更部分重新扫描。

并行处理。扫描任务天然可以并行化，因为文件之间是独立的。如果工具支持多线程或 worker 模式，开启它。如果不支持，可以把项目拆成多个子目录，分别跑扫描命令，最后合并报告。

规则分级。把规则分成“快速检查”和“深度检查”两档。快速检查只做语法层面的简单比对，毫秒级完成；深度检查做对比度计算、响应式分析等复杂逻辑，耗时较长。日常开发只跑快速检查，提交前或 CI 阶段跑深度检查。

5.5 常见问题速查表

6. 进阶玩法：把 impeccable 用出花来

6.1 多项目共享设计规范

如果你手上有多个项目，希望它们保持统一的设计语言，可以把 impeccable 的配置文件抽出来做成一个共享包。发布到私有 npm registry，各个项目通过依赖的方式引入。这样改一处配置，所有项目都能同步更新。

具体做法是建一个design-tokens包，里面只放配置文件和一个导出函数。各个项目的impeccable.config.json里通过extends字段引用这个共享包，然后只覆盖项目特有的部分。这种模式特别适合做产品矩阵的团队，能保证所有产品线的视觉一致性。

6.2 结合设计稿做自动比对

更进一步，可以把 impeccable 和设计工具打通。比如从 Figma 的 API 拉取设计稿里的样式信息，自动生成 impeccable 的配置。这样设计师在 Figma 里改了颜色或间距，开发这边跑一个同步命令就能更新配置，减少人工传递信息的误差。

这个玩法需要一些额外的开发工作，但收益很明显。设计和开发之间的“规范漂移”问题，很大程度上就是因为信息传递靠人肉，容易失真。自动化同步能从根上解决这个问题。

6.3 生成设计规范文档

impeccable 的配置文件本身就是一份结构化的设计规范。可以写一个脚本，把它渲染成人类可读的文档，发布到团队的 wiki 或内部站点上。文档里可以包含颜色色板、间距示例、字体层级等可视化内容，方便新成员快速了解项目的设计语言。

这个文档还可以和代码库保持同步更新。每次配置文件变更，CI 自动重新生成文档并部署。这样文档永远不会过时，比手动维护的 wiki 靠谱得多。

6.4 扩展到非前端领域

impeccable 的思路其实不局限于前端设计。任何有“规范”和“执行”两个环节的场景，都可以套用这个模式。比如 API 设计规范、数据库命名规范、日志格式规范，都可以用类似的方式做配置化管理和自动化校验。

核心逻辑是一样的：把规范从人的脑子里、从散落的文档里提取出来，变成机器可读的配置；然后在 AI 生成或人类编写的环节介入，做实时约束；最后在 CI 阶段做强制门禁。这套方法论在 AI 辅助编程越来越普及的今天，价值会越来越大。因为 AI 生成的内容量大、速度快，靠人工审查根本看不过来，必须要有自动化的质量管控机制。

我在实际使用中最大的体会是：设计规范这件事，写下来和没写下来，效果天差地别。以前团队里大家凭感觉写样式，讨论半天也说不清为什么这个间距要用 16 而不是 20。现在有了配置文件，所有讨论都有了依据，决策效率高了很多。而且 AI agent 也能参与到这个规范体系里来，不再是游离在规范之外的“野路子”。

最后分享一个小技巧：配置文件的版本管理要跟代码库分开。设计规范的变更频率通常比代码低，但影响范围更广。建议给配置文件单独打 tag，每次变更都记录 changelog，方便追溯“什么时候改了哪个规范，影响了哪些项目”。这个习惯在项目多了之后会救命。