[Hacker News 요약] Claude Code, 원격 플래그에 따라 AGENTS.md 로딩 여부 결정, 개인 정보 보호 설정과 충돌
24
설명
Claude Code 2.1.277 버전에서 AGENTS.md 파일 지원이 추가되었으나, 해당 기능이 원격 기능 플래그 뒤에 숨겨져 있어 문제가 발생하고 있습니다.
텔레메트리 또는 비필수 트래픽이 비활성화된 경우, 로컬 AGENTS.md 파일이 경고 없이 무시되는 현상이 발견되었습니다.
이 문제는 개인 정보 보호 설정을 우선시하는 사용자에게 예상치 못한 기능 제한을 초래하며, 개발자 커뮤니티에서 논의되고 있습니다.
### 배경 설명
AI 코딩 어시스턴트의 발전은 개발 생산성 향상에 크게 기여하고 있으며, Claude Code와 같은 도구는 코드 생성, 디버깅, 문서 분석 등 다양한 작업을 지원합니다. 특히, AGENTS.md와 같은 프로젝트별 지침 파일은 AI 모델이 특정 프로젝트의 맥락을 더 잘 이해하고 맞춤형 응답을 제공하도록 돕는 중요한 기능입니다. 이러한 파일은 개발자가 AI 에이전트의 동작을 세밀하게 제어할 수 있게 해주며, 복잡한 프로젝트 환경에서 AI의 효율성을 극대화하는 데 필수적입니다.
그러나 이러한 고급 기능이 사용자 설정, 특히 개인 정보 보호와 관련된 설정과 충돌할 때 문제가 발생합니다. 텔레메트리 비활성화는 사용자가 자신의 데이터를 더 잘 제어하려는 의지를 반영하지만, 이로 인해 AGENTS.md와 같은 로컬 파일 읽기 기능이 예기치 않게 차단되는 것은 사용자의 기대와 배치됩니다. 이는 단순히 기술적인 버그를 넘어, 사용자가 AI 도구와의 상호작용에서 신뢰와 투명성을 얼마나 중요하게 생각하는지를 보여주는 사례입니다. Anthropic과 같은 AI 개발사는 사용자 개인 정보 보호 정책과 기능 구현 간의 균형을 맞추는 데 더욱 신중해야 할 필요가 있습니다.
### AGENTS.md 로딩 메커니즘의 문제점
Claude Code 2.1.277 버전부터 AGENTS.md 파일 지원이 추가되었으나, 이 기능은 'tengu_agents_md_mod'라는 원격 기능 플래그에 의해 제어됩니다. 이 플래그는 기본적으로 비활성화되어 있으며, Claude Code가 원격 서버로부터 이 플래그 값을 성공적으로 가져오지 못하면 AGENTS.md 파일은 로드되지 않습니다. 흥미로운 점은 AGENTS.md 파일을 읽는 데 네트워크 연결이 전혀 필요 없음에도 불구하고, 이 기능이 서버 측 스위치에 의존한다는 것입니다. 이는 사용자가 텔레메트리 또는 비필수 트래픽을 비활성화할 경우, 로컬 AGENTS.md 파일이 경고 없이 무시되는 결과를 초래합니다. Przemek은 이 문제를 재현하기 위해 AGENTS.md 파일만 포함된 빈 디렉터리를 생성하고, 텔레메트리 비활성화 환경 변수(예: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 또는 DISABLE_TELEMETRY=1)를 설정한 후 Claude Code에 질의하는 방식으로 테스트했습니다. 두 변수 중 하나라도 설정되면 AGENTS.md 파일은 로드되지 않았으며, 이 문제를 해결하기 위해서는 두 변수를 모두 해제해야 했습니다. 또한, 프로젝트별 .claude/settings.json 파일 내의 환경 변수 설정도 이 문제를 해결하지 못했습니다.
### 측정 결과 및 워크어라운드
Przemek은 실험을 통해 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 또는 DISABLE_TELEMETRY=1 환경 변수가 AGENTS.md 파일 로딩을 차단함을 확인했습니다. 이 변수들이 설정된 상태에서는 AGENTS.md 파일이 로드되지 않아, 사용자는 AI 모델이 프로젝트 지침을 무시한다고 오해할 수 있습니다. 이로 인해 사용자는 문제의 원인을 파악하는 데 상당한 시간을 소비하게 됩니다. 이 문제를 해결하기 위한 워크어라운드로는 CLAUDE.md 파일에 '@AGENTS.md'를 포함시키는 방법이 제시되었습니다. 이 방식은 AGENTS.md 파일의 내용을 CLAUDE.md 파일에 포함시키는 것으로, 텔레메트리 비활성화 상태에서도 AGENTS.md 파일의 내용을 성공적으로 로드할 수 있습니다. 예를 들어, 'echo '@AGENTS.md' > CLAUDE.md' 명령을 실행하면 됩니다. 이 워크어라운드는 각 리포지토리마다 추가적인 CLAUDE.md 파일을 생성해야 하는 단점을 가지지만, AGENTS.md 지원의 원래 목적이었던 파일 중복 생성을 피하는 데는 도움이 됩니다. 또한, Claude Code 2.1.280 버전은 .agents/skills 디렉터리의 스킬을 직접 인식하지 못하지만, ~/.agents/skills 디렉터리의 스킬은 인식합니다. 이 또한 심볼릭 링크를 통해 해결할 수 있습니다.
### 문제의 부적절성 및 개선 제안
Przemek은 텔레메트리를 비활성화하는 사용자의 선택이 단순히 진단 데이터 공유를 거부하는 것을 넘어, 로컬 파일 읽기와 같은 관련 없는 기능까지 침묵적으로 비활성화하는 것은 부적절하다고 지적합니다. 특히, AGENTS.md와 같이 로컬 디스크에서 데이터를 읽는 기능이 원격 플래그에 의해 제어되는 것은 납득하기 어렵습니다. 이는 개인 정보 보호를 중요하게 생각하는 사용자, 그리고 Bedrock이나 Vertex와 같은 게이트웨이를 사용하는 팀에게 특히 불리하게 작용합니다. 이러한 사용자들은 종종 비필수 트래픽을 비활성화하는 정책을 따르기 때문입니다. 가장 큰 문제는 이러한 기능 차단이 사용자에게 전혀 통보되지 않는다는 점입니다. 사용자는 파일이 로드되지 않았음을 인지하지 못한 채 프롬프트에 시간을 낭비하게 됩니다. Przemek은 Anthropic이 점진적인 롤아웃을 원한다면, 플래그를 가져오지 못했을 때 기본 동작을 문서화하거나, 어떤 파일이 왜 건너뛰어졌는지 명확하게 알리는 메시지를 표시해야 한다고 제안합니다. 또한, 로컬 파일 읽기가 텔레메트리 설정에 의존하지 않아야 하며, AGENTS.md가 건너뛰어졌을 경우 시작 시 경고 메시지를 표시하는 것이 사용자 경험을 개선할 수 있다고 덧붙였습니다. 마지막으로, 사용자가 여러 에이전트에 대해 동일한 지침 파일을 사용하고 싶을 때를 대비하여, 전역 AGENTS.md 파일 지원이나 사용자 CLAUDE.md 파일과 연동되는 공유 에이전트 스킬 지원을 제안했습니다.
### 가치와 인사이트
이 사건은 AI 도구 개발 시 사용자 개인 정보 보호 설정과 기능 구현 간의 복잡한 상호작용을 명확히 보여줍니다. 텔레메트리 비활성화와 같은 개인 정보 보호 설정이 예상치 못한 기능 제한으로 이어질 경우, 사용자 경험에 부정적인 영향을 미칠 뿐만 아니라, 개발자에 대한 신뢰를 저하시킬 수 있습니다. 특히, 로컬 파일 접근과 같이 사용자 제어 하에 있어야 하는 기능이 원격 플래그에 의해 결정되는 것은 사용자에게 투명성을 제공하지 못한다는 점에서 비판받을 수 있습니다. 개발자는 기능 롤아웃 전략을 수립할 때, 사용자의 선택을 존중하고, 기능 차단 시 명확한 피드백을 제공하는 방안을 반드시 고려해야 합니다. 이는 AI 도구가 개발자 커뮤니티에서 널리 채택되고 신뢰받는 데 중요한 요소가 될 것입니다.
### 기술·메타
- Claude Code 2.1.277
- AGENTS.md
- CLAUDE.md
- `tengu_agents_md_mod` (remote feature flag)
- `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` (environment variable)
- `DISABLE_TELEMETRY` (environment variable)
- `.claude/settings.json`
- Bedrock
- Vertex
- Hugo (blog engine)
- pager (theme)
### 향후 전망
Anthropic이 이 문제를 어떻게 해결할지가 관건입니다. AGENTS.md 로딩을 텔레메트리 설정과 분리하거나, 플래그 오류 발생 시 명확한 사용자 알림을 제공하는 방향으로 개선될 가능성이 높습니다. 또한, 전역 AGENTS.md 파일 지원이나 공유 에이전트 스킬 관리 기능이 추가된다면, 복잡한 프로젝트 환경에서 AI 에이전트의 활용성이 더욱 높아질 것입니다. 경쟁사 AI 코딩 도구들도 유사한 기능들을 제공하고 있으므로, Claude Code는 사용자 경험과 개인 정보 보호 측면에서 경쟁 우위를 확보하기 위해 이러한 피드백을 적극적으로 반영해야 할 것입니다. 2026년 9월 23일에 공개된 이 문제는 향후 AI 도구의 설계 및 개인 정보 보호 정책 수립에 중요한 참고 사례가 될 것으로 보입니다.
📝 원문 및 참고
- Source: Hacker News
- 토론(HN): [news.ycombinator.com](https://news.ycombinator.com/item?id=49814947)
- 원문: [링크 열기](https://blog.szypowi.cz/p/claude-code-reads-agents.md-only-when-telemetry-is-on/)
---
출처: Hacker News · [원문 링크](https://blog.szypowi.cz/p/claude-code-reads-agents.md-only-when-telemetry-is-on/)
이 글에 대한 한 줄 의견
신고 · 불법·유해·아동 안전(CSAE) 관련 콘텐츠
댓글 0
아직 댓글이 없습니다. 로그인하면 바로 의견을 남길 수 있습니다.