Thực thi quy tắc cho tác nhân lập trình trong mọi lần chỉnh sửa với Abide

Abide thực hiện những gì

Abide thực thi các hướng dẫn dành riêng cho dự án mà những trình lint thông thường không thể đánh giá một cách đáng tin cậy. Các hướng dẫn này có thể nằm trong những tệp như AGENTS.md hoặc CLAUDE.md và bao gồm các quy tắc như sử dụng Yup thay vì tự xác thực thủ công, không tạo helper chỉ có một nơi gọi hoặc không bao giờ hiển thị lỗi thô cho người dùng.

Sau mỗi lần chỉnh sửa hoặc hoàn tất một lượt làm việc, Abide gửi quy tắc liên quan cùng phần diff của mã đến mô hình quyết định Jev của TypeSafe. Jev trả về một xác suất thay vì văn bản tự do. Nếu xác suất cho thấy có vi phạm, Abide cho tác nhân lập trình biết quy tắc nào bị vi phạm và yêu cầu tác nhân sửa mã ngay trong lượt làm việc đó.

Jev nhìn thấy quy tắc và phần diff, không nhìn thấy cuộc hội thoại của tác nhân. Nhờ đó, Abide có thể áp dụng nhất quán các bước kiểm tra trong suốt một phiên lập trình dài. Theo bài kiểm thử replay được công bố của kho lưu trữ, các bước kiểm tra mất khoảng 300 mili giây trong Jev, còn toàn bộ hook mất khoảng một giây khi tính cả thời gian khởi động Node.

Tính năng chính

• Kiểm tra chỉnh sửa tự động: Quy tắc có thể chạy ngay sau mỗi lần chỉnh sửa mã.
• Kiểm tra theo lượt: Các quy tắc cần toàn bộ diff của tác vụ có thể chạy một lần khi kết thúc lượt làm việc.
• Tích hợp tác nhân: Abide hỗ trợ Claude Code, Codex và OpenCode.
• Bộ tiêu chí do kho lưu trữ quản lý: Các quy tắc đã biên dịch được lưu trong tệp .abide/rubric.json dễ đọc và thuận tiện commit.
• Quy tắc theo phạm vi: Quy tắc có thể sử dụng phạm vi glob để áp dụng các câu hỏi khác nhau cho route API, stylesheet hoặc các nhóm tệp khác.
• Kiểm tra mã hiện có: Abide có thể đánh giá các tệp như thể chúng vừa được viết xong.
• Hiệu chỉnh và tinh chỉnh: Abide có thể kiểm thử quy tắc trên lịch sử Git gần đây, vô hiệu hóa các quy tắc không hiệu quả và hỗ trợ viết lại những quy tắc không bao giờ được kích hoạt.
• Hook mở khi lỗi: Thiếu thông tin xác thực, lỗi mạng hoặc lỗi hook không chặn phiên lập trình.
• Không có chính sách tích hợp sẵn: Abide thực thi các quy tắc được suy ra từ tệp hướng dẫn của bạn thay vì áp đặt một bộ quy tắc định trước.

Điều kiện tiên quyết

Bạn cần một kho lưu trữ có hướng dẫn dành cho tác nhân lập trình và ít nhất một tác nhân được hỗ trợ: Claude Code, Codex hoặc OpenCode. Bạn cũng cần khóa API TypeSafe từ typesafe.ai. Ngoài ra, Abide có thể sử dụng khóa Vercel AI Gateway hiện có thông qua biến môi trường AI_GATEWAY_API_KEY.

Cài đặt và cấu hình Abide

Bước 1: Lưu khóa API

Chạy lệnh đăng nhập và dán khóa TypeSafe khi được yêu cầu:

npx @coldtea/abide login

Abide lưu khóa trong ~/.abide/.env với quyền chỉ chủ sở hữu mới có thể truy cập. Thay vào đó, bạn có thể đặt thông tin xác thực trong .env.local hoặc .env ở thư mục gốc của kho lưu trữ. Thứ tự tra cứu thông tin xác thực là biến môi trường trước, tiếp theo là các tệp của kho lưu trữ, rồi đến ~/.abide/.env.

Nếu sử dụng Vercel AI Gateway, hãy đặt AI_GATEWAY_API_KEY thay cho khóa TypeSafe. Thông tin xác thực không được chấp nhận qua các cờ dòng lệnh và không được ghi vào nhật ký.

Bước 2: Cài đặt hook cho tác nhân

Từ kho lưu trữ của bạn, hãy khởi tạo Abide:

npx @coldtea/abide init

Khi không chỉ định tên tác nhân, init sẽ cài đặt vào mọi tác nhân được hỗ trợ mà nó tìm thấy. Bạn cũng có thể chỉ định rõ một tích hợp:

npx @coldtea/abide init claude
npx @coldtea/abide init codex
npx @coldtea/abide init opencode

• Claude Code: Tích hợp được thêm vào ~/.claude/settings.json.
• Codex: Tích hợp được thêm vào ~/.codex/hooks.json.
• OpenCode: Plugin được cài đặt tại ~/.config/opencode/plugins/abide.js.

Thêm --project khi bạn muốn cài đặt ở cấp kho lưu trữ để đồng đội có thể nhận được khi checkout:

npx @coldtea/abide init claude --project

Codex yêu cầu thêm một bước phê duyệt. Khởi động Codex, nhập /hooks và chấp nhận bốn mục hook của Abide. Codex yêu cầu phê duyệt này một lần cho mỗi hook mới.

Bước 3: Biên dịch các quy tắc của kho lưu trữ

Khởi động tác nhân lập trình như bình thường. Khi bắt đầu phiên đầu tiên, Abide kiểm tra xem các tệp hướng dẫn có thay đổi hay không. Sau đó, tác nhân biên dịch các hướng dẫn áp dụng vào .abide/rubric.json và báo cáo những gì đã tìm thấy.

Bạn cũng có thể biên dịch trước khi bắt đầu phiên mới:

abide compile

Hãy commit .abide/rubric.json nếu bạn muốn bộ tiêu chí có thể thực thi của kho lưu trữ được hiển thị và đội ngũ có thể xem xét. Mỗi kết quả đánh giá đều xác định một quy tắc trong tệp này và trích dẫn hướng dẫn nguồn mà quy tắc đó được suy ra.

Cách sử dụng cơ bản

Để Abide tự động kiểm tra các chỉnh sửa của tác nhân

Sau khi khởi tạo, hãy khởi động claude, codex hoặc opencode như thường lệ. Không cần chạy dịch vụ nền riêng. Giả sử một hướng dẫn quy định rằng các endpoint API phải sử dụng Yup và không được tự xác thực dữ liệu đầu vào. Nếu tác nhân viết một guard thủ công, Abide có thể trả về thông báo như sau:

Abide: Bản chỉnh sửa này dường như vi phạm một quy tắc trong hướng dẫn của kho lưu trữ này.
- Quy tắc "api-validation-uses-yup" từ dòng 65 của ~/.codex/AGENTS.md:
  "Khi viết các endpoint API, KHÔNG tự viết thủ công phần xác thực đầu vào.
  Hãy sử dụng Yup (với thông báo xác thực rõ ràng) + trả về sớm trong trình xử lý API".
  (0.86)
Hãy sửa apps/web/src/pages/api/logout.ts ngay bây giờ, sau đó tiếp tục công việc.

Agent nhận được yêu cầu sửa và có thể khắc phục vi phạm trước khi tiếp tục. Với OpenCode, các vi phạm trong quá trình chỉnh sửa được thêm vào kết quả công cụ. Vi phạm ở cấp lượt sẽ tạo ra một tin nhắn tiếp theo sau lượt đó.

Kiểm tra các thay đổi chưa commit theo cách thủ công

Sử dụng check để đánh giá các thay đổi chưa commit hiện tại theo cách tương tự các hook:

abide check

Bạn cũng có thể cung cấp đường dẫn khi muốn thu hẹp phạm vi kiểm tra:

abide check apps/web/src/pages/api/

Kiểm tra mã hiện có

Lệnh audit đánh giá các tệp hiện có như thể chúng vừa được tạo. Điều này hữu ích khi tích hợp Abide vào một kho lưu trữ đã có sẵn:

abide audit src/

Kết quả bao gồm bản tóm tắt theo từng quy tắc và danh sách được sắp xếp theo tệp. README cho biết việc kiểm tra 33 route API trong một ứng dụng Next.js thực tế mất khoảng 12 giây và tốn xấp xỉ một cent, dù kết quả thực tế phụ thuộc vào kho lưu trữ và các quy tắc.

Xem hoạt động của quy tắc

Chạy lệnh báo cáo để xem các quy tắc của bạn, những quy tắc đã được kích hoạt và những quy tắc chưa từng được kích hoạt:

abide report

Để nhận kết quả ở định dạng máy có thể đọc, hãy thêm --json. Kết quả JSON cũng có sẵn cho check, audit, bench và calibrate.

Hiểu thời điểm chạy và kết luận của quy tắc

Mỗi quy tắc đã biên dịch chạy trong một trong hai giai đoạn:

• Giai đoạn chỉnh sửa: Chạy sau từng lần chỉnh sửa và đánh giá phần thay đổi đó.
• Giai đoạn lượt: Chạy một lần khi kết thúc lượt và đánh giá toàn bộ diff dựa trên ảnh chụp được tạo lúc bắt đầu lượt.

Đánh giá ở cấp lượt rất quan trọng đối với những câu hỏi không thể trả lời chỉ từ lần chỉnh sửa đầu tiên, chẳng hạn agent có thêm chức năng mà người dùng không yêu cầu hay không. Khi kết thúc một lượt, Abide cũng áp dụng các quy tắc ở giai đoạn chỉnh sửa cho những thay đổi được tạo thông qua các lệnh shell.

Các kết luận được chia thành những khoảng xác suất:

• 0.8 trở lên: Agent được yêu cầu sửa vi phạm.
• Từ 0.5 đến dưới 0.8: Một ghi chú được hiển thị, nhưng agent không được yêu cầu sửa.
• Dưới 0.5: Không hiển thị gì.

Quy trình nâng cao

Hiệu chỉnh quy tắc dựa trên lịch sử Git

Một quy tắc diễn đạt kém có thể đạt điểm quanh mức trung bình trên nhiều thay đổi không liên quan và không bao giờ tạo ra kết quả hữu ích. Lệnh hiệu chỉnh đánh giá mọi quy tắc dựa trên các hunk thực tế gần đây từ lịch sử Git của kho lưu trữ:

abide calibrate

Abide sử dụng hai mươi hunk gần đây cho quá trình này và có thể tắt những quy tắc hoạt động không hiệu quả. Hãy xem xét kết quả trước khi áp dụng một bộ tiêu chí mới được biên dịch cho cả nhóm.

Điều chỉnh các quy tắc không bao giờ được kích hoạt

Sau khi xác định các quy tắc không hiệu quả, hãy sử dụng tune để yêu cầu agent viết lại chúng:

abide tune

Vì mỗi mục trong bộ tiêu chí đều trích dẫn chỉ thị nguồn, bạn có thể truy nguyên một kết luận đáng ngờ về cách diễn đạt đã tạo ra nó. Cải thiện chỉ thị nền tảng thường giúp việc kiểm tra tương ứng trở nên rõ ràng hơn.

Phát lại các phiên agent trước đây

Sử dụng replay để đánh giá các phiên trước đây từ một trong những agent được hỗ trợ:

abide replay claude
abide replay codex
abide replay opencode

Điều này giúp bạn đánh giá một bộ tiêu chí dựa trên công việc đã diễn ra thay vì chờ các vi phạm trong tương lai.

Đo độ trễ và chi phí cục bộ

Chạy lệnh benchmark để đo hiệu năng và chi phí trên máy của bạn:

abide bench

Kho lưu trữ cho biết việc kiểm tra 13 quy tắc sử dụng khoảng 1.000 đến 1.600 token đầu vào, tốn khoảng $0.00004 đến $0.00007 cho mỗi lần kiểm tra và mất khoảng 300 mili giây trong Jev. Các số liệu này được đo trực tiếp dựa trên TypeSafe và có thể thay đổi, vì vậy benchmark cục bộ sẽ là tham chiếu phù hợp hơn cho thiết lập của bạn.

Sử dụng phạm vi để giữ câu hỏi phù hợp

Các quy tắc trong .abide/rubric.json có thể bao gồm phạm vi dựa trên glob. Hãy sử dụng các phạm vi này khi một chỉ thị chỉ áp dụng cho một số tệp nhất định. Ví dụ, các quy tắc xác thực có thể thuộc về các route API, còn quy tắc kiểu dáng chỉ nên giới hạn trong các biểu định kiểu. Phạm vi hẹp giúp giảm các đánh giá không liên quan và khiến kết luận dễ hiểu hơn.

Quyền riêng tư và hành vi khi xảy ra lỗi

Các dòng đã thay đổi được gửi đến TypeSafe bằng khóa riêng của bạn, với yêu cầu không lưu giữ dữ liệu trong mọi lần gọi. README nêu rằng dữ liệu không được gửi đến máy chủ do Abide vận hành.

Các hook của Abide được thiết kế để không làm gián đoạn phiên agent. Đường dẫn hook thoát thành công, sử dụng thời hạn cứng và chỉ in ra những gì máy chủ yêu cầu. Nếu không có khóa hoặc mạng không khả dụng, thay đổi vẫn được thực hiện mà không cần kiểm tra. Lần kiểm tra bị bỏ qua được ghi vào .abide/events.jsonl, và abide report sẽ đưa lần này vào các số liệu thống kê.

Gỡ cài đặt Abide

Xóa Abide khỏi mọi agent đã được cài đặt:

abide uninstall

Để chỉ xóa một tích hợp, hãy chỉ định agent:

abide uninstall codex

Thêm --project khi xóa một cài đặt cấp dự án. Việc gỡ cài đặt chỉ xóa các mục do Abide tạo ra. Các tệp bộ tiêu chí và ~/.abide/.env vẫn được giữ lại cho đến khi bạn tự xóa chúng.

Kết luận

Abide chuyển các hướng dẫn dành cho kho mã được viết bằng ngôn ngữ tự nhiên thành những bước kiểm tra chạy xuyên suốt phiên lập trình bằng AI. Cài đặt các hook phù hợp, biên dịch và xem xét .abide/rubric.json, sau đó sử dụng các bước kiểm tra tự động, kiểm toán, báo cáo, hiệu chỉnh và tinh chỉnh để duy trì hiệu quả của các quy tắc. Kết quả là một lớp thực thi nhẹ cho những quy ước mà các trình kiểm tra mã truyền thống không thể diễn đạt.