도구

Claude Code의 AGENTS.md, 텔레메트리 켜져 있을 때만 읽혀 — Anthropic가 이미 패치

Claude Code가 프로젝트 레벨 AGENTS.md를 제대로 읽는지가 텔레메트리 토글에 따라 갈렸다. HN에서 374표를 받은 이 이슈는 AI 코딩 도구에서 텔레메트리와 기능 동작이 보이지 않게 결합되는 구조적 문제를 드러낸다.

글자 크기

개발자가 telemetry를 끈 이유는 단순하다. "데이터를 좀 덜 올려보내려고". 그런데 그 결과, 잘 정리해둔 AGENTS.md — Claude Code가 프로젝트 레벨 지시 파일로 읽어줘야 할 바로 그 파일 — 이 완전히 무시당했다. szypowi.cz의 블로그 글에서 코드를 까보자, 문제는 더 민망해졌다. AGENTS.md를 읽는 로직이 telemetry 활성화 분기 안에 매달려 있었던 것이다.

Anthropic는 이미 수정했다. 이슈 자체는 크지 않지만, 여기서 드러나는 것은 엔지니어링 조직 차원의 문제다.

무슨 일이었나: AGENTS.md는 '설정'이 아니라 '텔레메트리 토글의 부산물'

시작은 평범했다. 누군가 Claude Code 프로젝트에 AGENTS.md를 두고, 모델에게 프로젝트 컨벤션, 코드 스타일, 커밋 습관 같은 지시를 주려고 했다. 파일은 에러를 내지 않았고, 로그도 멀쩡해 보였다. 그런데 모델은 AGENTS.md 내용을 완전히 모르는 것처럼 동작했다.

telemetry를 껐다가 다시 켜니, 파일이 제대로 적용됐다.

블로그 작성자 szymon은 이게 석연치 않아서 Claude Code 소스 코드를 뒤졌다. 결과: AGENTS.md를 읽는 코드 경로가 telemetry 토글과 실제로 결합되어 있었다. telemetry off → 파일 읽기 코드에 도달하지 못함.

이건 일반적인 버그 리포트에서 말하는 "오작동"이나 "엣지 케이스 누락"이 아니다. 코드 구조 수준에서 드러난 설계 이슈 — 너무 깊이 묻혀버린 부작용이다.

Anthropic은 피드백을 받고 패치했지만, 수정 자체가 곧 설명은 아니다. "왜 처음에 이렇게 작성했는지", "telemetry가 꺼져 있을 때 더 어떤 기능이 묵음 처리되는지"에 대한 공식 답은 없다. 그건 나중에 다루고, 먼저 왜 이 이슈가 HN에서 374점, 211개의 댓글을 받았는지 짚어보자.

HN 토론 링크: https://news.ycombinator.com/item?id=49814947

이 버그가 중요한 이유: 텔레메트리와 기능이 한 코드에 묶여 있다

관점을 "파일이 안 읽힌다"에서 "텔레메트리와 기능이 같은 코드 경로를 탄다"로 옮겨보자.

개발자가 telemetry를 끄는 전형적인 이유는 프라이버시다. 코드 스니펫, 프롬프트, 업로드한 파일이 서버로 넘어가는 것을 원치 않는다. 합리적인 선택이고, 기업 컴플라이언스 환경에서는 필수에 가깝다. 그런데 이걸 끄면, 프라이버시와는 전혀 관련 없어 보이는 "프로젝트 레벨 지시 파일 읽기"라는 기본 기능이 덩달아 꺼진다.

더 본질적인 문제는: 이런 사실을 제품 문서 어디에서도 알려주지 않는다.

Claude Code 설정 패널을 보면, telemetry는 그저 토글 하나다. 대부분 "데이터 수집 스위치" 정도로 해석한다. 거기엔 "동시에 프로젝트 설정 파일 읽기도 비활성화됩니다" 같은 문구가 없다. 이런 암묵적 결합은 신뢰를 갉아먹는다. Anthropic이 나쁜 의도를 가졌기 때문이 아니라, 개발자가 스위치를 켜기 전에 일련의 결과를 알 수 있는 통로 자체가 없기 때문이다.

비슷한 암묵적 의존이 이 한 군데뿐일 리 없다. 구체적인 사례는 아래에서.

AGENTS.md란 무엇이며, .cursorrules와는 어떤 관계인가

먼저 이 파일을 짚고 가자. AGENTS.md는 2025년 중반부터 확산된 컨벤션이다. 프로젝트 루트에 두고, AI Agent / AI 코딩 도구가 읽어들이는 프로젝트 레벨 지시 파일이다. 형식은 README.md를 본떴지만, 내용은 사람을 위한 게 아니라 모델을 위한 것이다.

대표적인 내용은 이런 식이다:

# AGENTS.md

## Build & Test
- pnpm install
- pnpm test

## Style
- 2-space indent
- No `any` in TypeScript
- Prefer composition over inheritance

## Don't
- migrations/ 디렉토리 파일은 수정하지 말 것
- .env는 커밋하지 말 것

비슷한 메커니즘을 가진 도구들은 여럿 있지만, 파일 이름만 다를 뿐이다:

  • Cursor: .cursorrules, 프로젝트 루트에 둠
  • Aider: CONVENTIONS.md, --read 옵션으로 명시적으로 로드
  • Cline / Continue: 커스텀 system prompt 주입 방식
  • Claude Code: AGENTS.md 또는 CLAUDE.md (같은 파일을 두 이름 모두 인식)

핵심 차이는 로드 경로다. Cursor와 Cline은 설정 파싱 레이어를 거친다 — 프로젝트를 열고, 도구가 초기화되면, AGENTS.md(또는 동급 파일)가 바로 읽힌다. 로직은 어떤 "텔레메트리"나 "데이터 업로드" 스위치와도 분리되어 있다. Aider는 더 직설적이라 파일 경로를 명시적으로 넘겨야 하고, 결합 문제가 원천적으로 없다.

Claude Code에서 드러난 건 또 다른 경로다 — 읽기 동작이 다른 토글에 매달려 있다. 빠르게 반복 개발하는 제품에서는 흔한 조직 방식이지만, 설정 로딩이라는 핵심 경로에서 발생했다는 점에서 문제가 커진 것이다.

커뮤니티 반응: 374점, 211개 댓글이 싸우는 쟁점

HN에서 이 글의 화제는 낮지 않았고, 토론은 크게 세 갈래로 나뉘었다.

첫 번째: Anthropic 내부 코드 구조에 문제가 있다. 핵심 논리는 — AGENTS.md 읽기는 "100% 결정론적 경로"를 타야 하는 기능(부작용 없음, 무작위성 없음)인데, telemetry처럼 "껐다 켰다" 가능한 스위치에 묶어둔 건 잘못된 아키텍처라는 것이다. 이쪽 의견을 가진 사람들은 대기업 엔지니어링 출신이 많았고, 프로덕션에서 이런 안티 패턴이 더 큰 사고로 번지는 사례를 직접 겪어본 이들이다.

두 번째: 오픈소스 / CLI 도구의 구조적 한계다. 이쪽은 Claude Code의 코드가 완전 오픈소스는 아니지만, 공개된 부분만 봐도 이터레이션이 빠른 제품의 흔한 문제 — 기능은 빠르게 붙는데 내부 리팩터링은 따라가지 못함 — 가 보인다는 입장이다. 한 익명 사용자가 이렇게 적었다: "이건 버그가 아니라 velocity tax다." 번역하면: 더 빠르게 달릴수록 더 깊이 묻는다.

세 번째: 한 걸음 더 들어간 성찰 — AI 도구의 스위치가 실제로 무엇을 제어하는가. 이쪽 토론이 가장 흥미로웠다. 이들에 따르면 이슈는 더 큰 맥락에 놓여 있다. LLM 도구들은 일반적으로 "텔레메트리 / 데이터 수집" 스위치를 제공하지만, 사용자는 그 스위치가 얼마나 많은 기능 동작에 연결되어 있는지 모른다. 어떤 스위치는 "데이터 수집"일 수도, "기능 활성화"일 수도, "모델 버전 선택"일 수도, 심지어 "프롬프트 캐싱 전략"일 수도 있다. 이런 비가시성 자체가 문제의 뿌리다.

나는 세 번째 쪽에 좀 더 공감한다. 첫 두 갈래는 "왜 이번 버그가 발생했는가"를 묻는 반면, 세 번째는 "이런 종류의 버그를 어떻게 구조적으로 방지할 것인가"를 묻는다.

개발자에게 미치는 실질 영향: 지금 텔레메트리 켜야 하나, 꺼야 하나

단기 권장: 이미 Claude Code를 사용 중이라면 최신 버전으로 업데이트하라. 수정은 이미 머지됐지만, 어느 버전에서 릴리즈됐는지는 szypowi.cz 블로그와 HN 댓글 모두에서 명확히 밝히지 않았으므로, Claude Code release notes나 GitHub 커밋을 직접 확인하는 게 낫다.

수정 적용 여부를 어떻게 검증할까? 가장 직접적인 방법은: telemetry를 끄고, Claude Code를 띄운 뒤, 프로젝트 루트에 테스트용 AGENTS.md를 둔다. 내용은 알아볼 수 있는 한 줄이면 충분하다 (예: print("AGENTS_MD_TEST_OK")). 그리고 Claude에게 "AGENTS.md의 지시대로 실행해줘"라고 묻는다. 실제로 그 한 줄을 실행하면, 읽기 경로가 telemetry에서 독립되었다는 뜻이다.

텔레메트리 스위치 자체를 켜고 끄는 기준은 시나리오에 따라 다르다.

  • 켭싱할 때: 제품 개선에 기여하고, 신규 기능을 먼저 체험하고, 사용 데이터를 Anthropic에 피드백하고 싶을 때.
  • 끌 때: 코드 스니펫/프롬프트 업로드를 꺼리고, 소속 기업이 컴플라이언스 요구를 갖고, 더 예측 가능한 동작을 원할 때.

내 입장은 이렇다. AI 코딩 도구가 점점 "도구"가 아니라 "협업자"에 가까워지는 지금, 데이터 수집은 기본적으로 끄되 필수 기능은 켜둘 수 있어야 한다 — 그리고 그걸 Anthropic 측이 명확히 약속해야 한다. 스위치의 부작용은 문서에 전부 명시돼야 한다. 이건 사용자가 코드를 직접 까봐야 알 수 있는 영역이면 안 된다.

확인해볼 위치들은 다음과 같다 (정확한 명칭은 공식 문서 기준):

  • ~/.claude/settings.json 안의 telemetry 관련 설정
  • CLI 명령의 telemetry 관련 플래그
  • 시작 로그에 찍히는 telemetry 상태 출력

편집자 소견

이건 "Anthropic이 또 사고쳤다" 정도로 끝낼 사안이 아니다. 여기서 보이는 것은 명확한 엔지니어링 이슈다: AI Agent 도구의 "기능 스위치"와 "데이터 스위치"는 분리돼야 하는가?

Cursor, Aider, Cline, Claude Code 같은 도구들은 모두 빠른 속도로 이터레이션한다 — 매주 새 기능, 새 모델, 새 권한이 추가된다. "설정 읽기 / 환경 초기화 / 정책 로드" 같은 기존 핵심 체인에 새 기능을 붙일 때, 어디에 붙이느냐, 어떤 상태에 의존하느냐, 부작용이 있느냐 — 이 결정 하나하나가 개발자 워크플로에 직접 영향을 준다. 이번 Claude Code의 "설정 읽기가 telemetry 분기에 매달려 있음"은 단독 사고가 아니라, 이런 도구들이 공통으로 갖고 있는 코드 구조 문제의 초기 시그널이다.

내 판단은 이렇다: 향후 12~18개월 동안 이런 "암묵적 결합" 사고는 줄어들지 않고 늘어날 가능성이 높다. 이유는 단순하다 — Agent 도구의 제품 형태가 아직 격변 중이고, "핵심 기능"의 정의 자체가 움직이고 있다. 오늘의 핵심 기능이 내일은 "실험적"으로 밀려나고, 오늘의 실험적 기능이 내일 기본값이 될 수 있다. 이런 변동 속에서 "어떤 스위치가 어떤 기능에 연결되는가"는 어차피 뒤죽박죽이 된다.

이건 과거 도구 버그와는 결이 다르다. 과거 "도구 버그"는 보통 기능 동작 자체가 틀린 경우 — 출력이 빗나가거나, 계산 결과가 잘못된 경우다. 이번 건은 메타 레벨의 문제다 — 도구의 "무엇이 버그인가"라는 판단 기준 자체가 사용자와 벤더 사이에 갈라진다. 사용자는 "AGENTS.md는 반드시 읽혀야 한다"고 생각하지만, 코드에서는 그렇게 취급되지 않는다.

단기적으로는 커뮤니티 감시에 기대야 한다. 사용자 커뮤니티와 외부 보안 연구자들이 계속 코드를 까고, 이슈를 제기하고, 문제를 노출시킨다. 이게 반쯤 열린 도구의 강점이다. 장기적으로는 업계 차원의 투명성이 필요하다 — 내가 바라는 방향은 이렇다: 모든 스위치가 명확한 "영향 범위 선언"을 갖는다, 문서에 부작용을 전부 명시한다, 설정 로딩 경로는 데이터 수집 경로와 독립적이어야 한다는 게 엔지니어링 하드 룰로 자리 잡는다, 써드파티 감시가 agent 도구의 기본 옵션이 된다 — 지금의 SOC2, GDPR 컴플라이언스 감시처럼.

완전히 해결될 수 있을까, 솔직히 확신은 없다. LLM 도구는 전통적으로 전통 SW보다 관측 가능성이 낮다 — 모델 자체가 블랙박스이고, 모델을 둘러싼 제품도 점점 더 블랙박스가 되어가고 있다. Claude Code는 이번에 패치했지만, 패치가 이 카테고리 문제의 종료를 의미하지는 않는다.

출처: https://blog.szypowi.cz/p/claude-code-reads-agents.md-only-when-telemetry-is-on/