## 项目概述

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 安装器）：**

```bash
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 仓库**：https://github.com/pbakaus/impeccable
- **项目官网**：https://impeccable.style
- **npm 包**：https://www.npmjs.com/package/impeccable
- **案例研究**：https://impeccable.style/cases/neo-mirai

## 信息来源和分析时间

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