Claude Code, telemetry 비활성화 시 AGENTS.md 로드 실패 및 우회책

문제 현상 및 원인

Claude Code 2.1.277에서 도입된 AGENTS.md 지원 기능이 telemetry 비활성화 시 정상 동작하지 않는 것으로 확인됐다. 이는 내장 플러그인의 가용성이 원격 feature flag(tengu_agents_md_mod)에 의존하기 때문이다. 플래그를 가져오지 못하면 기본값(false)으로 설정되어 로컬 파일 읽기 시도조차 하지 않는다. DISABLE_TELEMETRY=1 또는 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 환경 변수가 설정된 경우, Bedrock, Vertex 등 타 플랫폼에서도 동일하게 발생하며 아무런 경고 없이 프로젝트 지침이 무시된다.

검증 및 영향

저자는 canary word를 포함한 테스트를 통해 이 문제를 재현했다. 대부분의 사용자는 파일이 로드되지 않은 것을 모른 채 모델이 지시를 무시한 것으로 오해하여 프롬프트 디버깅에 시간을 낭비한다. 특히 프라이버시 보호를 위해 telemetry를 끈 사용자나 다중 에이전트 관리자가 주요 피해자다. Anthropic은 staged rollout을 위해 원격 플래그를 사용했으나, 로컬 파일 읽기가 네트워크 상태에 종속되는 설계는 부적절하다는 비판이 제기됐다.

우회책 및 권장 사항

현재 가장 확실한 우회책은 CLAUDE.md를 생성하고 @AGENTS.md를 import하는 것이다. 이 방식은 원격 플래그에 의존하지 않으므로 telemetry 비활성화 상태에서도 정상 작동한다. 다만, AGENTS.md 지원으로 제거하려던 추가 파일(CLAUDE.md)을 다시 만들어야 하는 번거로움이 있다. 또한, Codex와 달리 Claude Code는 user-level AGENTS.md나 shared skills(.agents/skills)를 네이티브로 지원하지 않으므로, symlink나 /import 명령을 활용해 수동으로 동기화해야 한다.