第八章 · 工程化与 FAQ
git 里怎么记账、hook 怎么安全管理、CI 怎么接——以及新手最常问的七个问题。
1.impeccable/ 的 git 记账
一句话原则：共享的进仓库，易失的进忽略。
| 必须跟踪（团队共享） | 装进 .gitignore（易失 / 每人本地） |
|---|---|
.impeccable/config.json.impeccable/live/config.json.impeccable/design.json.impeccable/surfaces/*.md.impeccable/critique/*.md
|
config.local.json（个人配置）hook.cache.json / hook.pending.json*.png（截图产物）、review/、questions/live/server.json、live/sessions/、live/previews/live/annotations/、live/cache/、live/manual-edit-* 等
|
官方提供的 .gitignore 片段用 # impeccable-ignore-start 注释包起来，方便升级时整段维护。如果易失文件已经误提交，用 git rm --cached <path> 取消跟踪（不删本地文件）。
2设计 hook：便利与安全一起看
hook 在写盘前调用引擎检测拟写入内容，坏提案直接拦截。但它跑在「模型批准」之外，这是便利也是风险。
官方提示原文：「In Claude Code, installed command hooks run independently of model-tool approval」——也就是说 hook 不会每次弹窗征求同意。建议：接手陌生项目先读一下 .cursor/hooks.json（或对应 harness 的钩子清单），确认它只是调用本仓库内的 impeccable hook-before-edit，再决定是否信任；无人值守跑 Agent 前尤其要确认。需要临时关闭时，可按宿主方式禁用全部 hooks（例如 Claude Code 的 --settings '{"disableAllHooks": true}'）。
3接入 CI：把 61 条规则变成门禁
detect 的退出码天生就是给流水线准备的。
# 任意 CI 的 shell step 里：
npx impeccable detect --json src/ 2> findings.txt
case $? in
0) echo "design gate passed" ;; # 无主要发现
2) cat findings.txt; exit 1 ;; # 有主要发现，拦截合并
1) echo "some targets not scannable"; exit 1 ;;
esac团队策略示例：主分支门禁只拦 major 发现；个人分支用 npx impeccable detect src/ 看人读输出自查。豁免统一走第五章的 ignores 机制（带理由），别在 CI 脚本里堆特判。
4FAQ
按出现频率排的七个高频问题。
/impeccable 命令没有反应？
按序检查：① Cursor 是否在 Nightly 频道（Settings → Beta）；② Agent Skills 是否已开启（Settings → Rules）；③ 安装后是否 reload / 重开了 CLI 会话；④ 当前目录是否是装了 Skill 的项目。四步走完基本都能定位。
团队里有人用 Cursor、有人用 Claude Code，装几份？
一份安装多 provider：npx impeccable install --providers=cursor,claude。Skill 内容同源，各 harness 拿到自己的目录形态（.cursor/skills/…、.claude/skills/…），配置与 .impeccable/ 共享。Claude Code 也可以走插件市场：/plugin marketplace add pbakaus/impeccable。
引擎二进制在哪，会不会偷偷更新？
启动脚本把固定版本的引擎一次性下载到 ~/.impeccable/bin/，版本由仓库的 ENGINE_VERSION 锁定，不会自动漂移。想升级就重跑安装器（Codex 用户记得装完进 /hooks 重新批准项目钩子）。
不想接 AI，只想查一查？
完全可以：npx impeccable detect src/（或 URL）不需要任何 AI 参与与 API key。手动复制方式安装 Skill 也不需要 Node——只有 npx impeccable install 这一步用到 Node。
它会不会接管我的代码 / 依赖？
Skill 是指令层，不改依赖、不引运行时；引擎只在被调用时工作。它写入仓库的是文档与配置（PRODUCT.md、DESIGN.md、.impeccable/），代码改动永远走你熟悉的 Agent 流程与 git 审查。
检测全绿了，是不是就「设计很好」了？
官方原话：clean run 是证据，不是证明。确定性规则覆盖的是可枚举的问题，视觉与可访问性仍需人在相关视口实际浏览确认。把它当「下限守护」，不是「上限保证」。
哪些 Agent 环境被官方支持？
CLI 安装器覆盖 claude、codex、cursor、grok、hermes、veto；仓库另含 Gemini、Trae、Qoder、OpenCode、Kiro 等目录形态的手动复制说明（dist/ 下按 harness 分目录）。Codex 装完须进 /hooks 批准；Grok 需 --trust；VS Code Copilot 扩展要求 1.109.3+。
仓库地址：github.com/pbakaus/impeccable（Apache-2.0，作者 Paul Bakaus）。Cursor Skills 文档见 cursor.com/docs/context/skills。从导读的路线图回看一遍，你已经具备把它带进团队的全部知识。