# AGENTS.md

> VI: https://5ac.vn/wiki/agents-md/ · EN: https://5ac.vn/en/wiki/agents-md/ · lang: vi · spec_as_of 2026-10-18 (spec unversioned) · cluster C3

Tệp markdown ở gốc repository khai báo lệnh build, test, quy ước code và ranh giới quyền hạn cho agent viết code trước khi nó bắt đầu làm việc.

---
## Định nghĩa

AGENTS.md là tệp markdown đặt ở gốc repository mà agent viết code đọc trước khi làm việc: lệnh build và test, quy ước code, ranh giới được sửa và không được sửa. Định dạng không có trường bắt buộc, thuần Markdown; dự án lớn đặt thêm bản sao ở thư mục con để hướng dẫn sát vùng code hơn.

## Cơ chế

Nội dung khuyến nghị theo trang chuẩn gồm overview dự án, lệnh cài và chạy test, quy ước code style, ghi chú an toàn. Không có schema chung: agent đọc text bạn viết như định nghĩa công ước cho dự án đó.

Cơ chế đọc của Codex (OpenAI) là ví dụ cho cách một agent chuẩn xếp lớp hướng dẫn:

| Mức | Vị trí | Vai trò |
| --- | --- | --- |
| Toàn cục | ~/.codex/AGENTS.md | quy tắc chung cho mọi repository |
| Gốc dự án | repo/AGENTS.md | lệnh và quy tắc riêng dự án |
| Thư mục con | services/payments/AGENTS.md | override cho vùng code gần nhất |

Luồng: Toàn cục → Gốc repo → Thư mục đang sửa

Codex nối các tệp từ gốc xuống theo thứ tự, nên tệp nào gần thư mục hiện tại hơn thì thắng; mỗi thư mục chỉ đóng góp một tệp, và tổng bị chặn ở 32 KiB (project_doc_max_bytes) — vượt hạn mức thì tách chỉ dẫn ra thư mục con. Codex dựng chuỗi hướng dẫn một lần mỗi lần chạy, trong TUI là mỗi phiên, và bỏ qua tệp rỗng. Dự án đã có tệp hướng dẫn riêng như TEAM_GUIDE.md vẫn đưa được vào project_doc_fallback_filenames để Codex đọc như AGENTS.md. Quy tắc chung trên agents.md đi cùng hướng này: bản gần file đang sửa nhất thắng, còn lệnh người dùng trong cửa sổ chat áp đảo mọi tệp.

## Neo chuẩn (spec anchor)

Trang chuẩn là [agents.md](https://agents.md); nó không xưng phiên bản nên frontmatter ghi "unversioned" với ngày đối chiếu 18/10/2026. Cùng trang xác nhận AGENTS.md giờ do Agentic AI Foundation quản lý dưới Linux Foundation, và định dạng nổi lên từ cộng tác của OpenAI Codex, Amp, Jules từ Google, Cursor và Factory. Trang cũng liệt kê Jules từ Google, Factory, Aider, goose, opencode, Zed, Warp, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Phoenix, Semgrep, Windsurf và Ona trong số công cụ đọc cùng một tệp AGENTS.md, và đó là cách một định dạng mở đứng vững ngoài tệp cấu hình riêng của một hãng. Cách một công cụ cụ thể đọc tệp có [hướng dẫn chính thức của Codex](https://developers.openai.com/codex/guides/agents-md) để đối chiếu.

## Neo học thuật

Chưa có paper arXiv nào về AGENTS.md được kiểm chứng tại thời điểm viết, nên phần học thuật neo bằng số đo công khai:

| Nguồn | Số liệu | Ngày đo |
| --- | --- | --- |
| [agents.md](https://agents.md/) | hơn 60.000 open-source projects dùng (số trang tự công bố) | 18/10/2026 |
| [agents.md](https://agents.md/) | repo OpenAI có 88 tệp AGENTS.md tại thời điểm trang viết | 18/10/2026 |
| [developers.openai.com](https://developers.openai.com/codex/guides/agents-md) | project_doc_max_bytes mặc định 32 KiB cho mỗi lần gộp | 18/10/2026 |

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

**AGENTS.md khác README ở đâu?** README viết cho người đọc nhanh dự án; AGENTS.md viết cho agent đang thực thi, nên giữ dạng lệnh và ranh giới rõ thay vì kể chuyện dự án.

**Có trường bắt buộc nào không?** Không. Trang chuẩn khẳng định đây thuần Markdown, dùng heading nào cũng được, agent parse phần text bạn viết.

**Nhiều tệp khác nhau có xung đột không?** Không bị coi là lỗi: bản gần tệp đang sửa nhất thắng, còn prompt người dùng trong chat áp đảo mọi tệp.

**Agent tự chạy lệnh test không?** Có, nếu bạn liệt kê lệnh trong tệp; agent sẽ tìm cách chạy kiểm tra và sửa lỗi trước khi kết thúc tác vụ.

**Dự án đang có tệp AGENT.md cũ thì chuyển thế nào?** Trang chuẩn gợi ý đổi tên rồi tạo symbolic link để công cụ cũ vẫn tìm thấy: `mv AGENT.md AGENTS.md` kèm `ln -s AGENTS.md AGENT.md`.

**Những nguồn nào dựng nên entry này?** Hai trang chính, cùng truy cập ngày 18/10/2026: [agents.md](https://agents.md/) cho định dạng và luật đọc, [hướng dẫn AGENTS.md của Codex](https://developers.openai.com/codex/guides/agents-md) cho cơ chế phân cấp và hạn mức 32 KiB.

## Liên quan

- [Agent Skills (SKILL.md)](/wiki/agent-skills/)
- [Hệ thống điều hành multi-agent là gì?](/blog/he-thong-dieu-hanh-multi-agent-la-gi/)
- [Mô hình One-Person Company với 42 AI agents](/blog/one-person-company-42-agents/)