AI 코딩 도구가 프로젝트 루트의 설정 파일을 읽어 작업 지침을 반영하는 것은 이제 기본 기능처럼 여겨진다. Claude Code도 2.1.277 버전에서 AGENTS.md 지원을 추가했다. CLAUDE.md가 없는 프로젝트라면 대신 AGENTS.md를 읽어 지침으로 삼겠다는 것이다. 여러 에이전트 도구가 공통 규격으로 수렴하는 흐름을 생각하면 반가운 변화다. 그러나 한 개발자가 실제로 측정해 보니, 이 로더는 로컬 파일을 읽는 단순한 기능임에도 원격 기능 플래그(feature flag) 뒤에 숨어 있었다. 텔레메트리나 비필수 트래픽을 꺼 둔 환경에서는 같은 디렉터리에 놓인 AGENTS.md가 아무런 경고 없이 그냥 무시됐다.
로컬 파일이 서버 스위치를 기다린다
문제의 구조는 이렇다. AGENTS.md를 읽는 기능은 agents-md라는 내장 플러그인 형태로 배포되는데, 이 플러그인의 기본 활성화 값(isOnByDefault)은 false다. 사용 가능 여부를 판단하는 isAvailable 로직은 tengu_agents_md_mod라는 원격 플래그를 조회하며, 값을 가져오지 못하면 false로 처리한다. 즉 Claude Code가 어떤 이유로든 이 플래그를 서버에서 받아오지 못하면 플러그인은 '사용 불가' 상태가 되고, 로컬 파일은 끝내 읽히지 않는다. 작업 디렉터리에 있는 마크다운 파일을 읽는 데는 네트워크가 전혀 필요 없는데도, 그 동작이 서버 측 스위치에 묶여 있는 셈이다.
측정 방식도 분명하다. 개발자는 AGENTS.md 파일 하나만 든 빈 디렉터리를 만들고 그 안에 식별용 단어(canary word)를 넣은 뒤, claude -p로 그 단어를 물었다. 각 설정은 두 번의 세션으로 나눠 실행했는데, 새 구성에서의 첫 세션은 플래그를 가져오기만 하고 두 번째 세션이 그 값을 사용하기 때문이다. 텔레메트리를 끈 상태에서는 어떤 경우에도 경고가 출력되지 않았다. 세션은 정상적으로 시작되고, 모델은 프로젝트 지침 없이 답변하며, 파일이 건너뛰어졌다는 사실을 알리는 신호는 어디에도 없었다. 같은 문제는 서드파티 게이트웨이, Bedrock, Vertex 환경에도 적용된다. 이들 경로에서는 플래그가 true로 해석될 수 없기 때문이다.
우회책과 그 대가
다행히 실무적인 우회 방법은 있다. CLAUDE.md는 @path 형식의 임포트를 지원하고, 이 임포트는 문제의 플래그에 의존하지 않는다. AGENTS.md 옆에 그것을 불러오는 한 줄짜리 CLAUDE.md를 두면, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1을 그대로 유지한 채로도 canary 테스트가 단어를 정상 반환한다. 다만 대가는 저장소마다 파일 하나가 더 늘어난다는 것이다. 원래 AGENTS.md 지원이 없애 주려던 바로 그 중복이다. 이 개발자는 당분간 지침은 한 줄짜리 CLAUDE.md로, 스킬은 심볼릭 링크로 처리하고 있다고 밝혔다.
한국 실무자 관점에서 이 사례의 핵심은 프라이버시 설정이 무관한 로컬 동작을 조용히 꺼 버렸다는 점이다. 서버와 통신하는 기능이라면 원격 플래그로 단계적 배포를 제어하는 것이 타당하다. 그러나 이 기능이 필요로 하는 입력은 이미 작업 디렉터리 안에 전부 존재한다. 텔레메트리를 끈 사용자는 진단 정보 일부를 포기하는 것까지는 예상하지만, 자기 디스크의 파일을 읽는 기능까지 잃으리라고는 생각하지 않는다.
더 나쁜 것은 이 실패가 침묵한다는 사실이다. 하필 AGENTS.md에 신경 쓰는 사람일수록 각 도구가 무엇을 외부로 보내는지 민감하게 관리하는 경향이 있고, Bedrock·Vertex·게이트웨이를 쓰는 팀은 정책상 비필수 트래픽을 꺼 두는 경우가 많다. 기능이 '사용 가능하다'고 공지됐지만 정작 아무 일도 하지 않는 상황을 바로 이들이 겪게 되는 것이다. 대부분의 사용자는 바이너리 문자열 검색이나 canary 단어로 원인을 확인하지 않는다. 그들은 모델이 지침을 무시한다고 결론짓고, 파일이 애초에 모델에 도달하지도 못했다는 사실을 모른 채 프롬프트를 손보는 데 시간을 쓰게 된다.
결국 이 문제는 개발 도구 설계에서 반복적으로 지적되는 원칙을 다시 소환한다. 단계적 롤아웃이 필요하더라도, 플래그를 가져오지 못했을 때의 기본 동작은 문서화된 정상 동작이 되거나, 최소한 무엇이 왜 건너뛰어졌는지 알리는 눈에 보이는 메시지여야 한다는 것이다. 지침 파일이 반영되지 않는 원인을 도구 안쪽에서 조용히 삼켜 버리면, 그 비용은 고스란히 사용자의 디버깅 시간으로 전가된다. 이번 이슈는 이후 수정된 것으로 정리됐지만, 원격 플래그로 로컬 기능을 게이팅할 때 어떤 실패 모드가 생기는지 보여 주는 좋은 사례로 남는다.