Claude Code hiện đọc AGENTS.md: CLAUDE.md so với AGENTS.md và thư mục .claude

claude.md là gì và bạn nên đưa những gì vào đó?

CLAUDE.md là một tệp Markdown dạng văn bản thuần chứa các hướng dẫn mà Claude Code đọc vào ngữ cảnh phiên. Tệp này cung cấp nơi ghi lại những thông tin mà nếu không có nó, bạn sẽ phải nhắc lại: lệnh xây dựng và kiểm thử, quy ước viết mã, kiến trúc dự án và quy tắc quy trình làm việc.

Không có định dạng tài liệu bắt buộc. Bạn có thể tổ chức tệp bằng các tiêu đề và danh sách Markdown thông thường, chọn cấu trúc giúp hướng dẫn của dự án dễ hiểu. Của Claude Code /init lệnh tạo một tệp khởi đầu dựa trên dự án, như được mô tả trong tài liệu chính thức về các phương pháp thực hành tốt nhất.

Một điểm khởi đầu hữu ích là đề cập đến bốn lĩnh vực:

• Lệnh xây dựng và kiểm thử: các lệnh mà người đóng góp nên dùng để xây dựng dự án và kiểm tra các thay đổi.
• Quy ước viết mã: cách đặt tên, định dạng và các quy ước khác liên quan đến kho mã.
• Kiến trúc dự án: các thành phần chính và cách chúng kết hợp với nhau.
• Quy tắc quy trình làm việc: các bước bạn muốn Claude tuân theo khi thực hiện và kiểm tra các thay đổi.

Hãy xem đây là hướng dẫn lâu dài. Các chỉ dẫn được đưa vào ngữ cảnh của Claude; chúng không phải là cấu hình được thực thi bắt buộc. Nếu cần cấu hình chính Claude Code, hãy dùng tệp cài đặt phù hợp thay vì kỳ vọng nội dung văn bản trong CLAUDE.md hoạt động như một giá trị cài đặt.

Sự phân biệt này rất quan trọng khi tổ chức kho mã: kiến thức về dự án thuộc về các tệp chỉ dẫn, còn cấu hình ứng dụng thuộc về phần cài đặt. Trung tâm hướng dẫn Claude Code cung cấp điểm khởi đầu cho quy trình làm việc liên quan.

Nên đặt CLAUDE.md ở đâu

Claude Code hỗ trợ chỉ dẫn chung của dự án và chỉ dẫn cá nhân tại nhiều vị trí. Tài liệu về tệp chỉ dẫn mô tả các vị trí đã được quy định này và cách hoạt động của cơ chế tìm tệp chỉ dẫn.

Các tệp chỉ dẫn trong thư mục tổ tiên được nạp khi khởi chạy. Các tệp trong thư mục con được nạp theo nhu cầu, để chỉ dẫn trở nên phù hợp khi Claude làm việc trong những phần đó của dự án.

Đối với chỉ dẫn chung, hãy chọn vị trí phù hợp với nhóm của bạn. Một tệp CLAUDE.md ở cấp gốc đặt hướng dẫn cạnh các tệp cấp cao nhất khác của kho mã. .claude/CLAUDE.md đặt hướng dẫn cùng với các tệp dành riêng cho Claude của dự án.

Chỉ dẫn cá nhân ảnh hưởng đến nhiều thứ hơn cách tổ chức tệp

CLAUDE.local.md có mục đích khác với tệp chung của dự án: tệp này chứa chỉ dẫn cá nhân của bạn cho dự án đó. Trong phiên bản 2.1.277, sự hiện diện của tệp này cũng ảnh hưởng đến việc Claude Code có chuyển sang dùng AGENTS.md.

Điều đó có nghĩa là việc thêm tệp chỉ dẫn cục bộ có thể thay đổi những chỉ dẫn chung nào được đưa vào ngữ cảnh. Trước khi tạo tệp như vậy trong một kho mã dựa vào AGENTS.md, hãy kiểm tra cài đặt Chỉ dẫn dự án được mô tả bên dưới.

Các vị trí ở trên được lấy từ tài liệu cập nhật liên tục, và câu chữ chính xác của tài liệu vào tháng Chín năm 19 chưa được xác minh. Hành vi chuyển sang phương án dự phòng trong phần tiếp theo được ghi nhận cụ thể cho bản phát hành gắn thẻ 2.1.277.

Claude Code có tự động đọc AGENTS.md không?

Có, nhưng có điều kiện. Ghi chú phát hành Claude Code 2.1.277 nêu rõ: “Đã thêm hỗ trợ AGENTS.md: trong dự án không có CLAUDE.md, Claude Code sẽ đọc AGENTS.md thay thế”.

Hành vi mặc định là dùng phương án dự phòng, vì vậy chỉ riêng sự hiện diện của một tệp AGENTS.md không có nghĩa là tệp đó sẽ được nạp. Trong bản phát hành này, việc kiểm tra không chỉ xét một tệp ở cấp gốc CLAUDE.md.

Điều gì ngăn việc chuyển sang phương án dự phòng mặc định?

Bất kỳ tệp nào trong số này, ở bất kỳ đâu trên đường dẫn từ thư mục gốc của hệ thống tệp đến thư mục làm việc, đều ngăn việc chuyển sang phương án dự phòng mặc định AGENTS.md :

• CLAUDE.md
• .claude/CLAUDE.md
• CLAUDE.local.md

Chỉ dẫn được quản lý, chỉ dẫn cá nhân trong ~/.claude/CLAUDE.md, và .claude/rules/ có không ngăn việc chuyển sang phương án dự phòng đó.

Ví dụ, hãy xét một kho mã có tệp dùng chung AGENTS.md và không có tệp chỉ dẫn Claude đủ điều kiện trên đường dẫn qua các thư mục tổ tiên. Chế độ mặc định đọc các chỉ dẫn AGENTS. Nếu sau đó bạn thêm CLAUDE.local.md, việc chuyển sang phương án dự phòng mặc định sẽ bị ngăn—dù tệp mới chứa chỉ dẫn cá nhân thay vì hướng dẫn chung của nhóm.

Cách hoạt động của cơ chế tìm AGENTS.md

Khả năng hỗ trợ tích hợp được cung cấp bởi agents-md plugin, phiên bản 0.1.0. Plugin tìm cả AGENTS.md và .claude/AGENTS.md trên đường dẫn qua các thư mục tổ tiên và đính kèm các chỉ dẫn lồng nhau khi Claude đọc tệp bên dưới thư mục gốc của dự án.

Nội dung đã được nạp qua thao tác nhập hoặc liên kết sẽ được loại bỏ phần trùng lặp. Điều này quan trọng nếu một tệp chỉ dẫn Claude đã đưa vào cùng nội dung AGENTS.

Tính đến thời điểm chốt xuất bản vào tháng Chín năm 19, thông báo phát hành cho biết khả năng hỗ trợ này chưa có trên Bedrock, Vertex hoặc Foundry.

Cấu hình Claude Code để đọc một tệp hoặc cả hai

Mở /config và thay đổi Chỉ dẫn dự án để chọn hành vi nạp chỉ dẫn. README của plugin được gắn thẻ v2.1.277 ghi nhận bốn giá trị chính xác.

README có một lưu ý quan trọng đối với managed-only: các phần đính kèm lồng nhau CLAUDE.md vẫn có thể được đưa vào. Đừng hiểu giá trị này là sự bảo đảm rằng không có nội dung chỉ dẫn Claude lồng nhau nào có thể đi vào cuộc hội thoại.

Cấu hình chính xác cho phiên bản 2.1.277

Để nạp cả hai nhóm chỉ dẫn, hãy dùng cấu hình này:

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

Đối với bản phát hành này, hãy đặt cấu hình trong cài đặt người dùng tại ~/.claude/settings.json, trong một tệp được cung cấp qua --settings, hoặc trong cài đặt được quản lý. Tệp dự án .claude/settings.json có không cung cấp các tùy chọn plugin này.

Các thay đổi có hiệu lực khi ngữ cảnh được dựng lại lần tiếp theo, chẳng hạn ở lượt tiếp theo hoặc trong cuộc hội thoại mới. Hãy lưu ý thời điểm này khi kiểm tra xem một cài đặt đã thay đổi các chỉ dẫn được nạp hay chưa.

Nhập chỉ dẫn chung vẫn là một lựa chọn

Bạn cũng có thể đặt @AGENTS.md bên trong một tệp lân cận CLAUDE.md. Thao tác này nhập rõ ràng các chỉ dẫn chung thông qua tệp chỉ dẫn Claude.

Việc nhập trong tệp chỉ dẫn Claude sử dụng @path/to/file.md và được giới thiệu trong v0.2.107. Phiên bản 2.1.277 loại bỏ phần trùng lặp của nội dung AGENTS đã được nhập bởi CLAUDE.md.

Điều này cho bạn hai cách tổ chức hướng dẫn chung: cấu hình Claude Code để nạp cả hai tệp, hoặc dùng thao tác nhập để đưa nội dung AGENTS vào tệp chỉ dẫn Claude. Hãy chọn cách bố trí giúp người đóng góp vào kho mã hiểu rõ mối quan hệ này.

Nên đặt gì trong thư mục .claude?

Thư mục .claude chứa nhiều loại tệp dự án. Chúng phục vụ các mục đích khác nhau, vì vậy hãy chọn vị trí dựa trên việc bạn đang viết hướng dẫn lâu dài, cấu hình, câu lệnh nhắc có thể tái sử dụng, định nghĩa tác nhân phụ hay quy trình.

Cài đặt cá nhân áp dụng cho nhiều dự án nằm trong ~/.claude/settings.json. Định nghĩa tác nhân phụ cá nhân sử dụng ~/.claude/agents/, và các kỹ năng cá nhân sử dụng ~/.claude/skills/<name>/SKILL.md.

Lệnh, tác tử phụ và kỹ năng

Một tệp lệnh như .claude/commands/deploy.md tạo /deploy. Phiên bản 2.1.3 đã hợp nhất lệnh gạch chéo và kỹ năng, đồng thời các tệp lệnh hiện có vẫn tiếp tục hoạt động song song với kỹ năng.

Định nghĩa tác tử phụ sử dụng Markdown với phần frontmatter YAML. Các trường bắt buộc là name và description; các trường tùy chọn liên quan gồm tools, model, và permissionMode. Quản lý chúng bằng /agents, và sử dụng hướng dẫn về tác tử phụ cho phần đó trong quá trình thiết lập dự án của bạn.

Kỹ năng đóng gói các quy trình có thể tái sử dụng trong một thư mục chứa SKILL.md, cùng các tập lệnh và tài liệu tham khảo tùy chọn. Claude có thể chọn kỹ năng phù hợp, hoặc bạn có thể gọi một kỹ năng bằng /skill-name; nội dung kỹ năng được tải khi sử dụng. Tài liệu hướng dẫn về kỹ năng trình bày quy trình này.

Các cấu trúc này đã có trước bản phát hành bổ sung cơ chế dự phòng AGENTS. Nhật ký thay đổi gắn thẻ phiên bản xác nhận rằng cài đặt dự án, lệnh, tác tử và kỹ năng đã tồn tại vào phiên bản v2.1.277. Các mô tả chi tiết về thư mục dựa trên tài liệu được cập nhật liên tục, nhưng nội dung chính xác của tài liệu vào ngày chốt chưa được xác minh.

CLAUDE.md so với bộ nhớ tự động

CLAUDE.md và bộ nhớ tự động khác nhau ở người viết nội dung. Bạn viết các tệp chỉ dẫn để xác định hướng dẫn cho dự án; Claude lưu ngữ cảnh hữu ích vào bộ nhớ tự động.

Nhật ký thay đổi gắn thẻ phiên bản ghi nhận tính năng lưu và quản lý tự động thông qua /memory trong phiên bản 2.1.59. Vì vậy, bộ nhớ tự động có vai trò riêng, khác với các chỉ dẫn bạn chủ động duy trì trong CLAUDE.md hoặc AGENTS.md.

Khi quyết định nên đặt thông tin ở đâu, hãy dựa vào sự khác biệt về người viết nội dung. Đặt các lệnh dựng cụ thể, quy ước, ghi chú kiến trúc và quy tắc quy trình làm việc trong các tệp chỉ dẫn. Sử dụng /memory để quản lý ngữ cảnh hữu ích mà Claude tự động lưu.

Những điểm chính

• CLAUDE.md chứa các chỉ dẫn Markdown lâu dài mà Claude Code đọc vào ngữ cảnh; tệp này không thực thi cấu hình.
• Claude Code 2.1.277 bổ sung cơ chế dự phòng có điều kiện cho AGENTS.md , trong đó Bedrock, Vertex và Foundry bị loại trừ tại thời điểm phát hành.
• Một tệp ở thư mục cấp trên CLAUDE.md, .claude/CLAUDE.md, hoặc CLAUDE.local.md sẽ vô hiệu hóa cơ chế dự phòng mặc định.
• Đặt Chỉ dẫn dự án thành claude-md-and-agents-md để tải cả hai nhóm chỉ dẫn.
• Trong v2.1.277, các tùy chọn plugin thuộc về cài đặt người dùng, một tệp --settings , hoặc cài đặt được quản lý—không thuộc về .claude/settings.json.
• Thư mục .claude của dự án. Thư mục này cũng chứa cài đặt, lệnh, tác tử phụ và kỹ năng; bộ nhớ tự động chứa ngữ cảnh do Claude lưu.

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

CLAUDE.md là gì?

CLAUDE.md là một tệp Markdown văn bản thuần chứa các chỉ dẫn lâu dài cho Claude Code, chẳng hạn như lệnh dựng, quy ước lập trình, ghi chú kiến trúc và quy tắc quy trình làm việc. Claude đọc tệp này vào ngữ cảnh phiên, và /init có thể tạo một tệp khởi đầu dựa trên dự án.

Tệp nào được tải khi cả CLAUDE.md và AGENTS.md đều tồn tại?

Trong Claude Code 2.1.277, với cấu hình mặc định của claude-md-or-agents-md chế độ, một tệp hướng dẫn Claude đáp ứng điều kiện sẽ ngăn việc dùng AGENTS làm phương án dự phòng. Chọn claude-md-and-agents-md để tải cả hai, hoặc nhập các chỉ dẫn AGENTS nằm cạnh bằng @AGENTS.md bên trong CLAUDE.md.

Tại sao việc thêm CLAUDE.local.md lại ngăn cơ chế dự phòng AGENTS?

Phiên bản 2.1.277 đưa CLAUDE.local.md vào nhóm tệp vô hiệu hóa cơ chế dự phòng mặc định khi được tìm thấy trên đường dẫn từ thư mục gốc của hệ thống tệp đến thư mục làm việc. Vì vậy, sự hiện diện của tệp này có thể thay đổi việc các chỉ dẫn AGENTS dùng chung có được tải hay không, dù mục đích của nó là cung cấp hướng dẫn cá nhân cho dự án.

Tôi có thể bật cả hai tệp trong .claude/settings.json của dự án không?

Trong v2.1.277, tệp .claude/settings.json của dự án không cung cấp các tùy chọn plugin agents-md . Sử dụng /config, hoặc đặt cấu hình pluginConfigs được mô tả trong tài liệu vào cài đặt người dùng, một tệp --settings , hoặc cài đặt được quản lý.