Một tệp hướng dẫn cho Claude Code, Codex và Cursor trong năm 2026

Để biết thông tin về dịch vụ, xem tài liệu Ailoot.

Điều gì thay đổi khi bạn dùng Claude Code, Codex và Cursor cùng nhau?#

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.

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?#

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 chính xác những gì tùy thuộc vào các tệp có trong dự án:

Đố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:

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?#

Ví dụ tối thiểu hoạt động được từ tài liệu chính thức:

@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:

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?#

Tài liệu minh họa tùy chọn symlink như sau:

ln -s AGENTS.md CLAUDE.md

Và ngay sau đó đưa ra cảnh báo thẳng thắn về Windows:

Bảng so sánh:

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.

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?#

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ụ):

Đ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?#

Anthropic mô tả /init trong tài liệu như sau:

Đ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:

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.

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?#

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.
• 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?#

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:

---
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):

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ì?#

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?#

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 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.

Tìm hiểu về Ailoot.