close

Impeccable

Mã nguồn mở bởi pbakaus

Impeccable là một skill thiết kế cho AI coding agent như Claude Code, Cursor, Codex CLI. Nó cho agent một bộ lệnh có tên rõ ràng để chỉnh, rà soát và hoàn thiện giao diện, kèm bộ dò 62 luật cố định để bắt các dấu hiệu giao diện do AI làm đại trà trước khi phát hành.

Impeccable dùng để làm gì?

  • Ra lệnh chỉnh giao diện bằng từ có nghĩa cụ thể như bolder, quieter, typeset, layout thay cho câu mơ hồ kiểu làm cho nổi hơn
  • Chấm điểm UX bằng critique và rà chất lượng kỹ thuật bằng audit, phát hiện xếp hạng từ P0 đến P3
  • Quét mã nguồn hoặc trang đang chạy bằng 62 luật cố định, không cần LLM hay API key
  • Chọn phần tử ngay trên trình duyệt ở live mode, xem các phương án và ghi phương án đã chọn về mã nguồn
  • Chạy bộ dò trong CI, xuất chú thích GitHub Actions hoặc file SARIF cho code scanning

Giao diện

Ảnh và video lấy từ README của dự án trên GitHub, bản quyền thuộc nhóm phát triển.

Cần biết trước khi dùng

  • Lưu ýKhông tìm thấy docker-compose hay Dockerfile ở thư mục gốc: chưa thể gắn nút Deploy tự động.
  • Lưu ýDependency được khai báo theo khoảng phiên bản (ví dụ ">="), chưa tra lỗ hổng tự động được. Cần quét trên bản cài thật.
  • Lưu ýTino chưa kiểm thử dự án này.

Kiểm tra tự động ngày 21/11/2026 từ dữ liệu GitHub, OSV.dev và docker-compose. Đây không phải chứng nhận bảo mật; Tino không phát triển hay bảo trì repo này.

Impeccable là gì?

Khi giao cho agent dựng một trang mà không có hướng dẫn thiết kế, kết quả thường lặp lại cùng vài lựa chọn: font Inter cho mọi thứ, gradient tím sang xanh, thẻ lồng trong thẻ, chữ xám trên nền màu, ô icon bo góc trên mỗi tiêu đề. Impeccable gọi nhóm dấu hiệu này là AI slop và xử lý theo ba hướng: cho người dùng từ vựng để nói đúng thứ mình muốn, cho agent một vai người rà soát, và một bộ dò chạy bằng luật cố định.

Cách làm việc: chạy /impeccable init một lần cho mỗi dự án. Lệnh này đọc mã nguồn, hỏi những điều nó không suy ra được (sản phẩm cho ai, cần làm gì, ràng buộc nào) rồi ghi file PRODUCT.md. Lệnh /impeccable document ghi hệ thống hình ảnh hiện có vào DESIGN.md. Các lệnh sau đều đọc hai file này. Sau đó người dùng gọi tên lệnh kèm mục tiêu, ví dụ /impeccable critique the onboarding flow. README khuyên chọn mục tiêu hẹp: một phần của trang được xem kỹ cho kết quả tốt hơn cả trang xem lướt.

Bộ dò chạy được ở ba nơi. Trong agent, design hook quét mọi file giao diện mà agent sửa và trả phát hiện về trước khi agent báo xong; hook có trên Claude Code, Cursor, Codex, GitHub Copilot, Grok Build và Hermes Agent. Trong terminal hoặc CI, lệnh npx impeccable detect quét thư mục hoặc URL mà không cần agent. Trên trình duyệt, tiện ích Chrome hiển thị cùng các phát hiện đó lên trang bất kỳ.

README nói rõ Impeccable mạnh hơn khi làm trên giao diện đã có: trỏ vào một trang hoặc component rồi lặp. Dựng trang mới cũng được nhưng là chế độ khó hơn. Với ứng dụng native, đặt mục Platform trong PRODUCT.md là ios, android hoặc adaptive thì các lệnh thiết kế làm theo Apple HIG hoặc Material 3; bộ dò, live mode và hook chỉnh sửa vẫn chỉ dùng cho web.

Dự án do Paul Bakaus tạo, phát hành theo giấy phép Apache 2.0 và khởi đầu từ skill frontend-design của Anthropic. Ảnh so sánh có và không có Impeccable trong README là ví dụ do tác giả tự dựng, nên xem như minh hoạ chứ chưa phải kết quả đo độc lập.

Nên dùng khi

  • Bạn đã có giao diện chạy được và muốn agent rà soát, chỉnh từng phần theo lệnh có tên rõ ràng
  • Bạn muốn chặn các dấu hiệu giao diện đại trà ngay trong pull request bằng một bước CI không cần API key
  • Đội dùng nhiều coding agent khác nhau và cần một bộ lệnh thiết kế chung, có thể ghim phiên bản bằng git submodule
  • Bạn cần báo cáo accessibility, hiệu năng, theme và responsive có xếp mức ưu tiên trước khi phát hành

Không nên dùng khi

  • Bạn chạy live mode trong repo lạ hoặc chưa đọc kỹ: khi không có phiên chat nào đang chờ, nút Apply gọi codex hoặc claude với cờ tắt phê duyệt, kiểm tra quyền và sandbox (--dangerously-bypass-approvals-and-sandbox hoặc --permission-mode bypassPermissions), kế thừa toàn bộ biến môi trường của bạn
  • Bạn không muốn lệnh tự chạy ngoài sự phê duyệt của model: trong Claude Code, hook đã cài vẫn chạy kể cả khi bạn từ chối lệnh của model, và lần sửa đầu tiên có thể tải engine binary về ~/.impeccable/bin/
  • Bạn làm trong môi trường cấm kết nối ra ngoài: khi bắt đầu một thiết kế mới, skill vẫn gọi danh mục hướng thiết kế trên impeccable.style, tắt telemetry không chặn yêu cầu này
  • Bạn định gắn live mode vào site đã triển khai: README ghi rõ chỉ dùng trên bản checkout cục bộ, không nới CSP của production để chạy
  • Bạn cần bộ dò và live mode cho ứng dụng native: các phần này chỉ làm việc với HTML và CSS trên trình duyệt

Tính năng chính

  • 24 lệnh chia 5 nhóm: Steer, Review, Finish, Iterate live, Plan and set up (lệnh craft là bí danh đã ngừng khuyến nghị)
  • Bộ dò 62 luật cố định, chạy không cần LLM và không cần API key
  • Design hook quét file giao diện agent vừa sửa, có trên Claude Code, Cursor, Codex, GitHub Copilot, Grok Build, Hermes Agent
  • CLI npx impeccable detect: quét thư mục, URL, xuất JSON, chú thích GitHub Actions hoặc SARIF 2.1.0
  • Live mode với Vite, Next, SvelteKit, Astro, Nuxt và HTML thuần
  • File ngữ cảnh PRODUCT.md và DESIGN.md, thư mục làm việc .impeccable/
  • Tiện ích Chrome hiển thị phát hiện lên trang đang mở
  • Hỗ trợ native qua mục Platform: ios, android, adaptive (Apple HIG, Material 3)
  • README liệt kê 19 công cụ tương thích, gồm Claude Code, Cursor, Codex CLI, GitHub Copilot, Gemini CLI, OpenCode
  • Giấy phép Apache 2.0

Cách cài đặt Impeccable

  1. Cài skill từ thư mục gốc dự án Trình cài tự nhận diện coding tool đang có, hỏi cài cho dự án hay toàn máy, và hỏi có cài design hook không. Hook là mã chạy tự động sau mỗi lần agent sửa file giao diện, nên đọc mục cảnh báo trước khi đồng ý. Cài xong cần tải lại coding tool.
    npx impeccable install
  2. Khởi tạo ngữ cảnh dự án Gõ trong agent (trên Codex gõ $impeccable init). Lệnh đọc mã nguồn, hỏi thêm vài câu rồi ghi PRODUCT.md.
    /impeccable init
  3. Cách khác: cài qua plugin marketplace của Claude Code Sau đó mở /plugin và cài Impeccable.
    /plugin marketplace add pbakaus/impeccable
  4. Cách khác: ghim phiên bản cho cả đội bằng git submodule Commit .gitmodules, submodule và các liên kết được tạo. Cách này cài skill, không cài hook.
    git submodule add https://github.com/pbakaus/impeccable vendor/impeccable
    npx impeccable link --source=vendor/impeccable --providers=claude,cursor
  5. Cập nhật bản đã cài Làm mới bản cài hiện có. Trên Codex cần duyệt lại hook nếu bản cập nhật thay đổi hook.
    npx impeccable update

Lệnh chép từ README của dự án. Đọc kỹ trước khi chạy và đối chiếu với README mới nhất, vì lệnh có thể đổi theo phiên bản.

Cấu hình quan trọng

MụcÝ nghĩa
IMPECCABLE_LIVE_COPY_AGENTĐặt chat để nút Apply của live mode luôn gửi về phiên chat đang mở, hoặc off để tắt Apply. Server đọc biến này một lần khi khởi động live mode.
DO_NOT_TRACKĐặt bằng 1 để tắt telemetry ẩn danh. Yêu cầu lấy danh mục hướng thiết kế từ impeccable.style vẫn được gửi.

Cách tích hợp và sử dụng

  1. Rà soát một phần giao diệnGõ /impeccable critique the pricing cards để nhận bản chấm điểm UX kèm thứ tự việc cần sửa. Dùng /impeccable audit khi cần báo cáo accessibility, hiệu năng, theme và responsive.
  2. Chỉnh theo hướng cụ thểGọi tên lệnh kèm mục tiêu, ví dụ /impeccable quieter the landing page, /impeccable polish settings, /impeccable harden checkout. Có thể mô tả tự do như /impeccable redo this hero section.
  3. Ghim lệnh hay dùngChạy /impeccable pin audit để có lệnh tắt /audit. Gõ /impeccable không kèm gì để xem toàn bộ danh sách lệnh.
  4. Quét bằng CLIChạy npx impeccable detect src/ để quét thư mục, hoặc npx impeccable detect http://localhost:5173 để quét trang đã dựng. File JSX, TSX chỉ áp dụng luật theo mẫu; luật cần trang đã dựng như độ tương phản thấp, chữ quá nhỏ chỉ chạy khi quét URL. Mã thoát 2 là có phát hiện, 1 là không quét được.
  5. Xử lý khi cài đặt trục trặcChạy /impeccable doctor để tìm file ngữ cảnh cũ, thiết lập không dùng và hook hỏng.

Cập nhật và sao lưu

Cập nhật bằng npx impeccable update. Nếu cài qua git submodule: chạy git submodule update --remote vendor/impeccable, chạy lại lệnh link rồi commit.

Nên giữ trong repo: PRODUCT.md, DESIGN.md và các file dùng chung trong .impeccable/ gồm config.json, live/config.json, design.json, surfaces/*.md, critique/ignore.md. Phần còn lại trong .impeccable/ là ảnh chụp, cache và trạng thái tạm; README có sẵn đoạn .gitignore để loại ra.

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

Bộ dò của Impeccable có gửi mã nguồn của tôi cho mô hình AI nào không?

Theo README, 62 luật là luật cố định, chạy không cần LLM và không cần API key. Khi quét file HTML, ảnh nền cục bộ được đọc trực tiếp còn ảnh từ xa không bao giờ được tải về.

Tắt telemetry thì Impeccable còn gửi gì ra ngoài?

Vẫn còn yêu cầu lấy danh mục hướng thiết kế từ impeccable.style mỗi khi bắt đầu một thiết kế mới. Tắt telemetry chỉ dừng bản ghi ẩn danh về hướng nào được hiển thị và hướng nào được chọn. README ghi tên dự án, file, mã nguồn và PRODUCT.md không bao giờ được gửi.

Làm sao để dự án dùng font Inter làm font thương hiệu không bị báo lỗi?

Chạy npx impeccable ignores add-value overused-font Inter --reason "Brand font". Muốn tắt một luật cho riêng một file thì thêm chú thích dạng impeccable-disable trong file đó; lệnh detect --report-unused-ignores chỉ ra các chú thích bỏ qua đã hết tác dụng.

Không có Node thì cài Impeccable thế nào?

Tải file ZIP cho công cụ của bạn từ impeccable.style hoặc clone repo, rồi chép thư mục skills/impeccable vào đúng thư mục skill của công cụ. Cách chép tay bỏ qua design hook và subagent.

Làm sao tạm tắt hook của Impeccable cho một lần chạy tự động?

Với Claude Code, README hướng dẫn truyền --settings '{"disableAllHooks": true}' để tắt toàn bộ hook trong lần chạy đó. Nên xem lại các hook đã cài trước khi cho agent chạy không người giám sát.

Ứng dụng liên quan

Miễn trừ trách nhiệm

Tino không phát triển, không sở hữu và không liên kết với Impeccable hay nhóm phát triển pbakaus. Tên, logo và nhãn hiệu thuộc về chủ sở hữu tương ứng; việc nhắc tới chỉ để mô tả, không có nghĩa là dự án xác nhận hay hợp tác với Tino.

Impeccable được phân phối theo giấy phép Apache-2.0 của nhóm phát triển. Tino không bảo đảm về tính năng, bảo mật hay mức độ phù hợp của phần mềm; bạn tự chịu trách nhiệm khi cài đặt, cấu hình và sử dụng.

Lệnh cài và thông tin trên trang lấy từ tài liệu công khai của dự án tại thời điểm cập nhật và có thể đã thay đổi. Đọc tài liệu chính thức và sao lưu dữ liệu trước khi chạy trên máy chủ thật.