무슨 일이 있었냐면
한 개발자가 이상한 현상을 발견했어요. Claude Code에 AGENTS.md 파일을 만들어 놨는데, 텔레메트리(사용 데이터 수집)를 꺼둔 환경에서는 그 파일을 전혀 읽지 않더라는 거예요. 텔레메트리를 켜면 읽고, 끄면 안 읽고. 프라이버시를 신경 써서 데이터 전송을 막아둔 사람일수록 기능을 못 받는 아이러니한 상황이었죠. 이 내용을 정리한 글이 올라왔고, Anthropic 쪽에서 이미 수정을 내놓은 상태예요.
버그 자체는 고쳐졌지만, 이 사건이 보여주는 구조적인 문제는 한 번 짚어볼 가치가 있어요. 우리가 만드는 제품에서도 똑같은 실수를 하기 쉽거든요.
AGENTS.md가 뭐냐면
먼저 배경부터요. AI 코딩 에이전트에게 「이 프로젝트는 이렇게 빌드하고, 테스트는 이렇게 돌리고, 코드 스타일은 이렇다」 같은 정보를 알려주는 파일이 있어요. Claude Code는 처음부터 CLAUDE.md라는 파일을 썼고, Cursor는 .cursorrules, Gemini CLI는 GEMINI.md 하는 식으로 도구마다 제각각이었죠. 프로젝트 하나에 설정 파일이 대여섯 개 생기는 게 불편하니까, 도구를 가리지 않는 공통 이름으로 AGENTS.md라는 규약이 등장했어요. OpenAI의 Codex에서 시작해서 여러 도구가 채택했고, Claude Code도 이 파일을 지원하기 시작했고요.
그러니까 사용자 입장에서는 「AGENTS.md 하나만 두면 어떤 도구를 써도 알아서 읽어가겠지」라고 기대하는 게 당연해요. 그런데 그 기대가 특정 환경에서만 깨지고 있었던 거예요.
왜 텔레메트리와 엮였을까요
원인은 기능 플래그였어요. 이게 뭐냐면, 새 기능을 코드에 넣어두되 서버에서 내려주는 스위치로 켜고 끄는 방식이에요. 일부 사용자에게만 먼저 열어보고 문제 없으면 전체로 넓히는, 이른바 점진적 롤아웃에 쓰이죠. 웹 서비스에서는 아주 흔한 기법이에요.
Claude Code도 AGENTS.md 지원을 이런 원격 플래그 뒤에 넣어뒀던 걸로 보여요. 문제는 이 플래그를 가져오는 통신이 텔레메트리와 같은 「부가 트래픽」 묶음으로 취급됐다는 점이에요. 사용자가 데이터 수집을 끄는 환경변수를 설정하면 플래그 조회까지 같이 꺼지고, 서버에서 값을 못 받아온 플래그는 기본값인 「꺼짐」으로 남게 되죠. 결과적으로 AGENTS.md를 읽는 코드가 있는데도 실행되지 않았던 거예요.
재현하는 방법은 단순했어요. AGENTS.md에 「응답 첫 줄에 특정 단어를 넣어라」 같은 티 나는 지시를 적어두고, 환경변수를 바꿔가며 Claude Code를 실행해서 그 단어가 나오는지 확인하는 거죠. 이런 식의 간단한 실험이 없었다면 「AGENTS.md가 잘 안 먹네」 하고 넘어갔을 사람이 많았을 거예요.
업계 흐름에서 보면
이건 Claude Code만의 문제가 아니에요. VS Code도 실험 기능을 원격 설정으로 관리하고, 많은 SaaS 도구가 Statsig나 LaunchDarkly 같은 서비스로 플래그를 내려받아요. 웹에서는 자연스러운 방식인데, 개발자 로컬 환경에서 돌아가는 CLI 도구에 적용하면 상황이 달라져요. 같은 버전을 설치했는데 회사 방화벽 안에 있는 사람과 밖에 있는 사람의 동작이 다르고, 에어갭(외부망 차단) 환경에서는 영영 새 기능을 못 받는 일이 생기거든요.
여기서 설계 원칙 하나가 나와요. 플래그를 못 받아왔을 때 기본값을 「꺼짐」으로 둘지 「켜짐」으로 둘지, 그리고 텔레메트리 옵트아웃과 기능 설정 조회를 같은 스위치로 묶어도 되는지를 처음부터 분리해서 생각해야 해요. 이번 경우처럼 프라이버시를 선택한 사용자가 벌을 받는 구조는 신뢰를 갉아먹거든요.
한국 개발자에게 주는 시사점
팀에서 Claude Code를 쓰고 있다면 두 가지를 확인해 보세요. 하나는 최신 버전으로 업데이트했는지, 다른 하나는 보안 정책 때문에 걸어둔 환경변수가 무엇인지예요. 특히 금융권이나 대기업처럼 외부 통신을 제한하는 곳은 이런 류의 문제를 가장 먼저 겪게 돼요. 당분간은 CLAUDE.md와 AGENTS.md를 같이 두거나, CLAUDE.md에서 AGENTS.md를 참조하도록 해두는 게 안전한 전략이에요.
그리고 직접 제품을 만드는 입장이라면, 원격 플래그를 도입할 때 오프라인 기본값을 꼭 정해두세요. 「서버에 못 붙으면 마지막으로 받은 값을 쓴다」든지 「안정화된 기능은 플래그를 걷어내고 코드에 박는다」든지 하는 규칙이 있어야 이런 사고를 막을 수 있어요.
정리하면
원격 기능 플래그와 텔레메트리 옵트아웃을 한 스위치에 묶어두면, 프라이버시를 선택한 사용자가 기능을 잃는다. 여러분 팀에서는 기능 플래그를 어떻게 관리하고 계세요? 오프라인이나 폐쇄망 환경까지 고려한 기본값 정책이 있으신가요?
🔗 출처: Hacker News