AGENTS.md là gì: file hướng dẫn chung cho mọi AI agent lập trình

Thử hình dung một nhóm phần mềm ba người. Anh A dùng Codex, chị B dùng Cursor, em C mê Gemini CLI. Trưởng nhóm vừa đổi lệnh chạy test, sửa file luật của Codex, quên file của Cursor. Hôm sau Cursor vẫn chạy lệnh cũ, test báo xanh, code lỗi lên tới bản chạy thật.

Chuyện "mỗi công cụ một sổ luật" này chính là thứ AGENTS.md muốn dẹp. AGENTS.md là một định dạng mở, thực chất là một file Markdown đặt ở thư mục gốc dự án, dùng để dặn các AI agent lập trình cách làm việc với dự án: lệnh cài, lệnh test, quy ước code, cách đặt tên commit.

Đọc nhanh trong 30 giây

• AGENTS.md là định dạng mở, trang agents.md ra mắt ngày 19/08/2025, tự mô tả là "README cho agent". Mã nguồn trang theo giấy phép MIT.
• Một file duy nhất cho nhiều agent: Codex, Amp, Jules, Cursor, Factory, RooCode, Aider, Gemini CLI, Kilo Code, OpenCode, Phoenix, Zed.
• Không cần cài gì: tạo file AGENTS.md ở gốc repo, viết bằng Markdown thường.
• Hợp với đội dùng từ hai công cụ AI lập trình trở lên.

AGENTS.md là gì, dùng vào việc gì?

AGENTS.md là file hướng dẫn chung mà nhiều agent lập trình cùng đọc, thay cho việc mỗi hãng một tên file riêng. Trước đó, Claude Code đọc CLAUDE.md, Gemini CLI đọc GEMINI.md, Cursor có thư mục luật riêng. Một dự án dùng ba công cụ phải giữ ba file gần giống nhau, sửa chỗ này quên chỗ kia.

Ví von cho dễ hình dung: trước đây mỗi thiết bị một kiểu sạc, đi công tác phải mang ba cục sạc. AGENTS.md giống việc cả ngành thống nhất một chuẩn cổng sạc. Một sợi dây, cắm máy nào cũng vừa.

Ba sổ luật dễ lệch nhau; một sổ luật chung thì sửa một lần là đủ.

Còn README thì sao? README là tờ giới thiệu cho người mới vào nhóm: dự án làm gì, chạy thử ra sao. AGENTS.md là phần dặn dò riêng cho "đồng nghiệp AI": chạy test bằng lệnh nào, thư mục nào không được đụng, trước khi gửi pull request phải kiểm tra gì. Tách riêng để README gọn cho người đọc, còn agent có chỗ cố định để tìm luật.

Theo trang agents.md, định dạng này hình thành từ sự phối hợp của OpenAI Codex, Amp, Jules của Google, Cursor và Factory. Nếu anh chị chưa quen các agent này, có thể đọc trước bài về OpenAI Codex CLI và Gemini CLI.

Viết AGENTS.md: ghi những gì cho đủ?

AGENTS.md không có trường bắt buộc nào, chỉ là Markdown thường với tiêu đề tùy ý. Trang agents.md gợi ý năm mục hay dùng:

1. Tổng quan dự án.
2. Lệnh build và lệnh test.
3. Quy ước viết code.
4. Hướng dẫn kiểm thử.
5. Lưu ý bảo mật.

Ngoài ra, những gì anh chị sẽ dặn một đồng nghiệp mới đều có thể ghi vào: cách viết commit, quy định pull request, bước deploy, chỗ chứa dữ liệu lớn không nên mở. Một file mẫu ngắn, theo cấu trúc trang agents.md đưa ra:

# AGENTS.md

## Môi trường
- Cài thư viện: `pnpm install`
- Chạy bản dev: `pnpm dev`

## Kiểm thử
- Chạy toàn bộ test: `pnpm test`
- Sửa hết lỗi test và lỗi kiểu dữ liệu trước khi báo xong.

## Pull request
- Tiêu đề dạng: [ten-goi] Mô tả ngắn
- Luôn chạy `pnpm lint` và `pnpm test` trước khi commit.

Không có mẫu bắt buộc: viết như dặn một đồng nghiệp mới là được.

Mẹo

Trang agents.md cho biết phần lớn agent tự soạn được bản nháp nếu anh chị yêu cầu. Gõ thử: "Đọc dự án này và viết file AGENTS.md gồm lệnh cài, lệnh test, quy ước code." Sau đó đọc lại, xóa chỗ agent đoán sai, thêm những luật chỉ người trong nhóm mới biết.

Dự án lớn nhiều thư mục: agent nghe file nào?

Agent đọc file AGENTS.md gần nhất với chỗ đang sửa trong cây thư mục. Giống một cao ốc văn phòng: tòa nhà có nội quy chung, từng tầng lại có nội quy riêng của công ty thuê. Đứng ở tầng nào thì theo nội quy tầng đó trước, còn lời dặn trực tiếp của sếp (câu lệnh anh chị gõ trong khung chat) thắng mọi tờ nội quy.

Với dự án lớn nhiều gói (monorepo), cứ đặt thêm một AGENTS.md trong từng gói. Trang agents.md cho biết repo chính của OpenAI lúc viết có 88 file AGENTS.md.

Nội quy tòa nhà và nội quy từng tầng: file gần chỗ đang sửa nhất sẽ thắng.

Ví dụ một website có phần quản trị và phần API. Thư mục admin/ dùng React, api/ dùng Python. Đặt một AGENTS.md ở gốc ghi luật chung (commit, bảo mật), thêm admin/AGENTS.md ghi lệnh pnpm test, và api/AGENTS.md ghi lệnh chạy test Python. Khi agent sửa file trong api/, nó theo luật của api/AGENTS.md.

Chuyển sang AGENTS.md trong 5 phút

1. Tạo file AGENTS.md ở thư mục gốc repo, hoặc nhờ agent soạn nháp như mẹo ở trên.
2. Nếu dự án đã có file tên khác, trang agents.md hướng dẫn đổi tên rồi tạo liên kết để công cụ cũ vẫn đọc được:

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

3. Với Aider, thêm vào .aider.conf.yml:

read: AGENTS.md

4. Với Gemini CLI, khai báo trong .gemini/settings.json:

{
  "contextFileName": "AGENTS.md"
}

Câu lệnh mẫu khi giao việc:

Đọc AGENTS.md trước. Thêm trường số điện thoại vào form đăng ký,
chạy đúng lệnh test ghi trong AGENTS.md, sửa đến khi test qua hết rồi mới báo.

Mấy chỗ dễ vấp

Lưu ý

• Claude Code chưa nằm trong danh sách: tính tới ngày 21/08/2025, trang agents.md không liệt kê Claude Code; Claude Code vẫn đọc CLAUDE.md. Cách tôi hay làm là giữ nội dung chính ở AGENTS.md, còn CLAUDE.md chỉ là liên kết tới nó, hoặc một dòng nhập file theo cú pháp @ mà tài liệu Claude Code mô tả. Nên thử trên máy mình trước khi áp cho cả nhóm.
• Liên kết trên Windows: lệnh ln -s chạy trên macOS, Linux. Trên Windows, tạo liên kết thường cần quyền quản trị hoặc bật chế độ nhà phát triển, nên nhiều nhóm chọn chép file cho đơn giản.
• Agent sẽ chạy lệnh anh chị ghi: trang agents.md xác nhận agent sẽ cố chạy các lệnh kiểm tra được liệt kê và sửa lỗi trước khi xong việc. Đừng ghi lệnh nguy hiểm như xóa dữ liệu, deploy lên môi trường thật.
• Không ghi bí mật: AGENTS.md nằm trong repo, ai đọc được repo đều đọc được file. Mật khẩu, khóa API để ở file môi trường.

Nhận xét của chuyên gia

AGENTS.md là thay đổi nhỏ nhưng tôi đánh giá cao, vì nó giải đúng một chuyện tôi gặp khi đào tạo AI cho các nhóm kỹ thuật: mỗi người một công cụ, mỗi công cụ một file luật, vài tuần sau không ai biết file nào là bản đúng.

Hợp với ai: doanh nghiệp có đội phần mềm từ hai người trở lên, dùng nhiều agent khác nhau, hoặc thuê ngoài một phần việc lập trình. Một file luật chung giúp người mới và agent mới vào việc nhanh hơn, và là chỗ để trưởng nhóm ghi quy định bắt buộc.

Chưa hợp với ai: người chỉ dùng duy nhất Claude Code thì cứ viết CLAUDE.md là đủ; doanh nghiệp chưa có repo, chưa có lệnh test tự động thì AGENTS.md chưa giúp được nhiều, vì phần giá trị nhất của file là lệnh kiểm tra.

Cách bắt đầu của tôi: chọn một repo đang làm, nhờ agent viết bản nháp, trưởng nhóm duyệt trong 30 phút, dùng thử một tuần. Ghi lại những lần agent làm sai luật, bổ sung vào file. Coi AGENTS.md như tài liệu sống: ai đổi quy trình thì sửa file trong cùng pull request. Đủ ổn mới nhân ra các repo khác.

Một câu để nhớ: nhiều agent không đáng sợ, nhiều sổ luật mới đáng sợ.

Nếu anh chị đang theo dõi chuỗi bài, xem thêm các mốc trước đó ở dòng thời gian AI.

Câu hỏi thường gặp

AGENTS.md có bắt buộc theo mẫu nào không?

Không. Trang agents.md ghi rõ AGENTS.md chỉ là Markdown chuẩn, anh chị đặt tiêu đề tùy ý, agent đọc nội dung chữ trong đó.

AGENTS.md khác gì README.md?

README.md viết cho người: giới thiệu dự án, cách chạy thử, cách đóng góp. AGENTS.md viết cho agent: lệnh build, lệnh test, quy ước chi tiết mà ghi vào README sẽ làm rối.

Dự án có nhiều file AGENTS.md thì agent theo file nào?

Agent theo file gần nhất với file đang sửa trong cây thư mục. Câu lệnh anh chị gõ trực tiếp trong khung chat được ưu tiên hơn mọi file AGENTS.md.

Có cần sửa AGENTS.md sau khi viết không?

Có. Trang agents.md khuyên coi nó là tài liệu sống, quy trình đổi thì cập nhật file theo.

Nguồn: AGENTS.md, 21/08/2025.