agents.md là gì: đây là tệp Markdown chứa hướng dẫn cố định mà AI coding agent như Codex hoặc Claude Code đọc trước khi làm việc trong dự án, gồm lệnh chạy, quy ước code và quy tắc cần tuân theo.
Cập nhật: 31/10/2026
Tóm tắt nhanh
- agents.md là tệp Markdown chứa chỉ dẫn lâu dài mà AI coding agent đọc trước khi bắt đầu làm việc trong một dự án.
- Codex đọc agents.md theo hai cấp: cấp toàn cục trong thư mục ~/.codex và cấp dự án, đi từ thư mục gốc xuống thư mục hiện tại.
- Tệp ở thư mục gần công việc nhất được đọc sau cùng và có tác dụng ghi đè các chỉ dẫn chung trước đó.
- Claude Code có thể đọc AGENTS.md thay cho CLAUDE.md trong kho mã, nên bạn cần kiểm tra công cụ đang dùng nạp tệp nào.
- Bắt đầu bằng một tệp ngắn gồm lệnh kiểm tra và quy ước, sau đó bổ sung skill cho các quy trình nhiều bước.
agents.md là gì và dùng để làm gì?
Tệp agents.md dùng để ghi chỉ dẫn lâu dài cho AI agent, ví dụ lệnh cần chạy, quy ước viết code và những việc agent không được làm. Agent đọc tệp này trước khi xử lý tác vụ, nên bạn không phải nhắc lại cùng một yêu cầu ở mỗi phiên làm việc.
Nếu bạn chưa rõ agent là gì, hãy đọc trước bài ai agent là gì. Về bản chất, agents.md chỉ là một tệp văn bản thông thường, không cần cài phần mềm riêng. Codex của OpenAI có tài liệu chính thức mô tả cách đọc tệp này, và Claude Code cũng có thể đọc AGENTS.md thay cho CLAUDE.md.
agents.md hoạt động như thế nào khi AI agent khởi động?
Khi Codex khởi động, Codex tạo một chuỗi chỉ dẫn bằng cách đọc các tệp agents.md theo hai cấp: cấp toàn cục trong thư mục cấu hình cá nhân và cấp dự án trong kho mã. Việc này diễn ra một lần cho mỗi lần chạy, thường là mỗi lần mở một phiên trong giao diện dòng lệnh.
agents.md là gì trong Codex và Claude Code?
Trong Codex, agents.md là phần chỉ dẫn tùy chỉnh được nạp tự động trước khi thực hiện công việc. Trong Claude Code, tệp tương ứng là CLAUDE.md, được đọc ở đầu mỗi phiên, và Claude Code có thể đọc AGENTS.md thay cho CLAUDE.md. Bạn có thể xem thêm claude.md là gì để hiểu rõ hơn về tệp này.
Với Codex, thứ tự ưu tiên được quyết định theo vị trí thư mục. Bảng dưới tóm tắt cách Codex chọn tệp ở từng cấp.
| Vị trí | Tệp Codex kiểm tra | Mức ưu tiên |
|---|---|---|
| Thư mục toàn cục (~/.codex) | AGENTS.override.md, nếu không có thì AGENTS.md | Thấp nhất, áp dụng cho mọi dự án |
| Thư mục gốc của dự án | AGENTS.override.md, nếu không có thì AGENTS.md | Ghi đè chỉ dẫn toàn cục |
| Thư mục hiện tại | Tối đa một tệp trong thư mục này | Cao nhất, được đọc sau cùng |
Codex nối các tệp từ gốc xuống thư mục hiện tại, cách nhau bằng dòng trống. Tổng dung lượng mặc định được giới hạn ở 32 KiB, đặt bằng project_doc_max_bytes, và khi đạt giới hạn Codex ngừng thêm tệp mới. Tệp rỗng sẽ bị bỏ qua.
Thử ngay: Nếu bạn dùng Codex, trang hướng dẫn trong kho skill giải thích cách cài skill vào thư mục ~/.codex/skills, miễn phí và chỉ cần một lệnh. Xem hướng dẫn cài skill cho Codex
Ví dụ agents.md thực tế trông như thế nào?
Một tệp agents.md tốt thường ngắn và chỉ ghi những điều agent cần biết ở mọi phiên. Ví dụ dưới đây đặt ở thư mục gốc của dự án, dựa theo mẫu chính thức trong tài liệu Codex.
# AGENTS.md
## Repository expectations
- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.
Ví dụ này yêu cầu agent chạy lệnh kiểm tra trước khi mở pull request và cập nhật tài liệu khi thay đổi hành vi. Nếu một thư mục con như dịch vụ thanh toán có quy tắc riêng, bạn đặt thêm AGENTS.override.md ngay trong thư mục đó. Nên đặt quy tắc càng gần công việc càng tốt, vì Codex dừng tìm kiếm khi đến thư mục hiện tại.
agents.md khác gì CLAUDE.md, SKILL.md và README.md?
agents.md là chỉ dẫn chung cho AI coding agent, còn CLAUDE.md là tệp chỉ dẫn riêng mà Claude Code đọc ở đầu mỗi phiên. SKILL.md là tệp định nghĩa một skill, tức một quy trình được đóng gói để agent thực hiện, còn README.md là tài liệu giới thiệu dự án dành cho con người. Bảng dưới so sánh bốn tệp này.
| Tệp | Đối tượng đọc chính | Nội dung thường có | Khi nào nên dùng |
|---|---|---|---|
| agents.md | AI coding agent như Codex, Claude Code | Lệnh chạy, quy ước code, quy tắc review | Khi cần chỉ dẫn chung cho agent trong dự án |
| CLAUDE.md | Claude Code | Lệnh build, quy ước, cấu trúc dự án | Khi chỉ dùng Claude Code và muốn chỉ dẫn được nạp mỗi phiên |
| SKILL.md | Agent khi thực hiện một skill | Mô tả quy trình cụ thể cho một việc | Khi đóng gói một quy trình có thể dùng lại |
| README.md | Con người, đặc biệt người mới vào dự án | Giới thiệu, cách cài đặt, cách đóng góp | Khi cần tài liệu cho mọi người, không chỉ agent |
Theo tài liệu của Claude Code, quy trình nhiều bước hoặc phần chỉ liên quan đến một khu vực của mã nên chuyển sang skill hoặc quy tắc theo đường dẫn, thay vì để hết trong CLAUDE.md. Nếu bạn muốn biết cách đóng gói một quy trình thành skill, hãy đọc skill claude là gì.
Ai nên dùng agents.md?
Bạn nên dùng agents.md nếu thường xuyên giao việc cho AI coding agent trong một dự án có lệnh kiểm tra và quy ước lặp lại. Tệp này đặc biệt hữu ích khi nhiều người cùng làm một kho mã và cần thống nhất cách làm việc với agent.
- Lập trình viên dùng Codex hoặc Claude Code hằng ngày và muốn agent luôn chạy đúng lệnh kiểm tra.
- Nhóm có nhiều thành viên cần chung một bộ quy ước code, vì tệp nằm ngay trong kho mã.
- Người làm việc với tài liệu Word có thể tham khảo skill claude docx để agent xử lý file theo quy trình cố định.
- Người làm marketing hoặc SEO có thể xem danh mục Marketing SEO trong kho skill.
Nếu bạn chỉ dùng AI để trò chuyện và không giao việc cho agent thực hiện tác vụ, agents.md chưa thực sự cần thiết.
Bắt đầu với agents.md từ đâu?
Bắt đầu bằng một tệp AGENTS.md ngắn ở thư mục gốc dự án, khoảng ba đến năm quy tắc, rồi kiểm tra xem agent có đọc đúng không. Viết quá nhiều ngay từ đầu thường làm tệp khó bảo trì và dễ vượt giới hạn dung lượng.
- Tạo thư mục ~/.codex nếu chưa có, rồi viết tệp ~/.codex/AGENTS.md với các thói quen chung cho mọi dự án.
- Thêm AGENTS.md ở thư mục gốc của dự án, ghi lệnh kiểm tra và quy ước cụ thể của dự án đó.
- Chạy lệnh dưới đây để xem Codex có liệt kê đúng các chỉ dẫn đang được nạp hay không.
codex --ask-for-approval never "Summarize the current instructions."Lưu ý quan trọng: tệp rỗng bị bỏ qua, tệp vượt 32 KiB sẽ bị cắt bớt, và khi có AGENTS.override.md trong cùng thư mục thì AGENTS.md của thư mục đó không được dùng.
Khi đã có agents.md, bạn có thể bổ sung skill cho các quy trình lặp lại. Lệnh sau cài skill agent-merge-conflict-arbiter, một bên phân xử trung lập cho xung đột merge giữa hai agent, vào thư mục skill của Claude Code:
mkdir -p ~/.claude/skills && curl -fsSL https://skill.dn1nguoi.com/z/agent-merge-conflict-arbiter-54491.tgz | tar xz -C ~/.claude/skillsĐể cài skill khác, đổi id trong lệnh. Thư mục skill của Claude Code là ~/.claude/skills, Codex dùng ~/.codex/skills, Hermes Agent dùng ~/.hermes/skills, còn DeepSeek (Deep Code CLI) dùng ~/.deepcode/skills. Claude Code và Hermes Agent gọi skill bằng /tên-skill, Codex gọi bằng $tên-skill. Bạn có thể đọc thêm cách cài skill cho Claude Code để làm theo từng bước.
Nếu agent cần kết nối với các công cụ bên ngoài, bạn nên tìm hiểu thêm về mcp claude là gì trước khi thêm quy tắc phức tạp vào tệp.
Hiểu rõ agents.md là gì giúp bạn chuyển các yêu cầu lặp lại thành chỉ dẫn được agent đọc tự động ở mỗi phiên. Hãy bắt đầu với một tệp ngắn, kiểm tra kết quả rồi mới mở rộng. Để xem thêm các bài liên quan, bạn có thể vào tổng hợp bài về AI Agent Skills.
Thử ngay: Kho skill tại skill.dn1nguoi.com có hơn 4.000 skill miễn phí, mỗi skill cài bằng một lệnh một dòng. Bạn có thể bắt đầu với skill agent-memory, dành cho khi file CLAUDE.md đã quá dài và bạn muốn agent tự học các sự thật bền vững từ phiên làm việc.
Câu hỏi thường gặp
agents.md có bắt buộc không?
Không bắt buộc. agents.md là tệp chỉ dẫn tùy chọn, dự án vẫn chạy bình thường nếu không có tệp này. Tuy nhiên, nếu bạn muốn agent luôn làm theo cùng một bộ quy tắc, tệp giúp bạn không phải nhắc lại yêu cầu ở mỗi phiên làm việc. Hãy kiểm tra tài liệu của công cụ bạn đang dùng để biết cách công cụ đó nạp tệp.
agents.md và CLAUDE.md khác nhau thế nào?
agents.md là tệp chỉ dẫn theo tên chung cho AI coding agent, còn CLAUDE.md là tệp mà Claude Code đọc ở đầu mỗi phiên. Claude Code có thể đọc AGENTS.md thay cho CLAUDE.md trong kho mã. Nếu dự án chỉ dùng Claude Code, bạn có thể giữ một tệp duy nhất. Nếu có cả hai, hãy kiểm tra cách Claude Code nạp chúng để tránh trùng lặp quy tắc.
agents.md nên dài bao nhiêu?
Nên giữ ngắn, chỉ ghi những quy tắc agent cần trong mọi phiên làm việc. Codex giới hạn tổng dung lượng chỉ dẫn mặc định ở 32 KiB, nếu vượt quá sẽ bị cắt bớt. Khi cần nhiều nội dung hơn, bạn nên tách sang tệp trong thư mục con hoặc tăng giá trị project_doc_max_bytes trong cấu hình Codex.
Có cần cài skill khi đã có agents.md không?
Không bắt buộc, vì hai thứ phục vụ mục đích khác nhau. agents.md chứa chỉ dẫn nền cho cả dự án, còn skill là gói quy trình cụ thể cho một việc. Khi một quy trình có nhiều bước, bạn nên tách thành skill thay vì viết dài trong agents.md. Kho skill có hướng dẫn cài cho Claude Code, Codex, Hermes Agent và DeepSeek.
Người không biết lập trình có dùng được agents.md không?
Có thể dùng mà không cần biết lập trình sâu, nhưng bạn cần hiểu dự án của mình có những lệnh và quy tắc nào. Tệp là văn bản thường viết bằng Markdown, nên bạn chỉ cần gạch đầu dòng các yêu cầu bằng tiếng Việt hoặc tiếng Anh. Nếu chưa quen với cách agent làm việc, hãy đọc bài ai agent là gì trước.
Nguồn tham khảo
- Custom instructions with AGENTS.md (tài liệu chính thức của OpenAI Codex)
- How Claude remembers your project (tài liệu chính thức của Claude Code)
