텔레메트리를 끄면 Claude Code는 AGENTS.md를 조용히 건너뛰었습니다 — 2.1.281에서 고친 것과 남은 것

1. 핵심 요약

붙은 번호는 본문 끝 참고자료의 번호입니다. 모든 인용과 수치는 2026-09-24에 원문에서 확인했습니다.

2. 무슨 일이 있었나

Claude Code에서 AGENTS.md를 읽는 일은 본체가 아니라 내장 플러그인 agents-md가 맡습니다. 이 플러그인은 세션이 시작될 때 작업 디렉터리와 상위 디렉터리에서 AGENTS.md를 찾아, CLAUDE.md와 같은 자리에 프로젝트 지침으로 넣습니다. 아래 시각은 npm 레지스트리·GitHub·Hacker News에 기록된 UTC 시각입니다.

첫 보고는 문제의 조건을 정확히 짚었습니다. 이슈 #95690은 텔레메트리 트래픽을 끄거나 서드파티 게이트웨이·Bedrock·Vertex를 거치면 이 스위치가 true로 평가될 수 없고, "오류도 경고도 없이 그냥 로드되지 않는다"고 적었습니다. 다만 이슈는 그 스위치를 Statsig 게이트(Statsig라는 서비스로 관리하는 기능 스위치)라고 적었는데, 실행 파일 속 플래그 클라이언트와 공식 문서는 GrowthBook이라고 적고 있습니다. GrowthBook은 기능 플래그를 서버에서 내려주는 서비스입니다. [2] [5]

원문 저자는 이것을 직접 측정했습니다. AGENTS.md 하나만 든 빈 디렉터리에 카나리아 단어 — 그 파일에만 적어 둔, 다른 데서는 알 수 없는 단어 — 를 넣고 claude -p로 그 단어를 물었습니다. DISABLE_TELEMETRY와 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 가운데 하나라도 켜져 있으면 파일이 읽히지 않았고, 값을 0으로 줘도 마찬가지였으며, 어느 경우에도 경고가 나오지 않았다고 적었습니다. [1]

HN 게시 약 40분 뒤, 이 플러그인을 Anthropic 저장소에 커밋한 사람으로 보이는 개발자가 댓글을 달았습니다(HN 계정과 커밋한 GitHub 계정이 소개란에 같은 개인 도메인을 적었습니다) — "단계적 배포(롤아웃)의 부산물입니다. 문제가 생기면 기능 플래그로 원격에서 끌 수 있어야 했는데, 텔레메트리를 끄면 그 플래그를 받지 못합니다. 오늘 나오는 2.1.281에서 이미 고쳤습니다. … 전적으로 제 실수입니다. 킬 스위치를 달고 출시하는 더 나은 방법을 찾았어야 했습니다." 킬 스위치는 문제가 생겼을 때 이미 배포한 기능을 원격에서 끄는 스위치입니다. [8]

변경 로그의 2.1.281 항목에는 이 수정이 없습니다. 이슈는 2026-09-24 현재 열려 있고, Anthropic 쪽 답변은 달리지 않았습니다. [3] [2]

3. 어디서 꺼졌나 — 코드

변경 전후를 가리려고 npm에서 macOS(Apple Silicon)용 실행 파일 2.1.276·2.1.277·2.1.278·2.1.280·2.1.281을 받아 대조했습니다(2.1.279는 배포되지 않았습니다). Claude Code는 자바스크립트를 한 파일로 묶은 실행 파일이라, 축약된 코드가 문자열로 들어 있습니다. [6]

플러그인의 "쓸 수 있는가" 판단

내장 플러그인은 자신이 활성화될 수 있는지를 직접 판단합니다. 2.1.280과 2.1.281의 해당 부분을 축약된 그대로 옮깁니다.

// 2.1.280
var W=!1;var B=()=>Oa("tengu_agents_md_mod",W);

// 2.1.281
var W=!0;var B=()=>na("tengu_agents_md_mod",W);

!1은 false, !0은 true를 짧게 쓴 것입니다. W는 플러그인이 내보내는 isOnByDefault, B는 isAvailable입니다. Oa와 na는 축약 과정에서 이름만 달라진 같은 함수로, 기능 플래그 tengu_agents_md_mod의 값을 묻습니다. 기능 플래그는 이미 배포한 코드 안의 기능을 서버 설정으로 켜고 끄는 스위치입니다. 두 번째 인자 W는 서버 값을 쓸 수 없을 때 대신 돌려줄 플래그 기본값입니다.

플래그 값을 정하는 순서

이 함수가 호출하는 getFeatureValueWithSource는 두 버전에서 같습니다. 순서대로 옮기면 이렇습니다.

2단계의 예외는 문서에 없는 환경 변수 하나를 켰을 때뿐입니다. 그리고 Oa는 세션에서 처음 읽은 값을 끝까지 고정합니다(pinnedFeatureValues). 세션 도중에 서버 값이 도착해도 그 세션의 판단은 바뀌지 않습니다.

2.1.280까지는 2·4·6단계의 기본값이 false였습니다. 플래그 조회가 꺼진 세션에서는 서버에 묻지도 않고 곧바로 false가 나오고, 플러그인은 '쓸 수 없음'이 되며, AGENTS.md는 읽히지 않습니다. 2.1.281은 이 기본값을 true로 바꿨습니다. 두 버전의 플러그인 코드에서 짧은 식별자 이름을 지우고 구문 단위로 비교하면, 달라진 곳은 이 줄과 불러오는 모듈 목록뿐입니다. agents-md 플러그인 코드에서 동작을 바꾼 변경은 이 값 하나이고, 새 경고 문구는 추가되지 않았습니다. 2.1.277·2.1.278에는 플래그 앞에 조건이 하나 더 붙어 있었지만, 플래그 조회가 꺼진 세션에서 결과가 false인 것은 같습니다.

세 환경 변수는 같은 값도 서로 다르게 해석합니다

플래그 조회를 끄는 판단도 코드에 그대로 있습니다. 줄바꿈만 읽기 쉽게 넣었습니다.

function D(){
  if(process.env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC)return"essential-traffic";
  if(process.env.DISABLE_TELEMETRY)return"no-telemetry";
  if(De(process.env.DO_NOT_TRACK))return"no-telemetry";
  return"default"}

function De(e){if(!e)return!1;if(typeof e==="boolean")return e;
  let n=String(e).toLowerCase().trim();return["1","true","yes","on"].includes(n)}

앞의 두 변수는 '비어 있지 않은가'만 봅니다. 자바스크립트에서 문자열 "0"은 참이므로 DISABLE_TELEMETRY=0도 끈 것으로 읽힙니다. DO_NOT_TRACK만 De()를 거치는데, 이 함수는 1·true·yes·on만 참으로 읽습니다. 공식 문서도 같은 내용을 적어 두었습니다 — DISABLE_TELEMETRY는 "0이나 false로 설정해도 여전히 끈 것"이고, DO_NOT_TRACK은 "표준 불리언으로 읽으므로 0이면 켜진 것"입니다. [5]

공개 소스에는 이 기능 플래그가 없습니다

Anthropic은 anthropics/claude-code 저장소의 mods/agents-md에 이 플러그인의 소스를 공개했습니다. 그런데 저장소 전체를 검색해도 tengu_agents_md_mod는 한 번도 나오지 않습니다. 플래그는 공개되지 않은 등록 코드 쪽에 있고, 소스의 README는 "/plugin에서 끌 수 있다"고만 적었습니다. 공개 소스만 읽은 사람은 텔레메트리와의 관계를 알 수 없었습니다. [7]

4. 어떤 세션이 해당됐나

해당되는 세션은 공식 문서가 "플래그 조회를 건너뛰는 세션"으로 꼽은 세션과 설치 직후의 첫 세션입니다. "재현"이라고 적은 칸은 5장에서 저희가 직접 실행한 것이고, 나머지는 코드와 문서로 판단한 것입니다. [5]

CI는 두 조건에 함께 걸리기 쉽습니다. 러너가 매번 새 홈 디렉터리로 시작하니 모든 실행이 첫 세션이고, 비필수 트래픽을 끄는 설정도 흔합니다. 이슈 댓글 하나는 2.1.278을 새로 만든 홈 디렉터리에서 시험해 "설치 직후 첫 세션에서 건너뛰고, 플래그 조회를 끄면 매번 건너뛴다. CI 러너가 정확히 그렇다"고 보고했습니다. [2] 공식 GitHub Action(anthropics/claude-code-action)은 Claude Code 버전을 고정해서 설치합니다. @v1 태그는 2026-09-23 19:39(UTC) 커밋을 가리키고 이 커밋이 설치하는 버전은 2.1.281입니다. 그보다 앞선 커밋이나 v1.0.232 이하 릴리스로 고정해 두었다면 2.1.280 이하가 설치됩니다. [9]

원문 저자는 설정 파일로 이 문제를 비켜 갈 수 있는지도 시험했습니다. 프로젝트의 .claude/settings.json에 두 변수를 비우는 env 블록을 넣어도 소용이 없었고, 세션 단위로 claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}'를 주면 두 번째 세션부터 읽혔다고 적었습니다. 저자의 설명으로는 첫 세션이 플래그를 받아 오기만 하고 쓰지는 못하기 때문입니다. 이 두 가지는 저희가 재현하지 않았습니다. [1]

5. 직접 재현한 결과

원문 저자의 시험을 같은 방식으로 다시 했습니다. 2026-09-24, macOS(Apple Silicon)에서 npm의 공식 실행 파일 2.1.280과 2.1.281을 썼습니다. 빈 디렉터리에 The canary word is MARIGOLD. 한 줄만 적은 AGENTS.md를 두고, 원문과 같은 질문을 claude -p로 보냈습니다. 모델이 파일을 직접 열어 읽으면 시험이 무의미해지므로 --tools ""로 도구를 모두 껐습니다. 모델은 하이쿠(--model haiku)이고, 조합마다 한 번씩 실행했습니다. 사용자 수준의 ~/.claude/CLAUDE.md는 그대로 두었는데, 공식 문서상 이 파일은 "AGENTS.md를 대신 읽을지" 판단에 들어가지 않습니다. [4]

mkdir probe && cd probe
echo 'The canary word is MARIGOLD.' > AGENTS.md
DISABLE_TELEMETRY=1 claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.' \
  --model haiku --tools ""

열 가지 모두 코드로 예측한 결과와 같았습니다. 원문에 없던 내용이 두 가지 있습니다. 첫째, DO_NOT_TRACK=1도 같은 결과를 냈습니다. DO_NOT_TRACK은 여러 개발 도구가 함께 따르는 관례라 셸 설정에 넣어 두는 사람이 많습니다. 둘째, DO_NOT_TRACK=0은 읽혔고 DISABLE_TELEMETRY=0은 읽히지 않았습니다. 비슷해 보이는 두 변수가 0을 정반대로 해석합니다.

6. 2.1.281에서 바뀐 것과 남은 것

바뀐 것

플래그 기본값이 false에서 true로 바뀌었습니다. 그래서 플래그 조회가 꺼진 세션, 곧 텔레메트리를 끈 세션과 서드파티 제공자 세션에서도 AGENTS.md를 읽습니다. 공식 문서는 이렇게 적었습니다 — "2.1.281 이전에는 Amazon Bedrock이나 텔레메트리를 끈 세션 같은 일부 세션에서 CLAUDE.md 파일만 읽습니다. 그 버전이라면 Claude Code를 업데이트하세요." [4]

남은 것

• 킬 스위치는 그대로입니다. 플래그 조회가 되는 세션에서는 3장 표의 3단계, 곧 서버가 준 값이 먼저입니다. Anthropic이 이 플래그를 끄면 그 세션들은 다시 AGENTS.md를 읽지 않습니다. HN 댓글이 밝힌 설계 의도 그대로이고, 바뀐 것은 "서버에 물을 수 없을 때의 답"뿐입니다
• 건너뛸 때 알려 주지 않습니다. 새 경고 문구는 추가되지 않았습니다. 공식 문서가 적은 단서는 둘입니다. AGENTS.md를 읽으면 대화형 세션에 no CLAUDE.md found; AGENTS.md loaded: … 한 줄이 뜨고, 이 기능을 쓸 수 없는 세션에서는 /config에 Project instructions 항목이 나타나지 않습니다. 둘 다 대화형 화면의 단서라 claude -p 같은 비대화형 실행에서는 볼 곳이 없습니다 [4]
• 업그레이드 직후 첫 세션. 문서는 "2.1.276 이하에서 올린 뒤 첫 세션에서는 경우에 따라 읽지 않고, 다음 세션부터 읽는다"고 적었습니다 [4]
• 기록이 한쪽에만 있습니다. 변경 로그의 2.1.281 항목에는 수정이 없고, 이슈는 열려 있습니다. 2.1.277 변경 로그만 읽은 사람은 텔레메트리 조건을 알 수 없었고, 2.1.281 변경 로그만 읽은 사람은 고쳐졌다는 것을 알 수 없습니다 [3]

7. 플래그 조회가 꺼지면 함께 영향을 받는 것

AGENTS.md는 2.1.281부터 이 문제에서 벗어났지만, 플래그 조회가 꺼진 세션에서 쓸 수 없거나 동작이 달라지는 기능은 아직 많습니다. 공식 문서가 꼽은 15가지입니다(2026-09-24 확인). 일부는 기본 동작만 바뀌거나 환경 변수로 예외를 둘 수 있습니다. [5]

대부분은 기능이 보이지 않는 정도지만, 마지막 두 가지는 동작이 달라집니다. 특히 마지막 것은 MCP 서버 하나의 스키마 문제가 요청 실패로 이어질 수 있다는 뜻입니다.

이 블로그는 9월 19일 ZCode 글에서 "Claude Code는 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1로 불필요한 트래픽을 끈다"고 적었습니다. 그 설정은 지금도 유효한 선택지입니다. 다만 그 대가가 위 목록이라는 것까지 알고 고르는 것이 맞고, 2.1.277~2.1.280에서는 AGENTS.md도 그 대가에 들어 있었습니다.

8. 체크리스트

1. claude --version으로 버전을 확인하고, 2.1.277~2.1.280이면 claude update로 2.1.281 이상으로 올린다. 2.1.276 이하라면 공식 문서 기준으로 AGENTS.md를 직접 읽는 기능이 아직 없다
2. CI·컨테이너처럼 버전을 고정한 곳을 따로 확인한다. anthropics/claude-code-action은 @v1이면 2.1.281을 설치하고, 그보다 앞선 커밋이나 v1.0.232 이하로 고정했다면 2.1.280 이하다
3. 버전을 바로 올릴 수 없으면 AGENTS.md 옆에 한 줄짜리 CLAUDE.md를 둔다 — echo '@AGENTS.md' > CLAUDE.md. @ 가져오기는 기능 플래그와 무관하게 동작하고, 공식 문서도 이 방법을 권한다. 나중에 남겨 두어도 AGENTS.md가 두 번 읽히지는 않는다
4. 텔레메트리 변수를 다시 켤 때는 0을 넣지 말고 변수를 지운다(unset DISABLE_TELEMETRY). 세 변수 가운데 0이 "켜짐"인 것은 DO_NOT_TRACK뿐이다
5. AGENTS.md가 실제로 모델에 전달되는지 카나리아 단어로 확인한다. 5장의 명령을 쓰되, 디렉터리 이름에 힌트가 없게 한다
6. 대화형 세션이라면 시작할 때 no CLAUDE.md found; AGENTS.md loaded: 줄이 보이는지, /config에 Project instructions가 있는지 본다
7. AGENTS.md와 함께 CLAUDE.md나 CLAUDE.local.md가 있으면 기본 설정에서는 AGENTS.md를 읽지 않는다. 둘 다 읽히려면 Project instructions를 claude-md-and-agents-md로 바꾸거나 CLAUDE.md에 @AGENTS.md를 넣는다. 이 설정은 ~/.claude/settings.json·--settings·관리 설정에서만 적용되고, 프로젝트의 .claude/settings.json에서는 무시된다
8. 텔레메트리를 끄기로 했다면 7장의 15가지가 함께 영향을 받는다는 것을 알고 고른다
9. 기능 플래그를 쓰는 제품을 만든다면, 발표한 기능의 플래그 기본값은 발표한 동작과 같게 두고, 로컬 파일을 건너뛸 때는 한 줄이라도 알린다

9. 아직 결론이 아닌 것

• 재현은 한 환경에서, 조합마다 한 번씩 했습니다. macOS(Apple Silicon), 하이쿠 모델, 2026-09-24입니다. Linux·Windows와 다른 모델은 확인하지 않았습니다. 모델의 답은 지침이 전달됐는지를 보여 주는 간접 지표입니다
• 서드파티 제공자와 게이트웨이 세션은 실행해 보지 않았습니다. 4장의 해당 행은 코드와 공식 문서로 판단한 것입니다
• "첫 세션" 현상은 재현하지 않았습니다. 근거는 원문 저자, 이슈 댓글, 공식 문서입니다. 저희 대조군(2.1.280, 변수 없음)이 첫 실행부터 파일을 읽은 것은, 같은 컴퓨터에서 평소 쓰던 Claude Code가 플래그 값을 이미 디스크에 받아 두었기 때문으로 보입니다. 추정입니다
• 플래그 값은 서버가 정합니다. 계정과 시점에 따라 다를 수 있고, 저희가 본 것은 저희 계정의 값입니다
• 기능 플래그를 건 이유는 HN 댓글 하나로만 설명됐습니다. 변경 로그와 이슈에는 설명이 없습니다. 댓글 작성자가 이 플러그인의 커밋 작성자라는 것은 HN 계정과 GitHub 계정이 소개란에 같은 개인 도메인(code.lol)을 적은 것으로 판단했습니다
• DISABLE_GROWTHBOOK와 원문 저자의 설정 파일 실험은 재현하지 않았습니다
• 코드 해석은 저희의 것입니다. 축약된 실행 파일에서 읽었으므로 함수 이름이 버전마다 다르고, 같은 이름의 함수가 여러 개 있습니다. 결론에 쓴 부분은 5장의 실행 결과로 한 번 더 확인했습니다
• 2.1.281 이후는 보지 않았습니다. 2026-09-24 현재 npm의 최신 버전이 2.1.281입니다. 이후 버전에서 구조가 다시 바뀔 수 있습니다

10. 참고자료

편집 기준: 개발사 문서·변경 로그의 문장, 저희가 실행 파일에서 확인한 코드, 저희가 직접 실행한 결과를 구분해 적었습니다. 이슈와 HN 댓글은 커뮤니티 보고로 표시했습니다.