AGENTS.md: một file context cho mọi coding agent (Codex, Gemini, 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ử Gemini 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

Hiện tại bức tranh đang bị chia theo từng công cụ:

• CLAUDE.md là cái mà Claude Code đi tìm.
• GEMINI.md là quy ước của Gemini CLI.
• AGENTS.md là chuẩn dùng chung giữa các công cụ, được Codex và những cái khác đọc, thiết kế ra để làm file trung lập.

Nội dung gần như y hệt nhau ở cả ba: context dự án, lệnh, quy ước. Khác biệt thực sự duy nhất là tên file mà mỗi công cụ đọc mặc định. Đó đú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ộ).

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 file chuẩn, các con trỏ mỏng. Để hết mọi thứ trong AGENTS.md rồi biến CLAUDE.md và GEMINI.md thành file một dòng ghi "xem AGENTS.md," hoặc tạo symlink cho chúng. Một nguồn chân lý duy nhất, mọi công cụ đều được nuôi.
• Một file, dùng chung theo quy ước. Nếu các công cụ của bạn có thể trỏ tới một đường dẫn tùy chỉnh, hãy nhắm tất cả vào AGENTS.md rồi xóa phần còn lại.

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 Gemini 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.