# AGENTS.md là gì và cách tự viết tệp này trong 30 phút > Định dạng AGENTS.md, khả năng hỗ trợ trong các công cụ AI, mẫu có sẵn, quy tắc và lỗi thường gặp. Cách phối hợp AGENTS.md với CLAUDE.md và các tệp hướng dẫn khác. Source: https://ailoot.ai/blog/vi/agents-md-guide-template/ Canonical: https://ailoot.ai/blog/vi/agents-md-guide-template/ Language: vi Publisher: Ailoot (https://ailoot.ai/) Translation: guide-034 Revision: sha256-3ffd7f29634d719b77726a89523d817cf3c48bba60c8a56625e4d51ce83fc532 Tài liệu thực tiễn về vibe coding và làm việc với agent: [tài liệu Ailoot](https://ailoot.ai/docs/). ## AGENTS.md trong một đoạn
Điểm chính AGENTS.md là một tệp Markdown thuần ở thư mục gốc của dự án, chứa hướng dẫn cho một agent AI: cách cài đặt các phần phụ thuộc, cách chạy kiểm thử, phong cách mã cần tuân theo và những gì không được động tới. Đây là định dạng mở, do OpenAI tạo ra vào tháng 8 năm 2025 và gia nhập Linux Foundation vào tháng 12 cùng năm. Nhiều công cụ lập trình có thể dùng tệp này, nhưng cách tìm tệp khác nhau theo ứng dụng và phiên bản: một số tự nạp AGENTS.md, số khác cần cấu hình rõ tên tệp hoặc đường dẫn tệp cần đọc. Kể từ phiên bản 2.1.277 (tháng 9 năm 2026), Claude Code cũng đọc AGENTS.md nếu dự án không có CLAUDE.md. Nếu có CLAUDE.md, theo mặc định Claude Code chỉ đọc tệp đó; AGENTS.md được đưa vào bằng dòng `@AGENTS.md` hoặc thông qua một liên kết tượng trưng.
Dưới đây, định dạng này được xem xét dựa trên [agents.md](https://agents.md), tài liệu [OpenAI Codex](https://github.com/openai/codex), [JetBrains Junie](https://junie.jetbrains.com/docs/guidelines-and-memory.html), [Cursor Rules Docs](https://cursor.com/docs/rules), [nhật ký thay đổi GitHub Copilot Coding Agent](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) và [thông cáo báo chí của Linux Foundation về Agentic AI Foundation](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation). Tất cả số liệu và tính năng được cập nhật đến ngày 30 tháng 5 năm 2026; phần hỗ trợ AGENTS.md trong Claude Code được mô tả theo [tài liệu Anthropic](https://code.claude.com/docs/en/memory#agents-md), có cập nhật ngày 24 tháng 9 năm 2026. Nếu bạn chưa biết vườn thú công cụ trên thị trường này là gì hoặc tại sao chúng cần một tệp dùng chung, hãy đọc trước hướng dẫn [“Nên lập trình bằng gì trong năm 2026: 8 công cụ AI từ Claude Code đến Antigravity”](https://ailoot.ai/blog/vi/ai-coding-tools/). Bài viết này tập trung riêng vào định dạng AGENTS.md và cách tự viết tệp này trong 30 phút. ## AGENTS.md là gì và xuất phát từ đâu?
Điểm chính AGENTS.md là định dạng tệp Markdown mở, nơi bạn tự viết hướng dẫn cho các agent AI. OpenAI phát hành định dạng này vào tháng 8 năm 2025 cùng với Codex CLI và ngay lập tức mời các đồng tác giả: Cursor, Sourcegraph Amp, Google Jules và Factory. Ý tưởng rất đơn giản: “đừng tạo một tệp độc quyền cho từng công cụ; hãy thống nhất dùng một tệp.” Ngày 9 tháng 12 năm 2025, AGENTS.md cùng với MCP của Anthropic và goose của Block gia nhập Linux Foundation, trở thành một trong ba dự án sáng lập của Agentic AI Foundation mới. Đến tháng 12 cùng năm, hơn 60.000 kho lưu trữ GitHub đã có AGENTS.md ở thư mục gốc.
Trước đây, mỗi công cụ AI có tệp quy tắc riêng: Anthropic có `CLAUDE.md`, Cursor có `.cursorrules`, GitHub có `.github/copilot-instructions.md`, Aider có `.aider.conf.yml`, còn JetBrains có `.junie/guidelines.md`. Nếu nhóm của bạn có ba agent khác nhau, điều đó đồng nghĩa với ba tệp song song chứa cùng nội dung và sẽ bắt đầu lệch nhau chỉ sau một tuần. OpenAI là bên đầu tiên cảm thấy mệt mỏi vì chuyện này. Tháng 8 năm 2025, họ phát hành Codex CLI và đồng thời ra mắt [agents.md](https://agents.md) như một định dạng mở. Trích từ trang web: > “Hãy hình dung AGENTS.md như README dành cho agent.” > > ([agents.md](https://agents.md), bản dịch từ tiếng Anh) Điểm chính là AGENTS.md bổ trợ cho README. README dành cho con người: “dự án này là gì, cách chạy cục bộ, cách đóng góp.” AGENTS.md dành cho agent: các lệnh shell chính xác, tiêu chí “hoàn tất” có thể kiểm chứng và những giới hạn như “tuyệt đối không động vào mục này.” Trích từ trang web: > “AGENTS.md bổ trợ README: tệp này chứa ngữ cảnh bổ sung, đôi khi chi tiết, mà agent cần—các bước dựng, kiểm thử và quy ước vốn sẽ làm README trở nên rườm rà hoặc đơn giản là không cần thiết đối với người đóng góp.” > > ([agents.md](https://agents.md), bản dịch từ tiếng Anh) Đến tháng 9 năm 2025, GitHub Copilot Coding Agent đã hỗ trợ định dạng này ([nhật ký thay đổi, 28.08.2025](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/)). Đến tháng 12, Cursor, Junie, Gemini CLI, Aider và thêm một tá công cụ khác đã tham gia. Ngày 9 tháng 12 năm 2025, Linux Foundation thành lập [Agentic AI Foundation (AAIF)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation): ba dự án sáng lập là AGENTS.md của OpenAI, MCP của Anthropic và goose của Block. Các thành viên sáng lập gồm AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft và OpenAI. Đến ngày 24 tháng 2 năm 2026, foundation đã có [146 tổ chức](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members), bao gồm Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath và Hitachi. Từ đó, AGENTS.md không còn là “một thứ nữa của OpenAI” mà đã trở thành tiêu chuẩn trên thực tế. ## Agent AI nào đọc AGENTS.md và công cụ nào không đọc?
Điểm chính AGENTS.md được dùng trong nhiều công cụ lập trình, gồm các ứng dụng liệt kê bên dưới. Hãy xem bảng là bản đồ các cách nạp tệp, không phải cam kết về khả năng hỗ trợ trực tiếp giống hệt nhau: cơ chế tự tìm, cấu hình tường minh, thứ tự ưu tiên tên tệp và xử lý tệp lồng nhau có thể khác nhau. Claude Code của Anthropic là ngoại lệ trong thời gian dài: issue \#6235, yêu cầu hỗ trợ, vẫn mở từ tháng 8 năm 2025 đến tháng 8 năm 2026. Kể từ phiên bản 2.1.277 (ngày 18 tháng 9 năm 2026), Claude Code tự đọc AGENTS.md nếu dự án không có CLAUDE.md. Nếu có CLAUDE.md, theo mặc định chỉ tệp đó được đọc; AGENTS.md được đưa vào bằng dòng `@AGENTS.md` bên trong CLAUDE.md hoặc thông qua một liên kết tượng trưng.
Bảng hỗ trợ tính đến ngày 30 tháng 5 năm 2026; hàng Claude Code được cập nhật ngày 24 tháng 9 năm 2026: | Công cụ | Đọc AGENTS.md | Ngày / nguồn | |----|----|----| | OpenAI Codex CLI | Có (định dạng gốc) | Tháng 8 năm 2025, [agents.md](https://agents.md) | | GitHub Copilot Coding Agent | Có | 28.08.2025, [GitHub Changelog](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) | | Cursor | Có, thư mục gốc + thư mục lồng nhau | [Cursor Rules Docs](https://cursor.com/docs/rules) | | JetBrains Junie | Có, dự án + toàn cục `~/.junie/AGENTS.md` | [Junie Docs](https://junie.jetbrains.com/docs/guidelines-and-memory.html) | | Gemini CLI (Google) | Có, thông qua `.gemini/settings.json` với `fileName: AGENTS.md` | [agents.md](https://agents.md) | | Jules (Google) | Có, đồng tác giả của tiêu chuẩn | Tháng 8 năm 2025 | | Sourcegraph Amp | Có, đồng tác giả của tiêu chuẩn | Tháng 8 năm 2025 | | Aider | Có, thông qua `read: AGENTS.md` trong `.aider.conf.yml` | [agents.md](https://agents.md) | | Factory | Có, đồng tác giả của tiêu chuẩn | Tháng 8 năm 2025 | | OpenCode | Có | — | | Zed | Có | [agents.md](https://agents.md) | | Warp | Có | [agents.md](https://agents.md) | | VS Code | Có | [agents.md](https://agents.md) | | Windsurf | Có | — | | Devin (Cognition) | Có, thông qua Spec Kit Skills | Tháng 4 năm 2026 | | RooCode, Kilo Code, Augment Code | Có | [agents.md](https://agents.md) | | **Claude Code (Anthropic)** | **Có, nếu dự án không có CLAUDE.md** | Kể từ phiên bản 2.1.277 (18.09.2026), [tài liệu Claude Code](https://code.claude.com/docs/en/memory#agents-md) | Anthropic là hãng lớn cuối cùng tham gia. Tháng 8 năm 2025, issue \#6235 đề nghị hỗ trợ AGENTS.md được mở trong kho chính thức `anthropics/claude-code`. Issue này vẫn mở trong gần một năm và được đóng vào ngày 17 tháng 8 năm 2026; phiên bản 2.1.277 hỗ trợ AGENTS.md được phát hành ngày 18 tháng 9. Logic của Anthropic như sau: CLAUDE.md được ưu tiên, còn AGENTS.md được đọc khi không có CLAUDE.md trong thư mục làm việc hoặc bất kỳ thư mục cha nào. Theo [tài liệu](https://code.claude.com/docs/en/memory#agents-md), cách hoạt động như sau: | Trong dự án có gì | Claude Code đọc gì | |----|----| | Chỉ có AGENTS.md | AGENTS.md | | Có AGENTS.md và CLAUDE.md (hoặc CLAUDE.local.md) | Chỉ CLAUDE.md | | CLAUDE.md có dòng `@AGENTS.md` | CLAUDE.md, trong đó có nội dung AGENTS.md | Điểm cần lưu ý: một tệp cá nhân `CLAUDE.local.md` cũng được tính, và khi có tệp này, Claude Code ngừng đọc AGENTS.md. Bạn có thể thay đổi hành vi này trong `/config`, ở mục Project instructions—chẳng hạn để Claude Code đọc cả hai tệp cùng lúc. Trong các phiên bản cũ hơn 2.1.277, AGENTS.md sẽ không được tự động nạp; dòng `@AGENTS.md` trong CLAUDE.md vẫn là cách khắc phục. ## AGENTS.md khác CLAUDE.md và `.cursorrules` như thế nào?
Điểm chính Về mặt kỹ thuật, chẳng có gì đặc biệt: cả bốn định dạng (AGENTS.md, CLAUDE.md, `.cursorrules`, `.github/copilot-instructions.md`) đều là các tệp Markdown thông thường chứa hướng dẫn cho agent. Khác biệt nằm ở chỗ công cụ nào đọc chúng và chúng nằm ở đâu. AGENTS.md có thể lưu hướng dẫn dùng chung cho nhiều ứng dụng, còn cách tìm tệp hoặc cấu hình riêng của từng ứng dụng được giữ riêng. CLAUDE.md chỉ dành cho Claude Code, nhưng cung cấp các tính năng nâng cao: quy tắc theo đường dẫn, `CLAUDE.local.md` để ghi đè cá nhân, `@import` để đưa các tệp khác vào, cùng hệ thống phân cấp dự án + người dùng + cục bộ. `.cursorrules` đã lỗi thời trong Cursor—hệ thống mới dùng `.cursor/rules/*.mdc` với cơ chế tự đính kèm theo loại tệp. Chỉ Copilot trên web mới cần `.github/copilot-instructions.md`.
So sánh bốn định dạng tính đến ngày 30 tháng 5 năm 2026: | Định dạng | Công cụ đọc | Vị trí | Ưu điểm | Nhược điểm | |----|----|----|----|----| | **AGENTS.md** | Nhiều ứng dụng, cách nạp khác nhau | Gốc/tệp lồng nhau theo quy tắc từng ứng dụng | Hướng dẫn chung không phụ thuộc một nhà cung cấp | Cần xác minh cách tìm, cấu hình và thứ tự ưu tiên của từng ứng dụng | | **CLAUDE.md** | Chỉ Claude Code | Thư mục gốc + `~/.claude/CLAUDE.md` + `CLAUDE.local.md` | Phân cấp, quy tắc theo đường dẫn, `@import`, kỹ năng, hook | Chỉ Claude. Không hoạt động trong Cursor / Codex / Copilot | | **`.cursor/rules/*.mdc`** | Chỉ Cursor | `.cursor/rules/.mdc` | Tự đính kèm theo loại tệp (TS, Python, đường dẫn cụ thể) | Chỉ Cursor, cú pháp `.mdc` không theo chuẩn | | **`.github/copilot-instructions.md`** | GitHub Copilot (web + bản cổ điển) | `.github/` | Hoạt động trực tiếp trên trình duyệt tại GitHub.com | Chỉ Copilot, trùng lặp với AGENTS.md | AGENTS.md có thể giữ hướng dẫn dự án dùng chung, còn đường nạp và cài đặt cá nhân của từng ứng dụng vẫn cần cấu hình riêng. Claude Code có `CLAUDE.local.md` cho việc đó, còn Cursor có các tệp `.mdc` cục bộ trong thư mục người dùng. Chỉ AGENTS.md thì không đáp ứng được—bạn cần kết hợp với các tệp khác hoặc thống nhất trong nhóm rằng các quy tắc cá nhân sẽ được ghi trong những phần bị gitignore. Một chi tiết quan trọng khác là monorepo. Codex và Cursor áp dụng quy tắc “AGENTS.md gần nhất sẽ được ưu tiên”: > “Trong monorepo, hãy đặt một AGENTS.md riêng bên trong từng gói. Agent tự động đọc tệp gần nhất trong cây thư mục, và tệp gần nhất sẽ được ưu tiên.” > > ([agents.md](https://agents.md), bản dịch từ tiếng Anh) [agents.md](https://agents.md) cho biết monorepo chính của OpenAI có 88 tệp AGENTS.md cho các gói con khác nhau. Nếu bạn làm việc trong monorepo, hãy phân bổ quy tắc theo các cấp: quy tắc chung ở thư mục gốc, quy tắc cụ thể hơn ở thư mục con. ## Một AGENTS.md tốt nên có những gì?
Điểm chính Bố cục của một AGENTS.md tốt có 8 mục thường thấy trong các tệp phổ biến: Tổng quan dự án, Lệnh thiết lập, Phong cách mã, Mẹo về môi trường phát triển, Hướng dẫn kiểm thử, Quy tắc PR, Lưu ý bảo mật và Giới hạn (những việc không nên làm). Những phần khác đều tùy chọn. Quy tắc chính: mỗi mục phải là một lệnh chính xác hoặc ví dụ cụ thể, chứ không phải ý tưởng chung chung như “viết mã sạch.”
Trang [agents.md](https://agents.md) đưa ra một định dạng linh hoạt—“bất kỳ Markdown nào.” Nhưng 80% tệp tốt ngoài thực tế có cùng tám mục. Quy tắc chính: mỗi mục phải là một lệnh chính xác hoặc một ví dụ cụ thể. Ý tưởng trừu tượng như “viết mã sạch” sẽ bị agent bỏ qua. 1. **Tổng quan dự án** — 2–3 dòng. Dự án là gì, dành cho ai và mục tiêu chính là gì. Không dùng ngôn ngữ tiếp thị. Ví dụ: “Bot Telegram hỗ trợ người dùng làm quen với workshop trả phí. Stack: Next.js 14, Prisma, PostgreSQL. Được kích hoạt khi có bản ghi mới trong `purchases`.” 2. **Lệnh thiết lập** — các lệnh shell chính xác để chạy cục bộ. `npm install`, `npm run dev`, `npm run build`. Không viết kiểu “thường thì chúng ta làm như sau.” 3. **Phong cách / quy ước mã** — quy tắc cụ thể kèm ví dụ, không phải “viết cho gọn gàng.” Ví dụ: “TypeScript strict, dùng dấu nháy đơn, không dùng default export, tên component theo PascalCase, hook bắt đầu bằng `use`.” 4. **Mẹo về môi trường phát triển** — vị trí các thông tin quan trọng. Cần những biến nào trong `.env`, lưu bí mật ở đâu, đang dùng những cổng nào và cách làm việc với DB cục bộ. 5. **Hướng dẫn kiểm thử** — cách chạy một kiểm thử cụ thể và thế nào được tính là “đạt.” Ví dụ: `npm test -- --testPathPattern=user-auth`; kỳ vọng đạt 100%. 6. **Quy tắc PR / commit** — định dạng thông điệp commit, danh sách kiểm tra trước PR (kiểm thử, linter, tài liệu) và ai phê duyệt. 7. **Lưu ý bảo mật** — những điều tuyệt đối không được làm. “Không bao giờ commit `.env`. Chỉ lưu bí mật trong Vault. Không hiển thị dữ liệu cá nhân của người dùng trong log.” 8. **Giới hạn / Tuyệt đối không làm** — các điều cấm kèm phương án thay thế. “Đừng dùng `git push --force` trên main. Nếu cần hoàn tác, hãy dùng `git revert` hoặc `git reset` trên nhánh tính năng.” Trong mỗi mục, hãy áp dụng nguyên tắc “dùng lệnh thay vì ý tưởng.” Agent sẽ bỏ qua “hãy cẩn thận với các lần di trú.” Agent sẽ làm theo “Trước khi chạy `alembic upgrade head`, hãy chạy `alembic check`. Nếu báo lỗi, đừng áp dụng lần di trú; hãy hỏi tôi.” ## Mẫu AGENTS.md sẵn sàng sử dụng (sao chép và điều chỉnh)
Điểm chính Dưới đây là mẫu AGENTS.md khởi đầu cho một dự án web điển hình. Hãy sao chép vào thư mục gốc của kho, thay ``, ``, các lệnh chính xác và xóa những mục bạn không cần. Việc điều chỉnh mất 20–30 phút—hoặc lâu hơn nếu đây là lần đầu bạn làm.
````markdown # AGENTS.md ## Tổng quan dự án - . Stack: . Main entities: . Details for people are in README.md. ## Lệnh thiết lập ```bash # first install npm install cp .env.example .env # then fill in manually; see list below # run npm run dev # dev server on :3000 npm run build # production build npm run start # run production build ``` ## Môi trường phát triển - Node 20+ (via nvm: `nvm use 20`) - PostgreSQL 16 locally on :5432 (`docker-compose up postgres`) - Redis is optional, needed only for queues (`docker-compose up redis`) - `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET` - Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env` ## Phong cách mã - TypeScript strict mode - Single quotes, no semicolons (unless ESLint requires them) - Imports: external first, then internal via `@/`, then relative - Components in PascalCase; hooks start with `use` - No `any` without an explicit comment explaining “why it can’t be typed” Example of a good module: ```ts import { z } from 'zod' const UserSchema = z.object({ email: z.string().email(), name: z.string().min(2), }) export function parseUser(raw: unknown) { return UserSchema.parse(raw) } ``` ## Kiểm thử ```bash npm test # all tests npm test -- --testPathPattern=auth # auth only npm test -- --watch # watch mode ``` All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do. ## Hướng dẫn pull request - Commit format: `(): ` (`feat(auth): add magic-link`) - Before PR: `npm run build && npm test && npm run lint` - PR description = what changes, why, and how to test - Don’t approve your own PR—always wait for human review ## Bảo mật - Secrets only in `.env` and Vault, never in code - Don’t log personal data (email, phone, name) - When working with the production DB, use read-only queries only unless explicitly authorized - Don’t hardcode external service API keys (Stripe, OpenAI) in tests ## Tuyệt đối không làm - Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR - Don’t run DB migrations without `alembic check` (or the equivalent in your ORM) - Don’t use `npm install -g` or `sudo` for project dependencies - Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM) ```` Trung bình, mẫu có 80–120 dòng. Nếu tệp vượt quá 150 dòng, đó là dấu hiệu bạn nên tái cấu trúc: chuyển một phần sang `docs/`, liên kết đến nội dung đó hoặc nén thành một dòng. Trên thực tế, các tệp dài 100–150 dòng hoạt động tốt nhất; vượt quá ngưỡng đó, chất lượng bắt đầu giảm. ## 5 quy tắc nào giúp AGENTS.md thực sự hữu ích?
Điểm chính Một AGENTS.md tốt tuân theo năm quy tắc: dùng lệnh thay vì ý tưởng, đưa phương án thay thế kèm điều cấm, chỉ có đúng một nguồn chân lý, tiêu chí hoàn tất có thể kiểm chứng và tệp ngắn hơn 150 dòng.
1. **Dùng lệnh thay vì ý tưởng.** Agent không hiểu “hãy cẩn thận với các lần di trú.” Nó sẽ làm theo `alembic check` trước `alembic upgrade head`. Agent làm việc với lệnh và điều kiện, không phải tâm trạng. Hãy diễn đạt mọi quy tắc chính theo dạng “làm X, nếu không thì làm Y.” 2. **Điều cấm kèm phương án thay thế.** Agent sẽ lặng lẽ phớt lờ câu “đừng force push” sau hai hoặc ba câu lệnh. Cặp “đừng làm X; thay vào đó hãy làm Y” có tác dụng. Ví dụ: “đừng dùng `git push --force` trên main; nếu cần hoàn tác, hãy dùng `git revert` hoặc mở PR mới.” 3. **Chỉ có đúng một nguồn chân lý.** AGENTS.md ở thư mục gốc là nguồn chân lý cho toàn bộ dự án. Nếu có monorepo, hãy dùng các tệp AGENTS.md lồng trong thư mục con theo quy tắc “tệp gần nhất được ưu tiên.” Không tạo các tệp song song có hướng dẫn mâu thuẫn. 4. **Tiêu chí “hoàn tất” có thể kiểm chứng.** “Kiểm thử phải đạt” là vô ích. Tiêu chí chính xác là: `npm test` trả về mã thoát 0 và không in `FAIL` ra stdout. “Mã phải sạch” cũng vô ích. Tiêu chí chính xác là: `npm run lint` chạy thành công mà không có cảnh báo. Agent chỉ hiểu “hoàn tất” nghĩa là gì khi bạn mô tả rõ điều kiện. 5. **Tệp ngắn hơn 150 dòng.** Sau 150 dòng, các chỉ số bắt đầu giảm: agent tốn thêm ngữ cảnh để đọc và bỏ lỡ các quy tắc quan trọng. Nếu nội dung không vừa, hãy chuyển chi tiết sang `docs/architecture.md` và liên kết đến đó từ AGENTS.md, chỉ giữ lại lệnh và giới hạn trong tệp này. ## 10 lỗi nào biến AGENTS.md thành thứ vô dụng?
Điểm chính Nguyên nhân chính khiến AGENTS.md không hiệu quả là câu chữ mơ hồ. Trong nghiên cứu hơn 2.500 kho lưu trữ, GitHub Blog cho thấy phần lớn tệp thất bại vì được viết quá chung chung. Chẳng hạn, “Bạn là một trợ lý lập trình hữu ích” không cung cấp cho agent chút thông tin hữu ích nào. Dưới đây là 10 lỗi điển hình và biểu hiện trong các tệp kém: lặp lại README, văn xuôi thiếu cấu trúc, hơn 30 điều cấm không có phương án thay thế, mức độ ưu tiên mâu thuẫn, bí mật bị mã hóa cứng, tài liệu lỗi thời và kiến trúc quá rườm rà cho tác vụ đơn giản.
1. **Quy tắc mơ hồ, không có lệnh.** Agent sẽ bỏ qua “hãy cẩn thận với các lần di trú”—câu đó chẳng có ý nghĩa gì với nó. Chỉ có lệnh cụ thể kèm điều kiện mới hiệu quả: “Chạy `alembic check` trước `alembic upgrade head`. Nếu có lỗi, đừng áp dụng lần di trú; hãy hỏi tôi.” 2. **“Mã sạch.”** Cụm từ vô ích. Hãy thay bằng một mẫu cụ thể: “Dùng component hàm với hook. Ví dụ: `function LoginForm() { const [email, setEmail] = useState(''); ... }`” 3. **Văn xuôi thiếu cấu trúc.** Nếu AGENTS.md có 300 dòng văn xuôi không có đề mục, agent sẽ tốn 80K token ngữ cảnh cho các đoạn không liên quan và bỏ lỡ điều quan trọng. Hãy dùng đề mục H2/H3, các phần ngắn và danh sách gạch đầu dòng. 4. **Tệp dài hơn 150 dòng.** Các chỉ số chất lượng suy giảm khi vượt ngưỡng này. Hãy tách thành một tệp chính và liên kết đến nội dung chi tiết trong `docs/`. 5. **Hơn 30 điều cấm không có phương án thay thế.** Nếu tệp có một danh sách dài kiểu “đừng làm X, đừng làm Y” mà không giải thích “thay vào đó hãy làm Z”, agent sẽ loay hoay không biết làm gì. 6. **Lặp lại README.md.** Nếu bạn đã viết “cách cài đặt và chạy” trong README, đừng sao chép vào AGENTS.md. Thay vào đó, chỉ cần dẫn README trong một dòng và mô tả trong AGENTS.md những gì agent cần mà người đóng góp là con người không cần. 7. **Mã hóa cứng bí mật.** AGENTS.md có thể công khai (vì nằm trong git). Không đưa khóa API, token hoặc mật khẩu thật vào đó. Chỉ tham chiếu tới kho bí mật: “Xem Vault: `secret/staging/db`.” 8. **Mức độ ưu tiên mâu thuẫn, không phân hạng.** “Làm nhanh” + “duy trì độ bao phủ kiểm thử 90%” khiến agent không biết phải chọn gì. Hãy xếp thứ tự rõ ràng: “Độ bao phủ kiểm thử ≥80% được ưu tiên trước, rồi đến tốc độ. Nếu hai mục xung đột, kiểm thử được ưu tiên.” 9. **Tài liệu lỗi thời.** Mô tả kiến trúc ghi REST+polling trong khi thực tế đã chuyển sang WebSockets. Agent làm theo mô tả lỗi thời và phá vỡ kiến trúc. Quy tắc: cập nhật AGENTS.md trong cùng PR với mã mỗi khi kiến trúc thay đổi. 10. **Kiến trúc quá rườm rà cho tác vụ đơn giản.** Nếu ai đó yêu cầu đổi hai dòng trong cấu hình, agent không cần đọc toàn bộ sơ đồ của 14 dịch vụ vi mô. Chuyển phần kiến trúc “chuyên sâu” sang `docs/architecture.md`; trong AGENTS.md chỉ cần ghi “nếu tác vụ liên quan đến kiến trúc, hãy đọc `docs/architecture.md`.” [Nghiên cứu của GitHub Blog trên hơn 2.500 kho AGENTS.md](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) nêu kết luận chính: > “Phần lớn tệp dành cho agent thất bại vì quá chung chung. ‘Bạn là một trợ lý lập trình hữu ích’ không hiệu quả.” > > ([GitHub Blog](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/), bản dịch từ tiếng Anh) ## Giữ AGENTS.md và CLAUDE.md trong cùng một kho như thế nào?
Điểm chính Có ba kịch bản: (1) Chỉ dùng Claude Code—giữ CLAUDE.md; không cần AGENTS.md. (2) Chỉ dùng công cụ không phải Claude (Codex, Cursor, Copilot, Junie)—dùng AGENTS.md làm nguồn chân lý duy nhất. (3) Nhóm hỗn hợp có Claude Code và các công cụ khác—chọn AGENTS.md làm tệp chính. Nếu không có quy tắc riêng cho Claude, bạn có thể bỏ CLAUDE.md: kể từ phiên bản 2.1.277, Claude Code tự đọc AGENTS.md. Nếu có quy tắc riêng, hãy liên kết AGENTS.md với CLAUDE.md bằng liên kết tượng trưng hoặc lệnh nhập `@AGENTS.md`. Trên macOS và Linux, chỉ rename khi AGENTS.md chưa tồn tại. Nếu cả hai có sẵn, giữ và gộp quy tắc trước rồi dùng CLAUDE.md bọc ngắn với `@AGENTS.md`; không ghi đè AGENTS.md hiện có. Trên Windows, tạo liên kết tượng trưng cần Developer Mode, nên dùng lệnh nhập sẽ dễ hơn.
Câu hỏi thực tiễn chính là làm sao dùng cả hai tệp mà không nhân đôi nội dung. Có ba kịch bản: **Kịch bản 1: Chỉ dùng Claude Code.** Giữ CLAUDE.md và sử dụng mọi tính năng của Claude Code: `~/.claude/CLAUDE.md` cho hướng dẫn cấp người dùng, `CLAUDE.md` cho dự án, `CLAUDE.local.md` cho phần ghi đè cá nhân, `@import` để đưa các tệp khác vào và `.claude/skills/` cho kỹ năng chuyên biệt. Không cần AGENTS.md. **Kịch bản 2: Dùng nhiều ứng dụng lập trình.** Giữ quy tắc chung trong AGENTS.md, sau đó kết nối và kiểm tra riêng từng ứng dụng. Gemini CLI hỗ trợ cấu hình tên tệp ngữ cảnh; Aider có thể nạp tệp qua cấu hình read. Đây là những đường nạp tệp tường minh, không phải cùng một cơ chế tự tìm. | Cách nạp | Nội dung cần kiểm tra | |----|----| | Tự tìm AGENTS.md | Quy tắc thư mục gốc, tệp lồng nhau và thứ tự ưu tiên được tài liệu của phiên bản đang cài mô tả | | Cấu hình tường minh, như Gemini CLI hoặc Aider | Tên tệp/đường dẫn read đã cấu hình và màn hình xem ngữ cảnh đã nạp | | Claude Code nạp có điều kiện hoặc nhập tệp | Phiên bản đang cài và thứ tự ưu tiên các tệp; xem [hướng dẫn AGENTS.md riêng cho Claude Code](https://ailoot.ai/blog/vi/claude-code-agents-md-support/) | Mở phiên mới trong một kho thử nghiệm an toàn, thêm chỉ dẫn vô hại có dấu hiệu riêng như “đưa dấu instructions-loaded vào câu trả lời thử”, rồi kiểm tra cả màn hình tệp đã nạp hoặc log được ứng dụng công bố lẫn câu trả lời. Lặp lại với từng ứng dụng/phiên bản thực sự sử dụng. Việc mô hình tự nói đã đọc tệp không phải bằng chứng độc lập về việc nạp; một lần kiểm tra thành công không chứng minh mọi công cụ khác đều hỗ trợ. **Kịch bản 3: Nhóm hỗn hợp (Claude Code + các công cụ khác).** Đây là cách thiết lập phổ biến nhất năm 2026. Giải pháp là dùng AGENTS.md làm tệp chính. Nếu không có quy tắc riêng cho Claude Code, đừng tạo CLAUDE.md: kể từ phiên bản 2.1.277, Claude Code đọc AGENTS.md khi dự án không có CLAUDE.md. Nếu có quy tắc như vậy, hãy tạo CLAUDE.md dưới dạng liên kết tượng trưng hoặc một tệp bọc ngắn có lệnh nhập `@AGENTS.md`. Trước khi đổi, xem và backup cả hai tệp. Nếu đều tồn tại, gộp hướng dẫn chung không xung đột vào AGENTS.md, giữ phần Claude riêng trong CLAUDE.md với import `@AGENTS.md`. Giữ symlink hiện có thay vì thay nó. Với CLAUDE.md thường **chỉ khi AGENTS.md vắng**, guard macOS/Linux sau từ chối đè đích hoặc symlink tồn tại: ```bash if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2 elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md else printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2 fi ``` Sau rename thành công, CLAUDE.md là symlink tới AGENTS.md. Mọi agent đọc AGENTS.md đều thấy cùng nội dung. Claude Code, vốn đọc CLAUDE.md, cũng thấy nội dung đó thông qua liên kết tượng trưng. Trên Windows, tạo liên kết tượng trưng cần Developer Mode (hoặc quyền Admin), điều có thể bất tiện cho cả nhóm. Một lựa chọn khác là dùng CLAUDE.md ngắn để nhập AGENTS.md: ```markdown # CLAUDE.md @AGENTS.md ## Riêng cho Claude Code - Dùng .claude/skills/ cho các câu lệnh chuyên biệt - Khi làm việc với Skills, hãy tham khảo .claude/skills/INDEX.md - Dùng Plan Mode trước các thay đổi lớn (Shift+Tab) ``` Trong Claude Code, cú pháp này đưa AGENTS.md vào bằng một dòng và bổ sung các nội dung riêng cho Claude Code bên dưới. Nếu sau này bạn muốn bỏ AGENTS.md, chỉ cần xóa lệnh nhập. Dòng này không khiến tệp bị đọc hai lần: theo tài liệu Claude Code, cùng một AGENTS.md sẽ không được nạp hai lần, ngay cả khi công cụ có thể tự đọc tệp này. Bố cục chuẩn cho nhóm dùng nhiều công cụ trong năm 2026: ``` repo-root/ ├── AGENTS.md # nguồn chân lý, ≤150 dòng ├── CLAUDE.md # chỉ khi có quy tắc riêng cho Claude: symlink → AGENTS.md HOẶC @AGENTS.md + nội dung bổ sung ├── .cursor/rules/ # các phần ghi đè riêng cho Cursor ├── .github/copilot-instructions.md # “Xem AGENTS.md”, nếu sử dụng └── docs/architecture.md # kiến trúc chuyên sâu được AGENTS.md tham chiếu ``` Có thêm thông tin về CLAUDE.md trong hướng dẫn [“Cách cấu hình CLAUDE.md đúng cách”](https://ailoot.ai/blog/vi/claude-md-template/). Để hiểu thêm về lý do agent cần một tệp hướng dẫn lớn, hãy đọc [“Context Engineering là gì”](https://ailoot.ai/blog/vi/context-engineering/). ## Năm 2026 có gì thay đổi: Vì sao AAIF đưa AGENTS.md vào Linux Foundation?
Điểm chính Ngày 9 tháng 12 năm 2025, Linux Foundation thành lập Agentic AI Foundation (AAIF) với ba dự án sáng lập: AGENTS.md của OpenAI, MCP của Anthropic và goose của Block. Các thành viên sáng lập gồm AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft và OpenAI. Đến ngày 24 tháng 2 năm 2026, foundation có 146 tổ chức. Điều này có nghĩa là AGENTS.md không còn là “một thứ của OpenAI” mà đã trở thành tiêu chuẩn ngành cùng với MCP. Trên thực tế, nếu bạn xây dựng sản phẩm cần hoạt động với agent từ nhiều nhà cung cấp khác nhau, có AGENTS.md ở thư mục gốc là điều cơ bản. Nếu không có, bạn sẽ duy trì ba hoặc bốn tệp song song và chúng sẽ lệch nhau trong vòng một tháng.
Câu chuyện chính trị lớn nhất của tháng 5 năm 2026 trong lĩnh vực lập trình AI không phải là một mô hình mới được phát hành, mà là sự hợp nhất các định dạng. Trước đó, mỗi nhà cung cấp có tệp quy tắc riêng; điều này tiện cho nhà cung cấp nhưng gây bất tiện cho các nhóm làm việc với nhiều công cụ. Trong [thông cáo báo chí ngày 9 tháng 12 năm 2025](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation), Linux Foundation công bố Agentic AI Foundation như một mái nhà chung cho ba định dạng: - **AGENTS.md** của OpenAI — định dạng tệp hướng dẫn cho agent - **Model Context Protocol (MCP)** của Anthropic — giao thức kết nối công cụ bên ngoài với agent - **goose** của Block — framework agent mã nguồn mở Trích thông cáo báo chí của Linux Foundation: > “Đưa các dự án này về cùng một mái nhà AAIF đảm bảo chúng có thể phát triển với sự minh bạch và ổn định mà chỉ quản trị mở mới mang lại.” > > ([Thông cáo báo chí Linux Foundation, ngày 9 tháng 12 năm 2025](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation), bản dịch từ tiếng Anh) Đến ngày 24 tháng 2 năm 2026, [146 tổ chức là thành viên AAIF](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members) (97 thành viên mới trong hai tháng). Các thành viên Gold mới gồm Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express và Autodesk. Anthropic ở cấp Platinum, thúc đẩy MCP. OpenAI ở cấp Platinum, thúc đẩy AGENTS.md. Block ở cấp Platinum với goose. Điều này làm thay đổi vị thế của AGENTS.md: từ “định dạng của OpenAI” thành tiêu chuẩn ngành. Vào mùa xuân năm 2026, Claude Code vẫn đứng ngoài, nhưng đến tháng 9, với phiên bản 2.1.277, công cụ này đã tự đọc được AGENTS.md. CLAUDE.md vẫn còn, và theo mặc định vẫn được ưu tiên nếu có trong dự án. Điểm xuất phát thực tế là quy tắc dự án chung trong AGENTS.md cùng cơ chế import, wrapper hoặc cấu hình read mà từng ứng dụng cần. Với Claude Code, kiểm tra phiên bản đang cài và thứ tự ưu tiên tệp trước khi quyết định cần import trong CLAUDE.md hay liên kết tượng trưng. Xác minh việc nạp ở mọi ứng dụng; bài này chưa xác lập phần trăm bao phủ nào. ## Tiếp theo AGENTS.md là khối nền tảng đầu tiên trong “cách thống nhất với agent để công cụ hoạt động ổn định.” Tiếp theo là khối thứ hai—thư mục kiến thức của dự án, chứa ngữ cảnh kinh doanh, đối tượng khách hàng, sản phẩm và giá cả. Khối thứ ba là [kỹ thuật ngữ cảnh](https://ailoot.ai/blog/vi/context-engineering/), kết nối tất cả: agent nhìn thấy những tệp nào ở từng bước, trạng thái được duy trì giữa các phiên ra sao và cách chuyển đổi giữa các mô hình khác nhau. Tài liệu thực tiễn: [tài liệu Ailoot](https://ailoot.ai/docs/).
### Nguồn tham khảo - [agents.md — trang chính thức của tiêu chuẩn](https://agents.md) - [Linux Foundation: thành lập Agentic AI Foundation (ngày 9 tháng 12 năm 2025)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) - [AAIF chào đón 97 thành viên mới (ngày 24 tháng 2 năm 2026)](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members) - [OpenAI đồng sáng lập Agentic AI Foundation](https://openai.com/index/agentic-ai-foundation/) - [GitHub Changelog: Copilot coding agent hỗ trợ AGENTS.md (ngày 28 tháng 8 năm 2025)](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) - [GitHub Blog: bài học từ hơn 2500 kho AGENTS.md](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) - [Tài liệu Claude Code: cách Claude đọc AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) - [Tài liệu hướng dẫn JetBrains Junie](https://junie.jetbrains.com/docs/guidelines-and-memory.html) - [Cursor Rules Docs](https://cursor.com/docs/rules)
Tài liệu và công cụ khác: [Ailoot](https://ailoot.ai/). ## Câu hỏi thường gặp ### Nếu AGENTS.md và CLAUDE.md đều đã tồn tại thì sao? Sao lưu, so cả hai trước khi đổi. Gộp quy tắc chung vào AGENTS.md, giữ phần riêng Claude trong CLAUDE.md và thêm import @AGENTS.md; không rename đè tệp này lên tệp kia. ### Làm hướng dẫn có thể xác minh thế nào? Viết đúng lệnh thiết lập và kiểm thử, kết quả mong đợi, điều tác nhân không được đổi. Chuyển kiến trúc chi tiết sang docs được liên kết để tệp chính dễ đọc. ## Ailoot · Công ty và danh mục dự án của công ty Ailoot dựa trên kinh nghiệm vận hành tích lũy, cơ sở khách hàng lớn, dịch vụ ổn định và việc kiểm soát KPI liên tục. Công ty và danh mục dự án của công ty: hàng triệu khách hàng; doanh số hàng tỷ mỗi tháng. Ailoot áp dụng kinh nghiệm vận hành này để cung cấp quyền truy cập API vào các tính năng AI trong sản phẩm của khách hàng, tác tử, ứng dụng và quy trình tự động hóa.