Impeccable 新手教程

第二章 · 安装到 Cursor

推荐一条路：npx impeccable install 自动检测环境。但 Cursor 有两个前置开关（Nightly 频道 + Agent Skills），漏了它们装了也不生效。

1前置：先打开 Cursor 的两个开关

Cursor 的 Agent Skills 目前需要手动启用，这是新手最常踩的坑——安装成功但 /impeccable 没反应，九成卡在这里。

① Cursor Settings → Beta → 切到 Nightly 频道→ ② Cursor Settings → Rules → 打开 Agent Skills→ ③ 重启 Cursor / Cursor CLI

官方 README 原文要求：「Switch to Nightly channel in Cursor Settings → Beta」「Enable Agent Skills in Cursor Settings → Rules」。Agent Skills 是 Cursor 对 Claude Style Skills 的实现，Impeccable 整个命令体系都跑在这上面。

为什么

Skill 本质是一组按需加载的 Markdown 指令。如果 Agent Skills 开关没打开，Agent 根本不会去读 .cursor/skills/ 目录，后面装得再对也只是「一堆没人看的文档」。

2推荐方式：npx impeccable install

在项目根目录执行，安装器会自动检测你机器上的 AI 工具（含项目本地的 .cursor），让你确认后写入。

# 进入你的项目根目录
cd my-project

# 交互式安装：自动检测 harness（~/.claude、~/.codex、.cursor 等）
npx impeccable install

# 也可以在脚本 / CI 里跳过交互，直指 Cursor、装在项目级
npx impeccable install --providers=cursor --scope=project

安装过程大致是这样的：

你：npx impeccable install

安装器：Detected harnesses:
         ✔ .cursor (Cursor, project-local)
         ✔ ~/.claude (Claude Code)
       Keep all detected providers? (Y/n) y
       ✔ Wrote .cursor/skills/impeccable/ (skill + 23 commands)
       ✔ Wrote .cursor/hooks.json (design hook)
       ✔ Wrote .claude/skills/impeccable/
       Reload your harness to pick up the new skill.

两个常用参数：--providers 从 claude,codex,cursor,grok,hermes,veto 里挑；--scope 选 project（写进当前项目，随 git 分发给团队）或 global（写进用户目录）。装完记得 reload——重启 Cursor 或重开 Cursor CLI 会话。

3装完之后，磁盘上多了什么

理解这几处落点，后面排查问题（以及决定哪些进 git）会轻松很多。

位置内容作用
.cursor/skills/impeccable/SKILL.md + 23 个命令定义 + 引擎启动脚本Agent 的设计语言与命令入口
.cursor/hooks.json一条 hook-before-edit 钩子Agent 每次改文件前，先用引擎检测拟写入内容，坏提案在落盘前被拦截
~/.impeccable/bin/引擎二进制（固定版本，仅首次下载）确定性检测器 + live 模式本地服务，不依赖运行中的模型
.impeccable/（项目内，首次运行命令后生成）config.json、design.json、surfaces/、critique/ 等项目级配置与产出物，git 规则见第八章

其中 hook 最值得关注：Cursor 的写盘动作会先经过 impeccable hook-before-edit，相当于给 Agent 配了一个不分心、不看心情的守门员。

4替代方式：手动复制 / git submodule

机器上不方便跑 npx（没有 Node），或者想把 Skill 版本锁进仓库时用这两种。

# 方式 A：从仓库复制（不需要 Node）
git clone https://github.com/pbakaus/impeccable /tmp/impeccable
cp -r /tmp/impeccable/dist/cursor/.cursor your-project/

# 方式 B：作为 git submodule 锁定版本
git submodule add https://github.com/pbakaus/impeccable .impeccable
npx impeccable link --source=.impeccable --providers=cursor
git add .gitmodules .impeccable .cursor
git commit -m "Add Impeccable skills"

无论哪种方式，Cursor 的两个前置开关都不能省。

5验证安装：在 Cursor CLI 里叫它一声

重开一个 Cursor CLI 会话，在 Agent 输入框敲命令试试。

你：/impeccable

Agent：Impeccable 4.3.1 已加载。可用命令（节选）：
       /impeccable init      一次性项目初始化，写 PRODUCT.md
       /impeccable craft     完整「先规划再构建」流程
       /impeccable critique  UX 设计审查
       /impeccable audit     技术质量体检
       /impeccable live      浏览器可视化迭代
       …共 23 个命令。建议从 /impeccable init 开始。

如果 Agent 回答「不知道你在说什么」，按顺序排查：① Nightly 频道生效了吗（About 里看版本号带不带 Nightly）；② Rules 里的 Agent Skills 开了吗；③ 安装后 reload 了吗；④ 当前目录是不是装过 Skill 的那个项目。

下一步

进入第三章：init 产品画像——第一次真正跑命令，让 Impeccable 认识你的项目。

Impeccable 新手教程