Hầu hết team nghiêm túc dùng AI coding agent đều có file AGENTS.md. Nó đã trở thành best practice mặc định: đưa context dự án, quy ước, và hướng dẫn vào một file duy nhất ở root của repo, và agent sẽ tự động nhận và làm việc tốt hơn. Ý tưởng nghe có vẻ hợp lý. Nhưng thực thi, hóa ra, thường không.
Một nghiên cứu của ETH Zurich công bố tháng 2 năm 2026 đã kiểm tra các file context một cách có hệ thống trên hàng trăm GitHub issue thực tế, dùng 4 coding agent khác nhau. Kết quả chính: trong 5 trong 8 cấu hình được kiểm tra, file AGENTS.md do LLM tạo ra làm giảm tỷ lệ thành công so với không có file context nào. Chúng thêm 2,45 đến 3,92 bước reasoning thêm mỗi task. Chúng tăng chi phí inference lên 20-23%. File do human tuyển chọn vượt trội so với file do LLM tạo khoảng 4 điểm phần trăm trên benchmark AGENTbench.
Chúng ta đã dành nhiều tháng viết file context và nghiên cứu bây giờ đã rõ ràng: hầu hết chúng đang làm agent làm việc vất vả hơn, không thông minh hơn.
Tại Sao Agent “Quá Ngoan Lời”
Nhóm nghiên cứu xác định những gì họ gọi là “obedience trap” — bẫy tuân lệnh. Coding agent được train để theo dõi hướng dẫn. Khi file AGENTS.md tồn tại, agent cố gắng tuân theo nó — ngay cả khi hướng dẫn không cần thiết, trùng lặp với những gì agent có thể tự tìm ra, hoặc phản tác dụng.
Một AGENTS.md điển hình bao gồm tổng quan codebase, giải thích cấu trúc thư mục, quy ước đặt tên, hướng dẫn testing, CI/CD instructions, và style rules. Với human mới vào team, đây là tài liệu onboarding hữu ích. Với agent, hầu hết đây là overhead.
Vấn đề là agent đã giỏi tự khám phá cấu trúc file. Nghiên cứu ETH Zurich phát hiện “tổng quan codebase và danh sách thư mục không giúp agent điều hướng nhanh hơn” — agent đơn giản tự khám phá repo hiệu quả hơn so với xử lý mô tả dạng văn bản. Đọc một danh sách thủ công tiêu tốn reasoning token và thêm cognitive overhead làm chậm agent.
Khi bạn nói với agent “tests nằm trong thư mục /tests,” nó dành token xử lý hướng dẫn đó. Không có hướng dẫn, nó sẽ chỉ tìm thư mục tests. Hướng dẫn không gây hại khi đứng độc lập, nhưng một AGENTS.md đầy ắp những hướng dẫn như vậy tạo ra overhead tích lũy.
File Do LLM Tạo Ra Sai Chỗ Nào
Nhiều team tạo AGENTS.md bằng LLM: “tóm tắt codebase này và tạo file context cho AI coding agent.” Kết quả ETH Zurich cho thấy tại sao điều này phản tác dụng.
File do LLM tạo ra rất dài dòng. Chúng cố gắng toàn diện. Chúng bao gồm thông tin về mọi thư mục, mọi lựa chọn cấu hình, mọi quy ước — vì đó là cái mà tài liệu toàn diện trông như vậy. Nhưng toàn diện là mục tiêu sai cho agent context. Agent không cần biết mọi thứ về codebase; nó cần tín hiệu rõ ràng về vài thứ không thể tự tìm ra.
File do LLM tạo cũng thường trùng lặp với những gì đã có trong codebase. Nếu quy ước đặt tên được linter enforce, việc nói với agent về quy ước đặt tên là thừa — nó sẽ thấy feedback từ linter dù sao. Nếu test runner được định nghĩa trong package.json, agent có thể đọc file đó. Viết lại trong AGENTS.md nghĩa là agent xử lý cùng thông tin hai lần, và khi hai nguồn không đồng ý (điều sẽ xảy ra), agent phải giải quyết mâu thuẫn.
File Do Human Tuyển Chọn Làm Đúng Chỗ Nào
Nghiên cứu phát hiện file context do human tuyển chọn vượt trội file do LLM tạo trên tất cả 4 agent được kiểm tra. Pattern trong file human-curated hiệu quả:
Chúng mô tả những gì agent không thể tự tìm ra từ code. Business logic context, architectural trade-off không rõ ràng từ implementation, những gotcha đã biết, và ràng buộc tồn tại ngoài codebase (behavior của external service, đặc điểm deployment, quyết định lịch sử). Đây là thông tin mà người mới vào team sẽ cần một cuộc trò chuyện để học — không phải thứ có thể khám phá bằng cách đọc file.
Chúng ngắn gọn. Nghiên cứu phát hiện hiệu suất giảm dần sau vài trăm token context. Một AGENTS.md 50 dòng liên tục vượt trội so với file 500 dòng. File hoạt động tốt nhất tập trung vào 3-5 fact quan trọng thay vì cố gắng document mọi thứ.
Chúng chỉ định behaviors, không phải facts. “Luôn chạy integration test suite trước khi submit PR” hữu ích hơn “integration tests nằm trong /tests/integration.” Cái đầu nói với agent cần làm gì; cái sau nói điều nó sẽ tự tìm ra.
Chúng dùng ngôn ngữ cụ thể, không mơ hồ. “Đừng sửa file trong /legacy” hiệu quả hơn “thư mục legacy chứa code cũ hơn cần được xử lý cẩn thận.” Agent hiểu lời hướng dẫn theo nghĩa đen; qualifier mơ hồ tạo ra tín hiệu không rõ ràng.
Bốn Biến Cấu Trúc Quan Trọng
Paper ETH Zurich xác định 4 biến chiếm phần lớn sự khác biệt hiệu suất giữa file context hiệu quả và không hiệu quả:
- Độ dài — ngắn hơn tốt hơn, với ngưỡng khoảng 500 token mà hiệu suất bắt đầu giảm
- Độ cụ thể — hướng dẫn behavioral cụ thể vượt trội so với mô tả chung chung
- Sự trùng lặp — thông tin agent có thể lấy từ codebase gây hại, không giúp ích
- Xung đột hướng dẫn — khi hướng dẫn file context xung đột với những gì agent quan sát trong code, nó thêm bước giải quyết; loại bỏ xung đột bằng cách không duplicate những gì đã được mã hóa
Template AGENTS.md Thực Tế
Dựa trên kết quả nghiên cứu, một AGENTS.md hiệu quả cho backend service điển hình trông như thế này:
# Agent Context
## Ràng buộc quan trọng
- KHÔNG sửa file trong /legacy — đây là third-party integration không có tests
- KHÔNG thay đổi file database schema mà không tạo migration trong /migrations
- Service chạy trong multi-tenant context — user data isolation được enforce bởi TenantContext middleware; luôn verify nó trong scope cho data query
## Behavior bên ngoài không rõ ràng từ code
- Payment processor (Stripe) có timeout 5 giây; retry phải dùng exponential backoff với jitter
- Feature flags service cache value trong 60 giây; test dựa vào flag value phải tính đến điều này
## Chạy trước khi submit
- `make lint && make test-unit` phải pass
- Cho thay đổi trong /api/v2/* cũng chạy `make test-integration`Chỉ vậy thôi. Không có danh sách thư mục. Không có tổng quan kiến trúc. Không có style guide. Những thứ đó đều có thể khám phá từ code hoặc được enforce tốt hơn qua tooling.
Khi Nào Không Cần AGENTS.md
Nghiên cứu gợi ý rằng đối với codebase đơn giản, có cấu trúc tốt, nơi các quy ước được enforce nhất quán bởi tooling, file context tối ưu là không có file context nào. Overhead của việc xử lý hướng dẫn — ngay cả hướng dẫn ngắn — chỉ đáng khi hướng dẫn encode thông tin mà agent thực sự không thể lấy từ nơi khác.
Câu hỏi đúng không phải là “tôi nên đặt gì vào AGENTS.md?” Mà là “agent này thực sự cần biết gì mà nó không thể tự khám phá?” Nếu danh sách đó ngắn, AGENTS.md của bạn nên ngắn. Nếu danh sách trống, hãy cân nhắc xóa file.
Đo Lường Xem File Context Có Giúp Ích Không
Nếu bạn đang duy trì AGENTS.md, hãy đo lường tác động của nó. Điều này dễ hơn tưởng:
- Chạy cùng tập task với AGENTS.md hiện tại của bạn
- Chạy cùng task với AGENTS.md tối giản (3-5 ràng buộc quan trọng)
- Chạy cùng task không có AGENTS.md
- So sánh: tỷ lệ thành công task, số bước mỗi task, và chi phí token
Hầu hết team thực hiện phép đo này phát hiện AGENTS.md hiện tại của họ là net negative. Follow-up trung thực: xóa nó, xây dựng lại từ đầu bắt đầu chỉ với những ràng buộc thất bại trong lần chạy không có context.
Kết quả ETH Zurich không phải là file context xấu. Mà là file context tệ thì xấu, và hầu hết file context đều tệ. Fix không phải là thêm chi tiết — mà là tuyển chọn không thương tiếc những gì agent thực sự cần.
Thuận Lương là Tech Lead với 15+ năm kinh nghiệm về .NET, cloud architecture, và AI systems. Anh viết về những bài học từ việc xây dựng các hệ thống production thực tế.