AGENTS.md: một file context cho mọi coding agent (Codex, Antigravity, Claude)

Bạn bỏ ra cả buổi chiều để viết một file CLAUDE.md sạch sẽ. Cuối cùng thì agent của bạn cũng thôi đoán mò về stack và bắt đầu chạy đúng lệnh test. Rồi một đồng nghiệp mở chính cái repo đó bằng Codex, bạn thử Antigravity CLI trên một nhánh phụ, và toàn bộ cái context bạn vất vả gây dựng chẳng theo qua được. Mỗi công cụ lại đòi file riêng của nó, đặt ở chỗ riêng của nó.

AGENTS.md là câu trả lời cho mớ hỗn độn đó: một file Markdown thuần, đặt ở thư mục gốc của repo, mà bất kỳ coding agent nào cũng đọc trước khi đụng vào code của bạn.

AGENTS.md thực ra là gì

Không có phép màu nào cả. Nó là một file Markdown tên là AGENTS.md, thường nằm ở gốc repo, được agent nạp như một bộ chỉ dẫn cố định trước khi bắt tay vào việc. Hãy coi nó như cái README bạn viết cho đồng đội AI của mình thay vì cho đồng đội con người: dự án này là gì, build và test ra sao, các quy ước cần tôn trọng, và những cái bẫy cần tránh.

Đây là một quy ước mở, vốn đã được Codex và một danh sách công cụ agent ngày càng dài đọc tới, với mục tiêu rõ ràng là có thể dùng chung giữa chúng. Một file, nhiều agent, thay vì một file riêng cho từng công cụ.

AGENTS.md vs CLAUDE.md vs GEMINI.md

Khi hướng dẫn này được viết lần đầu, mỗi công cụ đi tìm file riêng của nó. Từ đó đến nay, phần lớn đã hội tụ về AGENTS.md:

• Codex đọc AGENTS.md, và GitHub Copilot CLI, Cursor, Amp cùng phần lớn các agent CLI mới hơn cũng vậy.
• Claude Code đọc CLAUDE.md, và từ phiên bản 2.1.277 nó cũng tự đọc AGENTS.md khi thư mục làm việc của bạn và các thư mục phía trên không có CLAUDE.md hay CLAUDE.local.md. Khi đã có CLAUDE.md, Claude chỉ đọc file đó, trừ khi bạn đổi thiết lập Project instructions trong /config.
• Antigravity CLI đọc AGENTS.md hoặc GEMINI.md, ở thư mục gốc repo hoặc trong bất kỳ thư mục con nào, cộng thêm một thư mục .agents/rules/ và các quy tắc toàn cục trong ~/.gemini/.

Nội dung gần như y hệt nhau ở cả ba: context dự án, lệnh, quy ước. Điều vẫn còn khác nhau là file nào được một công cụ chọn khi có nhiều file cùng tồn tại. Đó đúng là lý do vì sao chép tay cùng một bộ quy tắc vào ba file là một cuộc chiến cầm chắc phần thua (phần dưới sẽ nói thêm về chuyện giữ chúng đồng bộ). Chúng tôi đã kiểm tra các hành vi này vào ngày 10 tháng 10 năm 2026, đối chiếu với tài liệu về bộ nhớ (memory) của Claude Code và tài liệu về quy tắc (rules) của Antigravity.

Nếu bạn làm việc chủ yếu trong Claude Code, hướng dẫn CLAUDE.md của chúng tôi đào sâu vào cấu trúc riêng cho Claude. AGENTS.md là người anh em trung lập, không phụ thuộc provider, của file đó.

Nên ghi gì trong đó

Giữ nó ngắn và đậm tín hiệu. Agent đọc file này ở mọi tác vụ, nên từng dòng đều phải cạnh tranh để giành sự chú ý. Những thứ cốt lõi:

• Stack, gói gọn trong một hơi. "Next.js 16, TypeScript, Prisma, MariaDB." Không lịch sử, không quảng cáo.
• Những lệnh quan trọng. Cách cài đặt, chạy, build, test và lint. Lệnh chính xác: npm test, chứ không phải "chạy test đi."
• Quy ước. Cách đặt tên, cách bố trí file, cách xử lý lỗi, những pattern bạn thực sự bắt tuân thủ khi review.
• Một bản đồ thư mục. Hai dòng về việc mọi thứ nằm ở đâu, để agent thôi grep một cách mù quáng.
• Quy tắc "đọc trước khi đụng". "Đọc docs/payments.md trước khi sửa bất cứ thứ gì dưới billing/." Riêng thói quen này thôi đã tránh được khối tổn thất.
• Những điều cấm tuyệt đối. "Không bao giờ tạo nhánh khi chưa được yêu cầu." "Không để đường dẫn tuyệt đối gắn với máy trong các file đã commit."

Những sai lầm khiến agent phớt lờ file này

Một file context hỏng trong im lặng. Agent không báo lỗi, nó chỉ trôi dạt đi thôi. Các nguyên nhân thường gặp:

1. Quá dài. Một file 600 dòng chôn vùi năm quy tắc thực sự quan trọng. Cắt hết những gì agent có thể tự suy ra từ chính code.
2. Mâu thuẫn. "Luôn viết test" ở một mục, "bỏ qua test cho bản prototype" ở mục khác. Agent sẽ chọn đại một cái.
3. Đường dẫn gắn với máy. /Users/you/project/... trong file đã commit sẽ hỏng với mọi đồng nghiệp, và với mọi agent trên mọi máy khác. Hãy giữ đường dẫn tương đối.
4. Lệnh đã lỗi thời. Lệnh test thay đổi từ sáu tháng trước, còn file thì không. Giờ agent chạy nhầm thứ với một sự tự tin tuyệt đối.
5. Không có ưu tiên. Mọi thứ đều "quan trọng," nên chẳng có gì quan trọng cả. Đặt những điều không thể thương lượng lên đầu và gắn nhãn cho chúng.
6. Đổ tài liệu vào. Đây là chỉ dẫn, không phải wiki. Hãy đặt link trỏ ra tài liệu của bạn, đừng dán hết vào đây.

Giữ một context duy nhất xuyên suốt các provider

Đây là phần thực dụng mà hầu hết hướng dẫn bỏ qua. Nếu bạn, hoặc nhóm của bạn, chạy nhiều hơn một agent CLI, bạn sẽ không muốn có ba bản sao cùng một bộ quy tắc cứ trôi dạt mỗi bản một kiểu.

Hai cách làm gọn gàng:

• Một AGENTS.md, không gì khác. Nếu không ai cần quy tắc chỉ áp dụng cho Claude, hãy giữ một file AGENTS.md duy nhất: Codex, Antigravity CLI và Claude Code 2.1.277 trở lên đều đọc nó. Cái bẫy ở đây diễn ra trong im lặng: một file CLAUDE.md, hoặc một CLAUDE.local.md cá nhân, được thêm vào sau này sẽ khiến Claude Code ngừng đọc AGENTS.md.
• Một file chuẩn, một dòng import. Để hết mọi thứ trong AGENTS.md và mở đầu CLAUDE.md bằng dòng @AGENTS.md, rồi viết các quy tắc chỉ dành cho Claude bên dưới. Claude đọc file được import trước. Chính repo của chúng tôi làm theo cách này: file CLAUDE.md của nó chỉ có đúng một dòng đó. Một liên kết tượng trưng (ln -s AGENTS.md CLAUDE.md) cũng dùng được, nhưng không ổn trên Windows, nơi việc tạo liên kết tượng trưng cần quyền người quản trị hoặc Chế độ nhà phát triển, và một bản clone không có core.symlinks sẽ nhận được một file văn bản một dòng thay vì các chỉ dẫn của bạn.

Dù theo cách nào thì quy tắc vẫn vậy: viết context một lần, không phải một lần cho mỗi provider. Đó cũng là cách duy nhất để nó luôn đúng, bởi một file duy nhất mới là file mà người ta thực sự chịu khó bảo trì.

Khi bạn chạy nhiều agent cùng lúc

Một file AGENTS.md ở cấp repo trả lời cho câu hỏi "dự án này là gì." Nó không trả lời cho câu "agent này là ai." Khi bạn chạy song song một agent Backend, một agent Frontend và một agent QA trên cùng một code, mỗi agent đều cần context dự án dùng chung cộng với vai trò riêng của nó.

Đó chính là lớp mà AgentsRoom thêm vào bên trên file AGENTS.md của bạn. Mỗi agent nhận một vai trò riêng với system prompt riêng của nó (DevOps, Frontend, Security và nhiều nữa), để file dùng chung vẫn gọn nhẹ trong khi từng agent vẫn biết rõ phần việc của mình. Nó không phụ thuộc provider ngay từ thiết kế, nên cùng một thiết lập có thể chạy Claude, Codex hay Antigravity cạnh nhau, và những chỉ dẫn lặp đi lặp lại của bạn sống trong một Thư viện Prompt thay vì phải gõ lại trong từng phiên làm việc.

Khi đến được điểm đó, phương pháp để chạy nhiều agent song song mà không mất dấu là bài đọc tiếp theo tự nhiên nhất.

Điều cần nhớ

Hãy viết một file AGENTS.md duy nhất. Giữ nó ngắn, giữ nó cập nhật, giữ nó di động. Trỏ mọi công cụ vào nó thay vì duy trì một file cho mỗi agent. Context của bạn thôi bị trói vào cái CLI mà bạn tình cờ khởi đầu, và các agent của bạn, dù là những cái nào, đều bắt đầu từ cùng một trang.

Muốn mọi agent trên một màn hình, mỗi cái với vai trò riêng và context dùng chung của bạn? Tải AgentsRoom, kết nối provider của bạn, và cho cả đội của bạn vào việc.

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

AGENTS.md là gì?

Một file Markdown, thường đặt ở thư mục gốc của repo, được các coding agent nạp như một bộ chỉ dẫn cố định trước khi bắt tay vào việc: dự án này là gì, build và test ra sao, các quy ước cần tôn trọng và những cái bẫy cần tránh. Đây là một quy ước mở dùng chung giữa các công cụ chứ không phải file của riêng một công cụ, được Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp và, từ phiên bản 2.1.277, Claude Code đọc.

Claude Code có đọc AGENTS.md không?

Có, từ Claude Code 2.1.277, nhưng chỉ khi không có CLAUDE.md, .claude/CLAUDE.md hay CLAUDE.local.md trong thư mục làm việc của bạn hoặc các thư mục phía trên. Khi đó nó nạp mọi AGENTS.md từ thư mục làm việc đi ngược lên trên, và AGENTS.md của một thư mục con khi nó mở một file trong thư mục đó. Nếu đã có CLAUDE.md, Claude chỉ đọc file đó, trừ khi bạn đặt Project instructions thành claude-md-and-agents-md trong /config. Với các phiên bản cũ hơn, hãy đặt dòng @AGENTS.md ở đầu một file CLAUDE.md.

Antigravity dùng AGENTS.md hay GEMINI.md?

Cả hai. Antigravity đọc một AGENTS.md, một GEMINI.md hoặc một thư mục .agents/rules/ ở thư mục gốc repo hoặc trong bất kỳ thư mục con nào, cùng các quy tắc toàn cục trong ~/.gemini/. Các quy tắc cộng dồn với nhau thay vì thay thế nhau, và khi hai quy tắc mâu thuẫn, quy tắc của thư mục cụ thể hơn sẽ thắng.

Nên giữ AGENTS.md hay CLAUDE.md?

Giữ AGENTS.md làm file duy nhất bạn bảo trì. Nếu bạn cũng cần quy tắc chỉ dành cho Claude, hãy thêm một CLAUDE.md có dòng đầu tiên là @AGENTS.md và viết các quy tắc đó bên dưới: Claude đọc file được import trước. Nếu không cần, chỉ riêng AGENTS.md là đủ cho Claude Code 2.1.277 trở lên. Tránh giữ hai bản sao đầy đủ của cùng một bộ quy tắc: bản mà không ai sửa sẽ trở nên lỗi thời.

Nên đặt AGENTS.md ở đâu?

Ở thư mục gốc của repo, cho các quy tắc áp dụng ở mọi nơi. Claude Code và Antigravity cũng đọc các file AGENTS.md trong thư mục con, nên một package hay một service có lệnh riêng có thể mang file riêng của nó, được đọc khi agent làm việc trong thư mục đó.