- AGENTS.md đóng vai trò bổ sung cho README và là tệp chuyên dụng chứa ngữ cảnh và hướng dẫn cần thiết khi AI coding agent làm việc trong dự án
- Đang được sử dụng trong hơn 20.000 dự án mã nguồn mở, để sắp xếp các thông tin như build/test/code style tuy không cần thiết với con người nhưng lại quan trọng với agent
- Cung cấp hướng dẫn dành riêng cho agent ở một vị trí rõ ràng và dễ dự đoán, giúp README vẫn gọn gàng đồng thời tăng hiệu quả cộng tác
- Một AGENTS.md duy nhất có thể tương thích với nhiều agent và công cụ khác nhau, và trong các monorepo lớn có thể dùng AGENTS.md riêng cho từng dự án con
- Là một tiêu chuẩn mở được tạo ra nhờ sự hợp tác của nhiều hệ sinh thái như OpenAI Codex, Cursor, Google Jules
Why AGENTS.md?
- README.md là tài liệu dành cho con người, cung cấp hướng dẫn bắt đầu nhanh, mô tả dự án và quy tắc đóng góp
- AGENTS.md là tài liệu bổ trợ dành cho agent, chứa ngữ cảnh chi tiết như quy tắc build/test/code mà không làm README trở nên phức tạp
- Lý do đặt ở tệp riêng
- Cung cấp vị trí hướng dẫn dễ dự đoán để agent tham chiếu
- Giữ README ngắn gọn, tập trung vào người đóng góp là con người
- Cung cấp hướng dẫn chính xác dành riêng cho agent để bổ trợ cho tài liệu hiện có
- Áp dụng tên gọi tiêu chuẩn mở mà ai cũng có thể dùng, thay vì định dạng độc quyền
- Một AGENTS.md có thể tương thích với nhiều AI coding agent và công cụ
How to use AGENTS.md?
- 1. Tạo tệp AGENTS.md
- Đặt ở thư mục gốc của kho lưu trữ (nhiều agent hỗ trợ tự động tạo)
- 2. Viết các mục chính
- Tổng quan dự án
- Lệnh build và test
- Hướng dẫn code style
- Cách kiểm thử
- Các lưu ý về bảo mật
- 3. Thêm hướng dẫn bổ sung
- Những nội dung cần truyền đạt cho thành viên nhóm như quy tắc commit/PR, lưu ý bảo mật, tập dữ liệu lớn, các bước triển khai
- 4. Hỗ trợ monorepo
- Có thể đặt AGENTS.md cho từng package
- Agent sẽ đọc tệp gần nhất và làm theo hướng dẫn phù hợp với subproject đó
- Ví dụ: kho lưu trữ của OpenAI có 88 tệp AGENTS.md
FAQ
- Mục bắt buộc: Không có, có thể tự do dùng định dạng Markdown thông thường
- Khi xảy ra xung đột: AGENTS.md gần nhất được ưu tiên, prompt do người dùng chỉ định sẽ được áp dụng cuối cùng
- Có tự động thực thi hay không: các lệnh test được ghi trong tệp có thể được agent chạy để thử sửa lỗi
- Khả năng cập nhật: có thể thay đổi bất cứ lúc nào, được quản lý như một tài liệu sống
- Di chuyển từ tài liệu hiện có: đổi tên tệp rồi giữ tương thích bằng symbolic link
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
1 bình luận
Ý kiến Hacker News
Với các dự án nhỏ, chỉ một file .md là đủ, nhưng với dự án phức tạp thì cấu trúc thư mục phân cấp kèm index.md hiệu quả hơn nhiều theo kinh nghiệm của tôi
Cấu trúc gồm index.md và các file bên dưới như auth.md, performance.md vừa dễ bảo trì, vừa giúp LLM hay agent chỉ trích xuất đúng ngữ cảnh liên quan mà không tốn token không cần thiết
Các file .docs như vậy phù hợp cho cả con người lẫn LLM, và trong index.md cũng có thể thêm phần hướng dẫn ngắn cho từng file cùng chỉ dẫn tổ chức
Tuy vậy, thay vì tên ".agents", tôi nghĩ những cái tên trực quan hơn như ".codebots" hoặc ".context" sẽ tốt hơn
Tôi nghĩ những file và thư mục quan trọng không nhất thiết phải bị ẩn đi
Đặc biệt là tài liệu, nếu bị ẩn thì lại càng thiếu minh bạch; có lẽ vì thói quen truyền thống, nhưng cách này không phải một pattern tốt
Tôi đang nghĩ tới những cái tên như robot_docs
Thực ra những thông tin kiểu này trùng với điều mà người đóng góp muốn biết, nên tôi nghĩ vốn dĩ nó nên nằm trong CONTRIBUTING.md
Cấu trúc này giống một tài liệu hướng dẫn thiết kế/phong cách lập trình phần mềm dành cho cả con người lẫn robot
Tôi đặt các file .md như vậy trong thư mục docs/, Claude Code tự viết chúng
AGENTS.md và CLAUDE.md chỉ nên dành riêng cho robot, và dù là chia khu vực bằng header h2 trong một file lớn hay tách thành nhiều file thì mỗi cách đều có ưu nhược điểm riêng
Cũng có những định dạng tài liệu kiến trúc hỗ trợ cả hai như Arc42
So với việc tham chiếu một section cụ thể trong một file Markdown lớn, tạo file riêng rồi @mention sẽ dễ hơn và ít sai sót hơn
Khi cần tập trung vào một phần cụ thể, chia nhỏ thành các file nhỏ cũng tốt hơn cho code agent
Các file nhỏ cũng tiện hơn khi review diff/PR
Bạn cũng có thể đặt nhiều file AGENTS.md trong codebase
Tooling chỉ cần đọc cả AGENTS.md ở thư mục hiện tại lẫn thư mục gốc, như vậy thông tin có thể ở gần đoạn code liên quan mà vẫn đi cùng cách làm bạn mong muốn
Tôi cũng dùng cấu trúc tương tự, thêm phần chỉ dẫn ngắn cho từng file trong index.md và đã có kết quả khá tốt
Tôi cũng đang thử cách đặt file quy tắc hành vi mong muốn theo từng thư mục như rules.md
Ví dụ, trong thư mục có nhiều service như realtime-service.ts và queue-service.ts thì đặt một file rules.md ngay bên cạnh
Có thể chỉ định file quy tắc này trong prompt để tạo ra thứ mới một cách dễ dàng, dù cái tên thì vẫn cần nghĩ thêm
Hiện tại là giai đoạn quá độ, khi con người phải viết thêm những hướng dẫn đặc biệt vượt quá nhu cầu của người dùng bình thường để agent hiểu được codebase
Tôi nghĩ sớm thôi những thứ này sẽ không còn cần thiết
Nếu tài liệu dự án của chúng ta vốn đã đầy đủ ngay từ đầu, thì mọi nội dung trong AGENTS.md cũng có thể đã nằm trong đó
Chúng ta nên luôn viết tài liệu cho con người, và điểm mạnh của LLM là chúng có thể đọc được thứ do con người viết
Tôi nghĩ đây mới là góc nhìn đúng để thiết kế
Nó không chỉ hữu ích cho việc hiểu codebase mà còn để quy định một phong cách cụ thể, ví dụ viết test bằng thư viện assert nào, cấm comment, dùng structured logging, v.v.
Thậm chí có thể còn hữu ích hơn với dự án mới khi gần như chưa có code
Tôi đoán các quy tắc mà máy có thể đọc sẽ ngày càng được áp dụng rộng rãi trong xã hội
Ví dụ như xe tự lái và luật giao thông; ngay cả con người cũng khó hiểu những biển báo đòi hỏi nhiều ngữ cảnh như "cấm rẽ phải khi đèn đỏ, ngày học từ 7~9 giờ", thì với máy còn khó hơn
Rốt cuộc các cơ quan quản lý sẽ phải đổi sang tín hiệu ít phụ thuộc ngữ cảnh hơn hoặc có khả năng máy đọc được như QR code
Nếu không có thay đổi như vậy, máy móc sẽ thường xuyên vi phạm quy tắc
Ở những lĩnh vực như business logic, tôi nghĩ sau này vẫn sẽ cần những hướng dẫn đặc biệt dành cho agent
Máy không thể tự hiểu được đang xây gì, ý đồ là gì, hay mục tiêu cuối cùng của dự án trừ khi con người nói rõ
Ngay cả những thứ như kiến trúc cũng khác nhau tùy người; phải có một mô hình sẵn trong đầu thì mới hiểu được thay đổi thực tế đang diễn ra, và cuối cùng đây mới là nút thắt thật sự
Nhìn chung tôi đồng ý, nhưng cũng có lúc nảy sinh nhu cầu ép một số thông tin nhất định phải được đưa vào context mỗi lần, nên muốn tách nó ra thành file riêng
Nếu không tài liệu hóa những quy tắc và giả định mà chúng ta đang ngầm hiểu, LLM sẽ không biết được
Nó có thể suy ra một phần từ code, nhưng không thể đạt 100%, nên điều quan trọng là phải viết rõ yêu cầu ra
AGENTS.md rốt cuộc cũng chỉ đóng vai trò như README.md nhưng lại thu hút được làn sóng hype, và điều thú vị là mọi người thực sự đang điền nội dung vào nó
Mọi người vốn ngại viết tài liệu cho người khác, nhưng lại chăm chỉ viết cho robot, điều này khá thú vị
Hiện tượng này hơi giống việc thiết kế công thái học cho một nhóm rất nhỏ nhưng cuối cùng lại tạo ra kiểu tay cầm phù hợp hơn với tất cả mọi người
Có lẽ là ngược lại: vì mọi người không đọc tài liệu nên chẳng ai có động lực viết cả
Còn CLAUDE.md cho agent thì chỉ cần viết một lần là sắp có 1000 agent đọc, nên thấy đáng để viết hơn
Dù sao thì chẳng phải chỉ cần ghi tối thiểu vào README.md là được sao?
Thực tế thì ngay cả agent cũng có thể không đọc tài liệu này, hoặc chỉ cần chỉ thị thêm vài lần là quên sạch mọi thứ
Tình hình hiện tại là mọi người đang cố chủ động loại con người, kể cả chính mình, ra khỏi quá trình phát triển, nên agent bắt buộc phải có hướng dẫn phù hợp
Nguyên nhân là mong muốn loại bỏ mọi sự can dự của con người vào phát triển phần mềm đang ngày càng lớn
Có người đùa rằng không khí bây giờ đúng là vibe coding
Hình như trước đây cũng từng có ý kiến rằng viết tài liệu cho bot rốt cuộc cũng chẳng khác gì viết tài liệu tốt cả
Cuối cùng thì cảm giác như chỉ đang nói "hãy tạo file AGENTS.md rồi nhét phép thuật vào đó", sau đó dẫn link sang một website bên ngoài
Trường hợp của tôi là đang phát triển một coding agent quản lý hơn 5.000 repository
Trạng thái của agent được lưu trong thư mục ẩn .agent, bên trong có các thư mục cấu hình theo từng vai trò agent cùng chỉ dẫn rõ ràng cho từng vai trò
Tôi đặt một thư mục agents trong thư mục dự án, chia nhiều file theo vai trò và quản lý chúng theo kiểu <Role> <instruction>
Agent chỉ đọc file của vai trò đã được định nghĩa, còn trạng thái thì lưu trong thư mục dot<tên coding agent>
Việc khởi tạo được thực hiện bằng /init, và thay vì chỉ index toàn bộ code của repo, nó tạo ra một high-level summary tóm tắt toàn bộ kiến trúc và logic
Bản tóm tắt này được cung cấp dưới dạng "ghost comments" có thể bật tắt trong editor, là metadata không được commit vào code thực
Mỗi phần tóm tắt được nối chính xác với các dòng code nhờ một hệ thống mapping tinh vi
Ban đầu tôi từng áp dụng trực tiếp RAG vào code nhưng không đạt kết quả mong muốn nên mới chuyển sang cấu trúc hiện tại
Hiện giờ tôi dùng mô hình tìm kiếm lai, kết hợp tìm kiếm cú pháp nhanh dựa trên AST với tìm kiếm ngữ nghĩa (RAG) dựa trên phần tóm tắt
Ví dụ, nếu hỏi "cơ chế xác thực của app này hoạt động như thế nào?", tìm kiếm cú pháp chỉ tìm ra các hàm chứa từ như login, còn tìm kiếm ngữ nghĩa thì dùng phần tóm tắt để nắm được toàn bộ luồng xác thực theo kiểu tường thuật và kết nối nội dung nằm rải rác ở nhiều file, nên nó hoạt động gần như ma thuật
Bổ sung thêm, có thể tạo cấu trúc phân cấp cho phần tóm tắt, theo dạng B-tree hoặc tree thông thường
Tức là có summary cho từng method/class/module và mỗi tầng lại trỏ xuống tầng thấp hơn
RAG có thể đi sâu bao nhiêu tùy cần thiết theo semantic query, và ở mỗi bước, tầng dưới được tóm tắt lại để giảm lượng thông tin nhưng vẫn giữ đúng ý nghĩa cần thiết
Cách này đặc biệt hiệu quả khi code có mức độ trừu tượng tốt
Ví dụ như hàm add(n1, n2), chỉ nhìn tên là đã đủ hiểu nghĩa nên không cần biết implementation, nhưng các hàm ngoài đời thực thường kiêm nhiều vai trò như logging hay cache nên tùy tình huống vẫn có thể phải đưa code thực vào context
Tôi muốn nghe giải thích chi tiết hơn
Có cảm giác con người đang dần bị dẫn dắt để viết tài liệu dự án cho tử tế hơn
Nói đùa thôi nhưng thật ra tôi vẫn dùng chính điểm này để thuyết phục team
Ngay cả khi LLM không thật sự tăng năng suất quá nhiều, thì kết quả cuối cùng vẫn là mọi người tài liệu hóa tốt hơn hẳn
"Mission. Fucking. Accomplished." xkcd 810
Tôi vẫn chưa chắc việc phải tách riêng README.md và AGENTS.md có thực sự cần thiết hay không
Theo một bài tổng hợp liên quan,
lý do nên tách là
lý do không nên tách là
README.md giờ giống một trang marketing/landing page hơn, còn AGENTS.md và CLAUDE.md là nơi để lấy nội dung thực về code/kiến trúc/cách dùng
Khi đọc ví dụ, tôi cũng nghĩ y như vậy, và thực ra có lẽ chỉ cần một README.md đủ tốt là đã đủ rồi
README là cho con người, còn AGENTS.md v.v. là cho LLM
Cách dùng/cài đặt thì để trong readme, còn cách compile/chạy test, các quyết định kiến trúc, tiêu chuẩn coding, cấu trúc repo v.v. thì gom vào tài liệu cho agent
Cũng phải tính tới vấn đề dung lượng context trong LLM
README.md thường quá dài nên khó nhét toàn bộ vào context
AGENT.md chỉ nên chứa ngắn gọn các lệnh cốt lõi như test, build mà LLM thực sự cần
Có thể sẽ trùng với README, nhưng tôi vẫn muốn tránh việc nội dung không cần thiết bị gửi lặp đi lặp lại trong context
Chẳng phải lời hứa của AI là chúng ta không cần bám vào một format chính xác, chỉ cần viết theo cách mình muốn rồi máy sẽ tự hiểu sao?
Thực tế thì họ chỉ chuẩn hóa tên file, còn nội dung thì đúng là không ép format nào cả, ai muốn viết thế nào cũng được
AGENTS.md là Markdown tiêu chuẩn nên bạn có thể dùng bất kỳ heading nào, còn agent thì tự parse text
Dù vậy, ở mức độ nào đó cấu trúc và định dạng vẫn quan trọng
Chỉ là chưa đến mức cú pháp code chính xác mà thôi
Cuối cùng thì vẫn quay về kết luận là phải viết nội dung thật rõ ràng
Tài liệu càng dài thì cách tiếp cận có cấu trúc càng thuận lợi cho con người trong việc bảo trì
Mỗi agent tôi dùng, như Claude Code, Gemini, Aider, lại dùng tên file khác nhau
Sẽ rất tốt nếu được chuẩn hóa, nhưng hiện tại tôi vẫn chấp nhận công sức dùng ruler để tự động sinh nhiều định dạng
Đặc biệt là cách mỗi agent tiêu thụ file cấu hình MCP cũng khác nhau, nên tôi không nghĩ việc chuẩn hóa sẽ sớm xảy ra
ruler
Nếu nhìn hơi cynical một chút, tôi nghĩ đó là do các động thái nhằm tạo vendor lock-in
Chuẩn hóa có thể dẫn tới commoditization nên có vẻ các hãng không thích điều đó
Jules dùng AGENTS.md, cho thấy Google đang tham gia tiêu chuẩn này
Nếu Gemini Code Assist tiếp tục được duy trì, tôi đoán nó cũng sẽ hỗ trợ AGENTS.md
Tôi không thấy tài liệu của Aider nhắc đến một tên file cụ thể nào, nếu có link thì mong bạn chia sẻ
Có vẻ Anthropic hiện là bên duy nhất vẫn chưa hỗ trợ tên file tiêu chuẩn
Hơi tiếc là những công cụ như ruler lại thực sự cần thiết
Đây là một website có cảm giác khá lạ
Tôi tự hỏi liệu OpenAI làm ra nó để kéo traffic và phục vụ mục tiêu định vị marketing hay không
Thực chất không hề có format nào ngoài việc chỉ định tên file
Việc không có Anthropic/Claude cũng khá dễ thấy; dù vậy vẫn có thể dùng symbolic link để nối CLAUDE.md sang AGENTS.md
Thực ra nó do sourcegraph tạo ra và đã tồn tại từ tháng 5
Trước đây là agent.md, giờ được 301 redirect sang agents.md
Có thể xem link cũ
Cũng có bài công bố chính thức
Có vẻ gần đây họ đã hợp tác với OpenAI
Điều thú vị là ban đầu là agent.md nhưng giờ đã đổi thành agents.md
Lý do Claude không có trong danh sách là vì chỉ riêng Claude hiện vẫn chưa hỗ trợ quy ước tên file tiêu chuẩn