AGENTS.mdAGENTS.md: vị trí và cách các tool đọc tệp
AGENTS.md là tệp hướng dẫn dự án ở định dạng Markdown thuần, được hầu hết coding agent đọc mà không cần cấu hình thêm. OpenAI đã đóng góp tệp này cho Agentic AI Foundation thuộc Linux Foundation; hơn 60k dự án mã nguồn mở đang sử dụng.
Vị trí
- AGENTS.md ở thư mục gốc của repository, áp dụng cho toàn bộ dự án.
- Các tệp AGENTS.md lồng trong thư mục con hoặc package; agent sử dụng tệp gần nhất trong cây thư mục.
- OpenAI Codex: tệp toàn cục ~/.codex/AGENTS.override.md hoặc, nếu tệp đó trống hay không tồn tại, ~/.codex/AGENTS.md.
- Cline: tệp toàn cục ~/.agents/AGENTS.md.
- Claude Code cũng chấp nhận .claude/AGENTS.md.
Định dạng
Markdown thuần, không có frontmatter hay trường bắt buộc; có thể dùng mọi kiểu tiêu đề. Định dạng này không giới hạn kích thước, nhưng OpenAI Codex dừng đọc khi đạt project_doc_max_bytes, mặc định là 32 KiB.
# Acme web app
Customer-facing web app with an admin area and a REST API.
## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint and type-check: `pnpm lint && pnpm tsc --noEmit`
## Code style
- TypeScript strict mode; no `any` in new code.
- Keep database access in `src/db/`.
## Never
- Never commit secrets or .env files.
- Never edit files under `src/generated/` by hand.
Thứ tự ưu tiên và hợp nhất
Tệp AGENTS.md gần với tệp đang chỉnh sửa nhất sẽ được ưu tiên; chỉ dẫn trực tiếp trong chat luôn ghi đè mọi tệp. OpenAI Codex nối nội dung từ một tệp trong mỗi thư mục, đi từ thư mục gốc dự án đến thư mục làm việc, nên các tệp gần hơn xuất hiện sau và được ưu tiên. Claude Code mặc định bỏ qua AGENTS.md khi có CLAUDE.md.
Các tool đọc tệp này
| Công cụ | Hỗ trợ |
|---|---|
| OpenAI Codex | Hỗ trợ trực tiếp. Đọc tệp toàn cục, sau đó đọc tối đa một tệp trong mỗi thư mục từ thư mục gốc đến thư mục làm việc; giới hạn mặc định là 32 KiB. |
| Claude Code | Hỗ trợ trực tiếp từ v2.1.277, nhưng chỉ khi không có CLAUDE.md hoặc CLAUDE.local.md, trừ khi đặt thành claude-md-and-agents-md. |
| Cursor | Hỗ trợ trực tiếp ở thư mục gốc và các thư mục con; tệp lồng nhau được kết hợp với tệp ở thư mục cha, và tệp cụ thể hơn sẽ được ưu tiên. |
| GitHub Copilot (cloud agent, code review, VS Code) | Hỗ trợ trực tiếp ở mọi vị trí trong repository; tệp gần nhất sẽ được ưu tiên. |
| Devin Desktop (formerly Windsurf) | Hỗ trợ trực tiếp. Tệp ở thư mục gốc luôn được áp dụng; tệp trong thư mục con chỉ áp dụng cho thư mục đó. |
| Cline | Hỗ trợ trực tiếp, cùng với tệp toàn cục ~/.agents/AGENTS.md; bật hoặc tắt trong bảng Rules. |
| Gemini CLI | Tùy chọn: thêm AGENTS.md vào context.fileName trong .gemini/settings.json. |
| Aider | Tùy chọn: thêm read: AGENTS.md vào .aider.conf.yml. |
| OpenClaw | Hỗ trợ trực tiếp dưới dạng tệp hướng dẫn vận hành bắt buộc trong workspace của agent. |
| Listed on agents.md (not individually re-verified) | Nằm trong danh sách 23 công cụ trên agents.md, bao gồm Amp, Jules, Zed, Warp, goose, opencode và JetBrains Junie; chúng tôi chưa kiểm tra từng công cụ. |
Mẹo
- Đổi tên AGENT.md cũ? agents.md đề xuất chạy mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md để cả hai tên đều tiếp tục hoạt động.
- Liệt kê các lệnh test và lint: agent sẽ thử chạy những bước kiểm tra tìm thấy và sửa lỗi trước khi hoàn tất.
- Trong monorepo, hãy thêm một tệp AGENTS.md ngắn cho mỗi package thay vì mở rộng một tệp dài ở thư mục gốc.
- Trong OpenAI Codex, AGENTS.override.md được ưu tiên hơn AGENTS.md trong cùng thư mục.
Tạo AGENTS.md và các tệp rule tương ứng cho năm tool từ một biểu mẫu. Mở trình tạo AGENTS.md →