Bạn đang dùng AI để viết code, nhưng nó cứ tự ý đổi tên file, đoán mò cấu trúc thư mục, rồi làm ra một đống thứ không theo ý mình? Vấn đề không phải ở con AI — mà ở chỗ bạn chưa nói cho nó biết “luật chơi”. Đó chính xác là lý do mà hai file AGENTS.md và CLAUDE.md tồn tại.
AGENTS.md và CLAUDE.md là gì?
Hiểu đơn giản: đây là system prompt dạng file — tức là thay vì bạn phải gõ lại yêu cầu mỗi lần mở chat mới, bạn viết sẵn vào file này một lần, và AI sẽ tự đọc nó mỗi khi bắt đầu phiên làm việc.
Nhiều người gọi nó là “memory”, một số tool gọi là “file khởi đầu” — tên khác nhau nhưng vai trò giống nhau: giúp AI hiểu context của dự án mà không cần bạn giải thích lại từ đầu.
Vậy hai file này khác nhau chỗ nào?
- AGENTS.md — được dùng chung bởi nhiều công cụ AI khác nhau như Cursor, Windsurf, Codex… Nếu dự án bạn xài nhiều tool, đây là file bạn nên tập trung viết.
- CLAUDE.md — riêng cho Claude. Con này “chơi một mình”, không đọc AGENTS.md như các tool kia, nên nếu bạn dùng Claude Code thì cần có file riêng này.
Mẹo nhỏ: Trên hệ điều hành Ubuntu/Linux, bạn có thể tạo symbolic link để CLAUDE.md trỏ vào nội dung của AGENTS.md, tránh phải viết hai lần.
Lưu file ở đâu cho đúng?
Đây là phần mà nhiều người bỏ qua, rồi tạo xong file mà AI vẫn không chịu đọc — vì để sai chỗ.
Với Cursor
Cursor đọc AGENTS.md theo hai cấp:
- Trong thư mục gốc của dự án — đặt AGENTS.md cùng cấp với
package.json,src/, hay bất kỳ file cấu hình nào ở ngoài cùng. Đây là cách phổ biến nhất. - Trong từng thư mục con — nếu bạn muốn quy tắc chỉ áp dụng cho một phần cụ thể của dự án (ví dụ: thư mục
/backendcó quy tắc riêng khác/frontend), bạn tạo thêm file AGENTS.md ngay trong thư mục đó.
Cấu trúc trông sẽ như thế này:
my-project/
├── AGENTS.md ← quy tắc chung cho cả dự án
├── src/
│ ├── frontend/
│ │ ├── AGENTS.md ← quy tắc riêng cho frontend (nếu cần)
│ └── backend/
│ ├── AGENTS.md ← quy tắc riêng cho backend (nếu cần)Với Google Antigravity
Antigravity có cách tổ chức hơi khác một chút — nó dùng thư mục .agents/ thay vì đặt file ở ngoài:
- Quy tắc cho dự án: tạo file AGENTS.md trong thư mục
.agents/ở thư mục gốc:my-project/.agents/agents.md - Quy tắc toàn cục (áp dụng cho mọi dự án): lưu vào
~/.gemini/GEMINI.md
Lưu ý quan trọng với Antigravity: Tool này không tự đọc AGENTS.md như Cursor. Để nó hoạt động, bạn cần mở file
~/.gemini/GEMINI.mdvà thêm dòng hướng dẫn: “Kiểm tra file AGENTS.md trong thư mục dự án và làm theo các chỉ dẫn trong đó.” — Đây là workaround hiện tại, Google chưa hỗ trợ tự động.
Với Claude Code
Claude Code dùng file CLAUDE.md thay vì AGENTS.md — và nó hỗ trợ đến 3 cấp khác nhau:
- Cấp dự án — đặt
CLAUDE.mdở thư mục gốc của repo (cùng chỗ vớipackage.json,README.md…). File này được commit lên git và chia sẻ với cả nhóm. Đây là file bạn sẽ dùng nhiều nhất. - Cấp thư mục con — tương tự Cursor, bạn có thể đặt thêm CLAUDE.md trong từng thư mục con. Claude Code đọc theo kiểu đệ quy từ thư mục hiện tại ngược lên trên, nên quy tắc của thư mục con sẽ được kết hợp với quy tắc ở thư mục gốc.
- Cấp toàn cục — lưu vào
~/.claude/CLAUDE.md. File này áp dụng cho mọi dự án trên máy bạn, không cần commit git. Thích hợp để lưu những thứ cá nhân như phong cách code, ngôn ngữ giao tiếp ưa thích.
Cấu trúc trông như thế này:
~/.claude/
└── CLAUDE.md ← áp dụng toàn cục, mọi dự án
my-project/
├── CLAUDE.md ← quy tắc chung cho dự án
└── src/
└── backend/
└── CLAUDE.md ← quy tắc riêng cho backend (nếu cần)Mẹo: Nếu bạn không muốn tạo thủ công, gõ lệnh
/inittrong Claude Code — nó sẽ tự phân tích dự án và tạo file CLAUDE.md gợi ý cho bạn, rồi bạn chỉnh lại theo ý mình.
Tóm tắt nhanh
| Coding Agent | Mô tả | File / Đường dẫn cấu hình |
|---|---|---|
| Claude Code | Sử dụng CLAUDE.md cho project memory. Hỗ trợ user memory dùng chung cho tất cả dự án hoặc project memory riêng cho từng dự án. | CLAUDE.md |
| Cursor | Sử dụng .cursor/rules/ với định dạng MDC. Hỗ trợ user rules dạng text và project rules ở định dạng .mdc. | .cursor/rules/rules.md |
| WindSurf | Sử dụng .windsurf/rules cho workspace rules và global_rules.md cho các rule áp dụng toàn bộ workspace. | .windsurfrules |
| GitHub Copilot | Sử dụng .github/copilot-instructions.md để lưu instruction cho model. | github/copilot-instructions.md |
| Codex | Sử dụng AGENTS.md từ ~/.codex/AGENTS.md cho global instruction và AGENTS.md trong thư mục gốc dự án cho project-level instruction. | AGENTS.md |
| Antigravity | my-project/AGENTS.md | AGENTS.md |
Tại sao đây là thứ bạn cần biết sớm?
Cứ thử tưởng tượng: bạn có một dự án với cấu trúc thư mục riêng, quy tắc đặt tên file rõ ràng. Nhưng mỗi lần mở chat mới, AI lại “quên sạch” — nó không biết thư mục nào làm gì, không biết bạn đặt tên theo kiểu gì, thậm chí còn tự sáng tạo tên mới theo ý nó.
Với AGENTS.md, bạn chỉ cần viết một lần — AI sẽ đọc lại mỗi khi bắt đầu phiên mới, và làm đúng theo đó.
Cách viết file AGENTS.md chuẩn
Tin vui là bạn không cần biết gì cao siêu. File này chỉ là một file văn bản bình thường, viết bằng cú pháp Markdown — tức là dùng dấu # cho tiêu đề, dấu - cho gạch đầu dòng.
Không biết Markdown cũng không chết — bạn vẫn có thể viết thẳng dạng văn xuôi. Nhưng dùng Markdown có một lợi thế thực tế: AI đọc dễ hơn, phân biệt được đâu là phần quan trọng, đâu là phần phụ. Nó giống như bạn đưa cho AI một tài liệu có mục lục thay vì một đống chữ dính liền nhau.
Ví dụ nội dung nên có trong file:
1. Mô tả cấu trúc thư mục
Nói rõ dự án có những thư mục nào, mỗi thư mục dùng để làm gì. Ví dụ:
## Cấu trúc thư mục
- /src — chứa toàn bộ code nguồn
- /assets — hình ảnh, font chữ
- /docs — tài liệu dự án2. Đặt quy tắc “cứng” để AI không tự ý sáng tạo
Đây là phần quan trọng nhất. AI đôi khi thấy tên thư mục lạ, nó sẽ tự đoán ý nghĩa rồi đổi tên “cho có nghĩa hơn” — kiểu như thấy thư mục tên xyz nó đổi thành utilities vì nghĩ bạn quên đặt tên đúng. Bạn không muốn vậy, thì nói thẳng vào file:
## Quy tắc bắt buộc
- Không được tự ý đổi tên thư mục hoặc file
- Không được đoán ý nghĩa của tên — tên đặt thế nào, giữ nguyên thế đó
- Chỉ làm đúng theo yêu cầu, không thêm không bớt3. Ngôn ngữ giao tiếp
Bạn muốn AI trả lời bằng tiếng Việt? Ghi vào. Muốn nó giải thích code bằng tiếng Việt? Cũng ghi vào. Không cần dùng tiếng Anh nếu bạn không thích.
Lưu ý quan trọng: AI chỉ đọc file này khi mở phiên mới
Đây là điểm dễ bị bỏ qua nhất.
Mỗi khi bạn bắt đầu chat mới (New Chat), AI sẽ tự động đọc lại file AGENTS.md hoặc CLAUDE.md. Nhưng nếu bạn đang ở giữa chừng một phiên và bạn vừa cập nhật nội dung file — AI không tự biết. Lúc đó bạn cần chỉ thẳng vào file, kêu nó đọc lại thì nó mới cập nhật.
Lưu ý: Thay đổi file giữa chừng? Nhớ nói với AI “hãy đọc lại file AGENTS.md” — không thì nó vẫn chạy theo phiên bản cũ.
Thử nghiệm thực tế: AI có thực sự làm đúng không?
Câu trả lời là: có, và đáng ngạc nhiên hơn mình nghĩ.
Trong một bài thử nghiệm với Codex (GPT 4.5), khi được cấu hình đúng qua AGENTS.md:
- AI ghi nội dung vào đúng từng thư mục theo chỉ dẫn
- Không tự ý đổi tên, dù tên thư mục đặt khá ngẫu nhiên
- Ghi bình luận bằng tiếng Việt đúng như yêu cầu
Ngay cả thư mục tên “kỳ quặc” cũng được xử lý đúng — AI không đoán, không sửa, chỉ làm theo.
Tóm lại
Nếu bạn đang dùng AI để lập trình mà chưa biết đến AGENTS.md hay CLAUDE.md, bạn đang bỏ phí một công cụ kiểm soát rất mạnh. Thay vì phải nhắc đi nhắc lại mỗi phiên, bạn viết một lần — AI làm đúng mãi mãi (hoặc cho đến khi bạn cập nhật lại).
Thử tạo một file AGENTS.md đơn giản cho dự án đang làm xem sao. Chỉ cần vài dòng mô tả cấu trúc và một vài quy tắc cơ bản — bạn sẽ thấy sự khác biệt ngay lần đầu.
Bạn đang dùng tool nào để code với AI? Chia sẻ bên dưới để mình biết nên viết thêm về tool đó nhé!
Để lại một bình luận