AGENTS.md là gì và đặt ở đâu?

Là file Markdown ở gốc repo, ghi hướng dẫn cho coding agent: lệnh cài, chạy, test, convention, vùng cấm. Cursor, Codex, Gemini CLI, Copilot và nhiều tool khác đều đọc file này.

AGENTS.md nên ghi những mục nào?

Bảy mục chính: lệnh cài dependency, lệnh chạy dev/build, lệnh test, convention code, file/folder cấm sửa, quy tắc bảo mật (không commit .env, token), và cách dùng trong monorepo với file nested từng package.

Khi nào vẫn cần giữ CLAUDE.md riêng?

Chỉ khi bạn cần hướng dẫn riêng cho Claude Code mà không áp dụng cho agent khác. Còn lại dùng một AGENTS.md chung để team đỡ nhân đôi và tránh lệch nội dung giữa các file vendor.

Trong monorepo, AGENTS.md đặt thế nào?

Đặt một file ở gốc repo, thêm file AGENTS.md nested trong từng package cần hướng dẫn riêng. Agent ưu tiên file gần nhất với file đang sửa.

Lỗi hay gặp khi dùng AGENTS.md?

Hai lỗi phổ biến: copy cùng checklist sang nhiều file vendor rồi quên đồng bộ, và để file trống hoặc chỉ ghi chung chung kiểu 'làm theo README' mà không ghi lệnh cụ thể.

AGENTS.md có thay thế hoàn toàn README không?

Không. README viết cho người đọc, còn AGENTS.md viết cho agent. Nên ghi lệnh cụ thể trong AGENTS.md, không bắt agent đoán từ README.

Bắt đầu với AGENTS.md như thế nào?

Tạo AGENTS.md ở gốc repo, điền đủ 7 mục checklist, cập nhật Cursor/Codex/Claude Code lên bản mới, rồi thử mở repo bằng hai agent khác nhau và xem chúng có chạy đúng lệnh test không.

Công cụ AI

Một file AGENTS.md cho nhiều coding agent — checklist nhanh

AGENTS.md là file Markdown ở gốc repo để nhiều coding agent (Cursor, Codex, Claude Code…) đọc chung hướng dẫn. Bài gom 7 mục nên ghi, kèm lưu ý khi nào vẫn cần CLAUDE.md riêng cho Claude.

Phong Nguyen

PNTECH Writer · 20/09/2026

20/09/20263 lượt xem2 phút đọc

Một file AGENTS.md cho nhiều coding agent — checklist nhanh

Bạn đang mở cùng một repo bằng Cursor hôm nay, Claude Code ngày mai, rồi Codex lúc làm việc nặng. Mỗi tool lại đòi một file hướng dẫn riêng. Copy lệch một chỗ là agent làm sai.

AGENTS.md là file Markdown ở gốc repo (kiểu README dành cho agent): ghi lệnh build, test, convention, chỗ không được đụng. Đây là format mở — Cursor, Codex, Gemini CLI, Copilot và nhiều tool khác đã đọc. Claude Code từ bản 2.1.277 cũng đọc AGENTS.md khi repo không có CLAUDE.md. Nếu đã có CLAUDE.md thì Claude vẫn ưu tiên file đó [S1].

Checklist nên ghi trong AGENTS.md

Lệnh cài — package manager và lệnh cài dependency (pnpm install, dotnet restore…).
Lệnh chạy — dev server / build chính xác từng bước.
Lệnh test — chạy gì trước khi coi việc là xong.
Convention code — ngôn ngữ, lint, style ngắn gọn.
Vùng cấm — file/folder generated hoặc secret không được sửa.
Bảo mật — không commit .env, token; chỗ đặt biến môi trường.
Monorepo — AGENTS.md ở gốc + file nested trong từng package (agent ưu tiên file gần nhất).

Khi nào còn cần CLAUDE.md?

Chỉ khi bạn thật sự cần hướng dẫn riêng cho Claude Code. Còn lại: một AGENTS.md chung giúp team đỡ nhân đôi hướng dẫn giữa nhiều agent.

Xem thêm mục kiến thức trên /kien-thuc.

Không nên làm

Copy cùng một checklist sang 3 file vendor rồi quên sync.
Để AGENTS.md trống hoặc chỉ ghi “làm theo README” mà không ghi lệnh cụ thể.

Áp dụng nhanh

Tạo AGENTS.md ở gốc repo → điền đủ 7 mục trên → cập nhật Claude Code / Cursor / Codex lên bản mới → thử mở repo bằng 2 agent khác nhau và xem chúng có làm đúng lệnh test không.

Theo dõi PN Tech để nhận thêm tip tool coding. Đọc thêm trên pntech.space.

Nguồn: agents.md · Claude Code 2.1.277 (fallback AGENTS.md) · thảo luận cộng đồng trên Hacker News về AGENTS.md

Theo dõi PN Tech để nhận tip tool coding mỗi tuần.

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

Tool mình đã dùng thật

Xem danh sách tool và dịch vụ đã dùng trong công việc — kèm lý do nên cân nhắc và khi nào không cần.

Tool khuyên dùng Đọc bài khác