AGENTS.md hay CLAUDE.md: agent của bạn đọc file nào?

Repo của bạn có AGENTS.md, đồng nghiệp thêm CLAUDE.md, người thứ ba thả vài file vào .cursor/rules/. Một tháng sau không ai biết agent thực sự đọc file nào, và hai trong số đó đang nói ngược nhau. Dưới đây là những gì tài liệu chính thức của từng tool nói, theo hai bài tổng hợp đối chiếu docs trong tháng 10/2026.

Tool nào đọc file nào

File	Cursor	Claude Code	Codex	Copilot (GitHub.com)
AGENTS.md	Có, cả root và subfolder	Chỉ khi không có CLAUDE.md / CLAUDE.local.md (v2.1.277+)	Có	Có, file gần nhất thắng
CLAUDE.md	Có, giống AGENTS.md	Có	Chỉ qua project_doc_fallback_filenames	Có, một file duy nhất ở root
.cursor/rules/*.mdc	Có	Chỉ làm input cho /init	Không có tài liệu	Không có tài liệu
.cursorrules	Legacy, "sẽ bị deprecated"	Chỉ làm input cho /init	Chỉ qua fallback config	Không có tài liệu

Hai cái bẫy khiến rule của bạn bị bỏ qua

Bẫy 1 — CLAUDE.local.md cá nhân. Theo memory docs mà cả hai bài dẫn lại, Claude Code chỉ đọc AGENTS.md khi không tồn tại CLAUDE.md, .claude/CLAUDE.md hay CLAUDE.local.md ở thư mục làm việc hoặc bất kỳ thư mục cha nào. CLAUDE.local.md được tính vào phép kiểm tra đó. Nghĩa là một file cá nhân, không commit, có thể âm thầm chặn Claude đọc AGENTS.md của cả team — chỉ với riêng máy bạn.

Bẫy 2 — file .md trong .cursor/rules. Bạn kéo api-guidelines.md vào đó và không có gì xảy ra. Docs của Cursor nói thẳng: project rule bắt buộc dùng đuôi .mdc, còn file .md trong .cursor/rules bị hệ thống rule bỏ qua vì không có frontmatter để khai báo description, globs và alwaysApply.

Ba field đó quyết định lúc nào rule được nạp: alwaysApply: true thì luôn nạp; false kèm globs thì nạp khi có file khớp trong context; false kèm mỗi description thì agent tự quyết; không field nào thì chỉ nạp khi bạn @-mention.

Một nguồn sự thật, vài adapter mỏng

Cấu hình ít trôi lệch nhất, theo cả hai bài: lấy AGENTS.md làm nguồn chuẩn, vì Cursor, Codex và Copilot đọc thẳng nó. Với Claude Code, viết một CLAUDE.md một dòng import nó — Anthropic có tài liệu đúng pattern này, và file được import một lần nên không nạp trùng:

@AGENTS.md

## Claude Code
- Dùng plan mode cho thay đổi chạm hơn hai file.

Symlink (ln -s AGENTS.md CLAUDE.md) cũng chạy, nhưng docs cảnh báo bản clone trên Windows có thể check out symlink đã commit thành file text thường — nên với team lẫn hệ điều hành, import là lựa chọn an toàn hơn. Phần rule chỉ áp cho src/api/** hay file test thì để trong .cursor/rules/*.mdc kèm globs, và xoá .cursorrules sau khi đã chuyển nội dung.

Vài giới hạn nên nhớ

• Codex đi từ project root xuống thư mục làm việc, lấy tối đa một file mỗi thư mục và dừng ở 32 KiB theo mặc định.
• Copilot còn hỗ trợ .github/instructions/NAME.instructions.md với glob applyTo, nhưng file theo path hiện chỉ chạy với Copilot cloud agent và Copilot code review trên GitHub.com.
• Docs khuyên giữ mỗi CLAUDE.md dưới khoảng 200 dòng; Cursor khuyên mỗi rule dưới 500 dòng.

Điểm quan trọng nhất mà một trong hai tác giả nhấn mạnh: các file này là context, không phải cơ chế cưỡng chế. Nếu một việc bắt buộc phải xảy ra mỗi lần, dùng hook, đừng viết thêm một dòng rule. Test, CI và code review vẫn là cổng thật.

Việc nên làm ngay: chạy /memory (hoặc /context) trong repo của bạn để xem Claude Code thực sự nạp file nào, rồi ls -a .cursor/rules xem có file .md nào đang bị bỏ qua không.