Section 1.10.32 of "de Finibus Bonorum et Malorum", written by Cicero in 45 BC
"Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?"

1914 translation by H. Rackham
"But I must explain to you how all this mistaken idea of denouncing pleasure and praising pain was born and I will give you a complete account of the system, and expound the actual teachings of the great explorer of the truth, the master-builder of human happiness. No one rejects, dislikes, or avoids pleasure itself, because it is pleasure, but because those who do not know how to pursue pleasure rationally encounter consequences that are extremely painful. Nor again is there anyone who loves or pursues or desires to obtain pain of itself, because it is pain, but because occasionally circumstances occur in which toil and pain can procure him some great pleasure. To take a trivial example, which of us ever undertakes laborious physical exercise, except to obtain some advantage from it? But who has any right to find fault with a man who chooses to enjoy a pleasure that has no annoying consequences, or one who avoids a pain that produces no resultant pleasure?"

Section 1.10.33 of "de Finibus Bonorum et Malorum", written by Cicero in 45 BC
"At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga. Et harum quidem rerum facilis est et expedita distinctio. Nam libero tempore, cum soluta nobis est eligendi optio cumque nihil impedit quo minus id quod maxime placeat facere possimus, omnis voluptas assumenda est, omnis dolor repellendus. Temporibus autem quibusdam et aut officiis debitis aut rerum necessitatibus saepe eveniet ut et voluptates repudiandae sint et molestiae non recusandae. Itaque earum rerum hic tenetur a sapiente delectus, ut aut reiciendis voluptatibus maiores alias consequatur aut perferendis doloribus asperiores repellat."

1914 translation by H. Rackham
"On the other hand, we denounce with righteous indignation and dislike men who are so beguiled and demoralized by the charms of pleasure of the moment, so blinded by desire, that they cannot foresee the pain and trouble that are bound to ensue; and equal blame belongs to those who fail in their duty through weakness of will, which is the same as saying through shrinking from toil and pain. These cases are perfectly simple and easy to distinguish. In a free hour, when our power of choice is untrammelled and when nothing prevents our being able to do what we like best, every pleasure is to be welcomed and every pain avoided. But in certain circumstances and owing to the claims of duty or the obligations of business it will frequently occur that pleasures have to be repudiated and annoyances accepted. The wise man therefore always holds in these matters to this principle of selection: he rejects pleasures to secure other greater pleasures, or else he endures pains to avoid worse pains."

안녕하세요? 정리하는 개발자 워니즈입니다. 한창 작업하는 중에 한도에 걸려서 멈춘 적 있으신가요. 저는 그때마다 뭐가 그렇게 먹었는지를 몰라서 그냥 기다렸습니다. 새로 붙인 MCP 서버가 문제인지, 길어진 세션이 문제인지, 아니면 밤에 돌려둔 반복 작업이 문제인지 짐작만 했습니다.

찾아보니 짐작할 일이 아니었습니다. 클로드 코드는 무엇이 한도를 먹었는지를 스킬과 서브에이전트와 개별 MCP 서버 단위로 비율까지 보여줍니다. 제가 그 화면을 안 열고 있었을 뿐입니다.

이번 글은 클로드 코드 사용량을 확인하는 경로 3가지와, 그 숫자가 무엇을 못 보는지를 정리한 기록입니다. 화면 구성과 동작 규칙은 공식 문서의 비용 관리 문서를 근거로 적었고, 명령 표면은 제 환경(클로드 코드 2.1.274, 코덱스 CLI 0.145.0)에서 직접 확인했습니다.

이 글에서 알 수 있는 것

• 클로드 코드 사용량 화면에 무엇이 들어 있고 구독자와 API 사용자에게 어떻게 다르게 읽히는지
• 무엇이 내 한도를 먹는지 스킬과 플러그인과 MCP 서버별로 보는 방법
• 한도 창이 리셋되는 규칙과 모델별로 한도가 따로 잡히는 구조
• 이 숫자가 구조적으로 못 보는 것 하나

1. 클로드 코드 사용량은 한 화면에 모여 있다

클로드 코드 사용량 확인 경로는 /usage 하나입니다. 세션 안에서 입력하면 네 종류의 정보가 한 화면에 나옵니다.

Session 블록은 토큰 수와 함께 총비용을 달러로 찍어줍니다. 이 값은 클로드 코드가 토큰 수에 정가를 곱해 로컬에서 계산한 추정치입니다. 조직 관리자가 관리 설정에 요율 표를 넣어두면 그 요율로 계산되고, 그때는 총비용 줄에 조직 요율로 계산했다는 주석이 붙습니다.

구독자인데 Session의 비용 수치는 왜 안 맞을까요?

그 숫자가 구독료와 무관하기 때문입니다. Max나 Pro 구독자는 사용량이 구독에 포함되어 있어서 세션 비용 수치는 청구 목적으로는 의미가 없습니다. 공식 문서도 Session 블록을 API 사용자를 위한 것이라고 명시합니다. 구독자가 봐야 하는 것은 그 아래의 플랜 사용량 바입니다.

정확한 청구 기준이 필요하면 로컬 추정치가 아니라 콘솔의 사용량 페이지를 봐야 합니다. 데이터 레지던시 요율이 적용된 응답은 정가에 1.1을 곱해 세션 비용에 반영되는데, 이런 보정까지 들어가 있어서 로컬 값은 어디까지나 추정입니다.

2. 클로드 코드 사용량을 주체별로 분해해서 본다

이 글을 쓰게 된 부분입니다. Pro, Max, Team, Enterprise 플랜에서는 /usage가 한도를 먹은 주체를 분해해 보여줍니다.

Attribution은 최근 사용량을 스킬, 서브에이전트, 플러그인, 개별 MCP 서버별로 나눠 각각 전체의 몇 퍼센트인지 표시합니다. MCP 서버를 여러 개 붙여놓고 어느 것이 비싼지 몰랐다면 여기서 바로 갈립니다.

Behavior flags는 긴 컨텍스트나 캐시 미스 같은 행동이 최근 사용량의 10% 이상을 차지할 때 플래그를 세웁니다. 비율이 그 아래면 표시되지 않으니, 플래그가 떴다는 것 자체가 이미 무시할 수 없는 몫이라는 뜻입니다.

Loops는 반복 실행되는 작업별로 행을 하나씩 만듭니다. 작업이 얼마나 자주 발동하는지, 몇 번 돌았는지, 총 토큰과 회당 토큰이 얼마인지, 마지막으로 언제 돌았는지가 같이 나옵니다. 행의 키가 작업 프롬프트라서 중간에 멈추고 다시 만든 작업도 한 행으로 유지됩니다.

d와 w 키로 최근 24시간과 최근 7일을 전환할 수 있습니다. 하루 기준으로 보면 오늘 뭘 잘못했는지가 보이고, 주 기준으로 보면 상시로 새는 곳이 보입니다.

MCP 서버 지분이 과하게 잡히던 이유는 뭘까요?

귀속 규칙이 예전에 달랐기 때문입니다. 지금은 MCP 서버의 지분에 그 서버의 도구 결과를 실제로 소비한 요청만 셉니다. 그런데 2.1.222 이전에는 MCP 서버를 한 번 호출하면 그 뒤의 모든 요청을 그 서버에 귀속시켰습니다. 결과적으로 지분이 과대계상됐습니다.

그래서 예전 버전에서 “MCP 하나가 사용량의 절반을 먹는다”는 인상을 받았다면, 그 판단의 근거가 지금은 달라져 있습니다. 버전을 올리고 다시 재는 편이 맞습니다.

도구를 정리하기 전에 귀속 규칙이 바뀐 버전을 지나왔는지 먼저 확인합니다. 과대계상된 숫자를 근거로 멀쩡한 MCP 서버를 떼면 원인은 그대로 남습니다.

3. 창이 리셋되는 규칙을 안다

클로드 코드 사용량을 재는 창은 하나가 아니라 여러 개입니다.

모델별로 한도가 따로 있다는 점이 실무에서 자주 걸립니다. 한쪽 모델의 한도를 다 쓰면 다른 모델로는 계속 작업할 수 있습니다. 반대로 말하면 무거운 모델만 계속 쓰면 그쪽 창만 먼저 닫힙니다.

Team이나 Enterprise 플랜이라면 계산이 하나 더 붙습니다. 좌석에 붙은 할당량을 코드 작업만 쓰는 것이 아니라 채팅과 Cowork이 함께 나눠 씁니다. 코드 작업량은 그대로인데 한도가 빨리 닫히는 느낌이 들면 다른 쪽 사용을 같이 봐야 합니다.

세션 총계 쪽에도 규칙이 있습니다. /clear로 새 세션을 시작하면 총비용이 0에서 다시 시작합니다. 2.1.211 이전에는 /clear를 해도 프로세스가 사는 동안 계속 누적됐습니다. 예전 기억으로 “클리어했는데 숫자가 그대로”라고 판단하면 안 됩니다.

한도를 넘겨 계속 써야 할 때는요?

usage credits가 그 용도입니다. 켜져 있으면 /usage 화면에 크레딧 행이 하나 더 붙고, 플랜에 따라 보여주는 것이 다릅니다. Pro와 Max는 이번 달 지출을 월 지출 한도와 나란히 보여주고, 한도를 안 걸어뒀으면 한도 없이 지출만 나옵니다. Team과 Enterprise는 나에게 적용되는 조직 한도와 내 지출을 보여주는데, 조직 전체에 걸린 한도는 이 행에 나오지 않습니다.

한 가지 제약이 있습니다. 크레딧 관리 명령은 claude.ai 구독으로 로그인한 상태에서만 동작하고 API 키 인증으로는 쓸 수 없습니다. 팀에서 API 키로 붙여 쓰는 구성이라면 이 경로가 아예 없습니다.

이 숫자가 못 보는 것

클로드 코드 사용량 화면에서 제일 중요한 대목인데, 문서에 한 줄로 적혀 있어서 놓치기 쉽습니다.

Attribution과 behavior flags의 수치는 이 기계의 로컬 세션 히스토리에서 계산됩니다. 다른 기기에서 쓴 사용량과 claude.ai에서 쓴 사용량은 포함되지 않습니다.

노트북과 데스크톱을 번갈아 쓰거나, 코드 작업과 브라우저 채팅을 같이 쓰는 사람에게는 이 한 줄이 판정을 뒤집습니다. 한쪽 기계에서 본 비율이 낮다고 해서 그 항목이 한도를 안 먹은 것이 아닙니다. 플랜 사용량 바는 서버 쪽 값이라 전체를 반영하지만, 분해해서 보여주는 비율은 그 기계 몫입니다.

그래서 저는 순서를 이렇게 잡았습니다. 먼저 플랜 사용량 바로 얼마나 남았는지 보고, 그다음 Attribution으로 이 기계에서 무엇이 먹었는지 보고, 두 숫자가 어긋나면 다른 기기를 의심합니다.

VS Code 확장에서는 같은 정보가 Account 및 usage 다이얼로그에 들어 있고 Day와 Week 토글이 있습니다. 다만 Loops 행은 확장에 없어서 반복 작업을 보려면 터미널 쪽을 봐야 합니다.

아무것도 안 했는데 클로드 코드 사용량이 왜 오를까요?

세션을 열어둔 것 자체가 비용을 만들기 때문입니다. 유휴 상태에서도 클로드 코드는 배경에서 토큰을 씁니다. 이전 대화를 요약해두는 작업이 돌고, /usage 같은 일부 명령도 상태를 확인하는 요청을 냅니다. 공식 문서는 이 배경 몫을 한 세션에서 몇 센트 수준으로 적고 있습니다. 액수 자체는 작습니다.

문제는 세션이 길어질 때입니다. 몇 시간 열어둔 세션은 내가 한 일에 비해 한도를 훨씬 많이 먹을 수 있고, 이유가 네 가지로 정리됩니다.

첫 줄이 가장 큽니다. 프롬프트 캐싱이 붙어 있어서 그 히스토리를 캐시 요율로 다시 읽지만, 요율이 낮아지는 것이지 안 읽는 것이 아닙니다. 하루 열어둔 세션에서 한 줄만 물어봐도 대화 전체분에 해당하는 사용량이 잡힙니다.

두 번째 줄에는 알아둘 숫자가 있습니다. 캐시 수명이 구독 상태에서는 한 시간인데, usage credits를 끌어 쓰기 시작하면 5분으로 떨어집니다. API 키나 클라우드 제공자 경로는 기본이 5분입니다. 크레딧을 쓰기 시작한 뒤로 갑자기 사용량이 더 빨리 차는 느낌이 들면 이 변화가 원인일 수 있습니다. 한 시간을 유지하려면 TTL을 직접 지정해야 합니다.

Pro와 Max 플랜에서는 큰 세션을 오래 쉬고 재개할 때 요약에서 이어가겠느냐고 제안합니다. 받아들이면 이후 요청이 전체 히스토리를 들고 다니지 않습니다.

확인한 다음 줄이는 순서

클로드 코드 사용량을 확인했으면 다음은 줄이는 쪽입니다. 공식 문서가 권하는 레버를 제가 실제로 손댄 순서대로 적습니다.

1) 컨텍스트를 먼저 줄인다

/context를 열면 무엇이 컨텍스트를 먹고 있는지 범주별로 나옵니다. 여기서 큰 항목이 보이면 그게 매 요청에 실려 가는 몫입니다. 작업이 바뀔 때 /clear로 끊는 습관이 가장 값이 큽니다.

2) MCP 서버를 정리한다

MCP 도구 정의는 기본적으로 지연 로드입니다. 도구 이름과 서버 지시문만 먼저 들어가고 실제로 그 도구를 쓸 때 전체가 로드됩니다. 그래도 서버 수가 늘면 이름 목록만으로도 무시할 수 없어집니다.

여기서 문서가 권하는 대안이 흥미롭습니다. gh나 aws, gcloud처럼 CLI가 있는 것은 MCP보다 CLI가 컨텍스트 효율이 좋습니다. 도구별 목록을 컨텍스트에 추가하지 않기 때문입니다. 클로드 코드는 CLI 명령을 직접 실행할 수 있으니, MCP로 붙일 이유가 인증이나 응답 가공에 있지 않다면 CLI 쪽이 낫습니다. 쓰지 않는 서버는 /mcp에서 비활성화합니다.

3) 탐색 비용을 도구로 대체한다

타입이 있는 언어라면 코드 인텔리전스 플러그인이 심볼 탐색을 정확하게 해줍니다. 정의로 이동 한 번이 grep 한 번에 후보 파일 여러 개를 읽는 일을 대체합니다. 언어 서버가 편집 후 타입 오류를 자동으로 보고해주니 컴파일러를 따로 돌리는 왕복도 줄어듭니다.

4) 전처리를 훅과 스킬로 내린다

문서의 예시가 그대로 쓸 만합니다. 1만 줄 로그에서 오류를 찾으려고 모델이 파일을 통째로 읽는 대신, 훅이 먼저 오류 줄만 걸러 넘기면 수만 토큰이 수백 토큰이 됩니다. 도메인 지식은 스킬에 담아두면 모델이 탐색으로 알아내야 할 것이 줄어듭니다.

5) 에이전트 팀을 띄웠으면 팀원 수를 센다

에이전트 팀은 클로드 코드 인스턴스를 여러 개 띄우고 각자 자기 컨텍스트 윈도를 가집니다. 그래서 토큰 사용량이 활성 팀원 수와 각자가 돈 시간에 비례해서 늘어납니다. 문서가 권하는 것은 네 가지입니다.

• 팀원은 Sonnet으로 둔다. 조율 작업에는 성능과 비용 균형이 맞다
• 팀을 작게 유지한다. 팀원마다 컨텍스트 윈도가 하나씩 붙으니 사용량이 팀 크기에 거의 비례한다
• spawn 프롬프트를 좁게 쓴다. 팀원은 지침 파일과 MCP 서버와 스킬을 자동으로 불러오는데, 여기에 프롬프트에 적은 것이 처음부터 더해진다
• 일이 끝난 팀원은 내린다. 활성 상태인 팀원은 종료되거나 세션이 끝날 때까지 계속 토큰을 쓴다

이 기능은 기본이 비활성이고 환경 변수로 켜야 합니다. 켜본 적이 없다면 이 항목은 건너뛰어도 됩니다.

이 순서에는 이유가 있습니다. 위로 갈수록 한 번 손보면 계속 효과가 남고, 아래로 갈수록 설정하는 비용이 듭니다. 저는 1번과 2번만으로도 체감이 있었고, 3번과 4번은 프로젝트가 커진 쪽에만 넣었습니다. 5번은 팀을 안 띄우면 해당이 없습니다.

버전에 따라 화면이 다릅니다

이 글을 쓰면서 가장 의외였던 부분입니다. 같은 /usage 화면인데 버전마다 보여주는 것과 계산 규칙이 달랐습니다.

그래서 남의 글이나 예전 스크린샷과 내 화면이 다르면 설정 문제가 아니라 버전 차이일 수 있습니다. 판단하기 전에 claude --version을 먼저 봅니다. 제 환경은 2.1.274라 위 항목이 전부 적용된 상태입니다.

사용량 조회가 실패하면 어떻게 될까요?

가장 흔한 원인이 사용량 엔드포인트 자체가 속도 제한에 걸린 경우입니다. 이때 클로드 코드는 오류만 던지지 않고, 이 기계에서 최근 60분 안에 불러온 마지막 바를 보여줍니다. 화면에는 마지막으로 알려진 사용량이라는 주석과 그 데이터를 얼마 전에 가져왔는지가 같이 표시됩니다.

r을 누르면 재시도하고, 성공하면 옛 바가 새 값으로 교체됩니다. 60분 안에 스냅샷이 없으면 속도 제한에 걸렸다고 알려주면서 같은 재시도 단축키를 제안합니다.

이 동작을 모르면 옛 숫자를 현재 값으로 착각할 수 있습니다. 주석이 붙어 있는지부터 보는 것이 맞습니다.

토큰이 아니라 일하는 방식을 보고 싶다면

/insights가 다른 각도를 줍니다. 토큰을 얼마나 썼느냐가 아니라 어떻게 일했느냐를 보고서로 만들어줍니다. 이 기계의 최근 세션을 분석해서 무엇을 주로 작업했는지, 요청이 잘못 전달된 지점 같은 마찰이 어디였는지를 HTML 리포트로 씁니다.

사용량 최적화와 목적이 다릅니다. /usage가 무엇이 비쌌는지를 답한다면 /insights는 무엇이 잘 안 통했는지를 답합니다. 저는 한도가 아니라 왕복이 많아 느려진 날에 이쪽이 더 도움이 됐습니다.

코덱스와 비교하면 어떨까요?

확인 경로의 유무부터 다릅니다. 코덱스 CLI의 비대화형 서브커맨드를 전수로 훑어봤는데, 사용량이나 한도를 조회하는 전용 명령이 없었습니다.

codex --help
exec review login logout mcp plugin mcp-server app-server remote-control
app completion update doctor sandbox debug apply resume archive delete
unarchive fork cloud exec-server features help

25개 중에 usage나 limit에 해당하는 것은 없습니다. 반면 클로드 코드는 /usage 한 화면에 플랜 소진도와 귀속 비율과 행동 플래그를 모아둡니다. “무엇이 내 한도를 먹었는가”를 도구가 직접 답해주는지가 두 도구의 차이입니다.

다만 여기서 분명히 해둘 것이 있습니다. 저는 코덱스 CLI의 대화형 화면 안에서 같은 정보를 볼 수 있는지까지는 확인하지 못했습니다. 위 비교는 비대화형 명령 표면에 한정된 관찰이고, 두 도구의 플랜별 한도 수치를 나란히 놓는 비교는 공식 수치를 확인하지 못해 이번 글에서 하지 않았습니다. 요금과 한도 수치가 필요하면 각 사의 요금 페이지를 보는 것이 맞습니다. 클로드 쪽 구독 요금은 클로드 요금 페이지에 있습니다.

그리고 필자의 결론

클로드 코드 사용량 문제의 절반은 한도가 아니라 가시성입니다. 저는 한도에 걸릴 때마다 원인을 짐작했는데, 도구가 이미 스킬과 서브에이전트와 MCP 서버별 비율로 답을 갖고 있었습니다. 열어보지 않은 화면 하나 때문에 짐작으로 도구를 떼고 붙이고 있었던 셈입니다.

그래서 순서를 바꿨습니다. 한도 경고가 뜨면 기다리기 전에 /usage를 먼저 열고, 24시간과 7일을 번갈아 보고, 10% 이상으로 플래그가 선 항목부터 손을 댑니다.

반대로 이번에 안 한 것도 적어둡니다. 제 계정의 실제 소진 수치는 이 글에 넣지 않았습니다. 플랜과 조직 설정에 따라 다른 값이라 남의 환경에 그대로 대입되지 않고, 제 숫자를 공개할 이유도 없습니다. 이 글이 주려는 것은 제 수치가 아니라 확인 경로입니다.

한도 정책 자체도 바뀝니다. 그래서 숫자보다 구조에 무게를 뒀습니다. 창이 5시간과 주간으로 두 겹이고, 모델별로 따로 잡히고, 팀 플랜에서는 채팅과 공유된다는 구조는 정책이 조정돼도 판단 순서를 그대로 지켜줍니다.

무엇이 토큰을 먹는지 줄이는 쪽은 예전에 따로 정리한 적이 있습니다. 클로드 코드 플러그인 토큰 줄이기가 상시 로딩되는 쪽을 다루고, 도구에 권한을 얼마나 줄지는 AI 에이전트 권한 설계에 있습니다. 컨텍스트와 세션 관리를 책 한 권으로 보고 싶으면 클로드 코드 에이전틱 코딩 서평의 16장 정리를 참고하시면 됩니다. 다른 도구의 무료 한도를 같은 틀로 정리한 글은 퍼플렉시티 무료 한도와 Pro 차이입니다.

The post [DevOps] 클로드 코드 사용량 확인 3가지 appeared first on WONIZZ.LOG.