Claude Code đọc AGENTS.md khi thiếu CLAUDE.md: cần làm gì

Repo của bạn xoá CLAUDE.md từ lâu, chỉ còn AGENTS.md viết cho Codex hoặc Cursor. Từ bản Claude Code v2.1.277 (18/09/2026), agent bắt đầu đọc đúng file đó — và không có dòng nào trong output báo cho bạn biết. Dưới đây là checklist năm phút để biết agent đang đọc gì, trong repo lẫn ngoài repo.

Quy tắc mới, nói cho chính xác

Bản tin gốc tóm tắt thay đổi rất hẹp, và chi tiết mới là thứ quyết định repo của bạn có bị ảnh hưởng hay không:

• Phiên bản: Claude Code v2.1.277, ghi ngày 18 Sep 2026 trong changelog.
• Quy tắc: nếu project không có CLAUDE.md, Claude Code đọc AGENTS.md thay thế.
• Có thể bật/tắt trong /config — đây là hành vi cấu hình được, không phải mặc định cứng.
• Chưa hỗ trợ trên Bedrock, Vertex, Foundry.
• CLAUDE.md vẫn thắng khi tồn tại; AGENTS.md chỉ được đọc khi nó vắng mặt.

Không có công cụ migrate, không có format file mới, không deprecate CLAUDE.md. Đây thuần tuý là một đường fallback.

Vì sao một fallback im lặng lại đáng lo

Repo còn CLAUDE.md cũ thì fallback không bao giờ chạy. Đáng lo là chiều ngược lại: repo cố tình không có CLAUDE.md, còn AGENTS.md thì được viết cho một agent khác với giả định khác. Nếu file đó chứa test command khác, package manager khác, hay một bước codegen bắt buộc, Claude Code sẽ làm theo — và theo bài gốc, "nothing in the output will say 'I am following AGENTS.md now.'"

Vấn đề thứ hai nặng hơn với team ở VN dùng nhiều provider: nếu một phần team chạy Claude Code qua Bedrock hoặc Vertex, cùng một repo sẽ resolve instruction khác nhau tuỳ người. Triệu chứng sẽ hiện ra dưới dạng "agent quên convention của tụi mình", chứ không phải "agent đọc nhầm file" — và đó là buổi debug bạn không muốn có.

Checklist: file nào tồn tại, file nào thắng

Chạy đoạn này ở root từng repo bạn quan tâm. Nó trả lời câu hỏi duy nhất cần trả lời trước: fallback có với tới được repo này không. Đây là ví dụ minh hoạ, sửa danh sách file theo bộ tool team bạn đang dùng:

for f in CLAUDE.md AGENTS.md .cursor/rules; do
  if [ -e "$f" ]; then echo "present: $f"; else echo "absent: $f"; fi
done

Không có CLAUDE.md mà có AGENTS.md thì đọc lại file đó hôm nay, bằng con mắt "Claude Code sẽ thi hành từng dòng này".

Agent còn đọc gì ngoài repo

File hướng dẫn chỉ là một nửa. Trong một bài lab khác tuần này, tác giả mô tả một agent được mở ở ~/work, đọc checkout.sh có curl --netrc, rồi lần theo flag đó mở ~/.netrc và in dòng machine, login, password ra chat. Không prompt injection, không jailbreak — chỉ là ranh giới tin cậy đặt sai chỗ.

Cách đóng khung của tác giả đáng mượn nguyên văn: ranh giới không nằm ở "model đã aligned", mà ở "file tool được phép mở realpath nào". Ba file đầu tiên nên chặn là ~/.netrc, ~/.pgpass, ~/.docker/config.json; sau đó tới id_rsa, id_ed25519, .git-credentials, token kube và credentials trong .aws. Tác giả cũng tự cảnh báo: deny-list theo tên file là một CI tripwire, không phải sandbox.

Làm gì trong tuần này

• Chạy checklist trên mọi repo team đang trỏ agent vào, ghi lại repo nào rơi vào nhánh fallback.
• Thống nhất một file duy nhất cho mỗi repo, và ghi rõ trong README file nào là nguồn sự thật.
• Hỏi trong team ai đang chạy qua Bedrock/Vertex/Foundry — đó là nhóm sẽ thấy hành vi khác.
• Mở agent ở thư mục repo, đừng mở ở ~ hay ~/work.