AGENTS.md là file Markdown chứa ngữ cảnh và hướng dẫn làm việc cho AI coding agent trong một dự án. File có thể quy định nguồn thông tin, quy trình, cách kiểm tra và giới hạn tự chủ. Công cụ hỗ trợ sẽ tìm và nạp file theo cơ chế riêng; bản thân file không tự chạy hay cấp quyền. [1]
Bạn nhờ AI viết một bài giới thiệu sản phẩm. AI viết khá ổn, nhưng lại dùng sai tên thương hiệu, thêm một lời cam kết chưa được duyệt và kết thúc bằng câu bán hàng mà bạn không thích.
Bạn sửa lại, AI hiểu. Sang một phiên làm việc khác, bạn lại phải giải thích từ đầu.
Trong một công việc khác, bạn nhờ AI chỉnh website. Nó sửa được chức năng, nhưng làm theo cách khác với cấu trúc đang có. Người phụ trách kỹ thuật mở ra xem rồi hỏi: “Sao không dùng phần có sẵn?”
Một phần vấn đề nằm ở việc chúng ta đã giao nhiệm vụ, nhưng chưa bàn giao đủ cách làm việc.
AGENTS.md được tạo ra để giải quyết nhu cầu đó trong các dự án phần mềm. Với người đi làm đang sử dụng coding agent để xây website, xử lý dữ liệu hoặc tự động hóa công việc, đây là một file đáng hiểu trước khi xây những hệ thống phức tạp hơn.
Bạn có thể đọc từ đầu để hiểu bản chất, hoặc chuyển tới mẫu file và cách tạo để thực hành ngay.
AGENTS.md là một định dạng mở, đơn giản để hướng dẫn coding agent. Trang chính thức mô tả nó như README dành cho agent: một vị trí dễ tìm để đặt ngữ cảnh và chỉ dẫn của dự án. Nội dung là Markdown thông thường, không có các trường bắt buộc. [1]
Markdown là cách viết văn bản có cấu trúc bằng những ký hiệu đơn giản. Bạn có thể dùng tiêu đề, gạch đầu dòng, đường dẫn và khối lệnh mà không cần phần mềm chuyên dụng.
Tên file nên viết đúng là AGENTS.md, có chữ S. Đừng tự đổi thành agent.md rồi mặc định công cụ sẽ nhận diện.
Có thể hình dung: nếu AI là một đồng nghiệp được giao vào dự án, AGENTS.md là tài liệu bàn giao công việc. Trong đó, bạn giải thích cách tìm thông tin, quy tắc cần giữ và tiêu chí hoàn thành.
Phép so sánh này có giới hạn: một tài liệu bàn giao không tự tạo ra nhân viên, cũng không cấp chìa khóa vào mọi hệ thống. AGENTS.md cũng vậy.
Theo OpenAI, AGENTS.md xuất phát từ nhu cầu giúp Codex tìm hướng dẫn riêng của dự án ở một vị trí dễ đoán. Định dạng được công bố tháng 8/2025, sau đó được OpenAI đóng góp cho Agentic AI Foundation thuộc Linux Foundation. [2]
Người viết thường là người hiểu công việc: chủ dự án, lập trình viên, người quản lý hoặc người trực tiếp vận hành.
Người đọc là AI Agent thông qua công cụ hỗ trợ. Con người vẫn có thể mở, kiểm tra và chỉnh sửa file như một tài liệu bình thường.
Lợi ích của một định dạng chung là giảm việc duy trì nhiều bản hướng dẫn gần giống nhau cho những công cụ khác nhau. Tuy nhiên, mức độ hỗ trợ và cách nạp file vẫn cần kiểm tra ở từng công cụ.
Bạn không cần viết AGENTS.md chỉ để hỏi một câu hoặc nhờ AI sửa một đoạn văn. Nếu chưa quen khái niệm dự án mã nguồn, hãy đọc phần giải thích repo là gì dành cho người đi làm.
File này đáng dùng khi công việc có tính lặp lại, có tài liệu chung hoặc có những quy tắc mà bạn thường phải nhắc AI nhiều lần.
Ví dụ, bạn đang cùng AI:
Hãy thử nhớ lại ba lần gần nhất bạn phải nói: “Từ sau nhớ làm theo cách này.” Nếu những điều đó vẫn đúng ở nhiệm vụ tiếp theo, chúng là ứng viên để đưa vào hướng dẫn dùng chung.
Ví dụ với một dự án nội dung, bạn có thể quy định:
Chỉ sử dụng thông tin sản phẩm từ tài liệu đã được duyệt. Khi thiếu bằng chứng, đánh dấu cần xác minh. Mỗi bài phải có bản nháp trước khi xuất bản.
Đây là cách áp dụng tư duy của AGENTS.md vào công việc văn phòng. Nhưng định dạng gốc tập trung vào coding agent; với công cụ khác, bạn phải bảo đảm nó thực sự được thiết kế hoặc cấu hình để đọc file.
Cần tách hai thứ: nội dung hướng dẫn và phần mềm chạy agent.
AGENTS.md chứa văn bản. Phần mềm chạy agent chịu trách nhiệm tìm file, đọc và đưa nội dung vào ngữ cảnh mà AI sử dụng.
Nếu ví toàn bộ quá trình như giao việc cho một đồng nghiệp:
Ví dụ bạn giao: “Viết báo cáo doanh số tháng này.”
AGENTS.md có thể hướng dẫn: dùng ngày thanh toán để tính doanh thu đã thu; không gộp hợp đồng chưa thanh toán; khi có dòng thiếu dữ liệu phải tách riêng để kiểm tra.
Những quy tắc ấy giúp xác định cách làm. Còn AI có đọc được dữ liệu và tạo báo cáo hay không phụ thuộc vào công cụ cùng quyền truy cập thực tế.
Viết một lệnh trong AGENTS.md không làm lệnh đó tự chạy. Viết tên một phần mềm không tự kết nối AI với phần mềm ấy.
Với dự án phần mềm, vị trí khởi đầu thông dụng là thư mục gốc của repo. Dự án lớn có thể có thêm AGENTS.md ở thư mục con. Theo quy ước chung, hướng dẫn gần file đang sửa hơn được ưu tiên khi có xung đột. [1]
Ví dụ một cấu trúc đề xuất:
| Vị trí | Loại hướng dẫn |
|---|---|
| /AGENTS.md | Quy tắc toàn dự án |
| /website/AGENTS.md | Quy tắc phát triển website |
| /content/AGENTS.md | Quy tắc nội dung |
| /reports/AGENTS.md | Quy tắc xử lý báo cáo |
Đừng tạo nhiều file chỉ vì muốn tổ chức cho đẹp. Hãy tách khi các khu vực thực sự cần những quy tắc khác nhau.
Chẳng hạn, hướng dẫn chung yêu cầu kiểm tra trước khi hoàn thành. Phần nội dung cần kiểm tra dẫn chứng; phần báo cáo cần đối chiếu tổng số. Các yêu cầu bổ sung nhau, không nhất thiết phải viết lại toàn bộ quy tắc chung.
Cũng không nên hiểu rằng agent sẽ nạp tất cả file trong mọi thư mục ngay khi mở dự án. Thời điểm tìm và đọc phụ thuộc công cụ.
Không hoàn toàn.
Với Codex, tài liệu hiện hành mô tả việc nạp hướng dẫn toàn cục từ thư mục Codex home, mặc định là ~/.codex, rồi tìm từ gốc dự án xuống thư mục làm việc. Trong mỗi thư mục, Codex ưu tiên AGENTS.override.md, sau đó AGENTS.md rồi tên dự phòng được cấu hình. Mỗi cấp chọn tối đa một file; giới hạn tổng mặc định là 32 KiB. Chuỗi hướng dẫn được dựng khi bắt đầu lượt chạy hoặc phiên. [3]
Với Claude Code, tài liệu hiện hành ghi nhận đọc trực tiếp AGENTS.md từ phiên bản 2.1.277. Mặc định, sự hiện diện của CLAUDE.md hoặc CLAUDE.local.md ở thư mục làm việc hay phía trên có thể khiến AGENTS.md không được nạp trực tiếp. Có thể chọn đọc cả hai trong phần Project instructions, hoặc dùng dòng @AGENTS.md trong CLAUDE.md. [4]
Điều cần nhớ là: cùng một file dùng chung được không đồng nghĩa mọi công cụ tìm và ưu tiên nó giống nhau.
Bạn nên kiểm tra lại tài liệu của phiên bản đang dùng khi cấu hình, nhất là sau một lần nâng cấp lớn.
Một bản hữu ích nên giúp AI trả lời được các câu hỏi thực tế sau.
Dự án này làm gì?
Nêu mục đích, đối tượng sử dụng và kết quả cần đạt. Đừng chỉ ghi “Bạn là chuyên gia hàng đầu”, vì câu đó chưa giúp AI hiểu bài toán.
Thông tin đáng tin nằm ở đâu?
Chỉ đường đến tài liệu sản phẩm, cấu trúc mã nguồn, dữ liệu mẫu hoặc hướng dẫn nghiệp vụ. Nếu có nhiều bản tài liệu, nói rõ bản nào là nguồn đang có hiệu lực.
Phải làm theo quy tắc nào?
Ghi những yêu cầu cụ thể: cách gọi tên sản phẩm, cách tính chỉ số, phạm vi dữ liệu hoặc quy ước triển khai.
Việc nào được tự làm, việc nào cần duyệt?
Ví dụ được tạo bản nháp, phân tích dữ liệu mẫu và kiểm tra trong môi trường phát triển. Việc xuất bản, thay đổi dữ liệu thật hay phát sinh chi phí cần có điều kiện rõ ràng.
Kiểm tra thế nào là đạt?
Đưa tiêu chí có thể đối chiếu. “Làm thật chính xác” quá chung. “Đối chiếu tổng doanh thu trong báo cáo với dữ liệu nguồn và liệt kê chênh lệch” rõ hơn.
Báo cáo ra sao?
Nêu đầu ra mong muốn: đã làm gì, kiểm tra gì, phần nào chưa xác minh và việc tiếp theo cần xử lý.
Nếu chỉ viết một câu cho mỗi ý trên, bạn đã có một bản khởi đầu đủ để dùng thử.
Dưới đây là ví dụ đề xuất, không phải mẫu bắt buộc của định dạng. Chỉ áp dụng khi môi trường agent của bạn có thể đọc file này.
# Hướng dẫn làm việc trong dự án nội dung
## Mục tiêu
Tạo nội dung hữu ích cho người đi làm muốn ứng dụng AI.
Ưu tiên tính chính xác, dễ hiểu và khả năng áp dụng.
## Nguồn thông tin
- Đọc README.md để hiểu cấu trúc dự án.
- Dùng docs/product.md cho thông tin sản phẩm.
- Dùng docs/brand-voice.md cho giọng thương hiệu.
- Nếu tài liệu mâu thuẫn, nêu rõ trước khi sử dụng.
## Cách viết
- Viết bằng tiếng Việt.
- Giải thích thuật ngữ khi xuất hiện lần đầu.
- Dùng ví dụ sát với công việc thực tế.
- Không bịa trải nghiệm, khách hàng hoặc số liệu.
- Với thông tin có thể thay đổi, kiểm tra nguồn hiện hành.
## Phạm vi tự chủ
- Được nghiên cứu, lập dàn ý và tạo bản nháp.
- Được đề xuất chỉnh sửa tài liệu.
- Chỉ xuất bản hoặc gửi nội dung khi được yêu cầu rõ ràng.
## Kiểm tra
- Đối chiếu tên sản phẩm và các con số.
- Kiểm tra nguồn cho những khẳng định quan trọng.
- Ghi rõ nội dung chưa xác minh.
## Báo cáo
- Nêu bản nháp đã tạo và vị trí lưu.
- Liệt kê điểm cần người phụ trách quyết định.Trước khi dùng, hãy tạo các tài liệu được nhắc đến hoặc sửa đường dẫn theo dự án thật. Một đường dẫn trông hợp lý nhưng không tồn tại sẽ khiến việc bàn giao thất bại ngay từ đầu.
Cách thủ công: mở VS Code hoặc một trình soạn thảo văn bản, tạo file tên AGENTS.md trong thư mục dự án và viết các quy tắc. Nếu dùng Notepad, kiểm tra để tên không bị thành AGENTS.md.txt.
Cách nhờ AI: mở đúng dự án trong công cụ agent rồi giao việc:
Hãy khảo sát dự án và tạo AGENTS.md ở thư mục gốc. Ghi mục đích, cấu trúc, nguồn thông tin, quy tắc làm việc, lệnh chạy và kiểm tra đã xác minh, thao tác cần tôi duyệt và cách báo cáo. Không bịa thông tin; ghi rõ điểm chưa xác minh. Giữ nội dung ngắn và cụ thể. Trước khi chốt, chỉ ra các quyết định nghiệp vụ hoặc quyền tự chủ cần tôi xác nhận.
AI có thể tìm hiểu cấu trúc và đề xuất. Nhưng những câu như “được phép gửi báo giá tới mức nào” hoặc “ai có quyền duyệt xuất bản” cần phản ánh quyết định của người phụ trách.
Đừng để AI đoán rồi biến phỏng đoán thành quy định.
Sau khi thiết lập, hãy yêu cầu:
Liệt kê các file hướng dẫn đang áp dụng cho nhiệm vụ này, đường dẫn và những quy tắc chính. Nêu rõ file nào bạn đã đọc, file nào chưa truy cập được.
Tiếp theo, giao một việc nhỏ có tiêu chí dễ kiểm chứng.
Ví dụ, yêu cầu tạo một bài có dẫn chứng. Quan sát xem AI có sử dụng đúng nguồn, đánh dấu phần chưa xác minh và giữ bản nháp như yêu cầu không.
Đọc được file và tuân thủ đúng là hai việc khác nhau. Câu trả lời “tôi đã hiểu” chưa đủ để kết luận hệ thống đã hoạt động tốt.
Nếu hướng dẫn chưa có hiệu lực, kiểm tra tên file, vị trí làm việc, phiên bản công cụ và file hướng dẫn khác có thể ảnh hưởng việc nạp. Với Codex, có thể cần bắt đầu lại phiên ở đúng thư mục để dựng lại chuỗi hướng dẫn. [3]
Có thể dùng cách phân chia sau khi thiết kế hệ thống:
| Thành phần | Mục đích chính |
|---|---|
| Prompt giao việc | Nêu nhiệm vụ cụ thể của lần làm việc này |
| README | Giới thiệu dự án và cách bắt đầu |
| AGENTS.md | Đặt ngữ cảnh và quy tắc làm việc dùng lại |
| Skill | Đóng gói cách thực hiện một loại nhiệm vụ |
| MCP | Chuẩn kết nối ứng dụng AI với công cụ và dữ liệu |
| Bộ nhớ | Lưu và gọi lại thông tin qua các lần làm việc |
| Cấu hình quyền | Cho phép hoặc chặn hành động ở cấp hệ thống |
Hãy lấy việc tạo nội dung làm ví dụ.
Prompt giao việc: “Viết bài về AI Agent cho nhân viên Sales.”
AGENTS.md: quy tắc dùng nguồn, giọng viết và điều kiện xuất bản.
Skill: quy trình nghiên cứu và viết bài SEO.
Công cụ kết nối qua MCP: tạo bản nháp trên website.
Bộ nhớ: các quyết định và phản hồi cần giữ để dùng về sau.
Đây là cách phân chia theo chức năng để dễ thiết kế, không phải yêu cầu bạn phải cài đủ mọi thành phần trước khi bắt đầu. Bạn có thể đọc thêm bài API, Plugin, MCP và Skill khác nhau thế nào để hiểu phần kết nối và quy trình.
Bạn có thể ghi trong file:
Bạn là Trưởng phòng Marketing, phụ trách lập kế hoạch và phát triển nội dung.
Chỉ dẫn ấy giúp định hướng vai trò. Nó chưa tạo ra một agent độc lập, chưa cấp công cụ, chưa đặt lịch và chưa tổ chức được một phòng ban.
Tương tự, tên AGENTS ở dạng số nhiều không có nghĩa file sẽ khởi tạo nhiều agent. Muốn có người nghiên cứu, người viết và người kiểm tra làm việc phối hợp, bạn còn cần cơ chế phân công, truyền kết quả và theo dõi tiến độ.
AGENTS.md có thể là một phần của hệ thống đó. Đừng nhầm phần hướng dẫn với toàn bộ bộ máy vận hành.
Một chỉ dẫn bằng văn bản giúp định hướng hành vi, nhưng không nên được xem là lớp khóa quyền duy nhất. Tài liệu Anthropic cũng phân biệt hướng dẫn trong ngữ cảnh với cơ chế thực thi để chặn hành động. [4]
Ví dụ, nếu nhiệm vụ chỉ là đọc và phân tích doanh số, hãy cân nhắc cấp quyền đọc dữ liệu. Khi ấy, kể cả agent chọn sai hành động, quyền hệ thống vẫn hạn chế khả năng thay đổi dữ liệu.
AGENTS.md nên nói rõ quy trình và điều kiện. Cấu hình quyền, tài khoản và môi trường chạy cần hỗ trợ đúng quy trình ấy.
Cũng không nên ghi mật khẩu hoặc API key vào file hướng dẫn. Hãy ghi cách lấy thông tin qua cơ chế được phép và giữ bí mật ở nơi quản lý phù hợp.
Không. File chỉ cung cấp nội dung được viết trong đó và thực sự được nạp.
Nếu một cuộc họp đã chốt cách tính doanh thu nhưng quyết định ấy chưa được ghi vào nguồn AI có thể đọc, AGENTS.md không tự biết. Nếu bạn đổi máy, file cũng không tự xuất hiện trên máy mới.
Một cách tổ chức đề xuất là:
Khi dùng nhiều máy, bạn cần cách đồng bộ phù hợp. Khi dùng nhiều công cụ, cần kiểm tra công cụ nào đọc được nguồn nào.
Đừng gom toàn bộ lịch sử trò chuyện vào AGENTS.md chỉ để tạo cảm giác “có trí nhớ”. Xem thêm bài bộ nhớ AI Agent: Claude, ChatGPT, RAG và AGENTS.md.
Viết dài nhưng thiếu chỉ dẫn cụ thể. Nhiều câu ca ngợi vai trò không giúp AI chọn đúng nguồn dữ liệu hay xử lý một ngoại lệ.
Sao chép mẫu rồi giữ nguyên lệnh không có thật. Nếu dự án không có bộ kiểm tra đã mô tả, agent sẽ phải đoán cách xử lý. Hãy xác minh trước.
Đặt quy tắc mâu thuẫn. Một nơi yêu cầu tự đăng, nơi khác yêu cầu chờ duyệt. Cần sửa sự mâu thuẫn thay vì hy vọng AI tự chọn đúng.
Nhồi mọi quy trình vào file chính. Hãy giữ phần cần dùng thường xuyên, còn hướng dẫn dài có thể đưa sang tài liệu riêng và chỉ rõ lúc nào cần đọc. Đường dẫn không đồng nghĩa nội dung sẽ tự được nạp.
Không cập nhật khi công việc đổi. Quy tắc cũ được áp dụng đều đặn vẫn có thể tạo ra kết quả sai.
Đáng học là chính repo AGENTS.md có file hướng dẫn riêng cho website của nó. File đó nhắc agent dùng development server khi chỉnh sửa tương tác, tránh production build trong phiên ấy và đồng bộ lockfile khi thay dependency. Đây là các lưu ý cụ thể cho dự án Next.js đó, không phải quy tắc áp dụng cho mọi dự án. [5]
Nên bắt đầu khi bạn làm việc lâu dài trên một dự án, dùng nhiều phiên agent, có nhiều người cùng tham gia hoặc thường xuyên phải nhắc lại cùng một quy tắc.
Chưa cần đầu tư nhiều nếu công việc chỉ diễn ra một lần và một prompt rõ ràng đã đủ.
Ngay cả khi cần, bản đầu tiên cũng không phải một cuốn cẩm nang đầy đủ. Bạn có thể bắt đầu từ năm điều:
Sau một nhiệm vụ thật, hãy xem lỗi xuất phát từ đâu: thiếu hướng dẫn, thiếu dữ liệu, thiếu công cụ hay năng lực thực hiện chưa đủ. Chỉ trường hợp đầu tiên mới được giải quyết trực tiếp bằng việc bổ sung AGENTS.md.
Một file hướng dẫn rõ ràng giúp việc bàn giao tốt hơn. Giá trị nằm ở những quy tắc đúng, được kiểm chứng và cập nhật khi công việc thay đổi.
AGENTS.md là file Markdown cung cấp ngữ cảnh và chỉ dẫn cho AI coding agent trong dự án. Nội dung có thể gồm nguồn thông tin, quy tắc triển khai, cách kiểm tra và cách báo cáo.
Trong quy ước đang đề cập, tên file là AGENTS.md, viết hoa và có chữ S. Một file tên agent.md không mặc nhiên được công cụ tự tìm và nạp; chỉ dùng tên khác khi công cụ đã được cấu hình hỗ trợ.
Không cần biết lập trình để viết hướng dẫn bằng văn bản. Bạn có thể tạo file bằng VS Code hoặc Notepad, hoặc nhờ agent khảo sát và soạn giúp. Các lệnh và quy tắc kỹ thuật trong file vẫn cần được xác minh.
Thông thường bắt đầu ở thư mục gốc của dự án. Có thể đặt thêm file ở thư mục con khi cần quy tắc riêng. Việc tìm và nạp các file phụ thuộc công cụ agent đang sử dụng.
Không nên coi hai tên file là tương đương trong mọi cấu hình. Claude Code có hỗ trợ AGENTS.md ở các phiên bản hiện hành, nhưng việc nạp còn phụ thuộc CLAUDE.md, CLAUDE.local.md và cài đặt Project instructions. Hãy kiểm tra tài liệu của phiên bản đang dùng.
Không. AGENTS.md đặt hướng dẫn làm việc cho dự án. Skill đóng gói cách thực hiện một loại nhiệm vụ; MCP chuẩn hóa kết nối ứng dụng AI với công cụ và dữ liệu. Chúng có thể phối hợp trong cùng một hệ thống.
Không. Tên AGENTS ở dạng số nhiều không khởi tạo nhiều agent. Muốn nhiều agent làm việc cùng nhau, cần thêm môi trường chạy, cách phân công, công cụ, quyền và cơ chế trao đổi kết quả.
Không có bảo đảm như vậy. File phải được nạp đúng, nội dung phải rõ và còn hiệu lực. Bạn vẫn cần kiểm tra kết quả thực tế, nhất là dữ liệu, phân quyền và hành động ảnh hưởng tới hệ thống thật.
Thông tin về công cụ được đối chiếu ngày 22/10/2026; hành vi có thể thay đổi theo phiên bản.
Học cách ứng dụng AI Agent vào công việc qua 4 buổi online với 15 tình huống thực tế.
