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

> Impeccable là một skill thiết kế cho coding agent như Claude Code, Cursor, Codex CLI. Nó cho agent bộ lệnh như polish, bolder, critique, audit để chỉnh và chấm giao diện, kèm bộ dò lỗi thiết kế rập khuôn. Cài bằng một lệnh npx trong thư mục dự án, khá dễ nếu bạn đã có Node.

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

Impeccable là một bộ “từ vựng thiết kế” cài vào coding agent (Claude Code, Cursor, Codex CLI và nhiều công cụ khác). Có nó, bạn ra lệnh cho agent bằng các từ như `polish`, `bolder`, `critique`, `audit` thay vì nói chung chung kiểu “làm cho đẹp lên”. Repo hiện có khoảng 109.000 sao và 6.500 fork, giấy phép Apache-2.0.

Vấn đề nó giải quyết rất quen: nhờ AI làm trang web mà không hướ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 gradient tím xanh, thẻ lồng trong thẻ, chữ xám trên nền màu. Tác giả gọi đó là “AI slop”. Impeccable cho agent cách nói rõ hơn về điều bạn muốn, cho một người chấm bài, và cho một bộ dò các lỗi rập khuôn đó.

Người nên dùng: lập trình viên mới, chủ shop hay nhân viên văn phòng đang nhờ AI dựng trang web, trang giới thiệu, form. Điểm đáng giá nhất là bộ dò gồm 62 luật chạy cố định, không cần mô hình AI và không cần API key. Nó chạy được cả trong terminal hoặc CI mà không cần agent.

```repo
- repo | pbakaus/impeccable
- kind | Skill
- desc | Impeccable cho coding agent bộ lệnh thiết kế như bolder, polish, critique, audit, kèm bộ dò lỗi giao diện kiểu AI rập khuôn, không cần API key.
- stars | 109k
- lang | Rust
- license | Apache-2.0
```

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

**Bộ lệnh để “lái” thiết kế.** README ghi 24 lệnh, chia nhóm:

- Nhóm chỉnh hướng: `bolder` làm thiết kế an toàn mạnh tay hơn, `quieter` hạ bớt thiết kế quá ồn, `distill` bỏ những thứ trang không cần, `colorize` thêm màu cho giao diện xám, `typeset` sửa phông và phân cấp chữ, `layout` sửa khoảng cách và nhịp trình bày, `animate` thêm chuyển động, `delight` thêm cá tính, `overdrive` làm hiệu ứng mạnh như shader hay cuộn có hiệu ứng.
- Nhóm đánh giá: `critique` chấm điểm trải nghiệm người dùng, `audit` ra báo cáo kỹ thuật (khả năng truy cập, hiệu năng, giao diện sáng/tối, responsive) với mức ưu tiên P0 (chặn) đến P3 (chỉnh cho đẹp).
- Nhóm hoàn thiện: `polish` là lượt chỉnh cuối trước khi đưa ra, `harden` xử lý lỗi, đa ngôn ngữ, tràn chữ, 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ị khác nhau, `optimize` tăng tốc tải và hiển thị, `onboard` thiết kế luồng người dùng mới và màn hình trống.
- Nhóm chỉnh trực tiếp: `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 phương án cho một phần tử bạn gọi tên.
- Nhóm lập kế hoạch: `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ợi ích thực tế: câu `/impeccable bolder the pricing cards` chỉ rõ một động tác trên một đối tượng, nên agent đỡ phải đoán.

**Bộ nhớ ngữ cảnh.** Chạy `init` một lần, nó đọc code, 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) và ghi vào `PRODUCT.md`. Các lệnh sau đều đọc file này. `document` ghi hệ thống hình ảnh hiện có vào `DESIGN.md` để chỉnh sửa không lệch phong cách.

**Bộ dò “slop”.** Dò được các dấu hiệu rập khuôn, cộng thêm lỗi chất lượng như đệm quá chật hay nhảy cấp tiêu đề. Chạy được ba nơi: trong agent (qua hook), trong terminal/CI, và qua tiện ích Chrome.

**Chế độ live.** Mở máy chủ dev đang chạy kèm lớp phủ, chọn phần tử, chọn hướng, rồi xem các phương án thay thế tại chỗ. Chấp nhận một phương án thì nó ghi ngược vào mã nguồn. README nói hoạt động với Vite, Next, SvelteKit, Astro, Nuxt và HTML thuần.

Lưu ý: README nói Impeccable mạnh nhất với giao diện đã có sẵn (trỏ vào một trang hay một component rồi chỉnh dần). Dựng trang mới vẫn được nhưng khó hơn.

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

- Một coding agent thuộc danh sách 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, Veto.
- Node từ phiên bản 18.19.0 trở lên, vì lệnh cài chạy qua `npx`. README nói Node chỉ cần cho `npx`; phần skill tự chạy bằng một file engine đi kèm hoặc tải một lần về `~/.impeccable/bin/`.
- Một dự án có sẵn để thử. Mở terminal ngay tại thư mục gốc của dự án đó.
- Không cần API key riêng cho bộ dò. Agent của bạn vẫn dùng tài khoản của chính nó như bình thường.
- Muốn quét một trang đang chạy bằng CLI thì máy cần Chrome hoặc Edge đã cài.
- Riêng GitHub Copilot trong VS Code (cài qua tiện ích): cần VS Code 1.109.3 trở lên, Copilot Chat và workspace đã được tin cậy.

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

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

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

Đây là chỗ người mới hay vấp nhất. README dặn chạy “từ thư mục gốc dự án”. Nếu bạn dùng VS Code, mở thư mục dự án rồi mở terminal tích hợp là đúng chỗ.

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

```bash
npx impeccable install
```

Trình cài tự dò các công cụ lập trình có trên máy, hỏi bạn cài cho dự án này hay cài toàn cục, và đề nghị cài “design hook” nếu công cụ hỗ trợ. Nên đồng ý hook, vì README nói đó là nơi phần lớn lỗi thiết kế được bắt.

Muốn chạy không cần trả lời câu hỏi (ví dụ trong script), README cho phép truyền sẵn:

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

Có thể đổi `project` thành `global`. Cập nhật bản đã cài bằng:

```bash
npx impeccable update
```

### Cho phép hook (nếu dùng Codex, Grok Build hoặc Hermes)

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 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:

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

### Tải lại công cụ và chạy init

Tải lại agent rồi gõ trong khung chat của agent (không gõ vào terminal thường):

```
/impeccable init
```

Trên Codex dùng `$impeccable init`. Agent sẽ hỏi vài câu về sản phẩm của bạn rồi ghi `PRODUCT.md`. Muốn lưu luôn phong cách hình ảnh hiện có thì chạy thêm `/impeccable document`.

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

Dùng Claude Code, bạn có thể cài qua plugin: gõ lệnh sau, rồi mở `/plugin` và chọn cài Impeccable.

```
/plugin marketplace add pbakaus/impeccable
```

Với GitHub Copilot trong VS Code, README ghi:

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

Cách này cài skill nhưng không có hook. Với Grok Build:

```bash
grok plugin install pbakaus/impeccable#plugin --trust
```

Nếu cả team muốn dùng chung một phiên bản cố định, README hướng dẫn dùng git submodule:

```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ạy `git submodule update --init --recursive`. Cách này chỉ cài skill, không cài hook.

Không có Node thì có cách sao chép tay: tải file ZIP cho công cụ của bạn từ trang chủ dự án, hoặc clone repo rồi chép thư mục `skills/impeccable` vào đúng chỗ. Ví dụ README đưa ra cho Claude Code:

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

Bảng thư mục từng công cụ nằm trong README, mục Installation. Cách chép tay không có hook và subagent.

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

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

Có ba cách kiểm tra đơn giản:

1. Trong agent, gõ `/impeccable` một mình. README nói lệnh này liệt kê danh sách các lệnh. Thấy danh sách là skill đã nhận.
2. Chạy thử bộ dò trong terminal. Lệnh này không cần agent:

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

Nó in mọi luật cùng id và mô tả. Thấy danh sách là CLI đã chạy.

3. Nếu thấy lạ, gõ `/impeccable doctor`. README nói lệnh này tìm file ngữ cảnh cũ, cài đặt không dùng và hook hỏng.

Nếu không thấy lệnh `/impeccable`, bạn chưa tải lại công cụ. 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 Trae, cần khởi động lại sau khi chép tay.

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

### Chủ shop muốn chấm lại bảng giá

Bạn nhờ AI dựng trang bán khóa học, nhìn ra “na ná mọi trang AI khác”. Đừng sửa cả trang cùng lúc. README khuyên chọn mục tiêu hẹp, vì một phần được xem kỹ hơn một trang xem lướt. Hãy gõ:

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

Kết quả là một bản chấm điểm theo các nguyên tắc dễ dùng, xếp thứ tự việc nên sửa trước. Sau đó bạn có thể gõ `/impeccable bolder the pricing cards` nếu muốn mạnh tay hơn, hoặc `quieter` nếu thấy quá ồn.

> Nói rõ một động tác lên một mục tiêu, agent sẽ đỡ phải đoán.
>
> — Ông T

### Lập trình viên mới trước khi đưa trang lên

Bạn vừa xong trang thanh toán và sợ sót lỗi. Gõ:

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

`audit` cho báo cáo lỗi xếp từ P0 đến P3. `harden` xử lý lỗi nhập liệu, chữ tràn, đa ngôn ngữ. `polish` là lượt chỉnh cuối. Bạn xử lý P0 trước, P3 để sau.

### Nhóm dev kiểm tra tự động trong CI

Team muốn chặn giao diện “lên đời” kiểu rập khuôn ngay khi tạo pull request. Bộ dò CLI không cần agent:

```bash
npx impeccable detect src/
npx impeccable detect --github src/
```

Lệnh thứ hai xuất chú thích kiểu GitHub Actions. Theo README, mã thoát `2` nghĩa là có phát hiện, mã `1` nghĩa là không quét được mục tiêu. Với file mã nguồn như JSX, TSX chỉ chạy luật theo mẫu. Luật cần trang đã hiển thị (tương phản thấp, chữ quá nhỏ) chạy khi quét URL, ví dụ trang dev của bạn:

```bash
npx impeccable detect http://localhost:5173
```

Nếu thương hiệu của bạn dùng phông Inter thật, cho phép bằng:

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

### Thử nhiều phương án ngay trên trình duyệt

Bạn đang chạy máy chủ dev và muốn xem vài hướng cho phần hero. Gõ `/impeccable live`, chọn phần tử trên trang, chọn hướng, xem các phương án đổi qua lại tại chỗ. Chọn một cái thì nó được ghi vào mã nguồn. Hoặc nói thẳng bằng lời: `/impeccable redo this hero section`.

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

### Gõ `/impeccable` mà agent không nhận

Thường là chưa tải lại công cụ sau khi cài, hoặc công cụ cần bật tính năng skills (Cursor, Gemini CLI). Hãy reload hoặc khởi động lại, kiểm tra cài đặt, rồi chạy `/impeccable doctor`. Nếu vẫn không được, xem trang tài liệu tại impeccable.style/docs.

### Hook không chạy trên Codex, Grok Build hoặc Hermes

Ba công cụ này cần bạn duyệt hook thủ công. Codex: mở `/hooks` và duyệt. Grok Build: `/hooks-trust`. Hermes: lệnh `hermes plugins enable impeccable-design-hook`. Hermes cũng hỏi tin cậy skill của dự án, chạy `hermes skills trust` ở thư mục gốc dự án.

### Quét file JSX/TSX không báo lỗi tương phản

Đây không phải lỗi. Luật cần trang đã hiển thị (tương phản thấp, chữ nhỏ) chỉ chạy khi quét URL. Hãy bật máy chủ dev rồi chạy `npx impeccable detect` với địa chỉ `http://localhost:...` của bạn.

### Lệnh live Apply tự gọi agent khác

Theo README, nếu không có phiên chat nào đang chờ trong vòng một phút, Apply sẽ chạy CLI `codex` (hoặc `claude` nếu không có codex) với phê duyệt và sandbox bị tắt. Muốn giữ mọi thứ trong phiên chat của bạn, đặt biến môi trường `IMPECCABLE_LIVE_COPY_AGENT=chat` trước khi bật live; đặt `off` để tắt Apply. Chỉ dùng live trên bản code trên máy của bạn, đừng gắn vào trang đang chạy thật.

### Commit nhầm file tạm của Impeccable

Impeccable ghi file làm việc trong `.impeccable/`. Một số file nên được commit (`config.json`, `design.json`, `PRODUCT.md`, `DESIGN.md`), phần còn lại là ảnh chụp, cache, trạng thái chạy. README có sẵn đoạn `.gitignore` để sao chép. Nếu đã lỡ commit, `.gitignore` không gỡ được file đã được git theo dõi; dùng `git rm --cached` như README gợi ý.

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

**Điểm mạnh.** Bạn có từ vựng rõ ràng để ra lệnh cho AI. Bộ dò dùng luật cố định, không tốn API, chạy được trong CI. Hỗ trợ rất nhiều công cụ agent, có Apache-2.0, repo vẫn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Nó mạnh nhất khi sửa giao diện đã có, dựng trang mới là chế độ khó hơn. Bộ dò, chế độ live và hook sửa file chỉ dành cho web (HTML và CSS). Với app di động, README nói bạn đặt `## Platform` trong `PRODUCT.md` thành `ios`, `android` hoặc `adaptive` để lệnh theo chuẩn Apple HIG hay Material 3, nhưng phần dò vẫn chỉ cho web.

**Quyền riêng tư.** Khi bắt đầu một thiết kế mới, skill tải 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 này, chỉ chặn bản ghi ẩn danh về hướng nào được hiển thị và hướng nào bạn chọn. Tên dự án, file, mã và `PRODUCT.md` không bị gửi, theo README. Tắt 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 cần một thiết kế gốc từ nhà thiết kế người thật, thương hiệu có hệ thống chặt chẽ riêng, hoặc không dùng coding agent nào, thì công cụ này ít có ích hơn. Còn nếu bạn đã nhờ AI dựng giao diện và thấy nó cứ na ná nhau, đây là thứ đáng cài 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 và bộ dò 62 luật chạy không cần API key hay mô hình AI. Chi phí của agent bạn đang dùng (Claude Code, Cursor…) tính riêng theo tài khoản của bạn; tư liệu không nói gì thêm về giá.

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

Tư liệu chỉ yêu cầu Node từ 18.19.0 để chạy npx impeccable install và không nêu hạn chế hệ điều hành. Phần skill tự chạy một engine đi kèm hoặc tải về ~/.impeccable/bin/. Chưa có thông tin riêng về Windows trong tư liệu.

### Cần GPU hay API key không?

Bộ dò không cần API key và không dùng LLM. Tư liệu không nhắc yêu cầu GPU. Bạn chỉ cần một coding agent được hỗ trợ và Node để chạy trình cài.

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

README nói tên dự án, file, mã và PRODUCT.md không bao giờ bị gửi. Skill có tải bộ hướng thiết kế từ impeccable.style, và bản ghi ẩn danh về hướng được chọn có thể tắt bằng npx impeccable telemetry off hoặc DO_NOT_TRACK=1. Chi tiết đầy đủ nằm ở trang quyền riêng tư của dự án.

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

Impeccable đóng gói sẵn 24 lệnh như bolder, quieter, polish, audit, mỗi lệnh có playbook riêng và đọc PRODUCT.md, DESIGN.md của dự án. Nó còn có bộ dò 62 luật và hook tự kiểm tra file giao diện agent vừa sửa. Tư liệu không so sánh trực tiếp với công cụ khác.

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

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 có trên Claude Code, Cursor, Codex, GitHub Copilot, Grok Build và Hermes Agent.
