# Một tệp hướng dẫn cho Claude Code, Codex và Cursor trong năm 2026
> Một nguồn thông tin chuẩn duy nhất cho Claude Code, Codex và Cursor trong năm 2026: khi nào Claude Code tự đọc AGENTS.md, cách nhập @AGENTS.md vào CLAUDE.md, liên kết tượng trưng và /init.
Source: https://ailoot.ai/blog/vi/agents-md-claude-md-one-instruction-file/
Canonical: https://ailoot.ai/blog/vi/agents-md-claude-md-one-instruction-file/
Language: vi
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-004
Revision: sha256-456ae4aad7ff2272a24bcdbfa264500a75ab3db0d071332e07c2ff9774efbdb6
Để biết thông tin về dịch vụ, xem [tài liệu Ailoot](https://ailoot.ai/docs/).
## Điều gì thay đổi khi bạn dùng Claude Code, Codex và Cursor cùng nhau?
Điểm chính
Năm 2026, bộ công cụ điển hình của một vibe coder không chỉ có một công cụ mà có 3–5 công cụ. Claude Code là công cụ chính, Codex dành cho các tác vụ tự động dài hạn, còn Cursor dùng để chỉnh sửa nhanh trong IDE. Mỗi công cụ có tệp hướng dẫn riêng: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. Nếu bạn tự đồng bộ chúng, bạn sẽ phải sửa một dòng ở năm nơi, quên cập nhật Cursor, rồi một tuần sau Claude và Codex đưa ra kết quả khác nhau cho cùng một prompt.
Trong ví dụ được mô tả, Claude Code là công cụ chính, còn Codex và Cursor được dùng cho các tác vụ cụ thể. `CLAUDE.md` của tôi có khoảng 250 dòng hướng dẫn: cần đọc gì và theo thứ tự nào, không được đụng đến những gì, dùng lệnh nào để triển khai, và quy tắc định dạng commit. Khi lần đầu dùng Codex CLI trong dự án, nó không biết quy tắc nào cả: nó chạy `git push --force`, lục lọi `.env` và đổi tên tệp một cách tùy tiện.
Đầu tiên, tôi tự sao chép `CLAUDE.md` thành `AGENTS.md`. Hai tuần sau, tôi phát hiện dự án đã có bốn phiên bản của cùng một bộ hướng dẫn: trong `CLAUDE.md`, `AGENTS.md`, `.cursorrules` và `.windsurf/rules/`. Chúng chỉ khác nhau đôi chút. Đây không phải vấn đề riêng của Claude hay Cursor; đó là cái bẫy cơ bản của mọi hệ thống có nhiều nguồn thông tin chuẩn. Tôi bàn về vấn đề này chi tiết hơn trong [hướng dẫn làm việc với nhiều agent](https://ailoot.ai/blog/vi/claude-code-codex-together/).
Tháng 6 năm 2026, tài liệu về bộ nhớ Claude Code của Anthropic đưa ra một giải pháp: một tệp dùng chung cộng với thao tác nhập. Từ tháng 9 năm 2026, Claude Code tự đọc `AGENTS.md` nếu dự án không có `CLAUDE.md`; cần nhập tệp khi bạn có các quy tắc dành riêng cho Claude. Dưới đây, tôi giải thích khi nào chỉ cần một `AGENTS.md`, cách thiết lập thao tác nhập và cách tách các quy tắc dùng chung khỏi quy tắc dành riêng cho Claude.
## Claude Code có tự đọc AGENTS.md không?
Điểm chính
Có, bắt đầu từ phiên bản 2.1.277, phát hành ngày 18 tháng 9 năm 2026, nhưng chỉ khi không có `CLAUDE.md`, `.claude/CLAUDE.md` hoặc `CLAUDE.local.md` trong thư mục làm việc hay các thư mục cấp trên. Nếu có `CLAUDE.md`, Claude Code mặc định chỉ đọc tệp đó; `AGENTS.md` được đưa vào bằng dòng `@AGENTS.md` trong `CLAUDE.md` hoặc bằng liên kết tượng trưng. Hành vi này thay đổi trong `/config`, mục Project instructions. Trước tháng 9, Claude Code hoàn toàn không đọc `AGENTS.md`, nên nhập tệp là cách duy nhất.
Trước tháng 9 năm 2026, câu trả lời là “không”. Issue \#6235, yêu cầu hỗ trợ AGENTS.md, đã được mở từ tháng 8 năm 2025 và đóng vào ngày 17 tháng 8 năm 2026. Suốt thời gian đó, tài liệu về bộ nhớ chỉ ra một giải pháp: tạo CLAUDE.md rồi nhập `AGENTS.md` vào đó. Bắt đầu từ phiên bản 2.1.277, tài liệu nói khác đi:
Claude Code có thể đọc AGENTS.md làm hướng dẫn của dự án, vì vậy một kho lưu trữ đã được thiết lập cho các agent khác sẽ hoạt động mà không cần CLAUDE.md, thao tác nhập hay cấu hình.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
Claude Code đọc chính xác những gì tùy thuộc vào các tệp có trong dự án:
| Tệp trong dự án | Claude Code đọc gì |
|----|----|
| `AGENTS.md`, không có `CLAUDE.md` hoặc `CLAUDE.local.md` trong thư mục làm việc hay các thư mục cấp trên | `AGENTS.md` |
| `AGENTS.md` và `CLAUDE.md` (hoặc `CLAUDE.local.md`) trong thư mục làm việc hay các thư mục cấp trên | Chỉ `CLAUDE.md` |
| `CLAUDE.md` có dòng `@AGENTS.md` | `CLAUDE.md` và nội dung `AGENTS.md` được nhập vào bên trong |
Đối với bước kiểm tra này, `CLAUDE.md`, `.claude/CLAUDE.md` và `CLAUDE.local.md` trong thư mục làm việc và mọi thư mục cấp trên đều được tính. Tệp `~/.claude/CLAUDE.md` cá nhân, tệp do doanh nghiệp quản lý và các quy tắc trong `.claude/rules/` không được tính: chúng được tải cùng với `AGENTS.md`.
Khi không có `CLAUDE.md`, Claude Code đọc tất cả các tệp `AGENTS.md` và `.claude/AGENTS.md` trong thư mục làm việc và các thư mục cấp trên khi khởi động, đồng thời đọc `AGENTS.md` trong thư mục con khi mở tệp ở thư mục đó. Các thao tác nhập `@path` bên trong `AGENTS.md` cũng hoạt động. Claude Code không đọc `AGENTS.local.md`, `AGENTS.override.md` hay nội dung của thư mục `.agents/`.
Điểm cần lưu ý: `CLAUDE.local.md` cá nhân cũng được tính. Tạo tệp này để giữ các quy tắc chưa commit, và Claude Code sẽ âm thầm ngừng đọc `AGENTS.md`. Cài đặt bên dưới là giải pháp.
Hành vi này thay đổi trong `/config`, mục Project instructions:
| Cài đặt | Claude Code đọc gì |
|----|----|
| `claude-md-or-agents-md` (mặc định) | `CLAUDE.md`, hoặc nếu không có cả `CLAUDE.md` lẫn `CLAUDE.local.md` thì đọc `AGENTS.md` |
| `claude-md-and-agents-md` | Cả hai tệp: trong mỗi thư mục, đọc `CLAUDE.md` trước rồi đến `AGENTS.md` |
| `claude-md` | Chỉ `CLAUDE.md` |
| `managed-only` | Chỉ `CLAUDE.md` do doanh nghiệp quản lý và bộ nhớ tự động |
Nếu muốn giữ `CLAUDE.local.md` mà vẫn đọc `AGENTS.md`, hãy đặt `claude-md-and-agents-md`. Tệp sẽ không bị đọc lặp: nếu `AGENTS.md` đã được đưa vào qua dòng `@AGENTS.md` hoặc liên kết tượng trưng, Claude Code sẽ không tải nó lần thứ hai, bất kể cài đặt nào được chọn.
Bạn có thể kiểm tra xem tệp đã được nhận diện chưa bằng lệnh `/memory`: từ phiên bản 2.1.280, đường dẫn đến `AGENTS.md` sẽ xuất hiện trong danh sách. Ở các phiên bản trước 2.1.277 và trong các phiên có plugin tích hợp `agents-md` bị tắt, Claude Code chỉ đọc `CLAUDE.md`, đồng thời không có mục Project instructions trong `/config`. Trước phiên bản 2.1.281, các phiên qua Amazon Bedrock và các phiên tắt telemetry cũng hoạt động tương tự. Trong phiên đầu tiên sau khi cập nhật từ phiên bản cũ, `AGENTS.md` có thể vẫn chưa được nhận diện; tệp sẽ hoạt động từ phiên tiếp theo.
Điều này có ý nghĩa gì với cấu hình chỉ có một tệp? Nếu bạn không có quy tắc dành riêng cho Claude, có thể bỏ qua `CLAUDE.md`: chỉ cần `AGENTS.md`, và Claude Code, Codex cùng Cursor sẽ đọc tệp đó. Nếu có quy tắc dành riêng cho Claude (plan mode cho thư mục rủi ro, skills, hooks), bạn cần `CLAUDE.md`, và Claude Code sẽ ngừng tự đọc `AGENTS.md`. Khi đó, hãy đưa `AGENTS.md` vào `CLAUDE.md` bằng dòng `@AGENTS.md`; cách thiết lập này vẫn hoạt động như trước tháng 9. Nó cũng hữu ích với các phiên bản Claude Code cũ hơn. Tôi sẽ giải thích chi tiết bên dưới.
## Làm thế nào để nhập @AGENTS.md bên trong CLAUDE.md?
Điểm chính
Cần thao tác nhập khi dự án có `CLAUDE.md`: khi tệp này tồn tại, Claude Code mặc định không tự đọc `AGENTS.md`. Để thiết lập, hãy viết dòng `@AGENTS.md` ở đầu tệp `CLAUDE.md`. Khi Claude Code bắt đầu phiên, nó chèn nội dung của `AGENTS.md` vào vị trí dòng đó rồi đọc kết quả như một văn bản duy nhất. Bên dưới dòng nhập, bạn có thể thêm mục “Claude Code” với các quy tắc chỉ áp dụng cho Claude. Thao tác nhập hoạt động với đường dẫn tương đối và tuyệt đối, và có thể lồng nhau tối đa bốn cấp.
Ví dụ tối thiểu hoạt động được từ tài liệu chính thức:
```markdown
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
```
Cách hoạt động như sau. Dòng đầu tiên, `@AGENTS.md`, là chỉ thị nhập tệp. Khi Claude Code phân tích `CLAUDE.md` lúc bắt đầu phiên, nó tìm thấy chỉ thị này và chèn toàn bộ nội dung của `AGENTS.md` vào vị trí đó. Tiếp theo là tiêu đề `## Claude Code`: đây chỉ là Markdown, nhưng đóng vai trò như mục “bổ sung dành riêng cho Claude”. Bên dưới là quy tắc chỉ áp dụng cho Claude Code: dùng plan mode để thay đổi trong thư mục billing. Codex CLI hoặc Cursor hoàn toàn không mở tệp này; chúng sử dụng `AGENTS.md` nguyên bản.
Trích dẫn tài liệu về cách thao tác nhập hoạt động:
Tệp CLAUDE.md có thể nhập các tệp bổ sung bằng cú pháp @path/to/import. Các tệp được nhập sẽ được mở rộng nội dung và tải vào ngữ cảnh khi bắt đầu phiên, cùng với tệp CLAUDE.md tham chiếu đến chúng.
— Anthropic, https://code.claude.com/docs/en/memory
Một số chi tiết thực tế:
- **Đường dẫn tương đối và tuyệt đối.** `@AGENTS.md` là đường dẫn tương đối với tệp chứa chỉ thị nhập. `@/Users/me/shared/rules.md` hoặc `@~/.claude/personal.md` là đường dẫn tuyệt đối. Tôi dùng `@~/.claude/personal.md` để lưu các tùy chọn cá nhân mà tôi không muốn đưa vào kho lưu trữ.
- **Độ sâu bốn cấp.** `AGENTS.md` có thể nhập `@docs/coding-style.md`, rồi `coding-style.md` có thể nhập một tệp khác, tối đa bốn cấp. Mức này đủ cho mọi cấu trúc thực tế.
- **Dấu backtick ngăn việc nhập.** Nếu văn bản ghi `` `@README` ``, đó chỉ là nhắc đến tên, không phải thao tác nhập. Cách này hữu ích khi giải thích cho độc giả cách nhập mà không kích hoạt thao tác đó.
- **Cần phê duyệt đối với tệp ngoài dự án.** Nếu đường dẫn nhập nằm ngoài thư mục làm việc, như `@~/.claude/personal.md`, Claude Code sẽ hiển thị hộp thoại liệt kê các tệp đó lần đầu tiên. Nếu bạn từ chối, thao tác nhập tệp bên ngoài vẫn bị tắt và hộp thoại sẽ không xuất hiện lại. `@AGENTS.md` ở thư mục gốc dự án không làm hiện hộp thoại. Cơ chế này giúp tránh vô tình tải một tệp không liên quan vào ngữ cảnh.
Sau khi chuyển sang cách thiết lập này trong dự án đã mô tả, `CLAUDE.md` của tôi giảm từ 250 dòng xuống còn 60: `@AGENTS.md` cộng thêm năm đến bảy quy tắc chỉ áp dụng cho Claude Code (plan mode cho thư mục rủi ro, những gì không được đụng đến trong khu vực quản trị và cách viết commit). Mọi nội dung dùng chung nằm trong `AGENTS.md`, tệp mà Codex và Cursor đọc.
## Khi nào nên chọn symlink và khi nào nên dùng thao tác nhập?
Điểm chính
Anthropic cung cấp hai cơ chế: nhập qua `@AGENTS.md` hoặc tạo liên kết tượng trưng bằng `ln -s AGENTS.md CLAUDE.md`. Symlink đơn giản hơn — nó chỉ là bí danh và không cần sửa tệp. Nhưng có ba nhược điểm: Windows yêu cầu quyền quản trị, bạn không thể thêm quy tắc chỉ dành cho Claude vào `CLAUDE.md`, và đôi khi Git hiển thị symlink như một thứ rác trong diff. Thao tác nhập là cách dùng được rộng rãi. Nếu không có quy tắc dành riêng cho Claude, từ phiên bản 2.1.277 bạn không cần cách nào trong hai cách: Claude Code sẽ tự đọc `AGENTS.md`.
Tài liệu minh họa tùy chọn symlink như sau:
```bash
ln -s AGENTS.md CLAUDE.md
```
Và ngay sau đó đưa ra cảnh báo thẳng thắn về Windows:
Nếu bạn hoặc bất kỳ ai clone kho lưu trữ làm việc trên Windows, hãy dùng thao tác nhập `@AGENTS.md`. Tạo liên kết tượng trưng trên Windows cần quyền quản trị hoặc Developer Mode; nếu Git không bật `core.symlinks`, liên kết đã commit sẽ được checkout thành một tệp văn bản thông thường, để lại một dòng `CLAUDE.md` thay vì các hướng dẫn trong bản sao đó.
— Anthropic, https://code.claude.com/docs/en/memory
Bảng so sánh:
| Tiêu chí | Nhập `@AGENTS.md` | Symlink `ln -s` |
|----|----|----|
| **Hoạt động trên Windows mà không cần quyền quản trị** | Có | Không (cần Developer Mode) |
| **Có thể thêm quy tắc chỉ dành cho Claude** | Có, bên dưới dòng nhập | Không, tệp giống hệt |
| **Hiển thị trong Git như Markdown thông thường** | Có | Dưới dạng liên kết (tùy vào `core.symlinks`) |
| **Có thể nhập nhiều tệp** | Có, tối đa bốn cấp | Không, quan hệ một-một |
| **Bộ nhớ đệm/vô hiệu hóa bộ nhớ đệm trong Claude Code** | Theo chuẩn dành cho CLAUDE.md | Hoạt động, nhưng symlink có những vấn đề khó nhận ra về metadata |
| **Lựa chọn mặc định** | Phù hợp với mọi người | Chỉ khi không cần dùng đa nền tảng |
Tôi dùng thao tác nhập trong dự án đã mô tả vì những lý do sau:
1. **Nhóm dùng nhiều nền tảng.** Tôi dùng Mac; trong ví dụ này, nhóm có số người dùng Windows và Mac gần như ngang nhau. Nếu có symlink trong kho lưu trữ, người dùng Windows không có Developer Mode sẽ checkout nó thành tệp văn bản thông thường chỉ chứa một dòng `AGENTS.md`. Điều này gây ra các lỗi kỳ lạ: lúc thì quy tắc hoạt động, lúc thì không, và chẳng rõ vì sao.
2. **Tôi muốn có quy tắc chỉ dành cho Claude.** Bên dưới `@AGENTS.md`, `CLAUDE.md` của tôi có mục “Claude Code” với các quy tắc: dùng `--effort high` cho tác vụ kiến trúc, chạy `npm run build` trước `git push`, và không gọi thủ công `/api/v1/deploy`. Codex không hiểu các lệnh này.
3. **Dễ gỡ lỗi hơn.** Khi có trục trặc, tôi mở `CLAUDE.md` và thấy dòng nhập cùng các phần ghi đè của mình. Symlink không có dấu hiệu “phần này được thêm ở đây”. Để biết thêm về gỡ lỗi cài đặt Claude Code, xem [hướng dẫn safe mode](https://ailoot.ai/blog/vi/claude-code-safe-mode-recovery/).
Nếu không có quy tắc dành riêng cho Claude, từ phiên bản 2.1.277 bạn không còn cần symlink: xóa `CLAUDE.md`, Claude Code sẽ tự đọc `AGENTS.md`. Chỉ giữ symlink nếu có người trong nhóm dùng phiên bản cũ hơn 2.1.277 và không thể cập nhật. Nếu có quy tắc riêng cho Claude, thao tác nhập thuận tiện hơn trong chín trên mười trường hợp.
## Codex, Cursor, Copilot, Windsurf và Gemini CLI đọc những tệp nào?
Điểm chính
Mỗi công cụ đọc tệp riêng, đôi khi đọc nhiều tệp. Claude Code đọc `CLAUDE.md`, và từ tháng 9 năm 2026 cũng đọc `AGENTS.md` nếu dự án không có `CLAUDE.md`. Codex CLI đọc `AGENTS.md` cùng với `AGENTS.override.md`. Cursor đọc định dạng cũ `.cursorrules` hoặc định dạng mới `.cursor/rules/*.mdc`, và từ mùa hè năm 2026 cũng đọc `AGENTS.md`. Copilot đọc `.github/copilot-instructions.md` hoặc `.github/instructions/*.instructions.md`. Windsurf đọc `.windsurfrules` kiểu cũ hoặc `.windsurf/rules/` kiểu mới. Gemini CLI đọc `GEMINI.md`. Aider và Cline đã hỗ trợ `AGENTS.md`.
Bản đồ bảy công cụ chính (dựa trên tài liệu chính thức của từng công cụ):
| Công cụ | Tệp hướng dẫn chính | Tùy chọn khác | Có đọc AGENTS.md không? |
|----|----|----|----|
| **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, chính sách do hệ thống quản lý | Có, nếu dự án không có `CLAUDE.md` (từ 2.1.277); nếu có thì thông qua thao tác nhập |
| **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | Có (tích hợp sẵn) |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (đã ngừng dùng) | Có |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | Thông qua tiện ích mở rộng |
| **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (đã ngừng dùng) | Có |
| **Gemini CLI** | `GEMINI.md` | \- | Không |
| **Aider, Cline, opencode** | `AGENTS.md` | \- | Có (tích hợp sẵn) |
Điều này dẫn đến kết luận gì? Nếu kho lưu trữ có `AGENTS.md` (cộng thêm `CLAUDE.md` có thao tác nhập khi cần các quy tắc dành riêng cho Claude), năm trong bảy công cụ sẽ tự động nhận hướng dẫn mới nhất. Với Cursor và Windsurf, vốn có tệp riêng, bạn có thể giữ nguyên như hiện tại (`AGENTS.md` cũng được chúng đọc) hoặc thêm thao tác nhập `@AGENTS.md` — nhưng cú pháp của chúng khác nhau và không phải lúc nào cũng được hỗ trợ.
Chiến lược đơn giản nhất cho một dự án mới:
1. **Đưa mọi quy tắc dùng chung vào `AGENTS.md`** — 95% quy tắc nên nằm ở đó.
2. **Tạo `CLAUDE.md` nếu cần quy tắc chỉ dành cho Claude:** đặt `@AGENTS.md` ở dòng đầu tiên, rồi thêm mục chứa các quy tắc riêng cho Claude. Nếu không có quy tắc như vậy thì không cần `CLAUDE.md`; Claude Code tự đọc `AGENTS.md` từ phiên bản 2.1.277.
3. **Giữ `.cursor/rules/` cho Cursor** trong những trường hợp hiếm hoi cần nội dung riêng của Cursor (các lệnh `@Codebase` và `@Docs`).
4. **Làm tương tự với Windsurf:** bỏ `.windsurfrules` cũ; chỉ dùng `.windsurf/rules/` mới khi cần các mẫu phù hợp với cú pháp của nó.
Cách tiếp cận này đem lại 80% lợi ích với 20% công sức. Theo kinh nghiệm của tôi, khi sắp xếp các nhóm dùng nhiều công cụ trong “Antigravity”, việc duy trì hơn hai nguồn thông tin chuẩn (quy tắc dùng chung và quy tắc chỉ dành cho Claude) trở nên vất vả. Nếu ai đó trong nhóm thêm quy tắc vào `.cursorrules` mà quên `AGENTS.md`, một tuần sau Cursor và Codex sẽ bất đồng.
## /init trong Claude Code nhận AGENTS.md hiện có như thế nào?
Điểm chính
`/init` tạo `CLAUDE.md` từ những gì đã có trong kho lưu trữ và tiết kiệm 20–30 phút làm thủ công. Theo mặc định, lệnh này nhận các quy tắc của Cursor (`.cursor/rules/`, `.cursorrules`) và Copilot (`.github/copilot-instructions.md`), còn `AGENTS.md`, `.windsurfrules` và `.clinerules` được đọc trong chế độ `CLAUDE_CODE_NEW_INIT=1`. Chế độ này cũng khởi chạy quy trình tương tác nhiều giai đoạn: đặt câu hỏi, khám phá mã qua một subagent và đề xuất kế hoạch trước khi viết. Từ tháng 9 năm 2026, `/init` có một nhược điểm trong dự án có `AGENTS.md`: `CLAUDE.md` mới sẽ tắt việc tự đọc `AGENTS.md`, khiến các quy tắc nằm trong hai tệp.
Anthropic mô tả `/init` trong tài liệu như sau:
Chạy /init sẽ đọc các tệp hướng dẫn của công cụ khác và chuyển những phần liên quan vào CLAUDE.md được tạo: quy tắc Cursor từ .cursor/rules/ hoặc .cursorrules, quy tắc Copilot từ .github/copilot-instructions.md, và khi dùng CLAUDE_CODE_NEW_INIT=1, cả AGENTS.md, .devin/rules/, .windsurf/rules/ hoặc .windsurfrules, cùng với .clinerules.
— Anthropic, https://code.claude.com/docs/en/memory
Điều này có ý nghĩa gì trong thực tế? Kho lưu trữ mà tôi mô tả có `.cursorrules` từ lần tôi thử Cursor (khoảng 80 dòng) và `AGENTS.md` (120 dòng, được tôi tự tổng hợp). Khi chạy `claude /init`, lệnh đọc cả hai tệp, loại bỏ các quy tắc tương tự và tạo một `CLAUDE.md` gọn gàng trong một phút. Sau đó tôi kiểm tra và chỉnh sửa nhẹ: xóa những mục lỗi thời và thêm cấu trúc tiêu đề. Cách này nhanh hơn viết lại từ đầu.
Chế độ tương tác, trong đó `/init` cũng đọc `AGENTS.md`, được bật bằng một biến môi trường:
```bash
CLAUDE_CODE_NEW_INIT=1 claude
```
Sau khi `/init` khởi chạy, Claude đặt một loạt câu hỏi làm rõ: cần cấu hình những thành phần nào (`CLAUDE.md`, skills, hooks), dự án dùng stack nào và nên dùng lệnh nào để kiểm thử. Tiếp đó, một subagent khám phá codebase — đọc `package.json`, `README.md` và các tệp cấu hình — rồi bổ sung những phần còn thiếu. Cuối cùng, nó đưa ra đề xuất để bạn chỉnh sửa trước khi lưu. Để tìm hiểu thêm về cách cấu hình Claude Code khi bắt đầu dự án, xem [hướng dẫn riêng](https://ailoot.ai/blog/vi/spec-kit-claude-code-spec-driven-development/).
Giờ đến nhược điểm. Nếu dự án đã có `AGENTS.md` đang hoạt động, `/init` sẽ tạo thêm `CLAUDE.md` chứa bản sao các quy tắc của nó. Kể từ đó, Claude Code mặc định chỉ đọc `CLAUDE.md`, nên lại có hai nguồn thông tin chuẩn: bạn cập nhật `AGENTS.md`, còn Claude tiếp tục dùng bản sao cũ. Lệnh `/import` cũng làm điều tương tự: nó thêm một bản sao `AGENTS.md` vào `CLAUDE.md` chỉ một lần. Để duy trì một nguồn duy nhất, hãy đặt thao tác nhập `@AGENTS.md` ở dòng đầu tiên của `CLAUDE.md` sau khi chạy `/init`, rồi xóa nội dung trong `CLAUDE.md` trùng với `AGENTS.md`.
`/init` là điểm bắt đầu phù hợp cho dự án mới hoặc dự án bạn chuyển từ Cursor hay Copilot. Không cần tìm trực tuyến “mẫu CLAUDE.md tốt nhất” — Anthropic đã xét đến nội dung trong kho lưu trữ. Nếu dự án đã có `AGENTS.md` đang hoạt động và không có quy tắc riêng cho Claude, không cần dùng `/init`: Claude Code sẽ tự đọc `AGENTS.md`.
## Làm thế nào để tách hướng dẫn dùng chung khỏi hướng dẫn riêng cho Claude?
Điểm chính
Đặt trong `AGENTS.md` các quy tắc mà mọi AI agent đều hiểu được: không được đụng đến gì, cách đặt tên branch, thông tin `.env` chứa bí mật và lệnh cần dùng để kiểm thử. Đặt trong `CLAUDE.md` (bên dưới dòng nhập) các quy tắc dành riêng cho Claude Code: plan mode, skills, hooks, tham chiếu skill và tên model theo phiên bản. Phân biệt rất đơn giản: nếu quy tắc bắt đầu bằng “Claude nên”, nó thuộc về `CLAUDE.md`. Nếu bắt đầu bằng “công cụ nên”, nó thuộc về `AGENTS.md`.
Tôi phân chia theo nguyên tắc này. Các quy tắc dùng chung nên đưa vào `AGENTS.md`:
- **Những gì không được đụng đến trong mã.** Các thư mục `.env`, `node_modules`, `prisma/migrations` (chỉ thao tác qua `prisma migrate`), `.next/`, `.git/`.
- **Cách đặt tên.** Branch: `feat/`, `fix/`, `chore/`. Commit: các tiền tố `feat:`, `fix:`, `docs:` cộng với phần mô tả ngắn. Tệp component dùng `kebab-case`.
- **Lệnh test/lint.** `npm run build`, `npm run lint`, `npm test`. Lệnh nào cần chạy trước `git push`.
- **Nguyên tắc kiến trúc.** Nội dung nào thuộc `src/lib/`, nội dung nào thuộc `src/components/`, logic nghiệp vụ nằm ở đâu và giao diện người dùng nằm ở đâu.
- **Bảo mật.** Không bao giờ commit bí mật. Chỉ truy cập cơ sở dữ liệu production qua `prod-psql`. Chỉ truy cập production qua SSH bằng alias `prod`, không dùng `root@IP`.
Các quy tắc dành riêng cho Claude nên đưa vào `CLAUDE.md` (bên dưới `@AGENTS.md`):
- **Plan mode.** Dùng `plan mode` khi thay đổi các thư mục rủi ro (ví dụ `src/billing/`).
- **Mức độ nỗ lực.** Dùng `--effort high` cho tác vụ kiến trúc và `medium` cho công việc thường lệ.
- **Skills.** Nên chạy AI agent và skill nào trong từng tình huống. Ví dụ: “khi làm việc với một hướng dẫn, hãy chạy skill `build-masterskaya-guide`.”
- **Bộ nhớ Claude.** Nên đưa nội dung gì vào bộ nhớ tự động và nội dung gì vào `CLAUDE.local.md`. Để biết thêm về bộ nhớ Claude, xem [hướng dẫn về Memory và CLAUDE.md](https://ailoot.ai/blog/vi/claude-memory-claude-md-auto-memory/).
- **Hooks.** Nếu `.claude/settings.json` cấu hình hooks, hãy mô tả trong `CLAUDE.md` chúng làm gì (Codex và Cursor không biết về chúng và cũng không cần biết).
- **Skills và lệnh.** Danh sách slash command tôi thường dùng (`/init`, `/cd`, `/memory`, `/plan`).
Ranh giới này không phải lúc nào cũng rõ ràng. Ví dụ, “không bao giờ chạy `git push --force` lên `main`” rõ ràng là quy tắc chung nên thuộc `AGENTS.md`. Nhưng “khi chạy `git push` lên một branch nóng, hãy dùng plan mode trước” là quy tắc riêng cho Claude Code nên thuộc `CLAUDE.md`. Hãy tự hỏi: “Nếu ngày mai tôi gỡ Claude Code và chỉ giữ Codex, quy tắc này còn áp dụng không?” Nếu có, hãy đặt nó trong `AGENTS.md`. Nếu không, hãy đặt trong `CLAUDE.md`.
## Nội dung nào thuộc AGENTS.md, và nội dung nào thuộc CLAUDE.md hoặc .claude/rules?
Điểm chính
Với dự án lớn, chỉ một `AGENTS.md` là không đủ: tệp sẽ phình to, khiến mọi agent đưa những nội dung không cần thiết vào ngữ cảnh. Giải pháp là tạo thư mục `.claude/rules/`, chia các tệp theo chủ đề và thêm YAML frontmatter `paths:` để kích hoạt theo đường dẫn. Ví dụ, quy tắc API chỉ áp dụng khi Claude làm việc trong `src/api/`. Cách này tiết kiệm đáng kể dung lượng context window. Cursor và Windsurf có cách tương đương với `.cursor/rules/` và `.windsurf/rules/`.
Nếu các quy tắc vượt quá 200 dòng, đã đến lúc tách chúng ra. Tài liệu Anthropic khuyến nghị mục tiêu 200 dòng mỗi tệp, vì các tệp `CLAUDE.md` dài khiến Claude âm thầm tuân thủ kém hơn: có vẻ như Claude đọc chúng nhưng lại làm theo ít thường xuyên hơn.
Một cấu trúc cho dự án lớn phù hợp với tôi:
```
my-project/
├── AGENTS.md # 100-150 lines, shared
├── CLAUDE.md # 30-50 lines: @AGENTS.md + Claude-only
└── .claude/
├── CLAUDE.md # alternative to root file, same file
└── rules/
├── api.md # with paths: ['src/api/**']
├── components.md # with paths: ['src/components/**']
├── testing.md # without paths, always active
└── security.md # without paths, always active
```
Mỗi tệp trong `.claude/rules/` có thể có frontmatter:
```markdown
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required
```
Claude chỉ tải các quy tắc này khi làm việc với tệp khớp mẫu. Nếu nó sửa `src/components/Button.tsx`, các quy tắc API sẽ không được thêm vào ngữ cảnh. Nhờ vậy, context window chỉ dành cho nội dung liên quan. Thư mục `.claude/rules/` cũng hoạt động mà không cần `CLAUDE.md`: nếu dự án chỉ có `AGENTS.md`, các quy tắc được tải cùng với tệp đó và không tắt việc tự đọc `AGENTS.md`.
Cursor và Windsurf hỗ trợ cách tiếp cận tương tự thông qua thư mục `.cursor/rules/` và `.windsurf/rules/`. Tiêu chuẩn AGENTS.md có thể tham chiếu đến các thư mục này, nhưng cú pháp giữa các công cụ chưa hoàn toàn ổn định. An toàn hơn là giữ quy tắc dùng chung trong `AGENTS.md` và sao chép các quy tắc giới hạn theo đường dẫn vào `.claude/rules/` và `.cursor/rules/` — đây là những trường hợp riêng hiếm gặp, không phải phần lớn các quy tắc.
Các vị trí hữu ích cho CLAUDE.md (theo thứ tự từ phạm vi rộng nhất đến hẹp nhất):
| Cấp độ | Vị trí | Mục đích |
|----|----|----|
| **Chính sách do hệ thống quản lý** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | Quy tắc doanh nghiệp, IT/DevOps |
| **Người dùng** | `~/.claude/CLAUDE.md` | Tùy chọn cá nhân áp dụng cho mọi dự án |
| **Dự án** | `./CLAUDE.md` hoặc `./.claude/CLAUDE.md` | Quy tắc của nhóm dự án |
| **Cục bộ** | `./CLAUDE.local.md` (trong `.gitignore`) | Tùy chọn cá nhân cho một dự án cụ thể |
Ví dụ, `~/.claude/CLAUDE.md` có thể chứa hai quy tắc: “trả lời bằng ngôn ngữ người dùng muốn” và “viết chính xác Ailoot theo cách này”. Những quy tắc đó áp dụng cho mọi dự án, nên không cần lặp lại trong từng kho lưu trữ.
Trong bốn cấp độ này, chỉ `CLAUDE.md` cấp dự án và `CLAUDE.local.md` mới tắt việc tự đọc `AGENTS.md`. `~/.claude/CLAUDE.md` cá nhân và chính sách do hệ thống quản lý không cản trở; Claude Code đọc chúng cùng với `AGENTS.md`.
## Nếu AGENTS.md trong dự án đã lỗi thời thì nên làm gì?
Điểm chính
Nếu `AGENTS.md` được soạn từ năm 2025 cho Codex hoặc Aider và chưa được chỉnh sửa kể từ đó, hãy mở dự án trong Claude Code và yêu cầu Claude chỉnh sửa tệp. AGENTS.md là tài liệu sống; đặc tả của Linux Foundation cũng được cập nhật. Quy tắc chính để giữ tệp luôn mới là: mỗi quy tắc phải trả lời câu hỏi “Tôi chán phải nhắc Claude/Codex điều gì?” Nếu không, hãy đưa nó vào kho lưu trữ.
Trong dự án tôi mô tả, tôi có `AGENTS.md` từ tháng 5 năm 2025 — 180 dòng, nhiều mục đã lỗi thời (có nhắc đến các endpoint Anthropic API đã thay đổi; ví dụ với cú pháp `claude --tools` không còn tồn tại; và các quy tắc về `~/.claude/projects/` dùng cấu trúc cũ).
Kế hoạch tôi dùng để cập nhật tệp:
1. **Rà soát bằng `claude` trong plan mode.** Tôi mở kho lưu trữ, chạy `claude --safe-mode` và yêu cầu: “Đọc lại `AGENTS.md` và đề xuất danh sách những mục đã lỗi thời hoặc bị lặp. Đừng chỉnh sửa tệp; chỉ liệt kê các mục.” Trong hai phút, tôi nhận được danh sách 23 mục cần xem xét.
2. **Xóa các mục rõ ràng đã lỗi thời.** Trong số 23 mục, có 9 mục chắc chắn đã lỗi thời — cú pháp lệnh, endpoint và tên flag. Tôi xóa các dòng đó.
3. **Gộp nội dung trùng lặp.** Sáu mục khác lặp lại cùng ý bằng cách diễn đạt khác nhau (“đừng force-push”, “không bao giờ dùng `--force`”, “tránh `git push -f`”). Tôi gộp chúng thành một dòng.
4. **Thêm mục mới.** Tôi bổ sung những điều nhận thấy Claude/Codex thường xuyên làm sai trong tháng vừa qua, theo quy tắc “mỗi mẫu lỗi một dòng”. Kết quả là có 8 mục mới.
5. **Dùng subagent rà soát lần cuối.** Tôi yêu cầu Claude rà soát để tìm mâu thuẫn, điểm mơ hồ và nội dung trùng lặp. Nó tìm thấy ba cách diễn đạt có thể làm rõ hơn. Tôi đã sửa chúng.
Sau một giờ, `AGENTS.md` còn 110 dòng, đã được cập nhật và tôi nắm rõ từng dòng. Tạo `CLAUDE.md` 30 dòng từ đó rất dễ. Sau đó Codex cũng thận trọng hơn đáng kể với các bài kiểm thử — tôi nghĩ một số quyết định “lạ” của nó xuất phát từ những quy tắc lỗi thời mà nó vẫn nghiêm túc làm theo.
Các nguyên tắc chính để duy trì một `AGENTS.md` luôn được cập nhật:
- **Mọi quy tắc đều giải quyết một lỗi lặp lại.** Nếu trong cả tháng tôi không nghĩ đến quy tắc đó dù chỉ một lần, thì không có lý do gì để giữ lại.
- **Viết quy tắc dưới dạng mệnh lệnh, không phải lý thuyết.** “Dùng hai dấu cách” là một quy tắc. “Hãy giữ phong cách mã gọn gàng” thì không.
- **Cụ thể tốt hơn chung chung.** “Chạy `npm run build` trước `git push`” là quy tắc. “Kiểm thử các thay đổi” thì không.
## Điều gì chắc chắn KHÔNG hiệu quả với cách thiết lập này?
Điểm chính
Nhập `@AGENTS.md` không khiến các công cụ khác nhau hoạt động như một. Mỗi công cụ có đặc điểm riêng: Codex CLI không biết đến `.claude/rules/` hay hooks. Cursor có công cụ tự động hoàn thành riêng, không đọc CLAUDE.md khi gợi ý hoàn tất văn bản. Copilot tuân theo `.github/copilot-instructions.md`, nên chỉ có quy tắc trong AGENTS.md là chưa đủ. Đây không phải “một tệp = một hành vi”, mà là “một nguồn cho các quy tắc nền tảng, rồi mỗi công cụ có phần bổ sung riêng”.
Một số điều tôi đã rút kinh nghiệm sau sáu tháng làm việc với cách thiết lập này:
**1. Tự động hoàn thành của Cursor không dùng AGENTS.md.** Khi Cursor gợi ý hoàn thành một dòng trong trình soạn thảo, nó không đọc `AGENTS.md` theo thời gian thực — một công cụ tốc độ cao riêng đang hoạt động. Quy tắc trong AGENTS.md chỉ có tác dụng khi bạn gửi yêu cầu trò chuyện bên trong Cursor. Điều đó có nghĩa là viết “đừng dùng `var`, hãy dùng `const`” trong AGENTS.md sẽ không ảnh hưởng đến tính năng tự động hoàn thành; bạn phải cấu hình điều này qua ESLint hoặc cấu hình TypeScript.
**2. Hooks của Claude Code trong AGENTS.md không có tác dụng với Codex.** Nếu `.claude/settings.json` có cấu hình hook PreToolUse để chặn một hành động nào đó, thông tin này chỉ hữu ích cho Claude. Codex không biết hooks là gì; với nó, “công cụ tự quyết định”. Hợp lý nhất là viết “đừng làm X” trong `AGENTS.md`, còn “có một hook chặn X trực tiếp” trong `CLAUDE.md` bên dưới dòng nhập.
**3. Copilot và `.github/copilot-instructions.md`.** GitHub Copilot đọc tệp riêng của nó và vẫn chưa đọc AGENTS.md tốt lắm. Nếu nhóm bạn thường xuyên dùng Copilot, hãy thêm một `.github/copilot-instructions.md` riêng với bản rút gọn của các quy tắc, hoặc dùng [Copilot Extensions](https://github.com/marketplace?type=apps&category=copilot-extensions) có thể nhận diện AGENTS.md. Tình hình thay đổi nhanh, nên bức tranh có thể khác đi sau ba đến sáu tháng.
**4. Git không theo dõi symlink như một thay đổi trong CLAUDE.md.** Nếu bạn chạy `ln -s AGENTS.md CLAUDE.md` rồi cập nhật `AGENTS.md` một tuần sau đó, Git chỉ hiển thị diff của `AGENTS.md`. Điều này bình thường, nhưng đồng nghiệp xem PR có thể không nhận ra `CLAUDE.md` cũng đã được cập nhật thông qua symlink. Giải pháp: ghi rõ trong mô tả PR: “đã cập nhật `AGENTS.md`; Claude Code nhìn thấy cùng tệp đó qua symlink.”
**5. Khó gỡ lỗi khi nhập lồng sâu.** Nếu `AGENTS.md` nhập `@docs/coding-style.md`, rồi tệp đó nhập `@docs/typescript.md`, và có quy tắc mâu thuẫn với quy tắc khác, việc gỡ lỗi sẽ khó khăn. Tôi chỉ dùng một cấp nhập (`CLAUDE.md` → `AGENTS.md`) và không lồng sâu hơn. Anthropic cung cấp hook `InstructionsLoaded` để ghi lại những tệp đã được tải — rất hữu ích khi gỡ lỗi thiết lập nhiều lớp. Lưu ý: hook này chạy với `AGENTS.md` được đưa vào thông qua thao tác nhập hoặc symlink, nhưng không chạy với `AGENTS.md` mà Claude Code tự đọc.
### Nguồn
- [Tài liệu về bộ nhớ Claude Code — mục AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) — thời điểm Claude Code tự đọc AGENTS.md, cài đặt Project instructions, thao tác nhập và symlink, cùng hành vi của `/init`.
- [Tài liệu về bộ nhớ Claude Code — nhập các tệp bổ sung](https://code.claude.com/docs/en/memory#import-additional-files) — cú pháp `@path/to/file`, độ sâu bốn cấp, đường dẫn tương đối và tuyệt đối.
- [agents.md — tiêu chuẩn Linux Foundation](https://agents.md/) — tiêu chuẩn AGENTS.md chính thức và danh sách công cụ hỗ trợ.
- [Tài liệu Cursor Rules](https://docs.cursor.com/context/rules-for-ai) — Cursor đọc những gì (`.cursor/rules/*.mdc`, AGENTS.md).
- [Hướng dẫn tùy chỉnh cho GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) — định dạng `.github/copilot-instructions.md`.
- [Đặc tả AGENTS.md của Linux Foundation](https://aaif.io/projects/agents-md/) — đặc tả luôn được cập nhật.
Tìm hiểu về [Ailoot](https://ailoot.ai/).
## Câu hỏi thường gặp
### Khi nào dùng import thay symlink?
Dùng `@AGENTS.md` trong `CLAUDE.md` khi cần bổ sung riêng Claude hoặc đồng đội dùng Windows. Symlink khiến hai tên cùng nội dung nên không giữ được phần Claude riêng.
### Kiểm tra hướng dẫn chung đã nạp thế nào?
Chạy `/memory`, xem danh sách tệp hướng dẫn. Nếu `CLAUDE.md` hoặc `CLAUDE.local.md` chặn nạp trực tiếp AGENTS.md trong cấu hình, thêm import hoặc chọn nạp cả hai rồi mở phiên mới.
## 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.