Impeccable 怎麼讓 AI 編程工具審計前端：/impeccable audit、設計上下文與驗收

Wed, 15 Jul 2026 22:03:00 +0800

AI 能很快寫出可運行的前端，卻經常留下難以在單元測試中發現的問題：觸控目標太小、層級跳躍、窄屏溢出、灰字壓在彩色背景上，或每個區塊都套進卡片。Impeccable 的定位不是替你再生成一套頁面，而是給 AI 編程工具加上一套設計上下文、審計命令和可重複執行的檢測規則，讓“看起來還行”變成可以驗收的前端質量檢查。Impeccable 官方倉庫

本文只討論審計與驗收：如何初始化設計上下文、使用 /impeccable audit、檢查可訪問性和響應式，以及把結果接入 Codex/Claude Code 的日常改動流程。

它與 Taste、Astryx 的分工不同

這些工具都能改善 AI 生成的界面，但切入點不同：

工具	更適合解決什麼	本文不重複的部分
Taste	給生成過程加審美約束和前端風格方向	不展開安裝與設計示例
Astryx	將設計系統、React 組件與主題約束交給 Agent	不展開組件庫接入
Impeccable	記錄設計上下文，審計已生成界面，並給出可複查問題	聚焦 audit、檢測規則和發佈驗收

若你需要先建立風格方向，可閱讀 Taste Skill 的安裝與調用方法；若項目已有組件與主題體系，參考 Astryx 的設計系統接入流程。Impeccable 更適合作爲它們之後的質量閘門。

安裝到 AI 編程工具

在項目根目錄運行官方推薦的安裝命令：

`1`	`npx impeccable install`

安裝器會檢測可用的 harness 目錄，例如 ~/.claude、~/.codex 或項目內 .cursor；你可選擇項目級或全局安裝。腳本化安裝可顯式指定 provider 和範圍：

`1`	`npx impeccable install --providers=claude,codex,cursor --scope=project`

更新已存在的安裝：

`1`	`npx impeccable update`

對 Codex 有兩個容易漏掉的步驟：安裝後重載工具，並打開 /hooks 批准項目 hook。Impeccable 會把 Codex hook 寫入項目的 .codex/hooks.json，更新導致 hook 定義變化時，Codex 可能要求再次批准。

注意命令入口的差異：README 中展示的 /impeccable audit 適用於支持斜槓命令的界面；在 Codex 中它作爲 Skill 使用，應通過 /skills 或 $impeccable 找到並調用，而不是假設存在 /prompts: 命令。

先初始化設計上下文，而不是立刻審計

從新項目開始時執行：

`1`	`/impeccable init`

init 會區分當前界面是品牌/營銷頁面還是產品/儀表盤，並寫入 PRODUCT.md；可選的 DESIGN.md 會記錄受衆、產品定位、語氣、反例、顏色、字體和組件約定。後續的 audit、polish、critique 纔有判斷依據，不會把每個項目都套進同一套“通用 SaaS 審美”。

既有項目則可先讓它從代碼生成根目錄設計上下文：

`1`	`/impeccable document`

初始化後應人工檢查兩個文件：其中的品牌、受衆、禁止項是否真實；設計令牌、組件和現有約束是否被正確識別。錯誤的上下文會讓後續審計持續給出不適合項目的建議。

用 /impeccable audit 做技術質量審計

/impeccable audit 面向技術質量檢查，覆蓋可訪問性、性能和響應式問題。它可以審計整個區域，也可以限定目標：

1
2
3

/impeccable audit
/impeccable audit the header
/impeccable audit blog

一次審計不要同時讓 Agent 重構所有頁面。更可靠的提示是要求它按嚴重程度輸出問題、證據、受影響文件和最小修複方案，例如：

Use Impeccable to audit the checkout page.
Check keyboard navigation, form labels, error states, touch target size, narrow-screen overflow,
color contrast, and loading/empty states. Return findings grouped by blocker, major, and minor.
For each finding, cite the component and propose the smallest safe fix. Do not edit code yet.

先得到可審查報告，再批准改動。修復後再次運行 audit，確認問題消失且沒有引入新的響應式或可訪問性迴歸。

46 條確定性規則如何用於驗收

Impeccable 除了基於 LLM 的設計評審，還提供 46 條無需 API key 的確定性 detector 規則。它們會檢測常見 AI 前端模式與一般設計質量問題，例如過度使用的字體、紫色漸變、bounce easing、過小觸控目標、擁擠內邊距和跳過的標題層級。

不依賴 AI 編程工具時，也可以直接運行 CLI：

1
2
3

npx impeccable detect src/
npx impeccable detect index.html
npx impeccable detect --json .

--json 很適合 CI：把結果保存爲構建工件，或在新增高嚴重度問題時使檢查失敗。不要把 detector 當成絕對審美裁判；它能穩定發現已知反模式，但無法替代真實用戶、設計師或產品目標的判斷。

把可訪問性和響應式變成發佈門檻

每次較大的 UI 改動可以採用這套順序：

用 init/document 確認設計上下文仍有效。
讓 /impeccable audit 只審計本次改動的頁面或組件。
先修 blocker：鍵盤無法操作、表單標籤缺失、內容溢出、錯誤信息不可見等。
在至少一個窄視口和一個寬視口人工查看；交互組件再做鍵盤和焦點檢查。
運行 npx impeccable detect --json .，將新增問題與已有豁免分開。
修復後復跑 audit，並把報告或關鍵結論放進 PR 描述。

這種流程的目標不是追求檢測結果爲零，而是讓每一項保留的規則命中都有理由、有記錄，避免 AI 修改把已解決的設計問題重新帶回來。

哪些 .impeccable 文件該提交，哪些不該提交

執行命令後，Impeccable 會在 .impeccable/ 下寫入截圖、緩存、會話狀態、每位開發者配置和共享設計產物。不要把所有內容一併提交。

官方建議保持跟蹤的共享文件包括：

.impeccable/config.json
.impeccable/live/config.json
.impeccable/design.json
.impeccable/critique/*.md

而 config.local.json、hook 緩存、截圖、live 會話和預覽文件一般應寫入 .gitignore。如果截圖曾被提交，單純加入 .gitignore 不會停止追蹤；需要用 git rm --cached <path> 將其從索引移除，同時保留本地文件。

常見問題

audit 報了很多“審美問題”，是否要全部改？

不必。先按 blocker、major、minor 分類，結合設計上下文和產品目標評估。品牌字體、歷史頁面或有意的視覺選擇可以保留，但應在項目配置或文件註釋中寫明豁免原因，而不是每次忽略同一項。

檢測規則和現有設計系統衝突怎麼辦？

不要修改代碼去迎合默認規則。先檢查 PRODUCT.md、DESIGN.md 和 .impeccable/config.json，將經過確認的組件、字體或設計令牌作爲項目上下文或 ignore。規則應服務於系統一致性，而不是覆蓋既有設計系統。

hook 會阻止所有 UI 修改嗎？

不同工具的行爲不同。Impeccable 的 README 說明：Claude Code、GitHub Copilot 和 Codex 在編輯後反饋檢測發現；Cursor 則可在不佳的提議寫入前阻止。對 Codex，記得在 /hooks 審覈項目 hook 的內容和權限。

小結

Impeccable 的價值在於讓 AI 前端修改有一條可驗證的審計鏈：先建立 PRODUCT.md/DESIGN.md，再用 audit 限定範圍檢查可訪問性、性能和響應式，最後用確定性 detector 與復跑結果作爲驗收依據。它與 Taste、Astryx 可以共存，但更適合放在生成和設計系統接入之後，承擔前端質量檢查這一環。

Impeccable on KnightLi的博客