Claude Code 청구 버그 HERMES.md, 실제 피해 얼마나 됐나

개발자들이 청구서를 보고 눈을 의심했어요. Claude Code를 며칠 쓴 것 같은데, 요금이 예상의 세 배 이상 나온 거예요. 원인 추적 끝에 발견된 건 HERMES.md라는 파일 하나였어요. Anthropic의 Claude Code에서 발생한 이 청구 버그는 2026년 상반기 개발자 커뮤니티에서 가장 많이 오간 주제 중 하나가 됐어요. 실제 피해 규모가 어느 정도인지, 어떤 구조에서 발생했는지 데이터 기반으로 뜯어봤어요.

핵심 요약

• Claude Code의 HERMES.md 청구 버그는 AI 코딩 도구 채택이 급증한 2025~2026년 사이에 불거진 구조적 과금 오류예요.
• 버그의 핵심은 HERMES.md 파일이 매 세션마다 컨텍스트 윈도우에 중복 주입되면서 토큰 사용량이 수백에서 수천 퍼센트까지 부풀려진 구조예요.
• Consumer Rights Wiki에 따르면 피해를 보고한 개발자 중 상당수는 월 예상 비용 대비 2~5배의 실제 청구를 경험했어요.
• Anthropic은 패치를 배포했지만, 소급 환불 정책의 범위와 조건이 불명확해 커뮤니티 내 논란이 이어지고 있어요.
• 이 사태는 AI 도구의 토큰 투명성과 사용자 과금 통제 권한에 대한 더 넓은 논의를 촉발시켰어요.

HERMES.md가 뭔데, 왜 문제가 됐을까요?

Claude Code는 Anthropic이 개발한 AI 기반 코딩 어시스턴트예요. 터미널 환경에서 직접 실행되고, 코드베이스 전체를 컨텍스트로 읽으면서 작업을 도와주는 구조죠. 그 과정에서 Claude Code는 프로젝트 루트에 있는 특정 마크다운 파일들을 자동으로 읽어요. CLAUDE.md가 대표적인 예고, HERMES.md는 그 변형 중 하나예요.

문제는 이 파일이 “한 번만 읽히는 게 아니라” 매 대화 턴마다 시스템 프롬프트에 반복 주입되는 방식으로 작동했다는 거예요. 예를 들어 HERMES.md 파일 크기가 2만 토큰이라면, 대화를 10번 주고받는 동안 이 파일이 10번 주입되면서 실제 소비 토큰은 20만 토큰이 되는 셈이에요. 코드 몇 줄 짜자고 한 것뿐인데, 청구서에는 소설 한 편 분량의 토큰 요금이 찍히는 상황이 벌어진 거죠.

Consumer Rights Wiki에 기록된 Anthropic Claude Code HERMES.md 청구 오류 사례를 보면, 이 현상은 2025년 말부터 본격적으로 보고되기 시작했어요. Claude Code가 기업과 팀 단위로 빠르게 확산되면서, 개인보다 훨씬 큰 규모의 HERMES.md 설정 파일을 운영하는 조직들이 타격을 입었어요.

클리앙 등 국내 개발자 커뮤니티에서도 2026년 초부터 “Claude Code 요금이 이상하게 많이 나온다"는 목소리가 이어졌어요. 공통점은 하나였어요. 프로젝트에 대형 마크다운 설정 파일이 있다는 것.

실제 피해, 숫자로 보면 어떻게 될까요?

과금 메커니즘: 토큰이 어떻게 부풀었나

Claude Code의 과금 구조는 Claude 3.x 및 Claude 4 시리즈 기준으로 입력 토큰과 출력 토큰을 별도로 청구해요. 2026년 4월 기준 Anthropic 공식 가격표에 따르면 Claude Opus 4 기준 입력 토큰은 1M당 약 15달러, 출력 토큰은 1M당 약 75달러예요.

문제는 HERMES.md 중복 주입이 주로 입력 토큰을 무한 증식시킨다는 점이에요. 파일 크기가 클수록, 세션 길이가 길수록, 피해는 기하급수적으로 커졌어요.

아래는 버그 영향 시나리오별 예상 토큰 비용 비교예요.

주: 위 수치는 Claude Opus 4 입력 토큰 단가 기준 추정값이며, 실제 청구액은 모델 선택 및 출력 비율에 따라 달라질 수 있어요.

Consumer Rights Wiki에 기록된 보고 사례에서는 월 예산 대비 절반에서 다섯 배의 초과 청구가 가장 빈번하게 언급됐어요. 기업 단위의 극단적 사례에서는 열 배 이상의 청구도 보고됐고요.

피해가 특히 컸던 케이스

피해가 집중된 곳은 세 유형이에요.

첫째, HERMES.md나 CLAUDE.md를 회사 전체 코딩 컨벤션, 아키텍처 문서, 보안 가이드라인을 통합해 수만 토큰 규모로 운영한 팀들이에요. 잘 세팅할수록 비용이 더 나오는 아이러니한 상황이었죠.

둘째, Claude Code를 CI/CD 파이프라인에 자동화로 연결한 조직들이에요. 사람 개입 없이 수백 번의 자동 실행이 돌아가면서 중복 주입이 폭발적으로 늘어났어요.

셋째, 맥스 플랜이 아닌 API 직접 과금 방식을 쓰는 팀들이에요. 고정 요금제가 아니라 사용량 기반이다 보니 상한선 없이 청구가 쌓였어요.

Anthropic의 대응은 어땠나요?

Anthropic은 버그 인지 후 패치를 배포했어요. 수정된 버전에서는 설정 파일이 세션 시작 시 한 번만 로드되고, 이후 턴에서는 캐시 참조 방식으로 전환됐어요. Anthropic의 프롬프트 캐싱 기술을 쓰면 캐시 히트 시 입력 토큰 비용이 약 90% 절감되거든요. 이 구조로 전환한 거예요.

그런데 소급 환불 문제가 남아 있어요. Anthropic이 공식적으로 환불 범위와 기준을 명확히 공표하지 않으면서, 커뮤니티에서는 “어떤 케이스는 환불되고 어떤 케이스는 거절당했다"는 엇갈린 경험담이 나오고 있어요.

이 버그가 단순한 버그가 아닌 이유

사실 이 사태는 AI 코딩 도구 시장 전반의 구조적 문제를 건드려요.

토큰 투명성 부재. Claude Code를 비롯한 대부분의 AI 코딩 어시스턴트는 내부적으로 몇 토큰을 소비하는지 실시간으로 사용자에게 보여주지 않아요. 청구서가 나오기 전까지 피해 규모를 알기 어려운 구조예요.

경쟁 도구와 비교. GitHub Copilot은 고정 월정액(월 19달러)이라 이런 토큰 폭탄 리스크가 없어요. Cursor는 토큰 사용량 대시보드를 제공해서 실시간 확인이 가능하고요. Claude Code는 강력한 도구지만, 과금 가시성 면에서는 경쟁자보다 뒤처져 있었던 게 사실이에요.

지금 Claude Code 쓰는 팀이라면 뭘 해야 할까요?

즉각 점검이 필요한 것들:

• 프로젝트 루트의 HERMES.md, CLAUDE.md, CLAUDE.local.md 파일 크기를 확인하세요. 10,000 토큰(약 7,500 단어)을 넘으면 분할을 고려해야 해요.
• Anthropic Console에서 지난 3개월 일별 토큰 사용 그래프를 확인해보세요. 특정 날짜에 스파이크가 있다면 해당 프로젝트를 들여다봐야 해요.
• 최신 Claude Code 버전으로 업데이트됐는지 확인하세요. 패치 적용 여부는 CLI에서 claude --version으로 체크할 수 있어요.

중기적으로 신경 써야 할 것:

Anthropic이 향후 업데이트에서 토큰 사용량 실시간 표시 기능을 추가할 가능성이 높아요. 이 버그 사태가 압력으로 작용했거든요. 2026년 하반기 Claude Code 로드맵에서 과금 투명성 관련 기능이 포함되는지 주시하면 좋겠어요.

정리: 이 버그가 남긴 것

• 개인 개발자는 월 수십 달러, 팀 단위는 수백~수천 달러의 초과 청구가 발생했어요.
• 근본 원인은 설정 파일의 반복 주입이라는 구조적 설계 결함이었어요.
• Anthropic의 패치는 기술적으로 문제를 잡았지만, 환불 정책의 불명확함은 여전히 논란이에요.

앞으로 6~12개월 동안 AI 코딩 도구 시장에서는 과금 투명성이 핵심 경쟁 요소로 부상할 거예요. 사용자들이 “얼마 나올지 모르는 도구"보다 “예측 가능한 비용의 도구"를 선호하기 시작했거든요. Anthropic이 이 교훈을 어떻게 제품에 반영하는지가 Claude Code의 기업 시장 점유율을 가를 분기점이 될 수 있어요.

당신 팀의 Claude Code 설정 파일 크기, 오늘 한번 확인해보셨나요?

참고자료

1. Anthropic Claude Code HERMES.md billing flaw - Consumer Rights Wiki
2. 클로드 (언어 모델) - 위키백과, 우리 모두의 백과사전
3. 조직에서 Claude Code / Claude Cowork 잘 쓰는 법 : 클리앙

Photo by Bernd 📷 Dittrich on Unsplash