토큰 이코노미와 AI 프레임워크 설계 원칙

이 글은 SEMO 구축기 시리즈의 두 번째 글입니다.

1,800줄의 CLAUDE.md가 만든 토큰 지옥

SAX가 11개 역할 기반 패키지로 성장했을 때, 각 패키지의 CLAUDE.md를 합치면 총 1,800줄이었습니다. AI에게 프로젝트 규칙을 전달하려면 이 모든 내용이 컨텍스트 윈도우에 들어가야 했죠. 결과는 세 가지 문제로 나타났습니다.

1. 느려지는 응답 — 컨텍스트 윈도우의 상당 부분을 규칙 문서가 차지하면서, 복잡한 작업에서 응답 시간이 3초를 넘기기 시작했습니다.

2. 빈번한 컨텍스트 초과 — 히스토리가 쌓이면 기하급수적으로 토큰이 늘어나, 주 5회 이상 컨텍스트 초과 경고가 발생했습니다.

3. AI의 혼란 — 너무 많은 규칙이 한꺼번에 주입되면 AI가 오히려 중요한 규칙을 놓치는 역설적 상황이 벌어졌습니다.

분석 결과, 11개 패키지에 걸쳐 약 1,100줄이 중복이었습니다. 초기화 로직 50줄, Orchestrator 규칙 30줄, 메시지 포맷 20줄이 모든 패키지에 반복되고 있었죠.

토큰 경제학이라는 프레임

이 문제를 해결하기 위해 우리가 도입한 사고 프레임은 토큰 경제학(Token Economics)이었습니다. LLM의 컨텍스트 윈도우를 유한한 자원—화폐—으로 보는 관점입니다.

토큰을 아끼는 건 비용 절감만이 아니다. 품질과 속도의 문제다. 토큰이 적으면 컨텍스트 부족, 많으면 AI가 혼란. '적정'이 핵심이다.

토큰 사용량은 비용, 속도, 품질에 동시에 영향을 줍니다. 적게 쓰면 저렴하고 빠르지만 맥락이 부족하고, 많이 쓰면 느리고 비싸며 오히려 AI가 중요한 정보를 놓칩니다. 최적 지점을 찾는 것이 AI 프레임워크 설계의 핵심 과제입니다.

해결: Progressive Disclosure 패턴

우리가 적용한 핵심 전략은 Progressive Disclosure(점진적 공개)입니다. UX 디자인에서 빌려온 개념으로, '사용자에게 필요한 정보를 필요한 시점에만 보여준다'는 원칙을 AI 컨텍스트 관리에 적용했습니다.

전략 1: 공유 문서 분리

공통 내용을 _shared/ 디렉토리로 분리했습니다. 초기화 로직, 코어 원칙 참조, Orchestrator 규칙을 한 곳에 모으고, 각 패키지의 CLAUDE.md는 핵심 전문 내용만 남겼습니다. 1,800줄이 800줄로 줄었습니다.

전략 2: 온디맨드 컨텍스트 로딩

CLAUDE.md에는 기본 원칙만 두고, 스킬별 상세 지침은 해당 스킬이 호출될 때만 로드하도록 설계했습니다. 예를 들어 테스트 작성 요청이 들어오면 그때 TESTING_RULES.md를 참조합니다. 코드 구현 요청에서는 테스트 규칙이 로드되지 않으므로 불필요한 토큰 소비가 사라집니다.

전략 3: 패키지 맵으로 사일로 해소

각 패키지가 서로의 존재를 모르는 사일로 문제는 PACKAGE_MAP.md로 해결했습니다. 설치된 패키지 목록과 협업 규칙을 명시해, 풀스택 작업 시 Orchestrator가 자동으로 다수의 패키지를 조율할 수 있게 했습니다.

결과: 숫자가 증명한 최적화

토큰 최적화(v0.27.0) 적용 후 측정된 결과입니다.

• CLAUDE.md 총량: 1,800줄 → 800줄 (55% 감소)

• 평균 응답 시간: 3.2초 → 1.8초 (44% 개선)

• 컨텍스트 초과 빈도: 주 5회 → 주 1회 (80% 감소)

핵심 교훈은 명확합니다. AI 프레임워크를 설계할 때 토큰은 유한한 자원이라는 전제에서 출발해야 합니다. '더 많은 규칙 = 더 좋은 결과'가 아니라, '적정한 규칙 = 최적의 결과'입니다. 이 원칙은 이후 기능 기반 아키텍처 전환에서도 핵심 설계 제약으로 작용했습니다.

다음 글에서는 토큰 문제보다 더 예상치 못했던 위기—LLM 네이밍 충돌 사고를 다룹니다.