AGENTS.md vs CLAUDE.md có thực sự hiệu quả? Nghiên cứu nói: đừng viết dài (2026)
Các file như AGENTS.md / CLAUDE.md có giúp coding agent không? Một nghiên cứu 2026 trả lời: có, nhưng ít - và viết dài còn phản tác dụng. Trên nhiều agent và model, file ngữ cảnh không cải thiện rõ tỉ lệ hoàn thành task, trong khi chi phí inference tăng hơn 20%. Cách đúng không phải bỏ file đi, mà là viết gọn (lệnh test/build, rule cấm, path quan trọng) và đẩy phần còn lại sang các file nạp-the-nhu-cầu kiểu progressive disclosure.
- Số liệu nghiên cứu và trạng thái tool (AGENTS.md là chuẩn cross-tool, cú pháp import) đã đối chiếu với nguồn tại thời điểm viết; các tool này đổi nhanh nên hãy kiểm tra lại docs live.
AGENTS.md và CLAUDE.md - có giống nhau không?
Về cơ bản chúng là cùng một ý tưởng - một file hướng dẫn để agent đọc và nắm quy ước dự án - chỉ khác tên theo từng tool. CLAUDE.md là quy ước của Claude Code. AGENTS.md là chuẩn cross-tool đang lên: được Codex CLI, Copilot CLI, Gemini CLI, Cursor và cả Claude Code đọc.
Cả hai làm cùng một việc: đưa cho agent một bản brief bền vững, sống sót qua các phiên chat, để nó không phải hỏi lại quy ước mỗi lần. Điểm khác đáng nhớ: CLAUDE.md giữ được vài năng lực riêng của Claude Code mà AGENTS.md chưa chuẩn hóa - rõ nhất là nạp phân cấp (hierarchical loading) và cú pháp import. Muốn nắm cách viết CLAUDE.md từ A tới Z kèm mẫu, xem hướng dẫn viết CLAUDE.md chuẩn.
Một dòng để khỏi nhầm ba thứ na ná nhau: AGENTS.md (file chuẩn) khác AgentKit (bộ kit cho Claude Code, agentkit.best) và khác OpenAI AgentKit (Agent Builder/ChatKit).
Nghiên cứu nói gì? Có tác dụng, nhưng ít
Câu hỏi "file ngữ cảnh có thật sự giúp không" giờ đã có dữ liệu. Nghiên cứu "Evaluating AGENTS.md" của Gloaguen và cộng sự (nộp 02/2026) đo hiệu quả của file ngữ cảnh trên nhiều agent, nhiều model và nhiều repo. Kết quả đáng để dừng lại suy nghĩ:
- Không cải thiện rõ tỉ lệ hoàn thành task - đúng cho cả file do LLM sinh lẫn file do dev tự viết. Đây là điểm ngược với khuyến nghị phổ biến.
- Chi phí inference tăng hơn 20% trung bình.
- Repository overview (mô tả tổng quan repo) - thứ được nhiều nhà cung cấp khuyến nghị - lại không hữu ích. Ngược lại, các chỉ dẫn cụ thể trong file thì được agent tuân theo.
Lưu ý một chỗ hay bị nói quá: không phải "file do dev viết thì tốt hơn". Nghiên cứu cho thấy cả hai loại đều không cải thiện thành công một cách tổng quát. Nhưng vì chỉ dẫn thì được tuân theo còn overview thì không - kết luận thực dụng rất rõ: cắt phần overview thừa, giữ lại phần chỉ dẫn hành động được. File nhỏ đi, thành công không đổi, chi phí giảm.
Nghịch lý: agent làm theo... quá hăng
Điều thú vị là agent không phớt lờ chỉ dẫn - nó theo quá nhiệt tình. Nhắc tới test, nó chạy nhiều test hơn. Nhắc tới tool, nó dùng nhiều tool hơn. Nhắc tới workflow riêng của repo, nó explore nhiều hơn.
Vấn đề là nhiều chỉ dẫn trong đó không giúp giải task nhanh hơn - chúng chỉ làm task nặng hơn. Mỗi dòng bạn thêm vào là một dòng agent thấy mình "phải" làm gì đó. Đó là lý do một file phình to vừa tốn token vừa kéo dài task mà không đổi lại kết quả tốt hơn.
Vậy AGENTS.md không sai - cách ta VIẾT nó mới sai
Kết luận không phải "bỏ file ngữ cảnh". Kết luận là: đừng biến AGENTS.md thành cuốn cẩm nang 2.000 từ để agent đọc lại mỗi lần fix một con bug.
Giữ lại thứ hành động được:
- Lệnh test, lệnh build, lệnh chạy.
- Các rule không được phá (không đổi public API, không đụng thư mục X…).
- Các path / thư mục quan trọng.
Rồi để agent tự lo phần còn lại. Nói vui: nếu trói agent quá chặt vào hiểu biết của mình, nó cũng sẽ... dốt như mình thôi. Cho nó chút khoảng trời để bay, rồi lái về đúng yêu cầu sau.
Viết kiểu "progressive disclosure" (như SKILL.md)
Cách viết đáng học nằm ở chính SKILL.md: progressive disclosure - nạp theo nhu cầu. Thay vì nhồi mọi thứ vào một file, hãy tách thành các file nhỏ và lazy-load: "nếu làm A thì đọc file X". Khi không cần, agent bỏ qua và không tốn context cho nó.
Trong CLAUDE.md, bạn làm điều này bằng cú pháp import @path/to/file (kiểm tra lại cú pháp live vì tool đổi nhanh): file gốc chỉ giữ phần cốt lõi luôn đúng, còn chi tiết cho từng loại việc nằm ở file riêng, chỉ được kéo vào khi liên quan. Đây chính là cơ chế mà skills của Claude Code dùng để nạp hướng dẫn theo ngữ cảnh; muốn tự dựng một cái, xem cách tạo custom skill. Về ngân sách context tổng thể, xem quản lý context & memory.
Một file hay hai? (mẹo symlink)
Nếu chỉ muốn giữ một file, hãy chọn AGENTS.md vì nó là chuẩn được nhiều tool đọc nhất. Nếu Claude Code là agent chính nhưng bạn vẫn muốn dùng được mọi tool, một mẹo phổ biến là giữ một nguồn sự thật duy nhất: viết AGENTS.md rồi symlink CLAUDE.md trỏ về nó.
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.mdCách này giữ nội dung ở một chỗ mà vẫn phục vụ mọi tool. Đánh đổi: bạn mất phần nạp phân cấp và import riêng của CLAUDE.md - nên nếu bạn dựa nhiều vào import @path, cân nhắc giữ CLAUDE.md là file thật thay vì symlink.
Before/after: từ cẩm nang dài xuống ~chục dòng
Ai dùng bộ kit cho Claude Code từ ngày đầu tới giờ sẽ nhận ra: từ một CLAUDE.md dài dằng dặc, mình đã nén xuống còn hơn chục dòng. Vì file này nên là project-specific - chứa đúng các rule bổ sung mà dự án này cần - chứ không phải một file catch-all generic ôm đồm mọi thứ.
Nguyên tắc rút gọn: mỗi dòng phải trả lời được câu "dòng này đổi quyết định của agent chỗ nào?". Nếu không, nó là overview thừa - cắt, hoặc đẩy sang file lazy-load. Mẫu CLAUDE.md gọn để copy nằm ở hướng dẫn viết CLAUDE.md chuẩn.
Giữ gì / cắt gì (checklist)
| ✅ Giữ | ❌ Cắt (hoặc lazy-load) |
|---|---|
| Lệnh test / build / run | Mô tả tổng quan repo (overview) |
| Rule "không được phá" | Văn xuôi giải thích dài dòng |
| Path / thư mục quan trọng | Workflow hiếm dùng |
Import @path tới chi tiết khi cần | Kiến thức chung agent đã biết |
Bộ kit có sẵn chuẩn context gọn (AgentKit)
Nếu không muốn tự căn chỉnh, các bộ kit như AgentKit (agentkit.best, CLI ak - khác OpenAI AgentKit) ship sẵn quy ước CLAUDE.md gọn cùng bộ skills viết theo kiểu progressive disclosure, nên bạn đỡ phải tự viết một cuốn cẩm nang phình to. Muốn xem tổng quan, đọc review AgentKit hoặc xem thẳng AgentKit (giảm 20% qua link).
Câu hỏi thường gặp (FAQ)
AGENTS.md và CLAUDE.md có giống nhau không?
Cùng một ý tưởng, khác tên theo tool. CLAUDE.md là quy ước của Claude Code; AGENTS.md là chuẩn cross-tool được nhiều tool đọc (Codex, Copilot CLI, Gemini CLI, Cursor và cả Claude Code). CLAUDE.md còn giữ vài năng lực riêng như nạp phân cấp và import.
Claude Code có đọc AGENTS.md không?
Theo tình hình hiện tại, Claude Code đọc được AGENTS.md bên cạnh CLAUDE.md - nhưng đây là surface đổi nhanh, hãy kiểm tra docs live. Nếu bạn dựa vào import @path và nạp phân cấp, CLAUDE.md vẫn là file gốc đáng giữ.
File ngữ cảnh có thực sự giúp agent không?
Theo nghiên cứu 2026, không cải thiện rõ tỉ lệ hoàn thành task (cả file do LLM sinh lẫn do dev viết) và làm chi phí tăng hơn 20%. Riêng repository overview không hữu ích, trong khi chỉ dẫn cụ thể thì được tuân theo. Bài học: giữ chỉ dẫn hành động được, cắt overview.
CLAUDE.md nên dài bao nhiêu?
Càng gọn càng tốt - chỉ giữ phần cốt lõi luôn đúng, đẩy chi tiết sang file lazy-load qua import @path. Mỗi dòng phải đổi được quyết định của agent; nếu không thì cắt.
"Progressive disclosure" trong CLAUDE.md là gì?
Là tách nội dung thành các file nhỏ và nạp theo nhu cầu: "nếu làm A thì đọc file X". Khi không liên quan, agent bỏ qua nên không tốn context - giống cách skills nạp hướng dẫn khi ngữ cảnh khớp.
Nên bỏ gì / không bỏ gì vào AGENTS.md?
Giữ: lệnh test/build/run, rule không được phá, path quan trọng, và import tới chi tiết khi cần. Cắt: mô tả tổng quan repo, văn xuôi dài, workflow hiếm dùng, kiến thức chung agent đã biết.
Kết luận
File ngữ cảnh có tác dụng - khi gọn và viết kiểu progressive disclosure. Viết dài là tự bắn vào chân: tốn hơn 20% chi phí mà không tốt hơn. Cắt overview, giữ chỉ dẫn hành động được, lazy-load phần còn lại. Xem hướng dẫn viết CLAUDE.md chuẩn để có mẫu, và nếu bạn cũng đang chạy autonomous, đọc kèm cách dùng /goal hiệu quả.