Impeccable cho coding agent: 24 lệnh và detector AI-slop

Vì sao AI coding agent luôn làm giao diện na ná nhau?

Bảo Claude Code hay Cursor làm một landing page, kết quả thường quen thuộc: nền gradient tím chuyển xanh, font Inter cho mọi thứ, thẻ lồng thẻ, padding chật, tiêu đề nhảy cấp. Vấn đề là agent không có từ vựng chung để nói về thiết kế: không đặt tên được cho thao tác cụ thể, không phân biệt mức độ nghiêm trọng của lỗi, và không ghi lại quyết định đã chốt.

Prompt chung chung như “làm cho đẹp, hiện đại” không sửa được việc này, vì “đẹp” không phải chỉ thị thực thi được. Nghe xong, agent quay về mẫu an toàn nhất: gradient tím-xanh. Muốn thoát vòng lặp này, cần một bộ từ vựng để ra lệnh cho chính xác, và một cổng kiểm tra rẻ, lặp lại được trước khi ship. Impeccable làm đúng hai việc đó.

Impeccable là gì? Từ vựng thiết kế cho AI coding agent, không phải theme pack

Impeccable là một skill cho AI coding agent, mã nguồn tại pbakaus/impeccable, giấy phép Apache-2.0. Tại thời điểm kiểm tra ngày 2026-10-29, repo có 94.336 stars và 5.570 forks, bản mới nhất là cli-v4.8.0 phát hành ngày 2026-10-26. Con số tăng khoảng 1.476 sao mỗi ngày chỉ là số liệu từ tracker bên thứ ba.

Impeccable không bán theme. Nó cung cấp 24 lệnh đặt tên cho thao tác thiết kế, chia thành các nhóm Steer, Review, Finish, Live và Plan. Thay vì viết “làm cho phần này nổi bật hơn”, bạn dùng một lệnh có nghĩa xác định, kèm bộ phát hiện AI-slop chạy xác định, không cần LLM.

Khác biệt với Hallmark cần nêu thẳng. Bài Hallmark: skill giúp AI hết làm giao diện na ná nhau trước trên blog này xoay quanh kho 48 theme, kiểm tra bằng trình duyệt thật và thiết kế lại trang cũ. Impeccable xoay quanh từ vựng 24 lệnh, ngữ cảnh bền trong PRODUCT.md và DESIGN.md, và detector 62 quy tắc chạy không cần LLM, gắn được vào hook hoặc CI. Một bên cho theme để chọn, một bên cho ngôn ngữ để ra lệnh và cổng để chặn lỗi.

Impeccable phù hợp với dev dùng AI coding agent làm landing page hay sản phẩm web, team muốn chuẩn thiết kế lặp lại được, và sysadmin hay DevOps muốn gắn cổng kiểm tra vào hook hoặc CI. Ngược lại, bạn chưa cần nó nếu đã có design system chặt và review thủ công chạy tốt.

Kiến trúc và cơ chế hoạt động của Impeccable

Impeccable gồm ba lớp tách biệt. Lớp thứ nhất là skill, tức bộ từ vựng lệnh trong ngữ cảnh agent. Các nhóm: Steer (bolder, quieter, distill, colorize, typeset, layout, animate, delight, overdrive), Review (critique, audit), Finish (polish, harden, clarify, adapt, optimize, onboard), Live (live, generate), Plan/setup (shape, init, document, extract). craft chỉ là alias cũ cho yêu cầu build thông thường.

Lớp thứ hai là engine binary tự chứa, đi kèm skill hoặc tải một lần về ~/.impeccable/bin/; Node chỉ cần cho npx lúc cài đặt. Lớp thứ ba là detector xác định với 62 quy tắc: cùng đầu vào cho cùng đầu ra, không phụ thuộc prompt hay model, bắt các mẫu quen thuộc như gradient tím-xanh, thẻ lồng thẻ, padding chật, heading bị bỏ qua. Con số 62 lấy từ tài liệu chính thức của dự án.

PRODUCT.md và DESIGN.md là bộ nhớ bền

Theo mình, đây là phần đáng tiền nhất của Impeccable. Lệnh /impeccable init đọc code, chỉ hỏi những gì không suy ra được, rồi ghi vào PRODUCT.md: sản phẩm này là gì, dành cho ai, giọng điệu ra sao. Lệnh /impeccable document ghi hệ thống thị giác hiện có vào DESIGN.md: bảng màu, kiểu chữ, nhịp khoảng cách thực tế. Mọi lệnh sau đọc hai file này thay vì đoán lại phong cách mỗi phiên.

Luồng điển hình: init → shape/document → steer → critique/audit → polish/harden → live → detect. Bỏ qua init, các lệnh steer dễ thoái hóa thành prompt trang trí, vì agent không có sự thật sản phẩm để neo quyết định. Ngược lại, detector không có PRODUCT.md chỉ là linter mẫu: bắt được gradient tím-xanh, nhưng không biết khi nào một mẫu bị cấm lại là lựa chọn có chủ đích của thương hiệu. Vì vậy, theo mình, đánh giá Impeccable đúng nhất là đọc PRODUCT.md sau init: file này có đúng sự thật sản phẩm không?

Critique và audit giao diện khác nhau thế nào

Hai lệnh này hay bị nhầm là một, nhưng chúng trả lời hai câu hỏi khác nhau. Critique là bài review trải nghiệm người dùng có chấm điểm: luồng đọc, điểm nhấn, và bước tiếp theo của người dùng. Audit là báo cáo chất lượng kỹ thuật, xếp hạng P0 (chặn) tới P3 (tinh chỉnh). Dễ dùng hay không thì dùng critique; có lỗi phải sửa trước merge hay không thì dùng audit.

Live mode hoạt động ra sao và giới hạn ở đâu

Lệnh /impeccable live mở dev server đang chạy kèm overlay, cho phép hoán đổi biến thể tại chỗ và ghi biến thể được chấp nhận ngược vào source. Nó hỗ trợ Vite, Next, SvelteKit, Astro, Nuxt và HTML thuần. Live mode rút ngắn vòng lặp: xem biến thể tại chỗ, chỉ ghi lại cái đã chọn.

Giới hạn của nó cũng rõ ràng: live mode chỉ sửa checkout local, không inject overlay vào site đã deploy, không nới lỏng CSP của production.

Agent được hỗ trợ gồm Claude Code, Cursor, Codex CLI, GitHub Copilot, Devin, Replit Agent, Gemini CLI, Grok Build, OpenCode, Antigravity, Kiro, Trae, Rovo Dev, Qoder, Mistral Vibe, Pi, Hermes Agent, DeepSeek Harness và Veto. Detector quét URL dùng Chrome hoặc Edge đã cài; extension VS Code cần VS Code 1.109.3 trở lên, Copilot Chat và workspace tin cậy. Bài không nêu số liệu hiệu năng, chi phí token hay benchmark vì không có dữ kiện xác minh; cũng không khẳng định hỗ trợ tiếng Việt hay gói trả phí.

Hướng dẫn cài đặt Impeccable và chạy impeccable init

Nói thẳng: phần này mình chưa chạy thử, chỉ đối chiếu tài liệu chính thức của dự án; kiểm tra bản mới nhất trước khi chạy vì repo cập nhật tới ngày 2026-10-29. Điều kiện tiên quyết: Node để chạy npx, một agent được hỗ trợ, Chrome hoặc Edge nếu quét URL, Git nếu dùng submodule.

1. Từ gốc dự án, chạy npx impeccable install, rồi tải lại coding tool.
2. Trong agent, chạy /impeccable init (trên Codex là $impeccable init) để tạo PRODUCT.md; với codebase đã có giao diện, chạy thêm /impeccable document để tạo DESIGN.md.
3. Với team dùng chung chuẩn qua nhiều repo, đường đi tùy chọn là submodule: git submodule add https://github.com/pbakaus/impeccable vendor/impeccable, rồi npx impeccable link --source=vendor/impeccable --providers=claude,cursor.
4. Cập nhật và chẩn đoán: npx impeccable update để làm mới, /impeccable doctor khi context cũ hoặc hook hỏng, /impeccable pin audit để lấy shortcut /audit trong team.

Để xác minh, kiểm tra PRODUCT.md và DESIGN.md ở gốc dự án khớp sản phẩm thực tế, rồi chạy detector:

npx impeccable detect src/
npx impeccable detect https://example.com
npx impeccable detect --json .
npx impeccable detect --github src/
npx impeccable detect --list-rules

Nhớ trước khi gắn vào CI: exit code 2 nghĩa là có phát hiện, exit code 1 nghĩa là không quét được mục tiêu; pipeline chặn cứng trên exit code 2 sẽ fail ngay trên codebase cũ chưa có baseline sạch.

Lỗi thường gặp và cách xử lý

Agent không nhận lệnh sau install thường chỉ vì chưa reload tool: tải lại tool rồi chạy lại init. CI fail hàng loạt trên trang cũ là hệ quả của exit code 2: chuyển detect sang báo cáo trước, lập baseline, rồi siết dần. Hook chạy ngoài phê duyệt của model là hành vi có chủ đích trong Claude Code, nên xem lại hook đã cài trước khi chạy không giám sát; khi cần tắt hẳn, dùng --settings '{"disableAllHooks": true}'. Live mode không áp dụng lên production không phải lỗi: giới hạn cố ý, chỉ dùng ở local.

Đánh giá kỹ thuật: chống AI slop bằng detector xác định có đủ không?

Ưu điểm rõ nhất là chi phí và tính lặp lại: detector không tốn token LLM, không cần API key, chạy được ở hook, CLI, CI và extension — cùng một bộ quy tắc ở mọi nơi nên kết quả máy dev và CI khớp nhau. Thứ hai là từ vựng chung: thay vì “làm đẹp hơn”, team dùng bolder, quieter, distill hay typeset để chỉ đúng thao tác. Thứ ba là ngữ cảnh bền từ PRODUCT.md và DESIGN.md.

Nhược điểm: xác định nghĩa là chỉ bắt được mẫu, không bắt được gu — giao diện sạch quy tắc vẫn có thể nhạt, thiết kế cố ý phá mẫu vẫn có thể bị gắn cờ. Chất lượng đầu ra vẫn phụ thuộc model và PRODUCT.md: file ngữ cảnh viết ẩu thì mọi lệnh sau chạy trên nền sai một cách nhất quán. Ví dụ before/after trong tài liệu của dự án và case study Neo Mirai là tài liệu vendor, chưa kiểm chứng độc lập — chỉ nên đọc như minh họa.

Về bảo mật, telemetry tắt bằng npx impeccable telemetry off, DO_NOT_TRACK=1, hoặc "telemetry": false trong .impeccable/config.json — nhưng tắt telemetry chỉ dừng bản ghi ẩn danh về hướng thiết kế đã hiển thị và được chọn, không dừng fetch catalog từ impeccable.style khi bắt đầu thiết kế mới. Tài liệu của dự án nói tên dự án, file, code và PRODUCT.md không bao giờ được gửi đi — tuyên bố vendor chưa được audit độc lập, nên đừng dùng cho codebase nhạy cảm mà chưa rà soát chính sách nội bộ. Hook chạy ngoài phê duyệt của model nên cần rà soát trước khi chạy không giám sát, và đối chiếu engine binary trong ~/.impeccable/bin/ với release chính thức.

Về vận hành, detector không dùng LLM nên bước quét không phát sinh chi phí API; bài không nêu con số tốc độ hay token vì không có dữ kiện xác minh. Mở rộng theo hướng: hook cho từng dev, detect trong CI cho từng repo, submodule và link cho chuẩn chung nhiều repo, siết chặn dần để tránh fail dây chuyền.

So sánh Impeccable với các lựa chọn cùng phạm vi

Tiêu chí so sánh: cách đặt tên thao tác, bước soát lỗi có cần LLM hay API key không, ngữ cảnh có bền không, có cổng hook hoặc CI không, có lặp trực tiếp trên trình duyệt không, và chi phí vận hành.

Impeccable thắng ở cổng rẻ và từ vựng chung; thua Hallmark ở kiểm tra bằng trình duyệt thật và kho theme có sẵn; thua review thủ công ở đánh giá gu. Theo mình, detector là cổng “không tệ” trước review của con người, không phải chứng nhận “đẹp”.

Trường hợp sử dụng thực tế

Với dev solo, trình tự có giá trị cao nhất, theo mình, là init, critique, polish rồi audit.

Với team sản phẩm, PRODUCT.md và DESIGN.md cộng với submodule và link làm chuẩn chung qua nhiều repo; detect trong CI ở chế độ báo cáo trước, chặn sau.

Với DevOps và IT admin, hook quét file UI vừa sửa, CI chạy detect --json để lưu báo cáo; exit code 2 chỉ nên chặn pipeline sau khi baseline trang cũ sạch. Đây cũng là nơi duy nhất mà một quy tắc sai có thể chặn việc tốt một cách tự động — nên baseline và danh sách quy tắc cần được rà soát như code.

Với homelab và dự án cá nhân, dashboard nội bộ có thể bớt na ná nhau mà không cần designer: init, vài lệnh steer, rồi audit — detector local không gửi code ra ngoài.

Rủi ro và cách rollback

CI chặn hàng loạt do exit code 2: chạy detect ở chế độ báo cáo trước, lập baseline, rồi siết dần; rollback là gỡ bước chặn. Hook chạy ngoài phê duyệt của model: rà soát trước khi bật, rollback bằng cách tắt hook. Engine binary và fetch catalog: đối chiếu release chính thức, pin cli-v4.8.0; tắt telemetry không dừng fetch catalog. Live mode chạm production: chỉ dùng ở checkout local, rollback là revert commit chứa biến thể đã ghi ngược. Detector gắn cờ thiết kế có chủ đích: coi P0–P3 là tín hiệu để con người quyết.

Kết luận: ai nên dùng Impeccable, ai nên bỏ qua, bước tiếp theo là gì

Nên dùng Impeccable nếu bạn dùng AI coding agent, thấy giao diện đầu ra na ná nhau, và muốn một từ vựng chung cùng một cổng soát lỗi rẻ trước review của con người. Nên bỏ qua hoặc hoãn nếu team đã có design system và review chặt chạy tốt, giao diện không phải ưu tiên lúc này, hoặc codebase cũ chưa có baseline detector sạch.

Bước tiếp theo, theo mình, là: cài ở một dự án, chạy init và document, chạy detect ở chế độ báo cáo trong một tuần, rồi mới quyết định có chặn CI hay không. Tắt telemetry nếu chính sách nội bộ yêu cầu. Checklist trước khi ship: PRODUCT.md khớp sản phẩm thật, DESIGN.md khớp hệ thống hiện có, critique và audit đã chạy, detect không còn P0, live mode chỉ ở local, hook đã rà soát. Làm đủ checklist này, Impeccable là cổng “không tệ” đáng tin — phần “đẹp” vẫn thuộc về bạn.

Tài liệu tham khảo

• Repo Impeccable: https://github.com/pbakaus/impeccable
• Tài liệu Impeccable: https://impeccable.style/docs
• Changelog Impeccable: https://impeccable.style/changelog
• Bài viết liên quan trên phamnam.me: Hallmark: skill giúp AI hết làm giao diện na ná nhau