AGENTS.md (hoặc CLAUDE.md) là tệp cấu hình ngữ cảnh đặt ở thư mục gốc (root) của repository, đóng vai trò như một bản hướng dẫn dành riêng cho các coding agent (tác nhân lập trình — công cụ AI tự đọc, viết và chạy code) như Claude Code, Codex, hay Qwen Code.
Mục tiêu cốt lõi của nó là chuẩn hóa chuỗi thực thi (execution chain) thông qua việc định nghĩa tường minh cấu trúc dự án, các bộ lệnh linter, quy trình kiểm thử và các quy ước lập trình đặc thù mà agent không thể tự suy luận từ mã nguồn.
Tuy nhiên, dưới góc độ một kiến trúc sư giải pháp AI, hãy nhìn vào dữ liệu thực nghiệm thay vì các lời hứa hẹn marketing. Nghiên cứu mới nhất từ ETH Zurich chỉ ra một thực tế phũ phàng: chỉ thêm AGENTS.md không tự động khiến hệ thống thông minh hơn. Nó phát huy tác dụng hay không là tùy vào chất lượng và nguồn gốc của dữ liệu ngữ cảnh mà bạn cung cấp cho mô hình.
AGENTS.md là gì và nó giải quyết vấn đề gì?
Sự bùng nổ của các coding agent đã tạo ra một khoảng trống thông tin giữa dữ liệu huấn luyện (parametric knowledge) và ngữ cảnh cục bộ của dự án. Hiện tại, hơn 60.000 repository đã áp dụng định dạng này để giải quyết vấn đề "mù ngữ cảnh". Thay vì để agent tiêu tốn token để "mò mẫm" qua các file README vốn được tối ưu cho con người, AGENTS.md cung cấp một bản đồ máy (machine-readable map) về các công cụ quản lý gói, thiết lập kiểm thử và quy trình CI đặc thù.
Mục tiêu kỹ thuật của AGENTS.md là giảm thiểu entropy thông tin trong quá trình agent khởi tạo phiên làm việc. Nó ngăn chặn việc agent sử dụng sai công cụ (ví dụ: dùng unittest trong khi dự án ưu tiên pytest) hoặc vi phạm các ràng buộc kiến trúc không được thể hiện rõ ràng trong code nhưng tồn tại trong ý đồ của lập trình viên duy trì.
Cách coding agent đọc và áp dụng AGENTS.md
Các agent hiện đại như Claude Code, Codex (bao gồm GPT-5.2 và GPT-5.1 mini), hay Qwen Code nạp trực tiếp AGENTS.md vào cửa sổ ngữ cảnh (context window) ngay từ bước đầu tiên. Dữ liệu thực nghiệm cho thấy mức độ "trung thành" rất cao của agent: khi tệp này nhắc đến một công cụ như uv, tần suất sử dụng tăng vọt từ 0,01 lên 1,6 lần mỗi lần chạy (instance).
Nhưng có một lỗi hành vi hệ thống đáng chú ý: GPT-5.1 mini có xu hướng đọc lại file ngữ cảnh nhiều lần dù thông tin đã nằm trong cửa sổ ngữ cảnh, dẫn đến lãng phí token suy luận một cách vô ích. Ngoài ra, việc tuân thủ quy trình quá mức thường tạo ra "nghịch lý thăm dò": agent thực hiện nhiều bước tìm kiếm và chạy linter hơn, nhưng không giúp giảm số bước cần thiết để chạm tới file chứa lỗi thực tế.