RuleProbe – Công cụ kiểm tra liệu AI lập trình có tuân thủ đúng hướng dẫn hay không

Ngày nay, các AI lập trình như Claude, Copilot ngày càng được sử dụng phổ biến để hỗ trợ viết mã. Tuy nhiên, việc đảm bảo AI thực sự tuân thủ các quy tắc code, phong cách, và tiêu chuẩn do người dùng đặt ra vẫn là thách thức.

RuleProbe là một công cụ dòng lệnh (CLI) mã nguồn mở, giúp tự động xác minh các sản phẩm của agent AI có tuân thủ chính xác các quy tắc được lưu trong file hướng dẫn hay không bằng cách phân tích cấu trúc mã nguồn và hệ thống file. Công cụ này không dùng trí tuệ nhân tạo để đánh giá, mà kiểm tra một cách khách quan, không định tính.

Case study so sánh hai AI agent cùng nhiệm vụ, điểm số giống nhau nhưng lỗi khác biệt

Trong một thử nghiệm, hai AI lập trình được giao cùng một nhiệm vụ với file hướng dẫn gồm 10 quy tắc. Cả hai cùng đạt điểm tuân thủ là 70%. Tuy nhiên, chi tiết từng lỗi của mỗi agent lại khác biệt hoàn toàn:

Quy tắc	Agent A	Agent B
Biến dùng camelCase	Đạt	Không đạt
Không dùng kiểu any	Không đạt	Đạt
Không dùng console.log	Không đạt	Đạt
Chỉ xuất named exports	Đạt	Không đạt
Tối đa 300 dòng code	Đạt	Không đạt
Có file test đi kèm	Không đạt	Đạt

Agent A mắc lỗi về an toàn kiểu dữ liệu (dùng kiểu any không đúng). Agent B thì vi phạm nguyên tắc cấu trúc và phong cách code như dùng snake_case, xuất mặc định mặc dù hướng dẫn không cho phép, và tạo file code quá dài (338 dòng so với giới hạn 300).

Kết luận: Điểm số bằng nhau nhưng điểm yếu kỹ thuật của mỗi AI là hoàn toàn khác nhau.

RuleProbe hoạt động như thế nào?

RuleProbe đọc file hướng dẫn (hỗ trợ nhiều định dạng như CLAUDE.md, AGENTS.md, .cursorrules, v.v.) và trích xuất những quy tắc có thể kiểm chứng cơ học một cách chắc chắn. Công cụ này tránh những quy tắc cần đánh giá chủ quan như “viết code sạch” hay “xử lý lỗi hợp lý” để cho kết quả kiểm tra nhất quán mọi lần.

Ba phương pháp kiểm tra chính được sử dụng:

• Phân tích AST (Abstract Syntax Tree): Qua thư viện ts-morph để kiểm tra cấu trúc code như cách đặt tên biến (camelCase), kiểu dữ liệu (phát hiện kiểu any), kiểu export, v.v.
• Kiểm tra hệ thống file: Kiểm tra các luật liên quan đến tên file (kebab-case) hay sự tồn tại của file test đi kèm.
• Regex: Kiểm tra các mẫu ký tự trong file như số dòng không vượt quá giới hạn.

Phiên bản hiện tại có 15 bộ matcher, chỉ áp dụng cho TypeScript và JavaScript vì dựa trên nền tảng phân tích AST của ts-morph.

Mẫu báo cáo đầu ra

RuleProbe Adherence Report
Rules: 14 total | 11 passed | 3 failed | Score: 79%

PASS  naming/naming-camelcase-variables-5
PASS  naming/naming-pascalcase-types-7
FAIL  forbidden-pattern/forbidden-no-any-type-1
      src/handler.ts:12 - found: req: any
FAIL  forbidden-pattern/forbidden-no-console-log-10
      src/handler.ts:18 - found: console.log("handling request")
FAIL  test-requirement/test-files-exist-11
      src/handler.ts - found: no test file found

Thông tin vị trí lỗi rõ ràng gồm file, dòng, và nội dung vi phạm, giúp lập trình viên dễ dàng rà soát.

Tích hợp CI tự động với GitHub Actions

RuleProbe đi kèm GitHub Action tiện lợi, cho phép bạn tự động chạy kiểm tra trên mỗi pull request mà không cần API key ngoài. Kết quả kiểm tra được xuất dưới nhiều định dạng, thậm chí hỗ trợ reviewdog để hiển thị lỗi inline ngay trên giao diện PR, tăng hiệu quả review code và đảm bảo chất lượng đầu ra từ AI coding agent.

API lập trình cho tích hợp sâu

Ngoài CLI, RuleProbe cung cấp API JavaScript để tích hợp vào hệ thống công cụ kiểm thử hoặc quy trình DevOps hiện có, gồm các hàm parse, verify, generate report, format report, v.v.

Giới hạn và bảo mật

Hiện RuleProbe chỉ xử lý được các quy tắc có thể kiểm tra cơ học, chưa hỗ trợ các quy tắc kiến trúc, thiết kế API, hay xử lý lỗi phức tạp. Chỉ hỗ trợ JavaScript/TypeScript do phụ thuộc ts-morph.

Nổi bật: công cụ không thực thi mã nguồn, không gọi mạng ngoài, đảm bảo an toàn và không ảnh hưởng đến thư mục dự án khi chạy.

Tổng kết

RuleProbe là công cụ hữu ích giúp các đội phát triển và dự án tận dụng AI lập trình kiểm soát được chất lượng tuân thủ quy tắc code một cách tự động hóa, giảm tải cho công việc review thủ công. Với việc ngày càng nhiều AI tham gia viết mã, công cụ như RuleProbe giúp minh bạch tính tuân thủ kỹ thuật, phát hiện sớm lỗi tiềm ẩn và duy trì phong cách coding đồng nhất.

Bạn đọc quan tâm có thể truy cập mã nguồn và tài liệu tại:
https://github.com/moonrunnerkc/ruleprobe

---

Cài đặt nhanh:

npm install -g ruleprobe
# hoặc chạy ngay
npx ruleprobe --help

Bạn cũng có thể thử phân tích file hướng dẫn demo bằng lệnh:

ruleprobe parse CLAUDE.md

---

RuleProbe mở ra một hướng đi mới trong việc đánh giá và kiểm soát đầu ra AI lập trình dựa trên quy tắc đã thiết lập, rất đáng để cộng đồng phát triển phần mềm Việt Nam theo dõi và áp dụng.