빌딩 인 퍼블릭: 17일차 - 토큰 한계와의 전쟁

문제의 시작: 작업이 중간에 끊긴다

Claude Pro의 20만 토큰 제한에 계속 걸렸습니다. 가끔이 아니라 거의 매번이었어요.

가장 답답한 건 작업 기록을 업데이트하려는 순간에 토큰이 바닥났다는 거예요. 작업의 90%를 끝내놓고, 문서화하려다가 토큰 부족으로 세션이 끝나버립니다.

다음 세션을 시작하면? “어디까지 했더라?” 하면서 다시 맥락을 찾아야 했죠.

실패한 세션의 전형적인 패턴:

0-5만 토큰:     문서 읽고 상황 파악
5-15만 토큰:    기능 개발
15-20만 토큰:   로그 업데이트 시도... 토큰 부족 ❌

100일 프로젝트를 이런 식으로 진행할 순 없었습니다.

토큰은 어디로 사라지나

먼저 토큰이 어디에 쓰이는지 분석했습니다. 범인은 바로 컨텍스트 로딩이었어요.

토큰 사용 내역:

메시지당 컨텍스트: 1만-1만5천 토큰
파일 읽기: 파일당 1천-1만 토큰
응답 생성: 2천-1만 토큰
같은 파일을 여러 번 읽기: 엄청난 낭비

200개의 메시지를 주고받으면서 매번 1만 토큰씩 컨텍스트를 로딩하면? 컨텍스트 재로딩만으로 200만 토큰이 사라집니다.

핵심 인사이트: 모든 메시지가 전체 컨텍스트를 다시 로딩합니다. 처음에 읽은 블로그 포스트가 이후 50번 더 컨텍스트로 로딩되는 거죠.

해결책 1: 세션 로그 자동 정리

문제: SESSION_LOG.md 파일이 890줄까지 커졌습니다. Claude가 세션 시작할 때마다 읽으면 2만 토큰이 날아갔어요.

maintain_session_log.py 스크립트 작성:

# 최근 3개 세션만 유지
# 오래된 세션은 backup/ 폴더로 자동 이동
# 구조와 연속성은 보존

효과:

이전: 890줄 = 세션 시작마다 2만 토큰
이후: 200줄 정도 = 세션 시작마다 5천 토큰
절약: 세션당 1만5천 토큰

스크립트는 세션 종료 시 자동 실행됩니다. 오래된 세션은 backup/SESSION_LOG.md에 보관되어 필요할 때 참조할 수 있어요.

해결책 2: 토큰 관리 시스템 구축

명확한 임계값을 가진 완전한 프로토콜을 만들었습니다:

토큰 사용 구간:

🟢 0-15만 (안전): 정상 작업, 작업 후 로그 업데이트
🟡 15만-16만 (마무리): 현재 작업 완료, 새 작업 시작 금지
🟠 16만-17만 (업데이트 필수): 로그 업데이트 필수
🔴 17만-18만 (정리): 최종 요약, 인수인계 노트
⛔ 18만+ (긴급): 최소한의 소통만

핵심 혁신: 점진적 업데이트

예전 방식:

15만 토큰 동안 작업 → 마지막에 로그 업데이트 시도 → 토큰 부족 ❌

새로운 방식:

작업 1 완료 → 로그 업데이트 [2만 토큰 시점]
작업 2 완료 → 로그 업데이트 [4만 토큰 시점]
작업 3 완료 → 로그 업데이트 [6만 토큰 시점]
로그가 항상 최신 상태! ✅

작업하면서 업데이트하는 거죠. 마지막까지 미루지 않고요. 16만 토큰에 도달하면 이미 모든 게 문서화되어 있습니다.

해결책 3: 긴급 템플릿 생성기

토큰이 부족할 때를 위한 emergency_log_update.py 스크립트를 만들었습니다:

python3 emergency_log_update.py

몇 초 만에 미리 포맷된 템플릿을 생성합니다. 빈칸만 채우면 돼요:

완료한 작업
미완성 작업
다음 세션에서 할 일

18만 토큰 상황에서도 2분 이내에 작성 가능합니다. 로그가 반드시 업데이트되도록 보장하죠.

해결책 4: 토큰 최적화

.claudeignore 파일을 강화해서 제외:

node_modules, dist, build 파일들 (5만+ 토큰 절약)
이미지, PDF, 동영상 (3만+ 토큰 절약)
백업과 아카이브 폴더 (2만+ 토큰 절약)
생성된 에셋들 (소스 파일만 읽기)

자동 절약 효과: 세션당 약 10만 토큰!

모범 사례 문서화:

#1: 파일을 두 번 읽지 마세요 (3만+ 절약)

나쁨:  파일 읽기 → 수정 → 다시 읽기 → 수정
좋음:  파일 한 번 읽기 → 여러 번 수정

#2: 탐색에는 Task 도구 사용 (4만+ 절약)

나쁨:  "X는 어떻게 작동하나?" → 파일 10개 직접 읽기 (5만 토큰)
좋음:  Task/Explore 에이전트가 조사 → 결과 보고 (5천 토큰)

#3: 읽기 전에 Grep으로 찾기 (2만+ 절약)

나쁨:  함수 찾으려고 파일 5개 읽기 (3만 토큰)
좋음:  Grep으로 찾기 → 해당 파일만 읽기 (5천5백 토큰)

완전한 시스템

종합 문서를 작성했습니다:

TOKEN_MANAGEMENT.md - 긴급 프로토콜

시각화된 토큰 구간 (🟢🟡🟠🔴⛔)
각 임계값별 단계별 지침
세션 워크플로우 다이어그램

TOKEN_OPTIMIZATION.md - 모범 사례 가이드

흔한 토큰 낭비 요인과 해결책
도구 사용 패턴 (Read vs Grep vs Task)
토큰 예산 전략
전/후 비교

QUICK_START_TOKEN_OPTIMIZATION.md - 요약 버전

상위 5개 토큰 절약 팁
빠른 참조 체크리스트
예상 결과

CLAUDE.md 업데이트

토큰 관리 및 세션 종료 프로토콜 섹션을 추가해서 AI 에이전트에게 지시:

토큰 사용량을 능동적으로 모니터링
세션 중 점진적으로 로그 업데이트
15만 토큰에서 새 작업 중단
16만 토큰에서 로그 업데이트 필수
수동 파일 읽기 대신 Task 도구 사용

이제 AI가 자동으로 이 프로토콜을 따릅니다.

결과

최적화 이전:

세션: 자주 미완성 ❌
토큰 사용: 20만 토큰, 여유 없음
문서화: 누락되는 경우 많음
연속성: 세션 간 연결 불량

최적화 이후:

세션: 2-4만 토큰 여유 있게 완료 ✅
작업량: 세션당 2-3배 증가
문서화: 항상 업데이트됨
연속성: 매끄러운 인수인계

실제 세션당 토큰 절약:

강화된 .claudeignore: 10만 토큰 자동 절약
중복 읽기 방지: 3만 토큰 절약
Task 도구 활용: 탐색당 4만 토큰 절약
점진적 업데이트: 완료 보장

총: 50-70% 더 많은 작업 수행 가능!

배운 점

1. 토큰 제한은 더 많이 하는 게 아니라 시작한 걸 끝내는 것

깔끔하게 완료된 8만 토큰 세션이 미완성 20만 토큰 세션보다 낫습니다.

2. 점진적 업데이트가 일괄 업데이트보다 우수

토큰이 넉넉할 때 작업 후마다 로그를 업데이트하세요. 마지막까지 미루지 마세요.

3. 컨텍스트 로딩이 숨은 살인자

눈에 보이진 않지만 모든 메시지가 전체를 다시 로딩합니다. 공격적인 .claudeignore가 필수입니다.

4. 자동화가 인지 부담을 줄인다

개발자에게 로그 업데이트를 기억하라고 하지 마세요. 자동화하세요. 체크리스트가 아니라 시스템을 만드세요.

5. 긴급 상황에선 도구가 빨라야 한다

긴급 템플릿 스크립트는 18만 토큰 상황에서도 2분 안에 작동합니다. 토큰이 바닥날 때는 속도가 생명이죠.

변화

생성된 파일:

maintain_session_log.py - 오래된 세션 자동 아카이브
emergency_log_update.py - 긴급 템플릿 생성기
TOKEN_MANAGEMENT.md - 긴급 프로토콜
TOKEN_OPTIMIZATION.md - 모범 사례 가이드
QUICK_START_TOKEN_OPTIMIZATION.md - 빠른 참조

업데이트된 파일:

CLAUDE.md - 토큰 관리 프로토콜 추가
.claudeignore - 포괄적인 제외 목록으로 강화
SESSION_LOG.md - Day 17 작업 내용 업데이트
PROJECT_STATUS.md - Day 14-17 마일스톤 추가

철학

목표는 한 세션에 모든 걸 쑤셔넣는 게 아닙니다.

목표는 명확한 연속성을 유지하며 지속적인 진전을 만드는 것입니다.

불완전한 문서를 남긴 하나의 세션보다, 좋은 인수인계를 가진 2-3개의 완전한 세션이 낫습니다.

다음 단계

이 시스템은 프로젝트의 남은 83일을 위한 준비가 끝났습니다. 이제 모든 세션은:

최소한의 컨텍스트로 시작 (강화된 .claudeignore)
세션 중 점진적으로 로그 업데이트
문서화와 함께 깔끔하게 완료
다음 세션으로 매끄럽게 인계

토큰 제한 문제는 해결됐습니다.

이제 더 많은 스토리를 만들 시간입니다.

To be continued…