Phân tích 1.866 dự án GitHub cho thấy khoảng trống trong hướng dẫn dành cho AI agent

Cứ ba dự án GitHub phổ biến thì có một dự án hiện bao gồm các tệp hướng dẫn cụ thể dành cho AI coding agent, với định dạng chuẩn nổi lên là AGENTS.md. Một phân tích gần đây về 1.866 repository hoạt động cho thấy mặc dù mức độ áp dụng khá rộng rãi, đặc biệt là trong các dự án TypeScript, chất lượng và khả năng thực thi của những hướng dẫn này lại rất khác nhau.

Điều gì đã xảy ra

Các nhà nghiên cứu đã phân tích những repository có nhiều sao nhất trên GitHub để tìm hiểu cách các đội ngũ đang hướng dẫn trợ lý AI. Họ xem xét 1.866 dự án đã nhận được commit trong năm nay, tìm kiếm các tệp như AGENTS.md, CLAUDE.md và những tệp khác được thiết kế để điều chỉnh hành vi của agent. Nghiên cứu phát hiện rằng 627 trong số các dự án này, tương đương 34%, có ít nhất một tệp hướng dẫn như vậy.

Dữ liệu cho thấy sự ưu tiên rõ ràng đối với AGENTS.md, xuất hiện trong 78% các dự án có bất kỳ hướng dẫn nào cho agent. CLAUDE.md cũng phổ biến, có mặt trong 52% các dự án đó, nhưng nó thường tồn tại song song với AGENTS.md thay vì thay thế nó. Tỷ lệ áp dụng khác nhau đáng kể theo ngôn ngữ lập trình. TypeScript dẫn đầu với 73% các dự án bao gồm tệp agent, tiếp theo là Go ở mức 58% và Rust ở mức 52%. Ngược lại, các dự án Perl hiếm khi bao gồm chúng, với tỷ lệ áp dụng chỉ 4%.

Nghiên cứu cũng làm nổi bật các vấn đề liên quan đến độ dài tệp và sự trùng lặp. Một nửa số tệp hướng dẫn chính vượt quá 100 dòng, với độ dài trung vị là 106 dòng. Khoảng 30 dự án duy trì hai bộ quy tắc riêng biệt, chẳng hạn như một tệp AGENTS.md và một tệp CLAUDE.md với nội dung khác nhau, gây ra nguy cơ xung đột cho các agent sử dụng những công cụ khác nhau.

Cách thức hoạt động

Phân tích kết hợp giữa kịch bản tự động hóa và đánh giá giống con người từ một AI reviewer. Trước tiên, một script thu thập dữ liệu về sự tồn tại của tệp, độ dài và tiêu đề. Sau đó, một AI reviewer riêng biệt phân loại các mẫu ngẫu nhiên của các quy tắc để xác định xem chúng có phải là hướng dẫn thực sự hay không và liệu chúng có thể được thực thi bằng code hay không.

Các nhà nghiên cứu phát hiện rằng ba phần năm số quy tắc có thể được kiểm tra bởi một script, linter hoặc test, ít nhất là một phần. Tuy nhiên, chưa đầy một phần hai mươi quy tắc nêu đích danh cơ chế kiểm tra thực thi chúng. Hầu hết các quy tắc phụ thuộc vào việc agent đơn giản là ghi nhớ hướng dẫn, điều này kém tin cậy hơn so với việc thực thi tự động. Ví dụ, một quy tắc có thể ghi "Không sử dụng các pattern destructuring rỗng", điều mà một linter có thể dễ dàng bắt lỗi, nhưng tệp không chỉ định rõ quy tắc linter nào được áp dụng.

Nghiên cứu cũng xem xét vị trí lưu trữ của các tệp này. Mặc dù nhiều tệp nằm ở thư mục gốc của repository, 30% các dự án giữ các tệp hướng dẫn trong các thư mục con. Điều này cho phép các quy tắc trở nên cụ thể đối với những phần nhất định của codebase, ngăn chặn agent nạp ngữ cảnh không liên quan khi làm việc ở các khu vực khác.

Chi tiết chính

• Tỷ lệ áp dụng: 34% các dự án hoạt động phổ biến có tệp hướng dẫn cho agent, tăng lên 73% đối với TypeScript.
• Độ dài tệp: Tệp chính có độ dài trung vị là 106 dòng, với 52% vượt quá 100 dòng.
• Khả năng thực thi: 61% các quy tắc có thể được kiểm tra một phần hoặc toàn bộ bởi script, nhưng chỉ 3,7% nêu đích danh cơ chế kiểm tra cụ thể.
• Sự trùng lặp: Khoảng 30 dự án duy trì các tệp AGENTS.md và CLAUDE.md riêng biệt, không giống nhau.
• Tính cập nhật: Chỉ 2% các tệp tham chiếu đến đường dẫn hoặc script không còn tồn tại.
• Trọng tâm nội dung: Phong cách code, hành vi của agent và tính đúng đắn đặc thù của dự án là những chủ đề phổ biến nhất, trong khi bảo mật và hiệu suất lại hiếm gặp.

Tại sao điều này quan trọng

Đối với các đội ngũ kỹ thuật, dữ liệu này làm nổi bật khoảng cách giữa việc viết hướng dẫn và đảm bảo chúng được tuân thủ. Các tệp hướng dẫn dài làm tăng chi phí token và có thể làm loãng sự tập trung của agent. Nghiên cứu từ ETH Zurich được trích dẫn trong bài báo lưu ý rằng mặc dù các tệp do developer viết giúp ích một chút, chúng có thể làm tăng chi phí cho agent lên tới 19%. Giữ cho các tệp ngắn gọn và trỏ đến tài liệu bên ngoài sẽ hiệu quả hơn.

Quan trọng hơn, việc dựa vào bộ nhớ của agent cho các quy tắc then chốt là rủi ro. Khi một quy tắc nêu rõ cơ chế thực thi, chẳng hạn như một linter cụ thể hoặc bước kiểm tra CI, nó tạo ra một lưới an toàn. Nếu agent quên, công cụ sẽ bắt lỗi. Không có liên kết này, các đội ngũ phụ thuộc vào tính nhất quán của agent, vốn bị suy giảm khi cửa sổ ngữ cảnh (context window) đầy dần. Sự phổ biến của các quy tắc không được thực thi cho thấy nhiều đội ngũ đang coi những tệp này như danh sách mong muốn hơn là ràng buộc vận hành.

Bạn có thể làm gì

• Kiểm toán độ dài tệp: Giữ tệp AGENTS.md chính dưới 100 dòng bằng cách chuyển các giải thích chi tiết sang tài liệu liên kết.
• Nêu tên cơ chế kiểm tra: Đối với mỗi quy tắc, hãy chỉ định linter, test hoặc script thực thi nó, ví dụ: "Enforced by Sorbet/ForbidTMust".
• Xác minh đường dẫn: Thường xuyên kiểm tra xem tất cả các lệnh và đường dẫn tệp được tham chiếu trong hướng dẫn của bạn vẫn còn tồn tại.
• Hợp nhất tệp: Nếu bạn sử dụng nhiều tệp hướng dẫn, hãy đảm bảo các tệp phụ trỏ đến tệp chính để tránh xung đột quy tắc.
• Ưu tiên các quy tắc có thể thực thi: Tập trung vào các quy tắc có thể tự động hóa và loại bỏ những quy tắc chỉ phụ thuộc vào bộ nhớ của agent trừ khi chúng cực kỳ quan trọng.
• Sử dụng quy tắc trong thư mục con: Đặt các hướng dẫn cụ thể trong các thư mục con để giữ ngữ cảnh liên quan đến mã đang được chỉnh sửa.