AGENTS.md có thực sự giúp coding agent thông minh hơn?

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ế.

Một file AGENTS.md nên gồm những gì?

Dựa trên benchmark từ AGENTbench, một cấu hình tối ưu thường dài khoảng 641 từ với gần 10 mục nội dung. Để đảm bảo tính thực thi cao, tệp tin cần bao phủ 4 trụ cột: cấu trúc dự án, công cụ (tooling), quy trình làm việc (workflow) và yêu cầu kiểm thử.

Một mẫu cấu trúc chuẩn hóa cho lập trình viên giàu kinh nghiệm trông như sau:

# AGENTS.md - Technical Execution Context
 
## Project Architecture
 
- `src/core/`: Logic lõi, không sửa đổi trừ khi có yêu cầu đặc thù.
- `infrastructure/`: Chứa định nghĩa Terraform và CI scripts.
 
## Toolchain & Commands
 
- Manager: Sử dụng `uv` cho mọi thao tác dependency.
- Setup: `uv sync`
- Quality: `ruff check --fix .`
- Test Execution: `pytest tests/unit/`
 
## Constraints & Workflow
 
- Không bao giờ sử dụng `pip` trực tiếp.
- Mọi pull request phải đi kèm unit test mới.
- Ưu tiên type hints theo PEP 484.
- Kiểm tra file `docs/api_v2.md` trước khi thay đổi interface.

AGENTS.md có thực sự giúp agent code tốt hơn không?

Kết quả nghiên cứu từ ETH Zurich trên SWE-bench Lite và AGENTbench phơi bày một nghịch lý kỹ thuật:

• Hiệu suất: tệp do con người viết tăng 4% tỷ lệ thành công nhờ bổ sung thông tin duy nhất. Ngược lại, tệp do AI tạo gây nhiễu, làm giảm 0,5% hiệu suất trên các repo phổ biến và giảm tới 2% trên các repo đặc thù.
• Nghịch lý thăm dò (Exploration Paradox): file ngữ cảnh giúp agent biết cách chạy lệnh, nhưng không giúp nó tìm thấy bug nhanh hơn. Như một bản đồ thành phố đầy đủ nhưng không chỉ rõ tòa nhà nào đang bị cháy, agent thường sa lầy vào quy trình (chạy test, linter) thay vì tập trung vào logic sửa lỗi.
• Chi phí vận hành: sử dụng AGENTS.md làm tăng chi phí token suy luận từ 14% đến 22%, đồng thời kéo dài chuỗi thực thi thêm 2-4 bước. Bạn đang chi trả nhiều hơn cho quy trình, không phải cho kết quả.

Chiến lược tối ưu hóa (Best Practices)

Để tránh việc AGENTS.md trở thành "rác ngữ cảnh", lập trình viên giàu kinh nghiệm cần tuân thủ:

• Tối ưu hóa khoảng trống thông tin: chỉ ghi những gì mã nguồn và README không thể hiện (ví dụ: các điểm bất thường (quirk) của hệ thống CI cũ hoặc quyết định kỹ thuật phi mặc định). Đừng nhắc lại những gì agent có thể tự tìm thấy bằng lệnh ls.
• Triệt tiêu sự trùng lặp: dữ liệu cho thấy khi loại bỏ các tài liệu trùng lặp (.md, docs/) trước khi tạo file ngữ cảnh, hiệu suất của agent tăng thêm 2,7%. Sự lặp lại chính là nguyên nhân gây nhiễu hệ thống.
• Thiết lập ràng buộc tối giản: mỗi dòng lệnh trong AGENTS.md đều có giá vốn (inference cost). Hãy chỉ giữ lại các ràng buộc thực sự quan trọng để điều hướng logic vận hành.

Bắt đầu với AGENTS.md như thế nào?

Bạn có thể tận dụng lệnh /init trong các framework như Claude Code hoặc Qwen Code để khởi tạo bản phác thảo. Nhưng đó mới chỉ là bước đệm.

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

Tại sao AGENTS.md làm tăng chi phí suy luận (inference)? Không chỉ do tăng token đầu vào, mà còn do agent tốn thêm bước suy luận để tuân thủ các chỉ dẫn và thực hiện nhiều hành động thăm dò (exploration) rườm rà hơn theo quy trình.

Nên tự viết AGENTS.md hay để AI tự tạo? Luôn ưu tiên tự viết, hoặc ít nhất biên tập kỹ phần AI sinh ra. File để AI tự tạo thường chỉ chép lại tài liệu sẵn có, gây nhiễu và kéo tỷ lệ thành công xuống 0,5–2%.

Sự khác biệt giữa AGENTS.md và README.md là gì? README dành cho con người hiểu về dự án; AGENTS.md là bản hướng dẫn kỹ thuật để máy chuẩn hóa chuỗi thực thi và áp dụng đúng công cụ.

Tài liệu tham khảo

• AGENTS.md — Open Format for Guiding Coding Agents
• A Complete Guide to AGENTS.md — AI Hero
• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
• Does AGENTS.md Actually Help Coding Agents? — Elvis Saravia
• Does AGENTS.md Actually Help Coding Agents? (Notes) — Youssef Hosni
• How I Write My AGENTS.md Files — Best Practices (YouTube)
• Improve Your AI Code Output with AGENTS.md (YouTube)