Claude Code hiện đọc AGENTS.md: Những thay đổi trong 2.1.277

Ngày 18 tháng 9 năm 2026, Claude Code 2.1.277 đã bổ sung hỗ trợ AGENTS.md. Nếu tính năng này khả dụng trong phiên làm việc và trong thư mục làm việc, đồng thời không có CLAUDE.md, .claude/CLAUDE.md hoặc CLAUDE.local.md ở bất kỳ đâu trong chuỗi thư mục phía trên, Claude Code sẽ đọc AGENTS.md theo mặc định mà không cần nhập thủ công. Trước đây, việc này được thực hiện bằng cách nhập @AGENTS.md trong CLAUDE.md hoặc tạo liên kết tượng trưng từ CLAUDE.md đến AGENTS.md—xem bài viết về một tệp hướng dẫn dùng chung cho nhiều tác nhân để biết thêm chi tiết.

Nếu bạn dùng Claude Code cùng một hoặc hai công cụ khác trong cùng kho mã, chế độ Project instructions mà bạn chọn sẽ quyết định Claude Code đọc những tệp hướng dẫn nào. Dưới đây là các điều kiện cho từng chế độ trong số bốn chế độ và các bước chuyển từ cách thiết lập cũ.

Bạn có thể xem thêm tài liệu về cấu hình công cụ trong tài liệu Ailoot.

Có gì thay đổi trong phiên bản 2.1.277?#

CHANGELOG.md chính thức của dự án Claude Code trên GitHub mô tả thay đổi như sau:

Nói cách khác: đã bổ sung hỗ trợ AGENTS.md—trong dự án không có CLAUDE.md, giờ đây Claude Code đọc AGENTS.md thay thế; có thể chuyển chế độ này trong “Project instructions” tại /config (chưa khả dụng trên Bedrock, Vertex hoặc Foundry).

Trước phiên bản này, chỉ riêng việc không có CLAUDE.md, .claude/CLAUDE.md và CLAUDE.local.md trong thư mục làm việc và các thư mục phía trên không khiến AGENTS.md được đọc. Cần có lệnh nhập rõ ràng, liên kết tượng trưng hoặc hook thủ công. Giờ đây, khi tính năng khả dụng, tác nhân sẽ tự động nhận tệp này.

Những tệp nào ngăn việc tự động đọc AGENTS.md#

Nếu bạn có ~/.claude/CLAUDE.md cá nhân chứa các thiết lập về phong cách viết mã, tệp đó sẽ không ngăn Claude Code đọc AGENTS.md của dự án. Tuy nhiên, bất kỳ CLAUDE.local.md nào trong thư mục làm việc—kể cả tệp không được thêm vào Git và dùng để ghi chú cá nhân—đều ngăn việc tự động đọc AGENTS.md ở chế độ mặc định. Lệnh nhập rõ ràng vẫn hoạt động; để đọc trực tiếp cả hai tệp, bạn cần chuyển chế độ.

Nếu chọn chế độ đọc trực tiếp trong Project instructions (xem phần “4 chế độ Project instructions—nên chọn chế độ nào” bên dưới) và 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 phía trên, Claude Code sẽ đọc mọi tệp AGENTS.md và .claude/AGENTS.md trong các thư mục đó khi phiên làm việc bắt đầu. Với trường hợp không có tệp ngăn cản, tài liệu cho thấy một dòng như sau trong phiên tương tác:

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

Tệp AGENTS.md trong thư mục con được tải khi Claude mở một tệp ở đó bằng công cụ Read. Trong chế độ claude-md-or-agents-md, việc này chỉ xảy ra nếu thư mục con đó không có CLAUDE.md, .claude/CLAUDE.md hoặc CLAUDE.local.md riêng. Với claude-md-and-agents-md, tài liệu mô tả quy tắc chung: CLAUDE.md và AGENTS.md được đọc cùng nhau, trước tiên là CLAUDE.md, sau đó đến AGENTS.md trong từng thư mục. AGENTS.local.md, AGENTS.override.md và mọi thứ trong thư mục .agents/ không được tự động đọc.

Bạn có thể xem tài liệu về cấu hình không gian làm việc của tác nhân AI, bao gồm các tệp hướng dẫn chứa ngữ cảnh dự án, trong tài liệu Ailoot.

4 chế độ Project instructions—nên chọn chế độ nào#

Hành vi của các chế độ trong bảng được mô tả trong tài liệu của Anthropic. Cột bên phải đưa ra gợi ý để chọn chế độ:

Bạn cũng có thể chọn chế độ mà không cần giao diện, thông qua settings.json:

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

Claude Code bỏ qua giá trị này trong các thiết lập project và local. Theo tài liệu của Anthropic, có thể đặt giá trị này trong ~/.claude/settings.json, tệp --settings hoặc thiết lập do tổ chức quản lý.

Nếu bạn đã cấu hình một tệp hướng dẫn dùng chung cho nhiều công cụ AI trong cùng kho mã, hướng dẫn cho các phiên bản trước 2.1.277 giải thích cách lệnh nhập @ hoạt động. Phương pháp này hiện vẫn dùng được.

Vì sao không có Project instructions trong /config#

Trước tiên, hãy kiểm tra phiên bản bằng lệnh claude --version. Nếu thấp hơn 2.1.277, hãy cập nhật Claude Code. Nếu phiên bản phù hợp nhưng mục này vẫn không xuất hiện, hãy kiểm tra các lý do khác được liệt kê ở trên. Trong khi tính năng chưa khả dụng, nhập @AGENTS.md trong CLAUDE.md vẫn là phương án thay thế hoạt động được.

Nên làm gì với lệnh nhập @AGENTS.md cũ#

Các bước tiếp theo phụ thuộc vào cách thiết lập cũ. Trước hết, hãy chắc chắn tính năng khả dụng trong phiên của bạn như mô tả ở phần trước.

• CLAUDE.md có lệnh nhập @AGENTS.md. Bạn có thể giữ nguyên—Claude Code sẽ không đọc tệp hai lần với bất kỳ giá trị Project instructions nào. Xóa CLAUDE.md là tùy chọn: lệnh nhập đã giúp Claude truy cập nội dung của AGENTS.md. Tiếp tục kiểm tra việc tải qua lệnh nhập bằng /memory; hỏi trực tiếp Claude về nội dung hướng dẫn chỉ là cách kiểm tra chưa đáng tin cậy.
• CLAUDE.md yêu cầu bằng lời rằng hãy đọc AGENTS.md. Yêu cầu như vậy không phải lệnh nhập và tự nó không đảm bảo tệp sẽ được tải. Nếu muốn giữ CLAUDE.md (chẳng hạn để các công cụ khác cũng đọc được), hãy thay câu chữ đó bằng lệnh nhập @AGENTS.md. Nếu quyết định xóa hẳn CLAUDE.md và đã chọn chế độ claude-md-or-agents-md, trước tiên hãy kiểm tra rằng CLAUDE.md không chứa hướng dẫn riêng nào và không có CLAUDE.md, .claude/CLAUDE.md hoặc CLAUDE.local.md nào khác trong thư mục làm việc hoặc phía trên; nếu không, Claude Code sẽ tiếp tục đọc tệp còn lại thay vì AGENTS.md. Sau khi xóa, hãy đảm bảo quá trình chuyển đổi đã diễn ra: khi không còn tệp ngăn cản, dòng AGENTS.md loaded sẽ xuất hiện trong phiên tương tác. Nếu vẫn giữ CLAUDE.md và đọc cả hai tệp ở chế độ claude-md-and-agents-md, hãy kiểm tra /memory (trong phiên bản 2.1.280 trở lên). Hỏi trực tiếp Claude không thể phân biệt việc đọc trực tiếp với việc nhập tệp.
• Liên kết tượng trưng từ CLAUDE.md đến AGENTS.md. Bạn có thể giữ liên kết: không chế độ nào đọc trùng. Trước khi xóa liên kết ở chế độ claude-md-or-agents-md, hãy kiểm tra rằng các hướng dẫn cần thiết vẫn được giữ lại và không có CLAUDE.md, .claude/CLAUDE.md hoặc CLAUDE.local.md nào khác trong thư mục làm việc hay phía trên. Kiểm tra việc tải theo cách tương tự: tìm dòng AGENTS.md loaded khi bắt đầu phiên nếu không có tệp ngăn cản, hoặc kiểm tra /memory (2.1.280 trở lên). Nếu vẫn giữ CLAUDE.md trong chế độ claude-md-and-agents-md, hỏi trực tiếp Claude chỉ là cách kiểm tra chưa đáng tin cậy. Không có lỗi không đủ để xác nhận tệp đã được tải.
• Hook SessionStart tự in nội dung AGENTS.md. Khi tệp được đọc trực tiếp, hook như vậy sẽ đưa bản sao thứ hai vào ngữ cảnh. Khi hook đang chạy, câu hỏi “trong hướng dẫn của bạn có nội dung gì?” không xác nhận việc đọc trực tiếp: Claude có thể trả lời dựa trên văn bản do hook thêm vào. Hãy chuyển đổi theo thứ tự sau:
  1. Kiểm tra tính năng khả dụng: phiên bản 2.1.277 trở lên, phiên làm việc nhận được feature flags, plugin được bật và phiên đầu tiên sau khi cài đặt hoặc cập nhật đã hoàn tất. Chọn chế độ đọc trực tiếp—không phải claude-md hay managed-only. Với chế độ mặc định, hãy kiểm tra thêm rằng không có tệp ngăn cản.
  2. Xóa hook.
  3. Đóng phiên rồi mở phiên mới. Hook SessionStart thêm văn bản khi khởi động, vì vậy nội dung của nó vẫn còn trong ngữ cảnh của phiên đang mở. Câu trả lời của Claude về nội dung hướng dẫn trong phiên đó sẽ không xác nhận việc đọc trực tiếp.
  4. Kiểm tra việc tải trong phiên mới. Trong phiên bản 2.1.280 trở lên, đường dẫn đến AGENTS.md hiển thị trong /memory. Trong phiên bản 2.1.277–2.1.279, nếu không có tệp ngăn cản, hãy tìm dòng AGENTS.md loaded lúc khởi động: tài liệu mô tả dòng này cụ thể cho trường hợp không tìm thấy CLAUDE.md. Nếu giữ CLAUDE.md và dùng chế độ claude-md-and-agents-md, khả năng kiểm tra bị giới hạn: /memory không hiển thị AGENTS.md trong các phiên bản này, tài liệu không mô tả dòng thông báo tải cho trường hợp đó, và việc diễn đạt lại hướng dẫn không thể phân biệt đọc trực tiếp với lệnh nhập @ bên trong CLAUDE.md. Trong trường hợp này, hãy cập nhật lên 2.1.280 trở lên rồi kiểm tra /memory.

Cách kiểm tra AGENTS.md đã được tải#

Còn hai điểm khác biệt nữa so với CLAUDE.md thông thường: hook InstructionsLoaded không chạy với loại AGENTS.md này (nhưng có chạy với AGENTS.md được nhập qua cú pháp @ từ CLAUDE.md hoặc được liên kết bằng liên kết tượng trưng CLAUDE.md); các thư mục được thêm bằng cờ --add-dir cùng với biến CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD chỉ tải CLAUDE.md của thư mục đó—không bao gồm AGENTS.md.

Nếu cần xem lại nội dung của tệp hướng dẫn dự án lớn, hãy xem bài phân tích riêng về cách cấu hình CLAUDE.md mà không làm tệp trở nên cồng kềnh. Bài viết trình bày cấu trúc hướng dẫn, còn các điều kiện tải AGENTS.md đã được mô tả ở trên. Để xem ghi chú làm việc giữa các phiên, hãy đọc bài phân tích về bộ não thứ hai trong Claude Code—nội dung nói về bộ nhớ cá nhân được bổ sung bên trên hướng dẫn dự án.

Tiếp theo nên làm gì#

Tính năng được phát hành ngày 18 tháng 9 năm 2026 trong phiên bản 2.1.277. Anthropic có thể làm rõ chi tiết về các chế độ trong những bản phát hành sau, vì vậy trước khi thay đổi thiết lập trong một dự án quan trọng, hãy đối chiếu bài viết này với /config hiện tại và changelog chính thức.