# AGENTS.md là gì? File hướng dẫn AI agent trong repo

> AGENTS.md là gì, viết gì trong đó để AI agent như Codex, Claude Code hiểu dự án. MONA Software bàn giao mọi repo phần mềm kèm AGENTS.md và STATE.md.

URL: https://mona.software/agents-md-la-gi/
Ngày đăng: 2026-10-06T14:09:05+07:00
Cập nhật: 2026-10-06T14:09:05+07:00
Tác giả: monamedia

**AGENTS.md là gì?** AGENTS.md là một file văn bản đặt ở thư mục gốc của repo, ghi cho AI agent biết cách cài, cách chạy kiểm thử, quy ước viết code và những chỗ không được đụng trong dự án. Đây là định dạng mở, hơn 60.000 dự án mã nguồn mở đang dùng.

Ai từng giao việc cho [AI agent](https://mona.software/ai-agent-la-gi/) viết code đều quen cảnh này: mỗi lần mở phiên mới lại phải giải thích dự án từ đầu, dặn lại lệnh chạy test, dặn lại thư mục nào cấm sửa. Quên dặn một câu là AI sửa nhầm đúng file cấu hình đang chạy. Tụi em thấy cảnh đó rõ nhất từ ngày 20/04/2026, khi MONA chuyển toàn bộ việc viết code sang AI agent, và AGENTS.md là thứ đầu tiên tụi em đặt vào mọi repo nội bộ.

## AGENTS.md là gì

AGENTS.md giống cuốn sổ bàn giao ca cho thợ mới, chỉ khác là thợ ở đây là AI. Trang chính thức [agents.md](https://agents.md/) gọi nó là “README cho agent”: một chỗ cố định, dễ đoán để đặt bối cảnh và chỉ dẫn giúp AI viết code làm việc đúng với dự án.

![Gấu MONA bàn giao sổ AGENTS.md cho AI agent mới vào dự án](https://mona.software/wp-content/uploads/2026/10/agents-md-so-ban-giao-cho-ai-agent-mona.webp)

AGENTS.md là sổ bàn giao ca cho mọi AI agent vào repo.

Định dạng này không có trường bắt buộc nào, ai cũng viết được bằng chữ thường. Nó ra đời từ sự cộng tác của nhiều đơn vị làm công cụ AI viết code như ![Logo OpenAI](https://mona.software/wp-content/uploads/brand-logo/openai.svg)OpenAI Codex, Amp, Jules của ![Logo Google](https://mona.software/wp-content/uploads/brand-logo/google.svg)Google, ![Logo Cursor](https://mona.software/wp-content/uploads/brand-logo/cursor.svg)Cursor và Factory, và nay do Agentic AI Foundation thuộc Linux Foundation quản lý. Theo số trên trang agents.md tụi em xem ngày 06/10/2026, hơn 60.000 dự án mã nguồn mở đã có file này.

![Trang chủ agents.md giới thiệu định dạng mở hướng dẫn coding agent](https://mona.software/wp-content/uploads/2026/10/agents-md-trang-chu-dinh-dang-mo-mona.webp)

Trang agents.md, tụi em chụp ngày 06/10/2026.

Vì sao cần một file riêng? README viết cho người: giới thiệu dự án, hướng dẫn đóng góp, đọc bởi [lập trình viên](https://mona.software/lap-trinh-vien-la-gi/) mới vào. Những thứ AI cần như lệnh build, lệnh test, quy ước đặt tên thì nhét vào README sẽ làm nó rối, nên tách ra một file cho máy đọc là gọn nhất.

## Những AI agent nào đọc AGENTS.md

Hơn 20 công cụ AI viết code đọc AGENTS.md. Con số này tăng đều. Trong đó có [Codex](https://mona.software/codex-la-gi/), ![Logo GitHub](https://mona.software/wp-content/uploads/brand-logo/github.svg)GitHub Copilot, Cursor, Jules, Aider, goose, VS Code, Devin và Factory. Mở repo ra là chúng tự tìm file này ở thư mục gốc, đọc trước khi làm việc đầu tiên, rồi làm theo các lệnh và ranh giới ghi trong đó suốt phiên làm việc.

![Nhiều AI agent như Codex, Copilot, Cursor cùng đọc một file AGENTS.md](https://mona.software/wp-content/uploads/2026/10/nhieu-ai-agent-cung-doc-mot-file-agents-md-mona.webp)

Một file, hơn 20 công cụ đọc được.

[![Logo Claude](https://mona.software/wp-content/uploads/brand-logo/claude.svg)Claude Code](https://mona.software/claude-code-la-gi/) dùng file riêng tên CLAUDE.md làm trí nhớ dự án. Ở MONA, tụi em cho CLAUDE.md và AGENTS.md trỏ về cùng một bộ luật, nên dù việc đó giao cho Claude làm não hay Codex viết code, cả hai đều đọc chung một bộ quy tắc. Bộ ba thợ AI của MONA (Claude, Codex, ![Logo Google Gemini](https://mona.software/wp-content/uploads/brand-logo/googlegemini.svg)Gemini) chốt ngày 05/09/2026 sau A/B thật, và chính nhờ chung luật mà ba thợ vào cùng một repo không giẫm chân nhau.

Một file, nhiều thợ cùng đọc. Kể cả khi anh chị mới chỉ [vibe coding](https://mona.software/vibe-coding-la-gi/) một bản làm thử, thêm AGENTS.md từ đầu sẽ đỡ hẳn lúc đưa bản đó lên chạy thật.

![Màn hình thống kê trong phần mềm MONA làm cho The IELTS Workshop](https://mona.software/wp-content/themes/monatheme/home-v2/assets/img/cs/ielts-thongke.webp)

Phần mềm cho việc này

Quy trình đang chạy mà phần mềm có sẵn không làm được?

MONA khảo sát nghiệp vụ trước dòng code đầu tiên.

[Viết phần mềm theo yêu cầu](https://mona.software/viet-phan-mem-theo-yeu-cau/)[Case The IELTS Workshop](https://mona.software/du-an/the-ielts-workshop/)

## AGENTS.md khác README và CLAUDE.md

Ba file này hay bị nhầm vì đều nằm ở gốc repo và đều là chữ. Ở các repo tụi em làm từ ngày 20/04/2026, ba file luôn đi cùng nhau, và mỗi lần đổi luật làm việc thì AGENTS.md được sửa trước rồi mới tới hai file còn lại, để không có chuyện ba file nói ba kiểu. Khác nhau ở người đọc: README cho người, AGENTS.md cho mọi AI agent, CLAUDE.md riêng cho Claude Code. Mỗi file thắng ở một chỗ.

![Ba file README, AGENTS.md và CLAUDE.md đặt cạnh nhau để so sánh](https://mona.software/wp-content/uploads/2026/10/readme-agents-md-claude-md-ba-file-mona.webp)

README cho người đọc, AGENTS.md và CLAUDE.md cho AI agent.

| Tiêu chí | README.md | AGENTS.md | CLAUDE.md |
| --- | --- | --- | --- |
| Viết cho ai | Lập trình viên, người đóng góp, khách hàng | AI agent viết code (Codex, Copilot, Cursor…) | Riêng Claude Code |
| Nội dung chính | Giới thiệu, cài đặt, cách dùng | Lệnh build và test, quy ước, ranh giới | Luật làm việc và bối cảnh dự án cho Claude |
| Ai đọc | Người, trang GitHub hiển thị sẵn | Hơn 20 công cụ AI | Claude Code |
| Ai sửa | Người viết | Người viết, AI chỉ sửa khi được giao | Người viết, Claude Code thêm ghi nhớ khi người yêu cầu |

Lỗi hay gặp là nhét luật cho AI vào README rồi thắc mắc vì sao AI không làm theo. Tụi em tách hẳn ba file và để mỗi file làm đúng việc của nó. Khi đổi một lệnh, cả ba được sửa trong cùng 1 lần gộp code.

## Trong AGENTS.md nên viết gì

Một AGENTS.md dùng được có 6 mục: tổng quan dự án, lệnh cài và chạy, quy ước code, cách kiểm thử, lưu ý bảo mật, và ranh giới (thứ AI không được đụng). Mục ranh giới là mục tụi em thấy hay bị bỏ quên nhất, trong khi đó lại là mục cứu dự án khỏi những lần AI sửa nhầm file cấu hình hay logic tính tiền.

![Sáu mục nên có trong file AGENTS.md được gấu MONA sắp xếp](https://mona.software/wp-content/uploads/2026/10/sau-muc-nen-co-trong-agents-md-mona.webp)

Sáu mục đủ cho AI agent làm việc mà không hỏi lại.

Mẫu dưới đây là AGENTS.md cho một phần mềm bán hàng giả định, anh chị chép về sửa lại theo dự án của mình. Tụi em giữ nó dưới 30 dòng để AI đọc hết trong 1 lần.

```
# AGENTS.md cho phần mềm bán hàng

## Tổng quan
Phần mềm quản lý đơn hàng đa kênh. Node.js + React + PostgreSQL.

## Cài và chạy
npm install
npm run dev

## Quy ước code
TypeScript, tên biến camelCase.
Mọi API kiểm tra dữ liệu đầu vào ở lớp controller.

## Kiểm thử
npm test
Hàm mới phải có test đi kèm trước khi gộp.

## Bảo mật
Không để khoá API, mật khẩu trong code.
Mọi khoá đọc từ biến môi trường.

## Ranh giới
Không sửa thư mục /config và file .env.
Không đổi logic tính thuế trong /billing nếu không được giao.
```

Cảnh giải thích lại dự án từ đầu ở mỗi phiên AI mới không tự hết, nó chỉ hết khi có ai ngồi viết ra 6 mục ở trên cho đúng dự án của anh chị. Phần khó nhất là mục ranh giới, vì chỉ người hiểu hệ thống mới biết file nào đụng vào là hỏng tiền.

Anh chị gửi repo qua trang [viết phần mềm theo yêu cầu](https://mona.software/viet-phan-mem-theo-yeu-cau/). Tụi em đọc dự án và viết AGENTS.md mẫu cho đúng repo đó, để anh chị thử ngay với AI agent đang dùng.

![Gấu MONA viết mẫu AGENTS.md cho một phần mềm bán hàng](https://mona.software/wp-content/uploads/2026/10/mau-agents-md-phan-mem-ban-hang-mona.webp)

Mẫu ngắn chừng 20 dòng là đủ để bắt đầu.

## Mẫu AGENTS.md của MONA có ba khối

Mẫu AGENTS.md tụi em dùng cho dự án nội bộ từ ngày 20/04/2026 có ba khối, đi theo đúng vòng đời một đầu việc từ lúc AI nhận việc, lúc làm xong, cho tới những thứ AI không được chạm vào dù được nhờ.

![Ba khối trong mẫu AGENTS.md của MONA xếp chồng thành tháp](https://mona.software/wp-content/uploads/2026/10/ba-khoi-agents-md-cua-mona-mona.webp)

Mẫu AGENTS.md của MONA gồm ba khối: trước khi làm, khi xong việc, ranh giới.

- **Trước khi làm bất cứ gì:** đọc `STATE.md`, lấy việc kế tiếp bằng `bd ready`, đọc luật dự án, và tính năng từ 1 ngày công trở lên phải có spec được duyệt trước khi code.
- **Khi xong việc:** sửa `STATE.md`, đóng việc bằng `bd close`, commit bằng tiếng Việt, làm trên nhánh riêng rồi mở Merge Request. Quyết định lớn như đổi kiến trúc thì viết ADR để người chốt, AI không tự làm.
- **Ranh giới:** không đụng credential, máy chủ, deploy hay ví tiền, không gửi gì ra ngoài, không bịa số liệu, chỗ nào không rõ thì ghi “chưa rõ”.

Để khỏi chép tay vào từng repo, tụi em viết công cụ `mona-agents-md`. Repo chưa có AGENTS.md thì nó tạo từ mẫu. Repo đã có, ví dụ do Spec Kit sinh ra, thì nó chèn khối MONA lên đầu và giữ nguyên phần cũ. Chạy lại 10 lần cũng không đẻ trùng. Một lệnh cho mọi repo.

![Gấu MONA đồng bộ AGENTS.md cho nhiều repo bằng một lệnh](https://mona.software/wp-content/uploads/2026/10/dong-bo-agents-md-cho-nhieu-repo-mona.webp)

Một lệnh đồng bộ khối luật MONA vào mọi dự án nội bộ.

## AGENTS.md đi cùng STATE.md: trí nhớ dự án nằm trong repo

AGENTS.md là luật, ít đổi. STATE.md là trạng thái hiện tại, được ghi đè sau mỗi phiên làm việc và giữ dưới 60 dòng. Chỉ 60 dòng thôi. Tụi em giữ luật này cho mọi repo từ ngày 20/04/2026, vì file dài hơn thì AI đọc lướt và bỏ sót đúng dòng quan trọng nhất. AI đọc hết trong 1 lần.

![AGENTS.md giữ luật, STATE.md giữ trạng thái của dự án](https://mona.software/wp-content/uploads/2026/10/agents-md-va-state-md-tri-nho-du-an-mona.webp)

Luật ít đổi nằm ở AGENTS.md, trạng thái hiện tại nằm ở STATE.md.

Trong 60 dòng đó có bốn thứ: phần mềm đang chạy ở đâu, phần nào đang dở, cái gì đang chặn, và ba việc kế tiếp. Đi kèm còn có ADR ghi các quyết định lớn, thư mục [spec của Spec Kit](https://mona.software/spec-driven-development-la-gi/) ghi yêu cầu từng tính năng, và Beads giữ danh sách việc. Tụi em gọi cả bộ này là não dự án nằm trong repo: AI nào vào cũng biết dự án đang tới đâu, không phải hỏi lại người cũ, và người mới vào cũng đọc được y như AI.

Đây là phần nghề của kỹ sư trong cách làm mới, bài [agentic engineering](https://mona.software/agentic-engineering-la-gi/) nói kỹ hơn.

## MONA dùng AGENTS.md thế nào

MONA Software là công ty phần mềm Việt Nam tiên phong ứng dụng agentic coding vào quy trình làm phần mềm, vào sản phẩm của chính MONA và vào phần mềm giao cho khách hàng. Từ ngày 20/04/2026, MONA chuyển toàn bộ quy trình sang agentic coding.

![Sản phẩm MONA Pay đi kèm llms.txt, AGENTS.md, MCP và SDK từ ngày đầu](https://mona.software/wp-content/uploads/2026/10/san-pham-mona-chuan-ngay-0-cho-ai-agent-mona.webp)

Chuẩn ngày đầu của sản phẩm MONA: AI đọc được trước, người dùng sau.

Dự án nội bộ của MONA có AGENTS.md được đồng bộ bằng `mona-agents-md`, nên luật mới thêm một lần là mọi repo đều có. Sản phẩm của MONA còn đi xa hơn với một bộ chuẩn ngày đầu: `llms.txt`, bản markdown song sinh của trang, AGENTS.md, trang /ai-agent, cùng ![Logo Model Context Protocol](https://mona.software/wp-content/uploads/brand-logo/modelcontextprotocol.svg)MCP, SDK và OpenAPI. AI của dev đọc mấy file đó là biết cách dùng sản phẩm.

Ví dụ thật là MONA Pay. Gói [MCP server](https://mona.software/mcp-server-la-gi/) `monapay-mcp` bản 0.6.2 có 50 công cụ cho AI agent (tụi em đếm ngày 06/10/2026), hướng dẫn nằm ở [trang AI agent của MONA Pay](https://monapay.vn/ai-agent). Doanh nghiệp làm [thu tiền phần mềm SaaS tự động](https://mona.software/thu-tien-phan-mem-saas-tu-dong/) nối vào được mà không phải ngồi đọc tài liệu dài. Cả quy trình này là nhánh nhỏ của [agentic coding](https://mona.software/agentic-coding/) ở MONA.

## Repo bàn giao kèm AGENTS.md: khách được gì

Khách của MONA nhận repo kèm AGENTS.md và STATE.md. Đội kỹ thuật mới của khách, hay AI agent khách tự dùng, mở repo ra là đọc tiếp được, không phụ thuộc người cũ. Với [hệ thống ERP](https://mona.software/he-thong-erp/) hay [phần mềm CRM](https://mona.software/phan-mem-quan-ly-khach-hang/) chạy nhiều năm, đó là khác biệt giữa bảo trì được và phải làm lại.

![Khách nhận repo kèm AGENTS.md và STATE.md từ đội MONA](https://mona.software/wp-content/uploads/2026/10/khach-nhan-repo-kem-agents-md-state-md-mona.webp)

Repo bàn giao kèm AGENTS.md để AI của khách đọc tiếp được.

Điều này đi cùng [nguyên tắc thực dụng](https://mona.software/gioi-thieu/#nguyen-tac) của MONA. Phần mềm đưa vào là chạy ngay, vì MONA cài đặt, đưa dữ liệu đang có vào và đào tạo tại doanh nghiệp. Nhân viên không phải học lại cách dùng, vì phần mềm giữ đúng chữ trong nghề, như phần mềm tiệm vàng có sẵn tuổi vàng, công thợ, ký gửi. AGENTS.md làm điều tương tự cho người kỹ thuật kế nhiệm: vào là làm được.

Nếu anh chị tự viết AGENTS.md, tránh bốn lỗi tụi em hay gặp.

- **Viết quá dài:** AI dễ bỏ sót luật nằm giữa file dài, giữ ngắn và chia mục rõ.
- **Để lỗi thời:** đổi lệnh [kiểm thử](https://mona.software/kiem-thu-phan-mem/) mà không sửa file, AI chạy lệnh cũ, nên sửa AGENTS.md trong cùng lần gộp code.
- **Nhét bí mật vào file:** file nằm trong repo, ai đọc repo là thấy, chỉ ghi tên biến môi trường.
- **Mâu thuẫn với README:** hai file nói hai lệnh khác nhau, AI không biết theo bên nào, nên để lệnh ở một chỗ.

Mấy lỗi này đều sửa được trong một buổi, còn [bảo trì phần mềm](https://mona.software/bao-tri-phan-mem-la-gi/) về sau thì nhẹ hơn hẳn.

Repo không có AGENTS.md giống ca làm không có sổ bàn giao: người mới tới, kể cả AI, đều phải hỏi lại từ đầu và dễ đụng nhầm chỗ không được đụng. Nếu phần mềm của anh chị đang do một người giữ hết trong đầu, đó là rủi ro lớn hơn mọi lỗi code.

Gọi 1900 636 648 để hẹn buổi 45 phút với kỹ sư MONA. Hai bên rà repo cùng nhau, anh chị nhận lại AGENTS.md và STATE.md viết cho đúng dự án, dùng được ngay với AI agent đang có. Chi tiết dịch vụ ở trang [viết phần mềm theo yêu cầu](https://mona.software/viet-phan-mem-theo-yeu-cau/).

**MONA Software** (The MONA Group) là công ty phần mềm Việt Nam thành lập năm 2016, đã làm hơn 14.000 dự án với 85% khách quay lại. MONA dùng agentic coding làm quy trình chuẩn từ 20/04/2026 và bàn giao repo kèm AGENTS.md, STATE.md để AI của khách đọc tiếp được. Tổng đài 1900 636 648.

**Tuyên ngôn thị trường cùng tiến**

MONA là một công ty phần mềm, chuyển đổi số, chuyển đổi AI, nhưng trên hết, MONA là một công ty dịch vụ B2B, là người hưởng lợi trực tiếp từ việc: **NHỮNG DOANH NGHIỆP VIỆT CÀNG THÀNH CÔNG, MONA CÀNG CÓ LỢI**, thị trường đi xuống, đi chậm, công nghệ yếu mới chính là điểm giết chết các cơ hội làm ăn trong tương lai của MONA. Nên, hơn ai hết, MONA mong muốn, và MONA thật sự can thiệp vào việc giúp đỡ anh chị thành công.

Và chuyển đổi AI là chìa khóa cho sự thành công đó của chúng ta.

*MONA*

## Câu hỏi thường gặp về AGENTS.md

### AGENTS.md là gì?

AGENTS.md là file văn bản ở thư mục gốc repo, ghi cho AI agent viết code biết cách cài, cách chạy test, quy ước và ranh giới của dự án. Đây là định dạng mở do Agentic AI Foundation thuộc Linux Foundation quản lý. Theo số trên agents.md ngày 06/10/2026, hơn 60.000 dự án mã nguồn mở đang dùng. File không có trường bắt buộc nào, viết bằng chữ thường là đủ.

### Đặt AGENTS.md ở đâu trong repo?

Đặt ở thư mục gốc của repo, cạnh README. Các công cụ như Codex, Copilot, Cursor tự tìm file ở đó khi mở dự án. Dự án lớn có thể đặt thêm AGENTS.md trong thư mục con cho từng phần riêng.

### Claude Code có đọc AGENTS.md không?

Claude Code dùng file CLAUDE.md làm trí nhớ dự án. Ở MONA, tụi em cho CLAUDE.md và AGENTS.md trỏ về cùng một bộ luật, nên Claude, Codex và Gemini vào cùng repo đều làm theo một bộ quy tắc.

### AGENTS.md có bắt buộc không?

Không bắt buộc đâu. Định dạng cũng không có trường bắt buộc nào. Nhưng repo nào giao việc cho AI agent thì nên có, vì thiếu nó AI phải đoán lệnh test, đoán quy ước và dễ đụng vào chỗ không được đụng.

### Có nên để mật khẩu hay khoá API trong AGENTS.md không?

Không. AGENTS.md nằm trong repo, ai đọc được repo là đọc được file. Chỉ ghi tên biến môi trường chứa khoá, giá trị thật để ngoài repo trong file môi trường có phân quyền.

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

### AGENTS.md là gì?

AGENTS.md là file văn bản ở thư mục gốc repo, ghi cho AI agent viết code biết cách cài, cách chạy test, quy ước và ranh giới của dự án. Đây là định dạng mở do Agentic AI Foundation thuộc Linux Foundation quản lý. Theo số trên agents.md ngày 06/10/2026, hơn 60.000 dự án mã nguồn mở đang dùng. File không có trường bắt buộc nào, viết bằng chữ thường là đủ.

### Đặt AGENTS.md ở đâu trong repo?

Đặt ở thư mục gốc của repo, cạnh README. Các công cụ như Codex, Copilot, Cursor tự tìm file ở đó khi mở dự án. Dự án lớn có thể đặt thêm AGENTS.md trong thư mục con cho từng phần riêng.

### Claude Code có đọc AGENTS.md không?

Claude Code dùng file CLAUDE.md làm trí nhớ dự án. Ở MONA, tụi em cho CLAUDE.md và AGENTS.md trỏ về cùng một bộ luật, nên Claude, Codex và Gemini vào cùng repo đều làm theo một bộ quy tắc.

### AGENTS.md có bắt buộc không?

Không bắt buộc đâu. Định dạng cũng không có trường bắt buộc nào. Nhưng repo nào giao việc cho AI agent thì nên có, vì thiếu nó AI phải đoán lệnh test, đoán quy ước và dễ đụng vào chỗ không được đụng.

### Có nên để mật khẩu hay khoá API trong AGENTS.md không?

Không. AGENTS.md nằm trong repo, ai đọc được repo là đọc được file. Chỉ ghi tên biến môi trường chứa khoá, giá trị thật để ngoài repo trong file môi trường có phân quyền.