Claude Code는 텔레메트리가 켜져 있을 때만 AGENTS.md를 읽는다 [수정됨]

Who Should Read

여러 에이전트에 AGENTS.md 하나로 지침을 공유하는데 Claude Code에서만 반영이 안 돼 고민인 개발자

Core Mechanics

• AGENTS.md 로더가 원격 플래그에 묶여 있다
  • 로더는 agents-md라는 내장 플러그인이고 기본값(isOnByDefault)이 false다.
  • 사용 가능 여부를 원격 feature flag(기능 스위치) tengu_agents_md_mod에 물어보고, 못 가져오면 false로 처리한다.
• 텔레메트리 끄면 경고 없이 건너뛴다
  • DISABLE_TELEMETRY=1이나 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 중 하나만 있어도 AGENTS.md가 로드되지 않았다.
  • 경고가 전혀 없어서 모델이 지침을 무시한다고 오해하기 쉽다.
• 변수를 0으로 바꿔도 소용없다
  • 어떤 값이든 설정돼 있으면 켜진 것으로 취급돼서 0도 차단 상태가 유지된다.
  • 프로젝트 .claude/settings.json의 env로 비워도 효과가 없었다.
• 실행 시 --settings로 덮어쓰면 두 번째 세션부터 된다
  • 첫 세션은 플래그만 가져오고 두 번째 세션부터 적용된다.
  • Bedrock, Vertex, 서드파티 게이트웨이도 플래그가 true가 될 수 없어 같은 문제라고 이슈에서 지적한다.
• 한 줄짜리 CLAUDE.md로 우회된다
  • CLAUDE.md의 @path import는 플래그와 무관해서 echo '@AGENTS.md' > CLAUDE.md면 텔레메트리를 꺼도 로드된다.

Community Reactions

• Anthropic 쪽 답변: 롤아웃 부산물이라 v2.1.281에서 수정
  • 원격으로 끌 수 있는 kill-switch가 필요했는데 텔레메트리를 끄면 플래그를 못 받는다고 댓글로 설명했다.
  • 오늘 나가는 v2.1.281에 이미 고쳐졌고 사람의 실수였다고 사과했다.
• CLAUDE.md가 있으면 AGENTS.md는 기본적으로 안 읽힌다는 경험 공유
  • ~/CLAUDE.md만 있어도 AGENTS.md가 읽히지 않는다는 댓글이 있었다.
  • 둘 다 읽으려면 Project instructions 설정을 claude-md-and-agents-md로 바꿔야 한다고 한다.
• 기존 우회법이 잘 동작한다는 경험 다수
  • ln -s AGENTS.md CLAUDE.MD를 쓴다는 댓글이 있었다.
  • CLAUDE.md에 @AGENTS.md만 넣어 둔다는 댓글도 있고 여전히 잘 된다고 한다.
• 기능 플래그 자체는 정상 관행이라는 반론
  • 배포와 기능 활성화를 분리하는 분산 시스템의 흔한 방식이라는 의견이 있었다.
  • 다만 플래그와 텔레메트리를 분리하지 못한 점과 경고 없는 동작을 비판하는 댓글도 많았다.
• 시작 시 메시지가 뜬다는 불만과 다른 기능 제약 언급
  • 이제 매 시작마다 agents-md: no CLAUDE.md found; AGENTS.md loaded 메시지가 뜬다는 댓글이 있었다.

How to Apply

• 빈 폴더에서 canary 테스트 돌리기
  • 빈 디렉터리에 canary 단어가 든 AGENTS.md를 만들고 claude -p로 단어를 물어봐라.
  • 텔레메트리를 끈 셸에서 두 번 실행해 두 번째 세션 결과를 확인해라.
• AGENTS.md 쓰는 저장소에 CLAUDE.md 한 줄 추가하기
  • 각 저장소 루트에 echo '@AGENTS.md' > CLAUDE.md를 실행하고 커밋해라.
  • 텔레메트리나 게이트웨이 정책으로 비필수 트래픽을 막은 팀에 특히 필요하다.
• 공유 스킬은 심볼릭 링크로 연결하기
  • .agents/skills에 스킬을 두고 .claude/skills를 ../.agents/skills로 링크해라.
  • 복사본은 원본과 어긋나니 /import 복사 대신 링크를 써라.
• Claude Code를 v2.1.281 이상으로 올린 뒤 재검증하기
  • 업데이트 후 텔레메트리를 끈 상태로 canary 테스트를 다시 돌려라.
  • 통과해도 CLAUDE.md가 있으면 AGENTS.md가 기본적으로 안 읽히는 점은 확인해라.

Try It

# 셸(bash/zsh)에 그대로 붙여넣기: 텔레메트리 끈 상태에서 AGENTS.md 로드 여부 확인

mkdir /tmp/canary && cd /tmp/canary
echo 'The canary word is PERIWINKLE.' > AGENTS.md
export DISABLE_TELEMETRY=1

# 두 번 실행한다. 첫 세션은 플래그만 가져오고 두 번째부터 적용된다
for i in 1 2; do
  claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.'
done

# NONE이 나오면 우회: CLAUDE.md에서 @import
echo '@AGENTS.md' > CLAUDE.md
claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.'

# 이어서 해 볼 것: 스킬 공유
# ln -s ../.agents/skills .claude/skills

Terminology

관련 논문

• 같은 시뮬레이션, 다른 근거: 도구 출력을 파일로 넘기면 LLM 에이전트 정확도가 어디서 깎이나

  긴 툴 출력을 파일로 넘기자 GPT-5.1은 정확도 11.3%p 하락, 정식 출력 지정하니 회복

• 가짜 뉴스가 진짜 폭락을: LLM 트레이딩 에이전트 대상 정보 주입 공격

  가짜 헤드라인 한 줄로 LLM 트레이딩 에이전트 62%를 조종했다(프롬프트 주입은 14%)

• Harness Engineering 101: LLM은 뇌, harness는 몸

  에이전트는 JSON 배열을 관리하는 루프이고, 16개 챕터로 직접 만들어 본다

• Harness²: 에이전트 harness를 스스로 고쳐 쓰는 재귀 최적화 프레임워크

  모델은 고정하고 harness를 재귀로 고쳤더니 벤치마크 점수가 최대 11.8%p 올랐다

• 해고된 Savannah 경찰관, ICE 요원 남편에게 Flock 계정 공유

  경찰관이 Flock 계정을 남편(ICE 요원)에게 공유했고, 감사에서 983건 검색이 드러나 해고됐다

• tmux와 Claude Code: 세션, send-keys, 그리고 한계선

  tmux로 Claude Code 여러 개를 돌리면 편하지만 에이전트 4개쯤에서 한계가 온다

• Hybrid Reasoning Agents: 잠재 공간에서 생각하고 텍스트로 행동하는 LLM 에이전트

  잠재 공간 추론과 텍스트 도구 호출을 섞었더니 성능 10.4%↑, 토큰 최대 54.7%↓

Related Resources

• https://blog.szypowi.cz/p/claude-code-reads-agents.md-only-when-telemetry-is-on/
• https://news.ycombinator.com/item?id=49760187
• https://martinfowler.com/articles/feature-toggles.html
• https://github.com/anthropics/claude-code/tree/main/mods