Đừng tự động tạo AGENTS.md bằng /init — chỉ làm chi phí tăng thêm 20%

Luận điểm chính

• Nếu tự động tạo tệp ngữ cảnh cho AI coding agent (AGENTS.md) bằng lệnh /init, hiệu năng của agent thực tế còn giảm và chi phí tăng hơn 20%
• Cốt lõi của vấn đề là cung cấp lặp lại những thông tin mà agent vốn có thể tự phát hiện
• Trong AGENTS.md, chỉ nên đưa vào những thông tin mà agent không thể biết chỉ bằng cách đọc mã nguồn

Kết quả nghiên cứu: AGENTS.md giúp ích hay gây hại

• Lulla et al. (ICSE JAWs 2026): thí nghiệm ghép cặp trên 124 GitHub PR, chỉ thay đổi có hay không có AGENTS.md để so sánh
  • Khi có AGENTS.md, thời gian thực thi giảm 28,64%, token đầu ra giảm 16,58%
  • Tệp dùng trong nghiên cứu này là tài liệu được chính lập trình viên bảo trì ngoài thực tế, chứa tri thức đặc thù của dự án
• Nghiên cứu của ETH Zurich: kiểm thử 4 agent trên SWE-bench và các benchmark tương tự, đồng thời phân biệt tệp do LLM tự sinh với tệp do lập trình viên viết
  • Ngữ cảnh do LLM tự sinh: tỷ lệ thành công giảm 2–3%, chi phí tăng hơn 20%
    • Trong môi trường đã loại bỏ toàn bộ tài liệu sẵn có như README, tệp do LLM tạo lại tăng hiệu năng 2,7%
  • Tệp do lập trình viên tự viết: tỷ lệ thành công tăng khoảng 4%, chi phí tăng tối đa 19%
• Kết luận: vấn đề không phải nội dung tự động tạo là xấu, mà là sự trùng lặp
  • Nếu đưa cùng một thông tin hai lần, nó chỉ tạo thêm nhiễu; chỉ có tri thức không thể tự khám phá do con người viết mới thực sự hữu ích

Vì sao tự động tạo lại có hại

• AGENTS.md được tự động tạo phần lớn chứa những thông tin mà agent đã có thể tự tìm ra
  • Tổng quan codebase (100% đầu ra của Sonnet 4.5 và 99% đầu ra của GPT-5.2 đều bao gồm phần này)
  • Cấu trúc thư mục, tech stack, mô tả module
• Cung cấp lại thông tin mà agent đã biết chỉ tiêu tốn token mà không tạo thêm giá trị
• Hiệu ứng neo bám: nếu nhắc đến các pattern cũ, agent sẽ bị cố định vào chúng dù có phương án tốt hơn
  • Điều này phù hợp với nghiên cứu “Lost in the Middle” (Liu et al., 2024) — ngữ cảnh dài làm phân tán sự chú ý và giảm hiệu năng

Nên đưa gì vào AGENTS.md và không nên đưa gì

• Nên đưa vào (thông tin agent không thể tự khám phá)
  • Chỉ định công cụ: “hãy dùng uv để quản lý package”
  • Quy tắc không trực quan: “test phải luôn chạy với --no-cache, nếu không fixture sẽ sinh false positive”
  • Ràng buộc hệ thống: “module auth đang dùng middleware tùy biến, không được refactor sang Express tiêu chuẩn”
  • Khi công cụ được nêu trong tài liệu, agent dùng nó 1,6–2,5 lần mỗi tác vụ; nếu không được ghi rõ, con số này giảm mạnh xuống dưới 0,05 lần
• Không nên đưa vào (thông tin agent có thể tự khám phá)
  • Cấu trúc thư mục, layout monorepo
  • Tổng quan tech stack, các pattern kiến trúc tiêu chuẩn

Giới hạn cấu trúc của tệp tĩnh

• Ngay cả AGENTS.md được viết tốt cũng có nhược điểm nền tảng — tệp là tĩnh, còn công việc thì động
• Chỉ dẫn trong một tệp đơn không thể rẽ nhánh theo điều kiện của từng loại tác vụ
  • Ngay cả với tác vụ sửa tài liệu, chỉ dẫn “chạy toàn bộ test trước khi commit” vẫn được áp dụng, làm lãng phí token và thời gian
  • Cảnh báo migration DB bị nạp khi đang refactor CSS, còn gợi ý tối ưu hiệu năng lại đi kèm lúc sửa lỗi bảo mật
• Framework ACE (ICLR 2026): thay vì tệp tĩnh, cách tiếp cận Agentic Context Engineering dùng pipeline generator/reflector/curator để tiến hóa ngữ cảnh một cách động, cho hiệu năng cao hơn phương pháp tĩnh 12,3%

Cấu trúc tốt hơn, nhưng vẫn chưa được xây dựng

• Nhiều người đã độc lập đi đến cùng một kết luận về AGENTS.md
  • Cấu trúc đúng không phải một tệp đơn, mà là một lớp định tuyến + ngữ cảnh tập trung được nạp khi cần
• Layer 1 - tệp giao thức: không phải tổng quan codebase hay style guide, mà là tài liệu định tuyến
  • Định nghĩa các persona có thể dùng và điều kiện gọi, kỹ năng và loại tác vụ phụ trách, kết nối MCP và mục đích sử dụng
  • Chỉ chứa lượng tối thiểu các sự thật về repo mà agent không thể tự phát hiện, ngoài ra không thêm gì khác
• Layer 2 - tệp persona/kỹ năng: được nạp có chọn lọc tùy theo loại tác vụ
  • Agent UX và agent backend nạp ngữ cảnh khác nhau, và không nạp ngữ cảnh của phía còn lại
• Layer 3 - sub-agent bảo trì: agent chuyên trách giữ cho tệp giao thức luôn chính xác
  • Tài liệu sẽ bị mục ruỗng — nghiên cứu của ETH Zurich cho thấy ngay cả với tệp vừa mới tạo, hiệu năng vẫn giảm
  • Nếu một AGENTS.md bị bỏ mặc 6 tháng vẫn mô tả dependency đã bị thay hoặc cấu trúc thư mục đã đổi, vấn đề sẽ nghiêm trọng hơn nhiều
• Hiện chưa có coding agent lớn nào cung cấp lifecycle hook để triển khai kiến trúc này một cách dễ dàng — có thể xấp xỉ bằng sub-agent và scoped context, nhưng đây vẫn là khoảng trống công cụ chưa được lấp đầy

Tối ưu hóa tự động

• Arize AI không viết thủ công chỉ dẫn trong CLAUDE.md, mà dùng một vòng lặp tối ưu hóa tự động
  • Chạy agent trên các tác vụ huấn luyện → đánh giá kết quả → tạo phản hồi của LLM về nguyên nhân thất bại → cải thiện chỉ dẫn bằng meta-prompting → lặp lại
  • Độ chính xác tăng +5,19% trong bài test cross-repo và +10,87% trong bài test in-repo
• Điều khó chịu mà bộ tối ưu hóa phát hiện ra là: thứ giúp con người hiểu codebase không giống với thứ LLM cần để điều hướng
  • Những thông tin như “dịch vụ này dùng repository pattern” đương nhiên có vẻ hữu ích với lập trình viên, nhưng lại có thể chỉ là nhiễu với mô hình
  • Ngược lại, những gì mô hình thực sự cần (phân biệt đường dẫn import cụ thể, quy ước đặt tên tệp không trực quan, v.v.) thường đã được lập trình viên nội hóa đến mức không nghĩ tới chuyện viết ra
• Việc viết AGENTS.md thủ công ngầm giả định rằng lập trình viên biết agent cần gì
  • Bằng chứng thực nghiệm cho thấy có lẽ họ không biết
  • Bộ tối ưu hóa tìm ra khoảng cách giữa “những gì ta nghĩ là quan trọng” và “những gì thực sự làm thay đổi kết quả”
• Điều đó không có nghĩa là nên từ bỏ việc viết tài liệu — 5% là có ý nghĩa, nhưng không mang tính chuyển đổi. Ý ở đây là giữ trực giác một cách lỏng tay và kiểm thử trong thực tế

Tư duy đúng khi nhìn vào AGENTS.md

• Hãy xem AGENTS.md như bản ghi của một quy trình mà ta vẫn chưa sửa được
• Mỗi dòng được thêm vào là tín hiệu cho thấy trong codebase có điểm nào đó đủ mơ hồ để làm AI agent bối rối, và rất có thể người đóng góp mới cũng sẽ vướng y như vậy
• Phản ứng đúng không phải làm tệp ngữ cảnh ngày càng dài, mà là sửa nguyên nhân gốc rễ
  • Agent đặt utility vào sai thư mục → nghĩa là cấu trúc thư mục vốn đã gây nhầm lẫn, cần tổ chức lại
  • Agent cứ tiếp tục dùng dependency đã bị loại bỏ → nghĩa là cấu trúc import đang khiến việc chọn nhầm trở nên quá dễ, cần sửa lại
  • Agent bỏ sót kiểm tra kiểu dữ liệu → đừng dựa vào chỉ dẫn; hãy bắt lỗi này tự động trong pipeline build
• AGENTS.md không phải cấu hình vĩnh viễn mà là công cụ chẩn đoán — thêm một dòng, điều tra vì sao agent cứ lặp lại lỗi đó, sửa nguyên nhân gốc, rồi xóa dòng ấy đi
• Một kỹ thuật đáng thử: bắt đầu với AGENTS.md gần như trống, chỉ thêm một chỉ dẫn duy nhất là “nếu phát hiện điều gì bất ngờ hoặc gây bối rối trong dự án này, hãy để lại nhận xét”. Phần lớn các bổ sung mà agent đề xuất không nên được lưu giữ lâu dài, mà chỉ là dấu mốc cho những chỗ codebase đang thiếu rõ ràng

Khuyến nghị thực tiễn

• Hãy ngừng chạy /init — trừ khi repo hoàn toàn không có tài liệu, kết quả tự động sinh ra chỉ trùng lặp với tài liệu hiện có
• Trước khi thêm một dòng vào AGENTS.md, hãy tự hỏi: “agent có thể biết điều này bằng cách đọc code không?” Nếu có, đừng viết vào
• Khi agent thất bại lặp đi lặp lại, hãy sửa chính codebase trước khi mở rộng tệp ngữ cảnh
  • Cải thiện cấu trúc mã, thêm rule cho linter, mở rộng test coverage — chỉ khi vẫn chưa đủ thì mới đụng tới AGENTS.md
• Nếu bạn vận hành agent ở quy mô lớn trong CI/CD hoặc pipeline review tự động, hãy nhận thức rằng mức overhead chi phí 15–20% sẽ tích lũy theo lãi kép qua hàng nghìn lần chạy
• Bản năng muốn onboard agent như một nhân viên mới (tham quan văn phòng, sơ đồ tổ chức, giải thích kiến trúc) là điều tự nhiên, nhưng coding agent không phải người mới — nó có thể grep toàn bộ codebase trước cả khi bạn gõ xong prompt. Thứ agent cần không phải bản đồ, mà là vị trí của bãi mìn

[lloydkwon]

Nghe nói cuối cùng vẫn là cuộc chiến về context...
Có lẽ nên để tạo riêng file md cho agent và file md cho người dùng thì hơn.

[lukeio]

Hoàn toàn đồng ý. Cấu trúc dễ đọc cho con người (README) và cấu trúc dễ để LLM phân tích (AGENTS.md) vốn dĩ hoàn toàn khác nhau. Nếu cứ tự động tạo toàn bộ ngữ cảnh rồi ném vào một cách vô tội vạ thì chỉ lãng phí chi phí token API, thậm chí tôi còn thường xuyên thấy hiện tượng hallucination trở nên nghiêm trọng hơn. Cuối cùng, dù có hơi phiền, có lẽ vẫn hiệu quả nhất khi con người tự tay cô đọng và tinh chỉnh tài liệu hướng dẫn dành cho agent.

[sonnet]

Thuở ban đầu đã có README, và AGENTS.md thực chất chỉ là README được tạo ra dành cho các agent thôi.

[jaehar16]

Nhưng chẳng phải đã có README rồi sao?

[armila]

Nhưng bản thân mô hình cũng thay đổi chỉ trong vài tháng, và phải sửa agents cho phù hợp với mô hình... Có phải tốc độ thay đổi của mô hình còn nhanh hơn cả thời gian để tạo ra một cấu trúc agents phù hợp không? Cứ như thể công cụ đã thay đổi mất rồi trước khi con người kịp làm quen với nó...

[jjw9512151]

Cuối cùng có vẻ điều quan trọng là phải giữ cho mọi thứ trong context luôn thuần khiết và dùng ít token... Xét ở khía cạnh này thì Hán tự có vẻ cũng khá hữu ích nhỉ. haha

[aliveornot]

Với mô hình thì tiếng Anh gần như đã là 1 từ tương ứng 1 ký tự (token), chẳng phải về thực chất cũng giống Hán tự sao

[eususu]

Ồ, tôi chưa từng nghĩ đến cách tiếp cận này, nhưng có vẻ khá hợp lý!

[t7vonn]

Ồ ..