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

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 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 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.

Đị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ư OpenAI Codex, Amp, Jules của Google, 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.

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 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, 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.

Claude Code 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, 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 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.

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ỗ.

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.

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.

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ờ.

• 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.

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.

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 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 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.

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 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 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. Doanh nghiệp làm thu tiền phần mềm SaaS tự động 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 ở 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 hay phần mềm CRM chạy nhiều năm, đó là khác biệt giữa bảo trì được và phải làm lại.

Điều này đi cùng nguyên tắc thực dụng 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ử 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 về sau thì nhẹ hơn hẳn.

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.

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.