Claude Code hỗ trợ AGENTS.md: Cách kết hợp với CLAUDE.md

Claude Code đã hỗ trợ AGENTS.md từ phiên bản v2.1.277: trong một dự án không có CLAUDE.md, Claude Code giờ đây đọc AGENTS.md của bạn như chỉ dẫn dự án. Bạn không cần import, symlink hay cấu hình gì cả. Nếu repo của bạn có cả hai tệp, Claude chỉ đọc CLAUDE.md, trừ khi bạn chuyển cài đặt Project instructions trong /config sang chế độ tải cả hai.

Nếu nhóm của bạn dùng nhiều coding agent, tệp AGENTS.md mà Codex và Cursor đã đọc từ trước giờ cũng điều khiển được Claude Code. Bài viết này sẽ đề cập đến thứ tự ưu tiên, cách chuyển đổi, và một AGENTS.md dạy cho bất kỳ agent nào cách kiểm thử API của bạn bằng Apidog CLI.

AGENTS.md trong Claude Code là gì?

AGENTS.md là một tệp Markdown thuần chứa chỉ dẫn cho coding agent: lệnh build, lệnh test, style code và các quy tắc dự án. Từ phiên bản v2.1.277, Claude Code đọc tệp này thông qua một plugin tích hợp sẵn, nên một repo đã được thiết lập cho các agent khác hoạt động ngay với Claude Code mà không cần thêm tệp nào. Nó không yêu cầu trường bắt buộc hay cú pháp đặc biệt nào.

Bản thân định dạng này là mở. Trang AGENTS.md mô tả nó là "một định dạng mở, đơn giản để hướng dẫn coding agent", được hơn 60.000 dự án mã nguồn mở sử dụng và hiện được quản lý bởi Agentic AI Foundation thuộc Linux Foundation. Cả OpenAI Codex và Cursor đều tài liệu về việc hỗ trợ AGENTS.md, và Claude Code là "đại gia" còn lại chưa hỗ trợ cho đến bản phát hành này.

Mới tìm hiểu về định dạng này? Hãy bắt đầu với cách viết tệp AGENTS.md cho các nhóm phát triển API.

Dưới đây là dòng thời gian phát hành trích từ changelog chính thức của Claude Code:

Chạy claude --version trước khi dựa vào bất kỳ tính năng nào trong số này. Trên các phiên bản cũ hơn 2.1.277, Claude Code chỉ đọc các tệp CLAUDE.md.

CLAUDE.md vs AGENTS.md: tệp nào được ưu tiên?

Theo mặc định, CLAUDE.md được ưu tiên. Claude Code chỉ đọc AGENTS.md khi không có CLAUDE.md nào trong thư mục làm việc hoặc bất kỳ thư mục cha nào. Tài liệu bộ nhớ của Claude Code nêu rõ ba trường hợp:

Không phải tệp nào cũng được tính trong kiểm tra đó. Ba tệp sau sẽ chặn AGENTS.md:

• CLAUDE.md trong thư mục làm việc hoặc thư mục cha
• .claude/CLAUDE.md trong thư mục làm việc hoặc thư mục cha
• CLAUDE.local.md trong thư mục làm việc hoặc thư mục cha

Những tệp sau không chặn, và vẫn được tải song song với AGENTS.md: tệp người dùng của bạn tại ~/.claude/CLAUDE.md, CLAUDE.md do tổ chức quản lý, và các tệp trong .claude/rules/.

Hãy cẩn thận với "bẫy" CLAUDE.local.md: chỉ cần thêm một tệp cá nhân để lưu ghi chú chưa commit, Claude sẽ ngừng đọc AGENTS.md của nhóm đối với bạn.

Claude Code tải gì, và khi nào

Khi không có gì chặn, Claude Code sẽ đọc:

1. Khi bắt đầu phiên: mọi AGENTS.md và .claude/AGENTS.md trong thư mục làm việc và các thư mục cha. Phiên tương tác sẽ in một dòng như no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
2. Trong thư mục con: tệp AGENTS.md của thư mục con, khi Claude mở một tệp trong đó bằng công cụ Read và thư mục đó không có CLAUDE.md riêng.
3. Import: các import @path bên trong AGENTS.md được mở rộng, và các mẫu claudeMdExcludes được áp dụng.

Claude Code không đọc AGENTS.local.md, AGENTS.override.md, hay bất kỳ tệp nào dưới .agents/. Nếu bạn dùng chung repo với Codex — vốn tài liệu về AGENTS.override.md — hãy lưu ý điều này.

Cách thay đổi tệp chỉ dẫn mà Claude Code tải

Gõ /config trong một phiên và đặt Project instructions thành một trong bốn giá trị:

Với hầu hết các nhóm dùng nhiều agent, claude-md-and-agents-md là cài đặt bạn cần. Nó giữ lại CLAUDE.local.md cá nhân của bạn mà vẫn tải AGENTS.md chung.

Bạn có thể đặt nó trong tệp cài đặt thay vì trong /config. Claude Code đọc mục này từ ~/.claude/settings.json, tệp --settings, hoặc cài đặt do quản trị viên đặt, và bỏ qua nó trong các tệp cài đặt dự án và cục bộ:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Trước v2.1.285, ID của plugin là agents-md@builtin. Các phiên bản từ 2.1.285 trở đi chấp nhận cả hai ID, nên hãy dùng ID cũ nếu những bản cài cũ hơn dùng chung tệp. Thay đổi có hiệu lực từ tin nhắn tiếp theo của bạn.

Nếu Project instructions không xuất hiện trong /config, phiên của bạn không thể tải AGENTS.md: bạn đang dùng phiên bản cũ hơn 2.1.277, bạn đã tắt plugin tích hợp sẵn qua /plugin, hoặc đây là phiên đầu tiên sau khi nâng cấp (nó hoạt động từ phiên tiếp theo).

Cách chuyển đổi từ cách dùng AGENTS.md thủ công trước đây

Nhiều nhóm đã kết nối AGENTS.md vào Claude Code theo cách thủ công trước bản phát hành này. Tài liệu khuyến nghị:

Hãy giữ import @AGENTS.md nếu còn ai đó trong nhóm chạy phiên bản cũ hơn 2.1.277. Đây là cách cài duy nhất hoạt động trên mọi phiên bản.

Import hay symlink?

Nếu bạn cần các quy tắc riêng cho Claude trên nền tệp chung, hãy dùng import. Claude đọc tệp được import trước, sau đó là phần còn lại:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Nếu bạn không cần gì riêng cho Claude, symlink cũng hoạt động:

ln -s AGENTS.md CLAUDE.md

Hai lưu ý: các công cụ Edit và Write của Claude sẽ không ghi được qua symlink, và Git trên Windows checkout một symlink đã commit thành tệp văn bản một dòng trừ khi bật core.symlinks. Nếu ai đó trong nhóm dùng Windows, hãy chọn import.

Dù chọn cách nào, hãy chạy /context all trong phiên tiếp theo và xác nhận CLAUDE.md hiển thị dưới mục Memory files.

Một AGENTS.md cho Codex, Cursor và Claude Code

Lợi ích lớn nhất là có một nguồn thông tin duy nhất. Đặt các lệnh build, lệnh test và quy ước của bạn vào AGENTS.md ở thư mục gốc repo. Codex, Cursor và Claude Code đều đọc tệp này.

Một bố cục hoạt động hiệu quả trong thực tế:

• AGENTS.md ở thư mục gốc: tất cả những gì mọi agent cần. Các lệnh, sơ đồ thư mục, quy tắc style, những gì không được đụng đến.
• AGENTS.md trong các thư mục con lớn: các quy tắc chỉ áp dụng cho thư mục đó, như services/payments/AGENTS.md. Claude Code tải các tệp này theo yêu cầu khi đọc một tệp trong thư mục đó.
• CLAUDE.md tùy chọn: chỉ khi bạn cần hành vi riêng cho Claude, như plan mode hoặc hooks. Bắt đầu bằng @AGENTS.md.

Một lưu ý: AGENTS.md được tải qua cài đặt không kích hoạt hook InstructionsLoaded, và không được tải từ các thư mục --add-dir. Nếu bạn phụ thuộc vào một trong hai, hãy dùng cách import @AGENTS.md.

Dạy agent kiểm thử API bằng Apidog CLI trong AGENTS.md

Hãy viết quy tắc kiểm thử API của bạn một lần, và bất kỳ agent nào mở repo đều chạy test theo cùng một cách. Apidog CLI cung cấp cho agent đầu ra JSON có cấu trúc mà nó có thể đọc được, nhờ vậy vòng lặp làm việc vẫn nằm trong terminal.

Cài đặt một lần cho mỗi máy:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Một cách nhanh hơn: yêu cầu agent của bạn "Read https://apidog.com/apidog-cli-installation-guide.md and set up Apidog CLI". Hướng dẫn đó được viết cho agent và bao gồm cài đặt, đăng nhập và skill.

Sau đó thêm một mục như sau vào AGENTS.md của bạn:

## API testing (Apidog CLI)

- Apidog project ID: 123456. Staging environment ID: 7890.
- Never build Apidog JSON payloads from memory. Run
  `apidog cli-schema get <key>` first, then
  `apidog cli-schema validate <key> --file <path>`, and write only after it passes.
- After changing any handler under `src/routes/`, find its endpoint with
  `apidog endpoint list --project 123456` and its cases with
  `apidog test-case list --project 123456 --endpoint <endpointId>`.
- If a route has no test case, create one with
  `apidog test-case create --project 123456 --file case.json`.
- Run cases with
  `apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json`
  and summarize every failure before you say the task is done.
- Do not edit or delete endpoints in Apidog unless the task asks for it.

Bây giờ chỉ một prompt là đủ để công việc được thực hiện trong Claude Code, Codex hay Cursor:

I changed POST /orders to require a currency field. Update the Apidog test
case for it and run it against staging, following AGENTS.md.

Agent tuân theo quy tắc của bạn và chạy các lệnh như sau:

apidog endpoint list --project 123456
apidog test-case list --project 123456 --endpoint <endpointId>
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123456 --file case.json
apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json

Mọi flag ở trên đều lấy từ apidog <cmd> --help trên Apidog CLI 2.2.12. Cùng dòng lệnh apidog run với -r junit có thể dùng ngay trong CI, và --upload-report gửi tổng quan lần chạy lên ứng dụng để cả nhóm cùng xem. Để biết chi tiết về phía Claude Code, xem cách dùng Apidog CLI trong Claude Code; người dùng Codex có thể tham khảo Apidog CLI trong Codex. Apidog Free hỗ trợ tới 4 người dùng, nên một nhóm nhỏ có thể thử ngay hôm nay.

Xử lý sự cố: AGENTS.md của tôi không được tải

1. Kiểm tra xem có CLAUDE.md nào trên đường dẫn không. Một CLAUDE.md, .claude/CLAUDE.md hoặc CLAUDE.local.md trong thư mục làm việc hoặc thư mục cha sẽ được ưu tiên theo mặc định. ~/.claude/CLAUDE.md của bạn không bị tính.
2. Kiểm tra phiên bản. Chạy claude --version. Bạn cần 2.1.277 trở lên, và 2.1.281 trở lên trên Bedrock, Vertex AI, Foundry, gateway, hoặc khi telemetry bị tắt.
3. Kiểm tra cài đặt. Mở /config và đảm bảo Project instructions không phải là claude-md hay managed-only.
4. Xác nhận đã được tải. Chạy /memory và tìm đường dẫn AGENTS.md trong danh sách.

Câu hỏi thường gặp

Claude Code có đọc AGENTS.md không? Có, từ v2.1.277. Khi không có CLAUDE.md trong thư mục làm việc hoặc thư mục cha, Claude Code sẽ tự động đọc AGENTS.md như chỉ dẫn dự án.

Nếu tôi có cả CLAUDE.md và AGENTS.md, Claude Code dùng tệp nào? Chỉ CLAUDE.md, theo mặc định. Đặt Project instructions thành claude-md-and-agents-md trong /config để tải cả hai, với CLAUDE.md trước.

Tôi có nên xóa CLAUDE.md đang import @AGENTS.md không? Không cần. Import này không bao giờ tải AGENTS.md hai lần, và vẫn hoạt động cho đồng nghiệp dùng phiên bản cũ hơn 2.1.277. Chỉ xóa khi nó không chứa gì khác và tất cả mọi người đã nâng cấp.

Claude Code có đọc AGENTS.override.md như Codex không? Không. Claude Code bỏ qua AGENTS.override.md, AGENTS.local.md và mọi tệp dưới .agents/.

AGENTS.md có hoạt động trên Amazon Bedrock hoặc Google Vertex AI không? Có, từ v2.1.281. Các phiên bản cũ hơn trên Bedrock, Vertex AI, Foundry, gateway, hoặc khi telemetry bị tắt chỉ đọc CLAUDE.md; hãy dùng import @AGENTS.md trong trường hợp đó.