AI 코딩 도구 잔여량이 다르게 보이는 이유는?

첫 번째 차이: 서로 다른 기간을 보고 있습니다

사용량 화면에는 보통 ‘남은 비율’ 하나만 있는 것처럼 보이지만, 실제 데이터는 여러 한도 창(window)으로 나뉠 수 있습니다. 예를 들어 같은 제공자 안에도 단기 창과 주간 창이 따로 있을 수 있고, 다른 제공자는 계약 자체가 다릅니다. QuotaBeacon의 도메인 모델은 창 종류, 사용 비율, 재설정 시각을 별도 값으로 보관합니다. 일부 창이 응답에 없으면 없는 상태로 남기며 0%로 채워 넣지 않습니다.

이 글의 비교 예시는 사용 비율을 기준으로 읽습니다. 같은 한도 창에서 사용 비율이 40%라면 잔여 비율은 60%입니다. 반대로 잔여 비율 40%는 사용 비율 60%이므로, 사용·잔여 표기를 바꾸지 않고 같은 숫자처럼 비교해서는 안 됩니다.

여기서 가장 흔한 실수는 단기 창의 사용 비율 40%와 주간 창의 사용 비율 40%를 더해 ‘총 80%를 썼다’고 말하는 것입니다. 두 값은 기간과 대상이 달라 합계가 의미를 갖지 않습니다. 같은 예산의 서로 다른 지출 항목도 아니고, 서로 다른 시간 눈금의 측정치에 가깝습니다. 어느 창이 먼저 리셋되는지에 따라 다음 작업 가능성도 달라질 수 있습니다.

위 막대는 설명용 가상 도식입니다. 실제 Claude Code, Codex, Gemini, Grok, Z.ai 계정의 현재 비율이 아닙니다. 숫자를 읽을 때는 먼저 화면의 창 이름과 재설정 시각을 확인하세요. 서비스가 특정 창을 제공하지 않았는데 다른 서비스의 명칭을 억지로 끼워 맞추면 비교가 더 부정확해집니다.

같은 제공자라도 재설정 시각이 달라진 새 창은 이전 창과 동일한 관측 대상으로 취급해서는 안 됩니다. 저장소 테스트는 같은 종류의 창이라도 reset timestamp가 바뀌면 다른 window instance로 식별하는 경우를 검사합니다. 예전 창의 값과 새 창의 값을 연속 그래프로 연결할 때 주의해야 하는 이유입니다. 리셋 전 90% 사용과 리셋 후 10% 사용을 단순 감소 추세로 읽으면 잘못된 결론을 낼 수 있습니다.

두 번째 차이: 관측 시각이 다릅니다

앱을 새로 열었거나 새로고침 버튼을 눌렀다고 해서 모든 제공자가 같은 순간에 성공적으로 응답한 것은 아닙니다. 한쪽은 방금 응답했고, 다른 쪽은 캐시 값을 다시 보여주거나 이전에 성공한 값을 ‘오래된 값’으로 유지할 수 있습니다. QuotaBeacon은 값과 함께 관측 시각, freshness, 수집 출처를 모델에 넣습니다. 새 관측과 단순 캐시 재사용을 구별하려는 설계입니다.

가정 예시로, 오전 9시에 확인한 사용 비율 40%와 오전 11시에 확인한 사용 비율 35%를 나란히 놓았다고 해 보겠습니다. 두 값의 차이가 서비스 정책 차이인지, 그 사이의 사용 때문인지, 서로 다른 창 때문인지는 이 숫자만으로 알 수 없습니다. 비교 대상과 시각을 먼저 맞춰야 합니다. 이 시간·비율은 설명용 예시이며 실제 계정 측정값이 아닙니다.

특히 네트워크 오류 뒤에 마지막 성공값이 남아 있다면 ‘현재 잔여량’처럼 읽어서는 안 됩니다. 저장소의 테스트에는 마지막 정상값을 유지하면서 상태와 freshness를 stale로 바꾸는 경우가 있습니다. 이는 값을 무조건 버리는 것보다 맥락을 보존하지만, 새 관측과 같다는 뜻은 아닙니다. 화면에 보이는 40%가 10분 전의 값인지, 지금의 값인지가 작업 판단에 중요합니다.

세 번째 차이: 출처와 계약이 다릅니다

수집 경로가 공식 CLI 출력인지, 제공자의 읽기 전용 API인지, 로컬에서 집계한 사용 기록인지에 따라 의미가 달라집니다. QuotaBeacon은 Provider별 어댑터를 두고 얻은 값을 공통 스냅샷으로 정규화하지만, 출처 자체는 지우지 않습니다. 같은 비율 모양으로 표시하더라도 ‘어디서 온 숫자인가’가 남아 있어야 독자가 신뢰 범위를 판단할 수 있기 때문입니다.

예를 들어 로컬 기록의 사용량은 공식 구독 잔여량과 자동으로 같아지지 않습니다. 로컬에서 관찰한 요청 수, 비용 추정, 서버가 알려준 한도는 측정 대상과 계산 방식이 다를 수 있습니다. 이 글에서는 현재 가격이나 특정 요금제의 분당·주당 할당량을 제시하지 않습니다. 그런 값은 서비스와 계정 상태에 따라 달라지고, 이 저장소만으로 독자의 계약을 확인할 수 없기 때문입니다.

위 화면은 저장소에 들어 있는 QuotaBeacon 문서 이미지입니다. 제공자별 연결·오류 상태를 한 자리에 보여주지만, 이미지 속 상태를 지금 독자의 계정 상태나 최신 서비스 장애로 읽으면 안 됩니다. 화면의 숫자보다 중요한 정보는 각 제공자 줄의 상태, 실제 한도 창, 출처와 관측 시각입니다. 연결이 안 된 제공자와 정상 응답이지만 사용량을 보내지 않은 제공자도 구분해야 합니다.

빈 값은 0이 아닙니다

어떤 제공자에서 창 하나가 빠졌다면 그 창을 0% 사용 또는 100% 남음으로 번역해서는 안 됩니다. ‘알 수 없음’은 편의상 비워 둔 숫자가 아니라 다른 상태입니다. QuotaBeacon의 표시 코드는 성공 응답에 창이 없을 때도 서버가 사용량을 제공하지 않았다는 설명을 선택합니다. 파서 테스트에는 부분 응답에서 창 하나만 남기거나 reset 시각이 없는 값을 그대로 보존하는 사례가 있습니다.

이 차이는 실무적으로 큽니다. 0% 사용이라고 믿고 긴 작업을 시작했다가 실제 한도에 걸릴 수 있고, 반대로 단순 인증 오류를 한도 소진으로 오해해 작업 계획을 불필요하게 바꿀 수도 있습니다. 먼저 “데이터 없음”의 이유가 미연결, 인증 실패, 일시적 네트워크 오류, 정상적인 빈 응답 중 무엇인지 확인해야 합니다. 원인을 알기 전에는 값을 채워 넣는 대신 ‘확인 필요’로 남기는 편이 정확합니다.

실제로 읽을 때의 네 가지 질문

잔여량 숫자 하나를 확인할 때 아래 순서로 읽어 보세요. 다른 제품에도 적용할 수 있는 일반적인 판독 절차이지만, 버튼·메뉴 이름은 서비스마다 다릅니다.

1. 대상: 어느 제공자의 어느 한도 창인가요? 단기·주간 또는 모델별 창이 분리돼 있는지 확인합니다.
2. 시각: 언제 관측된 값인가요? 지금 새로 받은 값인지, 같은 관측값을 캐시로 다시 보여주는지 봅니다.
3. 출처: 제공자가 직접 알려 준 값인가요, 로컬 기록인가요? 출처가 다르면 숫자의 의미도 다를 수 있습니다.
4. 상태: 값이 없다면 정말 0인가요? 미연결·부분 응답·stale·오류를 구분합니다.

비교가 필요하다면 한 번에 하나의 조건만 맞춰 보세요. 같은 제공자, 같은 창, 비슷한 시각의 관측을 나란히 둔 뒤 차이를 확인합니다. 그래도 결과가 다르면 재설정 시각과 출처를 다시 봅니다. 추세 그래프가 있다면 리셋 전후를 한 창처럼 연결하지 않았는지도 확인하세요. 여러 제공자의 %를 합산해 ‘통합 잔여량’이라는 한 숫자를 만들지 않는 것이 출발점입니다.

QuotaBeacon 저장소에는 여러 최신 개발 항목과 별도 배포·검증 상태가 함께 기록돼 있습니다. 따라서 이 글은 특정 개발본을 설치해 정상 작동을 확인한 후기라고 주장하지 않습니다. 저장소에서 확인되는 데이터 구분 원칙만 사용합니다. 실제 서비스의 한도 정책과 인증 방식은 현재 공식 자료에서 따로 확인해야 합니다.

정리하면, 잔여량은 숫자 하나가 아니라 대상·기간·관측 시각·출처·상태가 붙은 관측값입니다. 값이 서로 다를 때는 어느 쪽이 틀렸다고 단정하기 전에 이 다섯 항목을 나란히 적어 보세요. 빠진 값은 0으로 채우지 말고 빠졌다는 사실을 보존해야 다음 확인 행동도 정확해집니다.

다음 글은 그래프의 연결선에도 비슷한 원칙을 적용합니다. 보이는 선과 원문으로 확인할 수 있는 관계를 분리해 읽는 방법입니다.