# Impeccable: bộ lệnh thiết kế giúp AI viết giao diện đẹp — hướng dẫn cài đặt và dùng

> Impeccable là một skill thiết kế cho coding agent (Claude Code, Cursor, Codex CLI…). Nó cho bạn các lệnh như polish, bolder, critique, audit để chỉ đạo và kiểm tra giao diện do AI tạo ra. Cài bằng một lệnh npx ở thư mục dự án nên khá dễ, nhưng bạn cần đã có sẵn một công cụ coding agent.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-27 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/impeccable-bo-lenh-thiet-ke-cho-coding-agent-huong-dan-cai-dat

Impeccable là một bộ "từ vựng thiết kế" cài vào coding agent của bạn (Claude Code, Cursor, Codex CLI và nhiều công cụ khác). Có nó, bạn không cần nói mơ hồ kiểu "làm cho đẹp lên" nữa. Bạn gọi đúng tên động tác, ví dụ `polish`, `bolder`, `quieter`, rồi để agent làm theo một quy trình viết sẵn cho đúng động tác đó. Repo hiện có khoảng 109.000 sao và khoảng 6.500 fork, giấy phép Apache-2.0.

Vấn đề nó giải quyết rất quen. Nhờ AI dựng một trang web mà không dặn gì thêm, bạn hay nhận về cùng một kiểu: chữ Inter cho mọi thứ, nền gradient tím sang xanh, thẻ lồng trong thẻ, chữ xám trên nền màu, ô icon bo tròn đặt trên mỗi tiêu đề. README gọi đó là "AI slop", tức giao diện làm ẩu theo công thức chung. Impeccable vừa giúp bạn chỉ đạo AI cụ thể hơn, vừa có bộ kiểm tra để bắt những lỗi này trước khi bạn đưa sản phẩm ra.

Người nên dùng là chủ shop hoặc nhân viên văn phòng đang nhờ AI dựng trang giới thiệu, và lập trình viên mới muốn giao diện bớt "đồ AI". Điểm đáng giá nhất theo mình là bộ dò lỗi: 62 quy tắc cố định, chạy không cần LLM và không cần API key, nên dùng được cả trong terminal lẫn CI.

```repo
- repo | pbakaus/impeccable
- kind | Skill
- desc | Impeccable cho coding agent bộ lệnh thiết kế như bolder, polish, critique, audit và bộ dò 62 quy tắc để bắt giao diện kiểu AI làm ẩu.
- stars | 109k
- lang | Rust
- license | Apache-2.0
```

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

### Lệnh để chỉ đạo thiết kế

README liệt kê 24 lệnh, chia theo nhóm việc. Bạn không cần nhớ hết, chỉ cần biết mỗi nhóm để làm gì:

- **Steer (điều hướng):** `bolder` làm đậm một thiết kế quá an toàn, `quieter` làm dịu thiết kế quá ồn, `distill` bỏ những gì trang không cần, `colorize` thêm màu cho giao diện xám xịt, `typeset` chỉnh phông chữ và thứ bậc chữ, `layout` chỉnh khoảng cách và nhịp trình bày, `animate` thêm chuyển động, `delight` thêm cá tính, `overdrive` đẩy tới hiệu ứng nặng như shader hay cuộn có hiệu ứng.
- **Review (đá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: khả năng truy cập, hiệu năng, theme, hiển thị đa kích thước màn hình, với mức từ P0 (chặn) đến P3 (chỉnh cho đẹp).
- **Finish (hoàn thiện):** `polish` là lượt chỉnh cuối trước khi đưa ra, `harden` lo lỗi, đa ngôn ngữ, tràn chữ và các trường hợp biên, `clarify` viết lại câu chữ khó hiểu, `adapt` lo màn hình và thiết bị, `optimize` lo tốc độ tải, `onboard` thiết kế luồng lần đầu dùng và màn hình trống.
- **Iterate live:** `live` cho bạn chọn một phần tử ngay trên trình duyệt rồi xem nhiều phương án. `generate` tạo các phương án cho một phần tử mà không cần bạn bấm chọn.
- **Plan and set up:** `shape` lên kế hoạch UX trước khi viết code, `init` tạo `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ệnh thứ 24 là `craft`, README ghi là bí danh đã bị loại bỏ, tương đương một yêu cầu "hãy xây" bình thường.

### Bộ dò lỗi thiết kế

Có 62 quy tắc cố định để phát hiện các dấu hiệu AI làm ẩu, cộng với lỗi chất lượng như đệm quá sát hay nhảy cấp tiêu đề. Bộ này không dùng LLM và không cần API key, nên kết quả lặp lại được và chạy rẻ.

### Bốn cách chạy bộ dò

Bạn có thể chạy ngay trong agent (qua hook tự quét mỗi file giao diện mà agent sửa), chạy bằng lệnh CLI trong terminal hoặc CI, hoặc dùng tiện ích mở rộng Chrome để xem lỗi chồng lên bất kỳ trang nào đang mở.

### File ngữ cảnh để giữ đúng thương hiệu

`init` viết file `PRODUCT.md` (sản phẩm cho ai, cần làm gì, ràng buộc gì). `document` viết `DESIGN.md` ghi lại hệ thống hình ảnh hiện có. Các lệnh sau đều đọc hai file này nên kết quả bám đúng sản phẩm của bạn.

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

Theo tư liệu, bạn cần:

- **Một coding agent đã dùng được.** README liệt kê các công cụ hỗ trợ: 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 từ phiên bản 18.19.0 trở lên**, vì `package.json` yêu cầu như vậy. README nói Node chỉ cần cho lệnh `npx`. Bản thân skill chạy bằng một engine đóng gói sẵn đi kèm, hoặc tải một lần về thư mục `~/.impeccable/bin/`.
- **Một dự án có sẵn** để thử. README nói công cụ mạnh nhất với giao diện đã tồn tại: chỉ vào một trang hoặc một thành phần rồi chỉnh dần.
- Muốn quét một trang đã hiển thị bằng CLI thì cần Chrome hoặc Edge đã cài trên máy.

Tư liệu không nêu yêu cầu GPU, dung lượng ổ đĩa hay hệ điều hành cụ thể cho cả bộ công cụ. Riêng tiện ích cho VS Code cần VS Code 1.109.3 trở lên, Copilot Chat và một workspace đã tin cậy.

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

```steps
- Mở terminal đúng chỗ | Vào thư mục gốc của dự án bạn đang làm
- Chạy trình cài | Gõ npx impeccable install và chọn công cụ, phạm vi cài
- Chấp nhận hook | Đồng ý để cài hook kiểm tra thiết kế tự động
- Tải lại công cụ | Khởi động lại hoặc reload coding agent
- Khởi tạo dự án | Chạy /impeccable init để tạo PRODUCT.md
- Thử một lệnh | Chạy /impeccable critique trên một thành phần
```

### Mở terminal ở thư mục dự án

README ghi rõ: chạy từ thư mục gốc của dự án. Đây là chỗ người mới hay vấp nhất. Nếu bạn mở terminal ở thư mục khác, bản cài sẽ nằm sai chỗ. Ví dụ bạn có dự án ở `my-site`:

```bash
cd my-site
```

### Chạy trình cài

Đây là lệnh chính trong README:

```bash
npx impeccable install
```

`npx` tải và chạy gói `impeccable` mà không cần cài trước. Trình cài sẽ 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 hook thiết kế nếu công cụ của bạn hỗ trợ. README khuyên bạn nên đồng ý cài hook.

Nếu cần chạy tự động trong script, README cho phép chỉ định sẵn công cụ và phạm vi:

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

Phạm vi có hai giá trị `project` hoặc `global`. Muốn làm mới bản đã cài, dùng:

```bash
npx impeccable update
```

### Bước thêm cho ba công cụ

Ba công cụ cần thêm một thao tác thì hook mới chạy:

- **Codex:** mở `/hooks` và duyệt hook của dự án (duyệt lại sau mỗi bản cập nhật có đổi hook).
- **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 lệnh sau:

```bash
hermes plugins enable impeccable-design-hook
```

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

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

```
/impeccable init
```

Trên Codex, bạn gõ `$impeccable init`. Lệnh này chỉ cần chạy một lần cho mỗi dự án. Nó đọc code của bạn, chỉ hỏi những gì không tự suy ra được (sản phẩm cho ai, cần làm gì, ràng buộc), rồi ghi `PRODUCT.md`. Muốn ghi lại hệ thống hình ảnh sẵn có, chạy tiếp `/impeccable document` để tạo `DESIGN.md`.

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

Nếu không dùng `npx`, README có thêm vài đường:

- **Claude Code (plugin):** gõ `/plugin marketplace add pbakaus/impeccable`, sau đó mở `/plugin` và cài Impeccable.
- **GitHub Copilot trong VS Code:** cài tiện ích từ Visual Studio Marketplace, hoặc chạy lệnh dưới đây. Bản này cài skill nhưng không có hook.

```bash
code --install-extension renaissance-geek.impeccable
```

- **Grok Build:**

```bash
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 vừa tạo. Đồng đội chỉ cần chạy `git submodule update --init --recursive`. Cách này chỉ cài skill, không cài hook.

- **Chép tay, không cần Node:** tải file ZIP cho công cụ của bạn từ trang impeccable.style, hoặc clone repo rồi chép thư mục `skills/impeccable` sang đúng chỗ trong dự án. Ví dụ cho Claude Code:

```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. Bảng đầy đủ thư mục của từng công cụ nằm trong README, mục Installation.

```note
Hook trong 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 có người trông. README cũng cho biết có thể tắt hook cho một lượt chạy bằng cờ --settings với disableAllHooks.
```

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

Cách kiểm tra đơn giản nhất là gõ `/impeccable` một mình trong agent. README nói lệnh này hiện danh sách các lệnh. Nếu danh sách hiện ra, skill đã nạp xong. Trên Codex, mở `/skills` hoặc gõ `$impeccable`.

Tiếp theo, chạy thử `/impeccable init` và xem nó có hỏi bạn về sản phẩm rồi tạo `PRODUCT.md` ở thư mục dự án không. Nếu cài hook, thử nhờ agent sửa một file giao diện: README nói hook sẽ quét file đó và trả kết quả về cho agent trước khi nó báo là xong.

Còn nếu thấy có gì trục trặc, README có sẵn lệnh chẩn đoán:

```
/impeccable doctor
```

Lệnh này tìm file ngữ cảnh đã cũ, cài đặt không dùng và hook bị hỏng.

Bạn cũng có thể thử bộ dò độc lập, không cần agent:

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

Lệnh này in ra mọi quy tắc cùng mã và mô tả.

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

### Chủ shop nhờ AI chấm điểm trang bảng giá

Bạn bán dịch vụ và đã nhờ AI dựng trang bảng giá. Nhìn vào thấy hơi chung chung nhưng không biết sửa gì. Trong agent, gõ:

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

Đây chính là ví dụ khởi đầu README đề nghị. `critique` chấm thiết kế theo các tiêu chí dễ dùng và xếp thứ tự việc cần sửa trước. Bạn nhận được một danh sách ưu tiên thay vì cảm giác mơ hồ. README lưu ý: mục tiêu hẹp cho kết quả tốt hơn, nên chọn một thành phần thay vì cả trang.

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

### Nhân viên văn phòng làm cho trang bớt nhạt hoặc bớt ồn

Trang giới thiệu công ty của bạn trông an toàn đến mức nhạt. Bạn gõ:

```
/impeccable bolder the landing page
```

Nếu ngược lại, trang quá rối, dùng `quieter`. README viết rằng `bolder` nạp một bộ hướng dẫn riêng cho đúng động tác đó và nhắm vào đúng một mục tiêu. Bạn cũng có thể mô tả bằng lời thường, ví dụ `/impeccable redo this hero section`.

### Lập trình viên kiểm tra trước khi đưa lên

Trước khi đẩy lên, bạn chạy lượt cuối và kiểm tra kỹ thuật:

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

`polish` là lượt chỉnh cuối, `harden` lo lỗi, tràn chữ và trường hợp biên, `audit` cho báo cáo xếp từ P0 đến P3. Nếu dùng lệnh nào thường xuyên, ghim nó lại bằng `/impeccable pin audit` để có luôn `/audit` làm lối tắt.

### Đội dev đặt bộ dò vào CI

Cả nhóm muốn chặn giao diện kém chất lượng ngay từ lúc gộp code. CLI không cần agent:

```bash
npx impeccable detect src/
npx impeccable detect --github src/
npx impeccable detect http://localhost:5173
```

Dòng đầu quét một thư mục, dòng hai in chú thích cho GitHub Actions, dòng ba quét trang đang chạy ở máy bạn (cần để bắt các lỗi như độ tương phản thấp hay chữ quá nhỏ, vì chúng chỉ phát hiện được trên trang đã hiển thị). 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. Nếu thương hiệu của bạn cố ý dùng phông Inter, cho phép nó bằng:

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

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

### Gõ /impeccable mà không thấy gì

Thường do chưa reload công cụ sau khi cài, hoặc cài sai thư mục. Hãy khởi động lại agent, xác nhận bạn chạy `npx impeccable install` ở thư mục gốc dự án. Với Cursor và Gemini CLI, README nói có thể phải bật Agent Skills trong phần cài đặt. Với OpenCode, cần chép thêm `.opencode/commands/impeccable.md` vào dự án để có lệnh `/impeccable`. Trae thì cần khởi động lại sau khi chép tay.

### Hook không chạy

Codex, Grok Build và Hermes Agent cần bước duyệt riêng như ở phần cài đặt. Nếu đã làm mà vẫn không thấy gì, chạy `/impeccable doctor` để tìm hook hỏng.

### Bộ dò báo ít lỗi khi quét mã nguồn

Với file JSX hay TSX, bộ dò chỉ áp dụng các quy tắc theo mẫu. Các quy tắc cần trang đã hiển thị, như độ tương phản thấp và chữ quá nhỏ, chỉ chạy khi bạn quét một địa chỉ URL. Hãy bật dev server rồi quét đường dẫn localhost.

### Quét URL báo không quét được

Mã thoát `1` nghĩa là không quét được mục tiêu. Với trang đã hiển thị, README nói CLI dùng Chrome hoặc Edge bạn đã cài, nên hãy kiểm tra máy có một trong hai trình duyệt đó và địa chỉ có truy cập được.

### Lệnh live mode làm bạn lo

Chế độ `live` mở dev server của bạn kèm lớp phủ chọn phần tử. Nó chỉ dành cho bản checkout ở máy bạn, đừng chèn vào trang đã triển khai và đừng nới lỏng CSP của bản production để nó chạy. Khi áp dụng chỉnh sửa chữ, nó chạy script `impeccable:manual-edit-validate` tùy chọn trong `package.json` bằng quyền của bạn, nên hãy đọc script đó trước khi dùng trong repo lạ.

```note
Khi bấm Apply trong live mode mà không có agent chat nào đang nhận, README nói công cụ có thể chạy lệnh codex (hoặc claude nếu thiếu codex) trong PATH với phê duyệt, kiểm tra quyền và sandbox đều tắt. Nếu bạn muốn giữ việc này trong phiên chat, đặt biến môi trường IMPECCABLE_LIVE_COPY_AGENT=chat khi khởi động live mode, hoặc đặt off để tắt Apply.
```

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

**Điểm mạnh.** Bạn có ngôn ngữ chung để nói chuyện với AI về thiết kế: nói tên động tác thay vì mô tả dài dòng. Bộ dò 62 quy tắc chạy không cần LLM và API key, dùng được cả trong terminal lẫn CI. Công cụ hỗ trợ rất nhiều agent, giấy phép Apache-2.0, và repo vẫn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Công cụ này không thay thế một người thiết kế thật. README nói nó mạnh nhất khi làm việc trên giao diện đã có, còn dựng trang mới là chế độ khó hơn. Bộ dò, live mode và hook sửa file chỉ dành cho web (HTML và CSS), còn ứng dụng gốc iOS hay Android chỉ được hỗ trợ ở các lệnh thiết kế và `audit`. Hook chạy ngoài sự phê duyệt của model và live mode có thể chạy lệnh với quyền rộng, nên cần đọc kỹ trước khi dùng trong repo lạ hoặc chạy không người trông.

**Về dữ liệu.** README ghi rằng khi bắt đầu một thiết kế mới, skill tải một bộ hướng thiết kế từ danh mục của impeccable.style. Tắt telemetry không chặn yêu cầu đó, chỉ chặn bản ghi ẩn danh về hướng nào được hiển thị và bạn chọn hướng nào. Tên dự án, file, code và `PRODUCT.md` không bị gửi đi. Tắt telemetry bằng `npx impeccable telemetry off`, hoặc `DO_NOT_TRACK=1`.

**Khi nên chọn cách khác.** Nếu bạn chưa dùng coding agent nào, hãy làm quen với một công cụ trước. Nếu chỉ cần kiểm tra giao diện của một trang bất kỳ, tiện ích Chrome hoặc lệnh `detect` là đủ, không cần cài cả skill. Nếu dự án là ứng dụng gốc, hãy nhớ phần dò lỗi tự động không áp dụng cho nó.

Tóm lại, nếu bạn đã dùng AI để dựng giao diện và thấy kết quả cứ na ná nhau, Impeccable là một bổ sung đáng thử. Cài mất một lệnh, và bạn có thể bắt đầu từ một thành phần nhỏ để xem hiệu quả.

## 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 và bộ dò lỗi không cần API key. Tư liệu không nói gì về chi phí của coding agent bạn dùng kèm, nên khoản đó phụ thuộc vào công cụ của bạn.

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

Bạn cần một coding agent được hỗ trợ và Node từ 18.19.0 trở lên để chạy npx. README còn nói có cách chép tay không cần Node. Tư liệu không nêu yêu cầu GPU.

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

Tư liệu không nói rõ về hệ điều hành cho cả bộ công cụ. Lệnh npx impeccable install là lệnh Node thông thường. Nếu gặp vấn đề, bạn có thể chạy /impeccable doctor hoặc xem tài liệu tại impeccable.style/docs.

### Impeccable có gửi code của tôi đi đâu không?

README nói tên dự án, file, code và PRODUCT.md không bao giờ bị gửi đi. Có một yêu cầu tải bộ hướng thiết kế từ danh mục impeccable.style khi bắt đầu thiết kế mới, và telemetry ẩn danh ghi hướng nào được hiển thị và chọn. Bạn có thể tắt telemetry bằng npx impeccable telemetry off hoặc DO_NOT_TRACK=1.

### Khác gì so với tự viết prompt cho AI?

Impeccable gói sẵn các động tác thiết kế có tên (polish, bolder, critique, audit…) mỗi cái nạp một quy trình riêng cho một mục tiêu. Nó còn có bộ dò 62 quy tắc cố định không dùng LLM. Tư liệu không so sánh chi tiết với công cụ khác.

### Dùng được với 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 kiểm tra tự động có trên Claude Code, Cursor, Codex, GitHub Copilot, Grok Build và Hermes Agent.

### Có dùng được cho ứng dụng di động không?

Có một phần. Đặt mục Platform trong PRODUCT.md là ios, android hoặc adaptive thì các lệnh thiết kế dùng chuẩn Apple HIG hoặc Material 3, và audit đọc được mã SwiftUI, Compose, React Native, Flutter. Bộ dò, live mode và hook sửa file chỉ dành cho web.
