# impeccable: bắt lỗi thiết kế do AI và chỉnh giao diện bằng lệnh — hướng dẫn cài đặt và dùng

> Impeccable là một skill cài vào coding agent (Claude Code, Cursor, Codex CLI, Gemini CLI và nhiều công cụ khác) để agent thiết kế giao diện tốt hơn, đồng thời có bộ dò lỗi thiết kế chạy không cần LLM. Cài bằng một lệnh npx impeccable install trong thư mục dự án, yêu cầu Node từ 18.19.0 trở lên. Với người đã dùng coding agent, việc cài khá dễ.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-07 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/impeccable-tu-vung-thiet-ke-cho-coding-agent-chong-ai-slop

Impeccable là một bộ skill cho coding agent, giúp agent hiểu các yêu cầu thiết kế như "táo bạo hơn", "một trang tin tức hơn", "rà lại trước khi giao", và kèm theo một bộ dò lỗi giao diện kiểu "AI làm ẩu". Bạn cài nó vào công cụ đang dùng như Claude Code, Cursor hay Codex CLI, rồi gõ lệnh dạng `/impeccable critique the pricing cards`.

Vấn đề nó giải quyết rất quen: nhờ AI làm một trang web mà không dặn gì thêm, bạn hay nhận về cùng một kiểu giao diện. Phông Inter cho mọi thứ, nền chuyển màu tím sang xanh, thẻ lồng trong thẻ, chữ xám đặt trên nền màu, ô icon bo tròn nằm trên mỗi tiêu đề. README gọi đó là "AI slop". Impeccable ra đời để tránh và bắt những lỗi này.

Bài này dành cho người làm kinh doanh, văn phòng hoặc lập trình viên mới, đã có một coding agent và muốn giao diện làm ra trông có chủ đích hơn. Điểm đáng giá nhất là hai thứ đi cùng nhau: bộ lệnh để ra chỉ dẫn thiết kế rõ ràng, và bộ dò lỗi gồm 62 quy tắc cố định, chạy không cần LLM, không cần API key. Repo hiện có khoảng 108.996 sao và 6.492 fork, giấy phép Apache-2.0.

```repo
- repo | pbakaus/impeccable
- kind | Skill
- desc | Bộ từ vựng thiết kế cho coding agent: ra lệnh bolder, polish, critique, audit và có công cụ bắt lỗi giao diện kiểu AI mà không cần API key.
- stars | 109k
- lang | Rust
- license | Apache-2.0
```

## Impeccable làm được gì

Impeccable gồm ba phần chính.

**Bộ lệnh thiết kế (24 lệnh).** Thay vì nói mơ hồ "làm cho nó nổi bật", bạn gọi đúng tên động tác. README chia lệnh thành các nhóm:

- **Chỉnh hướng:** `bolder` làm thiết kế an toàn trở nên mạnh hơn, `quieter` làm dịu thiết kế quá ồn, `distill` bỏ bớt thứ trang không cần, `colorize` thêm màu cho giao diện xám xịt, `typeset` sửa phông chữ và thứ bậc, `layout` sửa khoảng cách và nhịp trang, `animate` thêm chuyển động, `delight` thêm cá tính, `overdrive` đi xa hơn với hiệu ứng.
- **Đánh giá:** `critique` chấm điểm trải nghiệm người dùng và xếp thứ tự việc cần sửa. `audit` kiểm tra kỹ thuật như khả năng truy cập, hiệu năng, giao diện sáng tối, co giãn màn hình, với mức từ P0 (chặn phát hành) đến P3 (chỉnh cho đẹp).
- **Hoàn thiện:** `polish` là lượt rà cuối trước khi giao, `harden` xử lý lỗi, nhiều ngôn ngữ, tràn chữ và tình huống biên, `clarify` viết lại câu chữ khó hiểu, `adapt` lo màn hình và thiết bị, `optimize` tăng tốc tải, `onboard` thiết kế màn hình lần đầu dùng và trạng thái trống.
- **Lặp trực tiếp:** `live` cho bạn chọn một phần tử trên trình duyệt rồi xem các biến thể, `generate` tạo biến thể cho phần tử bạn gọi tên.
- **Lập kế hoạch và thiết lập:** `shape` lên kế hoạch UX trước khi viết code, `init` tạo file `PRODUCT.md`, `document` tạo `DESIGN.md`, `extract` gom các mẫu lặp lại vào hệ thống thiết kế.

Lợi ích thực tế: lệnh càng cụ thể, agent càng ít phải đoán. Ví dụ `/impeccable bolder the pricing cards` nạp một bản hướng dẫn riêng cho đúng động tác đó và chỉ nhắm vào đúng mục tiêu.

**Bộ dò lỗi.** 62 quy tắc cố định phát hiện các dấu hiệu quen thuộc ở trên, cùng một số vấn đề chất lượng như đệm quá chật hay nhảy cấp tiêu đề. Nó chạy được trong agent, trong terminal hoặc CI, và qua tiện ích Chrome.

**Ngữ cảnh dự án.** Lệnh `init` đọc code của bạn, hỏi những gì nó không tự suy ra được (sản phẩm dành cho ai, cần làm gì, ràng buộc nào) và ghi vào `PRODUCT.md`. Các lệnh sau đều đọc file này nên kết quả bám đúng dự án.

Theo README, Impeccable mạnh nhất khi làm với giao diện đã có sẵn: bạn trỏ vào một trang hoặc một component rồi lặp dần. Nó cũng dựng được trang mới, nhưng README gọi đó là chế độ khó hơn.

## Cần chuẩn bị gì

- **Một coding agent đã cài sẵn.** README liệt kê các công cụ tương thích: Claude Code, Cursor, Codex CLI, GitHub Copilot, Devin, Replit Agent, Gemini CLI, Grok Build, OpenCode, Google Antigravity, Kiro, Trae, Rovo Dev, Qoder, Mistral Vibe, Pi, Hermes Agent, DeepSeek Harness và Veto.
- **Node.js từ 18.19.0 trở lên** (theo `package.json`). README nói Node chỉ cần cho lệnh `npx`; bản thân skill chạy bằng một engine tự chứa, đi kèm hoặc tải về một lần vào `~/.impeccable/bin/`.
- **Một dự án giao diện** để thử, tốt nhất là dự án web có sẵn một trang hoặc component.
- **Không cần API key** cho bộ dò lỗi, README nói rõ "No LLM, no API key". Agent của bạn vẫn dùng tài khoản và chi phí riêng của nó như bình thường.
- **Chrome hoặc Edge** nếu muốn quét một trang web đang chạy bằng CLI (README: dùng Chrome hoặc Edge bạn đã cài).
- Về hệ điều hành hay phần cứng cụ thể, README đoạn được cung cấp chưa nêu rõ.

## Cài đặt từng bước

```steps
- Mở terminal ở thư mục dự án | Đứng đúng gốc dự án trước khi cài
- Chạy npx impeccable install | Trình cài đặt tự dò công cụ coding agent của bạn
- Chọn phạm vi và nhận hook | Chọn project hay global, và đồng ý cài design hook
- Tải lại công cụ | Khởi động lại hoặc reload để agent nhận skill
- Chạy /impeccable init | Tạo PRODUCT.md mô tả sản phẩm của bạn
```

### Mở terminal đúng chỗ

README yêu cầu chạy lệnh "from your project root", tức là từ thư mục gốc của dự án. Người mới hay vấp ở đây: nếu mở terminal ở nơi khác, skill sẽ cài nhầm chỗ. Bạn có thể dùng terminal tích hợp trong VS Code hoặc Cursor, nó thường mở sẵn đúng thư mục dự án.

### Chạy trình cài đặt

```bash
npx impeccable install
```

Trình cài đặt dò các công cụ coding agent trên máy, hỏi bạn muốn cài cho dự án này hay cài toàn cục, và đề nghị cài design hook ở công cụ nào hỗ trợ. README khuyên: hãy đồng ý cài hook, vì đó là nơi phần lớn lỗi AI được bắt trước khi agent báo xong việc.

Muốn cài không cần trả lời câu hỏi (ví dụ trong script), README cho phép truyền sẵn `--providers=claude,codex,cursor` và `--scope=project|global`. Để làm mới bản đã cài, dùng `npx impeccable update`.

### Bước thêm cho vài công cụ

Ba công cụ cần thêm một bước trước khi hook chạy:

- **Codex:** mở `/hooks` và duyệt hook của dự án (duyệt lại sau khi cập nhật nếu hook đổi).
- **Grok Build:** chạy `/hooks-trust` hoặc khởi động với `--trust`.
- **Hermes Agent:** hook là một plugin, chạy một lần `hermes plugins enable impeccable-design-hook`.

### Tải lại công cụ rồi khởi tạo

Sau khi cài, reload công cụ coding của bạn. Rồi trong khung chat của agent, gõ:

```
/impeccable init
```

Trên Codex, dùng `$impeccable init`. Lệnh này chỉ cần chạy một lần cho mỗi dự án. Nó sẽ hỏi vài câu về sản phẩm và ghi `PRODUCT.md`. Nếu muốn giữ nguyên phong cách hiện có, chạy tiếp `/impeccable document` để ghi hệ thống hình ảnh vào `DESIGN.md`.

### Các cách cài khác

README còn nêu mấy đường khác, bạn chỉ cần khi cách trên không hợp:

- **Claude Code dạng plugin:** `/plugin marketplace add pbakaus/impeccable`, rồi mở `/plugin` và cài Impeccable.
- **GitHub Copilot trong VS Code:** cài từ Visual Studio Marketplace hoặc chạy `code --install-extension renaissance-geek.impeccable`. Cách này cài skill nhưng không có hook.
- **Grok Build:** `grok plugin install pbakaus/impeccable#plugin --trust`.
- **Git submodule** (cố định một phiên bản cho cả nhóm):

```bash
git submodule add https://github.com/pbakaus/impeccable vendor/impeccable
npx impeccable link --source=vendor/impeccable --providers=claude,cursor
```

Sau đó commit `.gitmodules`, submodule và các liên kết sinh ra. Đồng đội chạy `git submodule update --init --recursive`.

- **Chép tay, không cần Node:** tải ZIP trên trang impeccable.style hoặc clone repo, rồi chép thư mục `skills/impeccable` của công cụ bạn dùng vào đúng chỗ. Ví dụ README đưa ra:

```bash
mkdir -p your-project/.claude/skills && cp -r.claude/skills/impeccable your-project/.claude/skills/
```

Chép tay sẽ không có hook và subagent. Muốn đủ bộ, hãy chạy `npx impeccable install`.

```note
Hook của Claude Code chạy ngoài sự phê duyệt của model: kể cả khi bạn từ chối lệnh của model, hook đã cài vẫn chạy, và lần sửa đầu tiên có thể tải engine về. Hãy xem lại các hook đã cài trước khi để agent chạy không người giám sát.
```

## Kiểm tra đã chạy được chưa

Cách đơn giản nhất: trong agent, gõ riêng `/impeccable` (không kèm gì). README nói lệnh này hiện danh sách các lệnh con. Nếu thấy danh sách, skill đã được nạp. Trên Codex, mở `/skills` hoặc gõ `$impeccable`.

Bạn cũng thử bộ dò lỗi ngay trong terminal, không cần agent:

```bash
npx impeccable detect src/
```

Theo README, mã thoát `2` nghĩa là có phát hiện lỗi, `1` nghĩa là không quét được mục tiêu. Muốn xem toàn bộ quy tắc:

```bash
npx impeccable detect --list-rules
```

Nếu có gì bất thường, gõ `/impeccable doctor`. Lệnh này tìm file ngữ cảnh cũ, thiết lập thừa và hook hỏng.

## Dùng vào việc thật

### Chủ shop nhờ rà bảng giá

Bạn có trang bán khoá học tự dựng bằng agent, phần bảng giá nhìn "na ná mọi trang khác". Hãy nhắm vào đúng một phần:

```
/impeccable critique the pricing cards
```

Bạn nhận về bản đánh giá có chấm điểm theo các nguyên tắc dùng được, kèm thứ tự việc cần sửa trước. Sau đó chọn một động tác, ví dụ `/impeccable bolder the pricing cards`, để agent chỉnh có định hướng thay vì đoán.

> Một phần được xem kỹ luôn tốt hơn cả trang được liếc qua.
>
> — Ông T

Đó cũng là lời khuyên của README: mục tiêu hẹp cho kết quả tốt hơn.

### Nhân viên văn phòng chuẩn bị giao trang nội bộ

Bạn dựng xong một trang đăng ký sự kiện cho công ty và sắp gửi sếp. Chạy lần lượt:

```
/impeccable polish settings
/impeccable harden checkout
```

Thay `settings` và `checkout` bằng tên phần của bạn. `polish` là lượt rà cuối, `harden` lo các trường hợp lỗi, chữ quá dài và nhiều ngôn ngữ. Kết quả là những chỗ dễ vỡ được xử lý trước khi người dùng thật gặp.

### Lập trình viên đưa kiểm tra vào CI

Bạn muốn mỗi lần đẩy code đều quét lỗi giao diện. README có sẵn các lệnh:

```bash
npx impeccable detect src/ # scan a directory
npx impeccable detect --json. # machine-readable output
npx impeccable detect --github src/ # GitHub Actions annotations
```

Với file nguồn như JSX/TSX, bộ dò chỉ áp quy tắc theo mẫu. Các quy tắc cần trang đã dựng (chữ tương phản thấp, chữ quá nhỏ) chỉ chạy khi quét URL, ví dụ `npx impeccable detect http://localhost:5173`. Nếu công ty dùng phông Inter làm phông thương hiệu, cho phép nó bằng:

```bash
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
```

### Người làm giao diện thử nhiều hướng ngay trên trình duyệt

Bạn đang chạy dev server và muốn xem vài biến thể cho một nút hoặc một khối. Gõ `/impeccable live`. Công cụ mở trang đang chạy kèm lớp phủ; bạn chọn phần tử, chọn hướng, các biến thể được thay trực tiếp, và khi bạn chấp nhận một biến thể thì nó được ghi ngược vào mã nguồn. README nói chế độ này chạy với Vite, Next, SvelteKit, Astro, Nuxt và HTML thuần.

```note
Chế độ live chỉ dùng trên bản checkout cục bộ. Đừng gắn nó vào site đã triển khai và đừng nới CSP của môi trường thật để nó chạy. Khi áp dụng chỉnh sửa chữ, nó có thể chạy script impeccable:manual-edit-validate trong package.json của bạn, hoặc gọi CLI codex/claude với quyền kiểm duyệt tắt. Muốn giữ việc này trong khung chat, đặt IMPECCABLE_LIVE_COPY_AGENT=chat; muốn tắt Apply, đặt off.
```

## Lỗi hay gặp và cách xử lý

**Gõ `/impeccable` mà agent không nhận.** Thường do chưa reload công cụ sau khi cài. Hãy khởi động lại hoặc tải lại rồi thử. Trên Codex, dùng `$impeccable`. Cursor và Gemini CLI, theo README, có thể cần bật Agent Skills trong cài đặt; Trae cần khởi động lại sau khi chép tay; OpenCode cần chép thêm `.opencode/commands/impeccable.md` vào dự án.

**Hook không chạy trên Codex, Grok Build hoặc Hermes.** Ba công cụ này cần bước duyệt riêng: `/hooks` trên Codex, `/hooks-trust` hoặc `--trust` trên Grok Build, `hermes plugins enable impeccable-design-hook` trên Hermes. Hermes còn cần `hermes skills trust` từ gốc dự án nếu dùng skill nằm trong dự án.

**Quét file JSX/TSX không thấy lỗi tương phản hay chữ nhỏ.** Đây là thiết kế chứ không phải hỏng: các quy tắc đó cần trang đã dựng. Hãy quét URL của dev server, ví dụ `npx impeccable detect http://localhost:5173`.

**Chép tay xong nhưng thiếu hook.** Bản chép tay không có hook và subagent. Chạy `npx impeccable install` để cài đầy đủ.

**File làm việc của Impeccable làm bẩn git.** Công cụ ghi file tạm dưới `.impeccable/`. README khuyên giữ `PRODUCT.md`, `DESIGN.md` và vài file dùng chung (`config.json`, `design.json`...) trong repo, còn ảnh chụp, cache và trạng thái chạy thì nên ignore bằng các dòng `.gitignore` mà README cung cấp. Lưu ý `.gitignore` không bỏ theo dõi được file git đã theo dõi từ trước; khi đó README hướng dẫn dùng `git rm --cached`.

Nếu vẫn chưa rõ nguyên nhân, `/impeccable doctor` là chỗ nên thử trước.

## Có nên dùng không

**Điểm mạnh.** Bạn có "ngôn ngữ chung" với agent: thay vì nói chung chung, bạn gọi đúng tên động tác và đúng mục tiêu. Bộ dò lỗi chạy không cần LLM hay API key, nên rẻ và lặp lại được, phù hợp để đặt vào CI. Một lệnh `npx impeccable install` hỗ trợ rất nhiều công cụ, kể cả cách chép tay không cần Node.

**Giới hạn.** Theo README, Impeccable mạnh nhất khi cải thiện giao diện đã có; dựng trang hoàn toàn mới là chế độ khó hơn. Bộ dò, chế độ live và hook sửa file chỉ dành cho web (HTML/CSS); với ứng dụng di động, README nói các lệnh dùng quy ước của Apple HIG hay Material 3 và `audit` đọc được SwiftUI, Compose, React Native hay Flutter, nhưng phần dò và live vẫn chỉ cho web. Hook chạy ngoài phê duyệt của model, và chế độ live có thể gọi agent với quyền kiểm duyệt tắt, nên bạn cần đọc kỹ trước khi dùng trong repo lạ.

**Về dữ liệu.** Khi bắt đầu một thiết kế mới, skill tải một bộ hướng hình ảnh từ danh mục trên impeccable.style. Tắt telemetry không ngăn yêu cầu này, chỉ ngăn bản ghi ẩn danh về hướng nào được hiển thị và bạn chọn hướng nào. README nói tên dự án, file, code và `PRODUCT.md` không bao giờ bị gửi. Tắt telemetry bằng `npx impeccable telemetry off`, biến `DO_NOT_TRACK=1`, hoặc `"telemetry": false` trong `.impeccable/config.json`.

**Khi nên chọn cách khác.** Nếu bạn chưa dùng coding agent nào, bộ lệnh này chưa có nhiều tác dụng. Nếu chỉ cần kiểm tra lỗi giao diện đơn giản, riêng lệnh `npx impeccable detect` là đủ, không cần cài vào agent. Nếu dự án không phải giao diện (backend thuần), repo này không phục vụ bạn. Còn nếu bạn đang làm giao diện web bằng AI và thấy sản phẩm nào cũng giống nhau, đây là một công cụ đáng thử trên một component trước.

## Câu hỏi thường gặp

### Impeccable có miễn phí không?

Repo dùng giấy phép Apache-2.0. Bộ dò lỗi, theo README, không cần LLM và không cần API key. Chi phí của agent bạn dùng (như Claude Code hay Cursor) vẫn tính theo gói của chính công cụ đó, tư liệu không nói thêm về giá.

### Cài Impeccable cần những gì?

Bạn cần Node.js từ 18.19.0 trở lên để chạy npx, và một coding agent được hỗ trợ. Lệnh cài là npx impeccable install, chạy từ thư mục gốc dự án. Có cả cách chép tay không cần Node nếu bạn không muốn dùng npx.

### Impeccable có cần GPU không?

Tư liệu không nêu yêu cầu GPU. README chỉ nói skill chạy bằng một engine tự chứa, đi kèm hoặc tải một lần vào ~/.impeccable/bin/, và bộ dò chạy bằng quy tắc cố định chứ không dùng mô hình AI.

### Dùng được với những công cụ nào?

README liệt kê Claude Code, Cursor, Codex CLI, GitHub Copilot, Devin, Replit Agent, Gemini CLI, Grok Build, OpenCode, Google Antigravity, Kiro, Trae, Rovo Dev, Qoder, Mistral Vibe, Pi, Hermes Agent, DeepSeek Harness và Veto. Hook tự động chỉ có ở một số công cụ như Claude Code, Cursor, Codex, GitHub Copilot, Grok Build và Hermes Agent.

### Dữ liệu và code của tôi có bị gửi đi đâu không?

Theo README, tên dự án, file, code và PRODUCT.md không bao giờ được gửi. Skill có tải bộ hướng hình ảnh từ danh mục impeccable.style khi bắt đầu một thiết kế mới, và có bản ghi ẩn danh về hướng nào được hiển thị và chọn, bạn có thể tắt bản ghi này bằng npx impeccable telemetry off hoặc DO_NOT_TRACK=1. Chế độ live có thể gọi CLI codex hoặc claude với quyền kiểm duyệt tắt, nên hãy đọc kỹ mục lưu ý trước khi dùng.

### Khác gì so với việc tự viết prompt thiết kế cho agent?

Impeccable đóng gói sẵn các động tác thiết kế thành lệnh có tên, như bolder, quieter, polish, audit, mỗi lệnh nạp một bản hướng dẫn riêng, và đọc PRODUCT.md của dự án để bám đúng ngữ cảnh. Nó còn có bộ dò 62 quy tắc chạy ngoài agent. Tư liệu chưa so sánh trực tiếp với công cụ cụ thể nào khác.

### Impeccable có chạy được trên Windows không?

Tư liệu README được cung cấp không nêu rõ danh sách hệ điều hành hỗ trợ. Điều đã biết là cần Node từ 18.19.0 để dùng npx, và có bảng thư mục skill theo từng công cụ để chép tay. Nếu dùng Windows, bạn nên xem trang docs của dự án hoặc thử lệnh cài trên một dự án nhỏ trước.
