pbakaus / impeccable

pbakaus/impeccable

open_in_new前往仓库

Impeccable 是一个为 AI 编程代理提供设计指导的开源技能包，包含 1 个技能、23 个设计命令、61 条确定性检测规则及实时浏览器迭代能力，帮助 AI 生成更高质量的前端界面设计。

项目概览

项目概述

Impeccable 是一个为 AI 编程代理（如 Claude Code、Cursor、Codex 等）提供设计指导的开源项目。它源于 Anthropic 的 frontend-design 技能，通过一套结构化的命令、规则和实时浏览器迭代机制，帮助 AI 生成更高质量、更具辨识度的前端界面设计，避免常见的 AI 设计模式（如过度使用 Inter 字体、紫色渐变、卡片嵌套等）。

核心功能

  • 单一技能入口：通过 /impeccable <command> <target> 调用全部功能。
  • 23 个设计命令：包括 init、craft、audit、critique、polish、bolder、quieter、distill、animate、live 等，覆盖从项目初始化、设计审查到最终打磨的完整流程。
  • 61 条确定性检测规则：用于识别 AI 生成界面中的常见反模式（如过度使用的字体、灰色文字、卡片嵌套等），无需 LLM 或 API 密钥即可运行。
  • 实时浏览器迭代：支持在浏览器中直接选择元素、生成多个视觉变体并循环比较，实现高效的视觉迭代。
  • 设计钩子（Hook）：在 Claude Code、Cursor、Codex 等工具中安装后，可在编辑 UI 文件时自动运行检测器并反馈结果。
  • 跨工具支持：支持 Cursor、Claude Code、GitHub Copilot、Gemini CLI、Codex CLI、Grok Build 等多种 AI 编程工具。

适用与不适用场景

适用场景：

  • 使用 AI 编程代理进行前端界面开发，希望提升设计质量。
  • 需要系统性地审查、打磨和迭代前端界面设计。
  • 希望避免 AI 生成界面中常见的同质化设计模式。

不适用场景：

  • 后端开发、数据库优化等非前端界面任务。
  • 独立的位图资产（如照片级 PNG 图片）生成。
  • 需要忽略现有设计系统和项目上下文的无约束重写。

技术架构与依赖

  • 核心语言：JavaScript。
  • 运行时：Node.js（CLI 工具）和 Bun（开发构建）。
  • 架构：采用配置驱动的工厂模式，将核心技能源文件（skill/SKILL.src.md）转换为多种 AI 工具特定的格式。
  • 主要组件：
    • skill/：技能源文件、命令参考和运行时脚本。
    • cli/：独立的 impeccable CLI（npm 包）。
    • site/：项目官网（Astro）。
    • extension/：Chrome 扩展。
    • dist/：生成的各工具特定输出。
  • 依赖：CLI 工具本身无外部依赖；开发构建需要 Bun。

安装与快速开始

推荐方式（CLI 安装器）：

npx impeccable install

该命令会检测已安装的 AI 工具（如 ~/.claude、~/.codex 等），并询问安装范围（当前项目或全局）。安装后需重新加载对应的 AI 工具。

其他安装方式：

  • Git Submodule：将仓库作为子模块添加并链接。
  • 插件安装：Claude Code 和 Grok Build 支持通过插件市场安装。
  • 手动复制：从 dist/ 目录复制对应工具的文件到项目或全局目录。

快速开始：

  1. 在项目根目录运行 npx impeccable install。
  2. 在 AI 编程工具中运行 /impeccable init 进行初始化，生成 PRODUCT.md 文件。
  3. 开始使用各种命令，如 /impeccable audit、/impeccable polish 等。

典型使用方法

/impeccable init              # 初始化项目，收集产品上下文
/impeccable audit blog        # 审查博客页面
/impeccable critique landing  # 进行 UX 设计评审
/impeccable polish settings   # 发布前最终打磨
/impeccable harden checkout   # 添加错误处理和边界情况
/impeccable live              # 进入实时浏览器迭代模式

也可以直接使用 /impeccable 加描述：

/impeccable redo this hero section

常用命令可通过 /impeccable pin audit 创建独立快捷方式（如 /audit）。

配置与部署要点

  • 配置文件：.impeccable/config.json（共享配置）和 .impeccable/config.local.json（个人配置，应加入 .gitignore）。
  • 构建路径：可在配置中设置 buildPath 为 comp（先设计稿后编码）或 code（直接编码）。
  • Git 忽略：建议将 .impeccable/ 下的临时文件（截图、会话状态等）加入 .gitignore，但保留 config.json、design.json 等共享文件。
  • 钩子信任：Codex 和 Grok Build 用户需要额外的信任步骤才能运行设计钩子。
  • 更新：运行 npx impeccable update 刷新已安装的技能。

限制、风险与许可证

  • 许可证：Apache-2.0。
  • 限制：
    • 实时模式在 Bun 静态 HTML 导入等不支持 HMR 的环境中体验较差。
    • 一次只能进行一个生成/循环会话。
    • 生成过程中无法取消。
  • 风险：
    • 技能文件属于程序化文档，从克隆的仓库自动加载可能被视为提示注入向量（如 Hermes Agent 的处理方式）。
    • 检测器运行结果不能替代人工视觉审查。

官方链接

信息来源和分析时间

  • 信息来源：GitHub 仓库 README、文档（docs/ 目录）、发布信息。
  • 分析时间：2026-09-02（基于最新发布版本 skill-v4.1.3 的日期）。