# AGENTS.md là gì? Một file hướng dẫn dùng chung cho Codex, Claude Code và Cursor

URL: https://opcaios.org/blog/agents-md-la-gi
Ngày: 2026-11-03
Cập nhật: 2026-11-03
Tác giả: Lê Quốc Nghĩa
Chuyên mục: Hướng dẫn

AGENTS.md là gì? AGENTS.md là một file Markdown thường, đặt ở gốc dự án (và có thể ở thư mục con), chứa hướng dẫn dành cho tác tử lập trình AI: dự án làm gì, chạy thử bằng lệnh nào, quy ước code, điều không được làm. Trang chuẩn agents.md (đọc ngày 03/11/2026) gọi đây là "README cho tác tử". Điểm khiến AGENTS.md đáng dùng là nhiều công cụ cùng đọc một file: Codex của OpenAI, Cursor, Gemini CLI, GitHub Copilot coding agent, Claude Code và hàng chục công cụ khác. Bài này không hứa AGENTS.md làm tác tử luôn tuân thủ: file là ngữ cảnh, không phải cơ chế ép buộc, và OPCAIOS không có số đo về mức cải thiện. Bài gồm: cách Codex nạp AGENTS.md theo từng cấp, khi nào Claude Code đọc, Cursor hỗ trợ ra sao, nên ghi gì, một mẫu ngắn, và cách OPCAIOS giữ một nguồn sự thật cho nhiều tác tử.

![Sơ đồ AGENTS.md: file cấp người dùng trong thư mục Codex, file ở gốc kho, file trong thư mục con được nối từ gốc xuống thư mục đang làm việc, file gần hơn được ưu tiên; AGENTS.override.md thay file cùng cấp; Codex, Cursor và Claude Code cùng đọc một file chung](https://opcaios.org/images/blog/agents-md-la-gi/so-do.webp)
*AGENTS.md theo cấp và các công cụ cùng đọc. Sơ đồ: OPCAIOS.*

## AGENTS.md là chuẩn của ai và những công cụ nào ủng hộ?

AGENTS.md là một định dạng mở, không thuộc riêng hãng nào. Theo trang agents.md (đọc ngày 03/11/2026), định dạng này hiện do Agentic AI Foundation thuộc Linux Foundation quản lý, và trang ghi hơn 60.000 dự án mã nguồn mở đã dùng. Công cụ được nêu trên trang gồm OpenAI Codex, Google Jules, Gemini CLI, Cursor, GitHub Copilot coding agent, VS Code, JetBrains Junie, Devin, Windsurf, Aider, Zed, Warp và nhiều công cụ khác. Chuẩn này không có trường bắt buộc, không cần frontmatter. Quy tắc quan trọng nhất là khi có nhiều file lồng nhau, file gần file đang sửa nhất được ưu tiên, còn lời dặn trực tiếp của người dùng trong khung chat đứng trên tất cả. Trong danh sách chúng tôi đọc không thấy Claude Code, nhưng tài liệu riêng của Claude Code có mục AGENTS.md (xem phần dưới).

## Codex đọc AGENTS.md theo thứ tự nào?

Codex đọc AGENTS.md theo hai tầng: tầng người dùng rồi tầng dự án, và nối chúng thành một chuỗi hướng dẫn mỗi lần chạy. Theo trang AGENTS.md trong tài liệu Codex (developers.openai.com chuyển hướng sang learn.chatgpt.com/docs/agent-configuration/agents-md, đọc ngày 03/11/2026), thứ tự cụ thể là:

1. **Cấp người dùng:** Codex tìm trong thư mục home của Codex, mặc định `~/.codex` trừ khi bạn đặt biến `CODEX_HOME`. Nếu có `AGENTS.override.md` thì dùng file đó, không thì dùng `AGENTS.md`. Ở cấp này chỉ lấy file đầu tiên không rỗng.
2. **Cấp dự án:** Codex bắt đầu từ gốc dự án (thường là gốc Git) rồi đi xuống từng thư mục cho tới thư mục hiện tại.
3. **Mỗi thư mục tối đa một file:** lần lượt thử `AGENTS.override.md`, rồi `AGENTS.md`, rồi các tên dự phòng khai báo trong cấu hình.
4. **Nối từ trên xuống:** các file được ghép từ gốc xuống, cách nhau bằng dòng trống. File càng gần thư mục hiện tại càng đứng sau, nên ghi đè được hướng dẫn chung phía trên.
5. **File rỗng bị bỏ qua.**

Chuỗi được dựng một lần mỗi lần chạy: sửa AGENTS.md xong phải khởi động lại Codex.

### File AGENTS.override.md dùng khi nào?

`AGENTS.override.md` dùng khi cần thay hẳn file cùng cấp mà không xoá file gốc. Ví dụ giả định: thư mục thanh toán cần quy tắc khác hẳn; đặt `AGENTS.override.md` ở đó thì Codex dùng nó thay AGENTS.md cùng chỗ.

### Giới hạn dung lượng và tên file dự phòng là gì?

Codex dừng thêm file khi tổng dung lượng chạm giá trị `project_doc_max_bytes`, mặc định 32 KiB theo tài liệu đọc ngày 03/11/2026. Tài liệu gợi ý hai cách khi vượt: tăng giới hạn, hoặc chia hướng dẫn xuống các thư mục con. Dự án đã có file hướng dẫn tên khác thì khai báo `project_doc_fallback_filenames` trong `~/.codex/config.toml` (tài liệu ví dụ `TEAM_GUIDE.md`). Muốn biết Codex đã nạp file nào, tài liệu gợi ý hỏi thẳng Codex liệt kê nguồn hướng dẫn. Chi tiết về config.toml có trong bài [config.toml của Codex](/blog/cau-hinh-codex-config-toml).

## Claude Code đọc AGENTS.md khi nào?

Claude Code đọc AGENTS.md khi dự án không có CLAUDE.md. Theo trang "How Claude remembers your project" của Claude Code (đọc ngày 03/11/2026): nếu thư mục làm việc và các thư mục cha chỉ có AGENTS.md, Claude dùng AGENTS.md; nếu có cả CLAUDE.md hoặc CLAUDE.local.md, mặc định chỉ đọc CLAUDE.md; nếu CLAUDE.md nhập AGENTS.md bằng dòng `@AGENTS.md`, cả hai cùng được nạp. Cách dựng CLAUDE.md và cú pháp import xem bài [CLAUDE.md là gì](/blog/claude-md-la-gi).

## Cursor hỗ trợ AGENTS.md ra sao?

Cursor hỗ trợ AGENTS.md ở gốc dự án và ở thư mục con. Theo trang Rules trong tài liệu Cursor (cursor.com/docs/context/rules, đọc ngày 03/11/2026), AGENTS.md là file Markdown thuần, không cần metadata, được giới thiệu như phương án thay `.cursor/rules` cho trường hợp đơn giản. File trong thư mục con tự áp dụng khi làm việc với file trong thư mục đó, được gộp với hướng dẫn của thư mục cha, và hướng dẫn cụ thể hơn được ưu tiên. Tài liệu không nói rõ AGENTS.md xếp trên hay dưới quy tắc trong `.cursor/rules`. File `.md` thường đặt trong `.cursor/rules` bị bỏ qua. OPCAIOS không dùng Cursor hằng ngày nên chưa tự kiểm chứng hành vi này; xem thêm [Cursor là gì](/blog/cursor-la-gi).


## Nên ghi gì vào AGENTS.md?

AGENTS.md nên chứa những điều tác tử không tự đoán được từ code và sẽ cần ở mọi phiên. Trang agents.md gợi ý các nhóm: tổng quan dự án, lệnh build và chạy thử, quy ước viết code, cách test, lưu ý bảo mật, quy tắc commit hay pull request, các bước deploy. Thứ tự ưu tiên chúng tôi gợi ý:

1. **Lệnh chính xác:** cài đặt, chạy thử, build. Theo agents.md, tác tử sẽ thử chạy lệnh test được ghi và sửa lỗi trước khi xong việc.
2. **Ranh giới:** thư mục, file sinh tự động, dữ liệu thật không được chạm.
3. **Quy ước riêng:** đặt tên, ngôn ngữ trả lời, định dạng commit.
4. **Quy trình đầu và cuối phiên:** đọc file nào trước, ghi nhật ký ở đâu.
5. **Bảo mật:** không ghi khoá API, mật khẩu, địa chỉ máy chủ vào AGENTS.md vì file thường được commit lên kho. Xem [5 quy tắc bảo mật dữ liệu khi dùng AI](/blog/bao-mat-du-lieu-kinh-doanh-khi-dung-ai-5-quy-tac).

Không nên ghi: mô tả lại từng file, tài liệu dài cho người, lời dặn mơ hồ kiểu "viết code sạch".

## Mẫu AGENTS.md ngắn cho người làm một mình

Dưới đây là mẫu do OPCAIOS soạn để minh hoạ, không phải file thật của dự án nào; thay lệnh và đường dẫn cho đúng dự án của bạn:

```markdown
# Hướng dẫn cho tác tử

## Dự án
Website bán khoá học, Next.js + Postgres. Code trong src/, migration trong db/.

## Lệnh
- Cài đặt: npm install
- Chạy thử: npm run dev
- Kiểm tra trước khi xong việc: npm run lint && npm test

## Quy tắc
- Trả lời bằng tiếng Việt, ngắn gọn.
- Không sửa file trong db/migrations đã chạy; tạo migration mới.
- Không commit file .env hay khoá API.
- Chỉ commit đúng file mình đã sửa.

## Cuối phiên
- Ghi một dòng tóm tắt vào docs/NHAT_KY.md.
```

Mỗi dòng là một việc kiểm tra được.

## Giữ một nguồn sự thật cho nhiều tác tử thế nào?

Một nguồn sự thật nghĩa là quy tắc chung chỉ được viết ở một chỗ là AGENTS.md, còn file riêng của từng công cụ chỉ trỏ về đó và thêm phần đặc thù. Khi dùng song song Codex, Claude Code và một tác tử khác trên cùng kho, cách làm thực dụng gồm bốn bước:

1. Viết quy tắc chung (lệnh, ranh giới, quy trình phiên) trong AGENTS.md ở gốc kho.
2. Tạo CLAUDE.md chỉ gồm dòng `@AGENTS.md` và vài điều riêng cho Claude Code.
3. Để thói quen cá nhân (ngôn ngữ, giọng trả lời) ở file cấp người dùng của từng công cụ, ví dụ `~/.codex/AGENTS.md` cho Codex.
4. Sửa quy tắc thì chỉ sửa AGENTS.md, rồi mở lại phiên.

Hai file mâu thuẫn thì khó đoán tác tử theo bên nào, nên đừng chép một quy tắc vào nhiều file. Khi nhiều phiên cùng sửa một kho, đọc thêm [nhiều phiên AI cùng sửa một dự án](/blog/nhieu-phien-ai-cung-sua-mot-du-an) và bài [dùng Codex và Claude Code cùng lúc](/blog/dung-codex-va-claude-code-cung-luc).

## Kinh nghiệm của OPCAIOS

OPCAIOS dùng Codex CLI, ứng dụng desktop Codex, Claude Code và Google Antigravity song song trên máy làm việc chính; chúng tôi không dùng Cursor hằng ngày. Cách tổ chức file hướng dẫn hiện tại (kiểm tra ngày 03/11/2026):

1. **Một AGENTS.md chung cho mọi tác tử** ở thư mục gốc người dùng và trong kho ghi chú Obsidian: thứ tự đọc tài liệu đầu phiên, cuối phiên ghi vào file trạng thái chung và nhật ký ngày, cấm để file rác.
2. **Một AGENTS.md cấp người dùng cho Codex** trong thư mục home của Codex, tương đương file cấp người dùng của Claude Code: trả lời tiếng Việt, đọc tài liệu theo thứ tự, ghi nhật ký cuối phiên.
3. **Mỗi phiên chỉ commit đúng file của mình**, vì nhiều phiên dùng chung một kho và chỉ mục Git; commit gộp dễ kéo theo file của phiên khác.
4. **Một số dự án chỉ được sửa code trên một máy nhất định.** Lý do có thật: từng có lần một tác tử deploy từ máy Windows làm hơn 1.500 file hiện là "đã thay đổi" chỉ vì khác kiểu xuống dòng.

Điều chúng tôi chưa có: số đo tác tử tuân thủ hướng dẫn tốt hơn bao nhiêu khi có AGENTS.md, và chưa tự kiểm chứng cách Cursor đọc file. Vẫn cần người kiểm tra kết quả cuối, xem [tôi để tác tử AI xây và vận hành website: 10 bài học thật](/blog/toi-de-tac-tu-ai-xay-va-van-hanh-website-10-bai-hoc-that).

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

### AGENTS.md có bắt buộc phải đặt ở gốc dự án không?

Không bắt buộc, nhưng gốc dự án là chỗ hầu hết công cụ tìm đầu tiên. Codex còn đọc file ở thư mục con trên đường từ gốc kho tới thư mục đang làm việc, và file cấp người dùng trong `~/.codex`. Cursor đọc cả ở gốc lẫn thư mục con. Với dự án nhỏ, một file ở gốc là đủ; dự án nhiều mảng mới cần thêm file con cho từng mảng.

### AGENTS.md khác README.md thế nào?

README viết cho người: giới thiệu, cách cài, cách đóng góp. AGENTS.md viết cho tác tử: lệnh chính xác cần chạy, ranh giới không được sửa, quy ước riêng, những chi tiết sẽ làm README rối nếu nhét vào. Trang agents.md khuyên tách hai file để README vẫn gọn. Không nên chép nguyên README sang AGENTS.md, nhưng trùng vài dòng như lệnh cài đặt thì không sao.

### File AGENTS.md dài bao nhiêu là vừa?

Codex mặc định chỉ đọc tổng cộng 32 KiB từ chuỗi AGENTS.md, theo tài liệu đọc ngày 03/11/2026; phần vượt sẽ không được thêm. Ngoài giới hạn kỹ thuật, file càng dài thì quy tắc quan trọng càng dễ bị chìm. Nên giữ file gốc ngắn, mỗi dòng là một việc kiểm tra được, và chuyển chi tiết của từng mảng xuống AGENTS.md trong thư mục con.

### Dùng cả CLAUDE.md và AGENTS.md có bị xung đột không?

Có thể, nếu chép cùng quy tắc vào hai file rồi sửa lệch nhau. Theo tài liệu Claude Code, khi có CLAUDE.md thì Claude Code mặc định chỉ đọc CLAUDE.md, nên quy tắc chỉ nằm trong AGENTS.md sẽ bị bỏ sót. Cách an toàn: quy tắc chung để trong AGENTS.md, CLAUDE.md chỉ có dòng `@AGENTS.md` và phần riêng cho Claude Code. Sửa một chỗ, mọi tác tử cùng thấy.

### Có nên ghi khoá API hay mật khẩu vào AGENTS.md không?

Không. AGENTS.md thường được commit lên kho và được nạp vào ngữ cảnh của mô hình AI, nên mọi thứ trong đó coi như có thể bị lộ. Ghi tên biến môi trường thay vì giá trị, ví dụ "khoá đọc từ biến môi trường của dịch vụ", và để giá trị thật trong file `.env` nằm ngoài kho. Nếu muốn có người hướng dẫn dựng bộ file hướng dẫn cho nhiều tác tử theo dự án thật của bạn, xem [khoá đào tạo ứng dụng AI](/services/dao-tao-ung-dung-ai) của OPCAIOS.

*Nguồn: agents.md; tài liệu Codex, trang AGENTS.md (developers.openai.com chuyển hướng sang learn.chatgpt.com/docs/agent-configuration/agents-md); tài liệu Claude Code, trang "How Claude remembers your project" (code.claude.com/docs/en/memory); tài liệu Cursor, trang Rules (cursor.com/docs/context/rules); đọc ngày 03/11/2026. Danh sách công cụ ủng hộ, con số 60.000 dự án và giới hạn 32 KiB lấy từ các trang trên, có thể đổi theo bản cập nhật; hành vi AGENTS.md trong Cursor chưa được OPCAIOS tự kiểm chứng. Kinh nghiệm là của OPCAIOS.*