Claude Code chỉ đọc file AGENTS.md khi bật Telemetry: Giải pháp thay thế từ cộng đồng

Claude Code 2.1.277 đã thông báo hỗ trợ AGENTS.md. Trong một dự án không có CLAUDE.md, nó được cho là sẽ đọc AGENTS.md thay thế. Tôi luôn tắt telemetry trong shell của mình, và trong các repo của tôi, tệp này không bao giờ được tải. Vấn đề #95690 giải thích lý do tại sao, và tôi đã thêm các phép đo của riêng mình vào đó. Bài viết này tập hợp chúng lại tại một nơi.

Cổng kiểm soát nằm ở đâu

Trình tải được phân phối dưới dạng một plugin tích hợp có tên là agents-md. Việc đăng ký của nó trong gói 2.1.280 trông như thế này:

var W = !1;
var B = () => Oa("tengu_agents_md_mod", W);
var H =
  "AGENTS.md as project instructions: by default loaded where the project has no CLAUDE.md; ...";

W là giá trị isOnByDefault của plugin và nó là false. B là isAvailable, và nó truy vấn một cờ tính năng từ xa có tên là tengu_agents_md_mod, với giá trị mặc định là false. Khi Claude Code không thể lấy được cờ này, plugin sẽ không khả dụng và tệp cục bộ không bao giờ được đọc. Việc đọc một tệp markdown từ thư mục làm việc không cần mạng, nhưng ở đây nó lại phụ thuộc vào một công tắc phía máy chủ.

Cách tôi kiểm thử

Tôi tạo một thư mục trống chỉ chứa một tệp AGENTS.md với một từ khóa kiểm thử (canary word) bên trong, và yêu cầu claude -p từ khóa đó. Mỗi thiết lập được chạy trong hai phiên, vì phiên đầu tiên trong một cấu hình mới chỉ thực hiện việc lấy cờ và phiên thứ hai mới sử dụng nó.

echo 'The canary word is PERIWINKLE.' > AGENTS.md
claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.'

Những gì tôi đã đo lường

• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 chặn tính năng này, như vấn đề đã nêu.
• DISABLE_TELEMETRY=1 cũng chặn nó. Với bất kỳ biến nào được thiết lập, AGENTS.md không bao giờ được tải, vì vậy tôi phải xóa cả hai.
• Việc đặt bất kỳ biến nào thành 0 cũng không giúp ích gì. Khối chặn vẫn tồn tại. Tài liệu về biến môi trường nói rằng bất kỳ giá trị nào cũng được tính, nhưng điều đó rất dễ bị bỏ qua khi bạn cố gắng bật một tính năng.
• Một khối env trong tệp.claude/settings.json của dự án giúp xóa cả hai biến cũng không có tác dụng. Không có cách nào để bật tính năng này cho một repo đơn lẻ.
• Một ghi đè ở cấp độ phiên làm việc có hiệu quả từ phiên thứ hai trở đi:

claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}'

Không trường hợp nào trong số này in ra cảnh báo. Phiên làm việc bắt đầu, mô hình trả lời mà không có các hướng dẫn của dự án, và không có gì thông báo cho bạn rằng một tệp đã bị bỏ qua. Vấn đề cũng chỉ ra rằng các cổng kết nối của bên thứ ba, Bedrock và Vertex cũng gặp vấn đề tương tự, vì cờ này cũng không thể phân giải thành true ở đó.

Giải pháp thay thế

CLAUDE.md hỗ trợ các lệnh nhập @path, và chúng không phụ thuộc vào cờ này. Một tệp CLAUDE.md một dòng đặt cạnh AGENTS.md sẽ tải nó với telemetry đã tắt:

echo '@AGENTS.md' > CLAUDE.md

Với tệp đó, cùng một bài kiểm tra canary trả về từ khóa ngay cả khi CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 vẫn được thiết lập. Cái giá phải trả là thêm một tệp cho mỗi repo, điều mà sự hỗ trợ AGENTS.md lẽ ra phải loại bỏ.

Tại sao tôi nghĩ điều này là không thể chấp nhận được

Tôi đã tắt telemetry một cách có chủ đích và tôi mong đợi lựa chọn đó chỉ ảnh hưởng đến việc chẩn đoán chứ không gì khác. Ở đây, nó âm thầm khiến tôi mất đi một tính năng đọc tệp từ chính ổ đĩa của mình. Một cờ từ xa có thể hợp lý cho một tính năng giao tiếp với máy chủ, nhưng dữ liệu đầu vào duy nhất mà tính năng này cần đã nằm sẵn trong thư mục làm việc.

Cổng kiểm soát này cũng ảnh hưởng đến những người quan tâm nhất đến AGENTS.md. Một người giữ một tệp hướng dẫn cho nhiều tác nhân thường rất cẩn thận về những gì mỗi công cụ gửi về nhà, và các nhóm sử dụng Bedrock, Vertex hoặc cổng kết nối thường vô hiệu hóa lưu lượng không thiết yếu theo chính sách. Tất cả họ đều nhận được một tính năng được thông báo là khả dụng nhưng sau đó lại không hoạt động.

Sự im lặng là phần tồi tệ nhất. Tôi đã xác nhận nguyên nhân bằng từ khóa canary và tìm kiếm chuỗi trong tệp nhị phân, và hầu hết mọi người sẽ không làm điều đó. Họ sẽ kết luận rằng mô hình bỏ qua hướng dẫn của họ, và họ sẽ lãng phí thời gian vào các câu lệnh (prompt) trong khi tệp tin chưa bao giờ đến được mô hình ngay từ đầu.

Một cài đặt quyền riêng tư không bao giờ nên âm thầm tắt các hành vi cục bộ không liên quan. Nếu Anthropic muốn triển khai theo giai đoạn, phương án dự phòng cho một cờ không thể lấy được nên là hành vi đã được ghi nhận, hoặc ít nhất là một thông báo hiển thị cho biết những gì đã bị bỏ qua và lý do tại sao.

Những gì tôi muốn thấy

• Việc đọc tệp cục bộ không nên phụ thuộc vào telemetry. Nếu cổng kiểm soát phải tồn tại để triển khai dần dần, một cảnh báo khởi động khi AGENTS.md hiện diện và bị bỏ qua sẽ giúp mọi người tiết kiệm thời gian mà tôi đã dành cho bài kiểm tra canary.
• Một tệp AGENTS.md toàn cục. Plugin chỉ tìm kiếm AGENTS.md và.claude/AGENTS.md trong các thư mục dự án, và không có tệp cấp người dùng nào bên cạnh tệp CLAUDE.md của người dùng. Codex đọc một tệp toàn cục ~/.codex/AGENTS.md, và lệnh /import trong Claude Code có thể sao chép nó vào CLAUDE.md của người dùng, nhưng bản sao đó không cập nhật theo các chỉnh sửa sau này. Nếu bạn giữ một bộ hướng dẫn cá nhân cho nhiều tác nhân, bạn vẫn cần một lệnh nhập @ trong CLAUDE.md của người dùng để trỏ đến tệp dùng chung.
• Hỗ trợ gốc cho các kỹ năng tác nhân dùng chung. Codex đọc các kỹ năng từ.agents/skills trong dự án và từ ~/.agents/skills trong thư mục home. Claude Code 2.1.280 chỉ biết các đường dẫn đó trong /import, lệnh này sao chép các kỹ năng vào.claude/skills. Tôi đã đặt một kỹ năng canary vào.agents/skills và Claude Code không liệt kê nó, nhưng nó lại liệt kê cùng kỹ năng đó từ.claude/skills trong cùng repo. Một bản sao sẽ bị lệch so với nguồn, vì vậy tôi liên kết (symlink).claude/skills tới../.agents/skills thay thế, và Claude Code tuân theo liên kết đó.

Cho đến lúc đó, tôi sử dụng tệp CLAUDE.md một dòng cho các hướng dẫn và một liên kết tượng trưng (symlink) cho các kỹ năng.