- 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
Chưa có bình luận nào.