Claude Code chỉ đọc tệp AGENTS.md khi bật telemetry: cú lừa im lặng với người dùng quan tâm quyền riêng tư

Claude Code phiên bản 2.1.277 tuyên bố hỗ trợ tệp AGENTS.md — chuẩn hướng dẫn chung cho nhiều AI agent lập trình. Theo tài liệu, nếu một dự án không có tệp CLAUDE.md, công cụ sẽ tự động đọc AGENTS.md thay thế. Nhưng trên thực tế, với những người dùng đã tắt telemetry, tệp này không bao giờ được tải.

Đây không phải lỗi ngẫu nhiên. Nguyên nhân được chỉ ra trong issue #95690, và một lập trình viên đã tự đo đạc lại để xác nhận. Kết quả cho thấy tính năng bị chặn sau một cờ tính năng từ xa (remote feature flag) do Anthropic kiểm soát — điều đáng lẽ không nên xảy ra với một thao tác hoàn toàn cục bộ.

Cơ chế đằng sau lỗi: một cờ từ xa điều khiển thao tác đọc tệp cục bộ

Trình tải AGENTS.md được đóng gói dưới dạng plugin tích hợp có tên agents-md. Trong bản bundle 2.1.280, đoạn mã đăng ký plugin cho thấy:

• Giá trị isOnByDefault của plugin là false — tức mặc định tắt.
• Hàm isAvailable gọi một cờ tính năng từ xa có tên tengu_agents_md_mod, với giá trị dự phòng cũng là false.

Nói cách khác: nếu Claude Code không thể truy vấn cờ này từ máy chủ Anthropic, plugin sẽ bị coi là không khả dụng và tệp AGENTS.md trong thư mục dự án sẽ bị bỏ qua hoàn toàn.

Điểm vô lý nằm ở chỗ: đọc một tệp markdown từ thư mục làm việc không cần đến mạng. Nhưng ở đây, thao tác đó lại phải chờ một công tắc phía máy chủ.

Kiểm chứng bằng từ khóa canary

Để xác minh, tác giả tạo một thư mục trống chỉ chứa AGENTS.md với một từ khóa đánh dấu (canary word), rồi yêu cầu Claude Code đọc từ đó mà không được phép mở tệp:

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.'

Mỗi cấu hình được chạy trong hai phiên, vì phiên đầu tiên chỉ dùng để lấy cờ từ xa, còn phiên thứ hai mới thực sự sử dụng nó. Kết quả đo được:

• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 chặn tính năng — đúng như issue mô tả.
• DISABLE_TELEMETRY=1 cũng chặn tính năng. Chỉ cần một trong hai biến này được đặt, AGENTS.md sẽ không bao giờ được tải.
• Đặt các biến này về 0 không giúp gì. Cơ chế chặn vẫn giữ nguyên. 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 này rất dễ bị bỏ qua khi bạn cố bật lại một tính năng.
• Khối env trong tệp .claude/settings.json của dự án để xóa hai biến này không có tác dụng. Không có cách nào bật tính năng cho riêng một kho mã nguồn.
• Chỉ có ghi đè ở cấp phiên mới hoạt động, và phải từ phiên thứ hai trở đi.

Đáng chú ý nhất: không trường hợp nào in ra cảnh báo. Phiên làm việc vẫn khởi động, mô hình vẫn trả lời mà không có hướng dẫn dự án, và không có gì cho bạn biết rằng một tệp đã bị bỏ qua. Issue cũng chỉ ra rằng các cổng kết nối bên thứ ba, Bedrock và Vertex gặp vấn đề tương tự, vì ở đó cờ tính năng cũng không thể trả về giá trị true.

Giải pháp tạm thời cho lập trình viên

Hiện tại, cách vượt qua đơn giản nhất là tận dụng cơ chế nhập tệp @path của CLAUDE.md — vốn không phụ thuộc vào cờ từ xa. Chỉ cần tạo một tệp CLAUDE.md một dòng nằm cạnh AGENTS.md:

echo '@AGENTS.md' > CLAUDE.md

Với tệp này, bài kiểm tra canary trả về đúng từ khóa ngay cả khi CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 vẫn được đặt. Cái giá phải trả là thêm một tệp cho mỗi kho mã nguồn — đúng thứ mà tính năng hỗ trợ AGENTS.md được kỳ vọng sẽ loại bỏ.

Vì sao đây là vấn đề nghiêm trọng

Tác giả bài viết đặt vấn đề thẳng thắn: anh tắt telemetry một cách có chủ đích, và chấp nhận mất một số tính năng chẩn đoán, chứ không phải mất 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ý với tính năng cần giao tiếp máy chủ, nhưng đầu vào duy nhất của tính năng này đã nằm sẵn trong thư mục làm việc.

Cơ chế chặn này còn ảnh hưởng nặng nhất đến đúng nhóm người dùng quan tâm đến AGENTS.md:

• Người dùng giữ một tệp hướng dẫn dùng chung cho nhiều agent thường rất cẩn trọng về dữ liệu mà mỗi công cụ gửi đi.
• Các nhóm dùng Bedrock, Vertex hoặc gateway thường vô hiệu hóa lưu lượng không thiết yếu theo chính sách bảo mật nội bộ.

Tất cả những nhóm này đều nhận được một tính năng được quảng cáo là khả dụng, nhưng thực tế không làm gì cả — và im lặng là phần tệ nhất. Người dùng phổ thông sẽ không kiểm chứng bằng từ khóa canary hay tìm chuỗi trong tệp nhị phân. Họ sẽ kết luận rằng mô hình phớt lờ hướng dẫn của mình, rồi dành thời gian tinh chỉnh prompt — trong khi tệp hướng dẫn chưa từng đến được mô hình.

Đề xuất cải thiện

Bài viết đưa ra ba kiến nghị cụ thể:

• Đọc tệp cục bộ không nên phụ thuộc vào telemetry. Nếu buộc phải giữ cờ để triển khai dần, ít nhất hãy hiển thị cảnh báo lúc khởi động khi có AGENTS.md bị bỏ qua.
• Hỗ trợ AGENTS.md toàn cục. Plugin hiện chỉ tìm AGENTS.md và .claude/AGENTS.md trong thư mục dự án, không có tệp cấp người dùng. Trong khi đó, Codex đọc tệp ~/.codex/AGENTS.md toàn cục.
• Hỗ trợ gốc cho kỹ năng agent dùng chung. Codex đọc skill từ .agents/skills trong dự án và ~/.agents/skills trong thư mục home. Claude Code 2.1.280 chỉ biết các đường dẫn này qua lệnh /import, vốn sao chép skill vào .claude/skills — và bản sao sẽ lệch khỏi bản gốc theo thời gian.

Trước mắt, tác giả dùng tệp CLAUDE.md một dòng cho hướng dẫn và tạo symlink cho skill. Với người dùng Việt Nam đang làm việc với Claude Code trong các dự án đa agent, đây là mẹo đáng lưu ý — đặc biệt nếu bạn thuộc nhóm phải tắt lưu lượng không thiết yếu vì lý do bảo mật hoặc tuân thủ.

Một thiết lập quyền riêng tư không bao giờ nên âm thầm tắt đi những hành vi cục bộ không liên quan.