AI 에이전트 토큰 절약 운영법: 토큰 아끼려고 AI 작업 프로세스를 다시 짰다

개인 프로젝트(원본 앱을 통째로 복제해 디자인만 바꾼 클론을 뽑는 도구)를 Claude Code로 밤새 돌리는 일이 잦아졌다. 8월 말~9월 초에 토큰이 눈에 띄게 새는 자리가 보여서, 일주일 동안 운영 방식을 하나씩 바꿨다.

코드 기능이 아니라 **"AI가 일하는 절차"**를 바꾼 것들이고, 전부 리포에 PR로 남아 있다.

새는 자리가 다섯 종류였다

1. 매 세션 같은 지침을 통째로 읽는다. 리포 진입 지침(CLAUDE.md)이 600줄이었고 그중 82%가 게이트 명령어 목록이었다. 화면(web)만 만지는 세션도 조립 도구 설명 379줄을 전부 읽고 시작했다.
2. 검사가 필요 이상으로 돈다. 한 줄만 바꿔도 전 영역 게이트를 다시 돌렸다. 검증 결과가 "워크트리 전체 해시"에 묶여 있어서 무관한 파일 한 줄에도 green이 무효가 됐다.
3. 압축은 되는데 세션 교체가 안 된다. 밤샘 주행 한 세션에서 압축 18회, 새 세션으로 넘긴 건 0회. 압축이 두 번째부터는 "요약의 요약"이라 코드는 남는데 결정과 함정이 죽는다. 그러면 다음 턴이 같은 함정을 다시 밟으며 토큰을 태운다.
4. 비싼 모델이 안 비싼 일을 한다. 계획도 구현도 검토도 같은 모델이 했다. 수정 라운드마다 큰 모델을 재개하니 한 태스크에 재개 5회 이상이 나왔다.
5. 사람이 병목이다. PR마다 내 승인을 기다렸는데 나는 코드를 볼 시간이 없었다. 기다리는 동안 컨텍스트는 그대로 살아 있다.

어떻게 풀었나

바꾼 것 하나하나와, 왜 그렇게 했는지.

1. 항상 읽는 지침을 600줄에서 109줄로

루트 지침에는 공통 규칙과 "어디를 읽나" 표만 남기고, 영역별 상세는 그 폴더의 CLAUDE.md로 옮겼다. 그 폴더를 만질 때만 읽힌다.

지우지 않고 옮겼다는 게 중요했다. 게이트 명령을 지우면 다음 PR 전까지 안내가 사라지니, 옮긴 뒤 옛 섹션 전 줄이 어느 파일로 갔는지 기계로 대조해 유실 0을 확인했다.

같은 김에 릴레이 규칙이 세 곳(루트·정본 문서·내 전역 설정)에 복사돼 있던 것도 정본 하나만 남기고 나머지는 가리키게 했다.

2. 검사 범위를 "영향받은 영역"으로

변경으로 무엇을 돌려야 하는지 도구가 정한다. 핵심은 범위가 **"수정한 파일"이 아니라 "검사가 읽는 것"**이라는 점이다. A 영역 검사가 B를 오라클로 띄우고 B는 C를 가져오면, C를 바꾸면 A 검증도 무효가 된다(전이 의존).

기준 완화가 아니라는 걸 문구로 못 박았다. 안 건드린 영역의 게이트는 결과가 같고, 모르는 검사가 하나라도 있으면 그 작업은 전체 범위다(안전한 쪽으로 실패). 처음엔 "귀속 못 하는 경로는 무관"으로 뒀다가 기존 테스트가 회귀를 드러내서 귀속 못 하는 경로는 공용으로 고쳤다.

3. 역할이 모델을 정한다

역할	언제	모델
scan	결과물이 명확한 독립 탐색(파일 목록·로그 요약)	작은 모델
design	큰 기능·리팩터의 계획 단계	제일 큰 모델
build	구현·버그 원인 분석·단순 수정 (기본값)	중간 모델

두 가지 결정이 들어 있다.

• 분류에서 모델을 파생하지 않는다. "긴 작업 + 산출"이 설계라는 보장이 없고(큰 구현도 그 모양), "조사"가 단순 탐색이라는 보장도 없다(버그 원인 분석이 그 모양). 조건으로 정하면 판단이 필요한 일이 조용히 작은 모델로 내려간다. 모르면 기본값.
• 단계가 바뀌면 역할도 바뀐다. 큰 기능도 계획만 큰 모델이고 구현으로 넘어가면 기본 모델. 작업 전체에 큰 모델이 고정되지 않는다.

구현을 작은 모델로 내리는 건 안 했다. 시도했다가 리뷰에서 되잡는 비용이 절약분보다 컸다.

4. 요청을 받으면 어떻게 판단하나

역할표는 "역할→모델"만 정하고 "이 요청이 어떤 역할인가"는 매번 판단이었다. 나는 내부 용어를 말하지 않으니 그 판단은 에이전트 몫이다. 그래서 기준을 문서에 박았다.

요청	어떻게
작은 수정·버그	한 세션. 계획 문서 따로 안 만든다
큰 기능·리팩터	계획 서브에이전트 → 작업 문서에 저장 → 구현
독립 탐색	작은 모델
독립 작업 2개 이상 + 실제 이득	그때만 병렬

나누는 것이 기본이 아니다. 분할이 재독·인계 비용을 늘리면 단일 세션. 목적은 토큰이지 에이전트 수가 아니다.

5. 작업 문서는 하나, 리포 안에

docs/work/<작업>.md 하나에 목표·완료 조건·결정·함정을 적고 커밋한다. 체크포인트 도구가 실행 상태 구역만 갱신한다.

전에는 상태 파일을 리포 밖 폴더에 뒀다가 그 폴더가 사라져 인계가 끊긴 적이 있다. 리포 밖은 유실된다.

6. 세션 릴레이 — 압축은 세고, 끊는 조건은 둘

• 압축 횟수는 추측하지 않고 훅이 센다. 세션은 자기가 몇 번 압축됐는지 모른다. 세션 시작 훅이 파일에 한 줄씩 남긴다.
• 방아쇠 둘 다 참일 때만 새 세션으로 넘긴다. ① 압축이 1회 이상 났다 ② 안전한 인계점에 있다(게이트 green + 커밋됨). 첫 압축은 요약이 원문에 충실해 거의 공짜라, "컨텍스트가 크다"가 아니라 "압축이 이미 한 번 났다"를 방아쇠로 잡았다.
• 탈출구. 압축 2회인데 안전한 인계점이 한 번도 없었으면 코드가 아니라 계획이 틀린 것이다(덩이가 컨텍스트보다 크다). 그때는 릴레이도 계속도 아니고 멈춘다. ## 막힘을 쓰고 세션을 끝낸다. 밤에 걸리면 아침에 내가 본다.
• 덩이 선언. 주행 시작 때 "덩이: PR 하나 이름"을 못 박는다. "이 축 전부"는 덩이가 아니다.

7. 리포 경량화

앞으로 키울 축이 하나인데 이전 단계 산출(옛 카탈로그·분석기·옛 스펙)이 그대로 쌓여 있었다. 289 파일 46,627줄을 지웠다(추적 파일 730→481). git 기록에 있으니 복구 가능.

읽을 게 줄면 탐색 토큰이 준다. 지우면서 깨지는 결속(숨은 심링크 의존 등)은 실주행으로 확인했다.

8. 제품 의도 정본 한 장

INTENT.md에 목적·대상 사용자·비목표·품질 기준만 담았다. 확정/제안/미결 표기를 구분했다.

"요청이 비목표에 걸리면 시작하지 않고 말한다." 되묻기와 헛일을 앞에서 자른다.

9. 두 AI의 검토 루프 — 같은 코드를 두 번 읽지 않기

AI 두 세션(Codex와 Claude)을 같이 쓰는데 역할을 갈랐다.

• Codex: 요구사항·승인 범위 전달, 결과 보고에서 완료 조건·검증·미해결만 확인. 제품 코드 구현·전체 재검토는 안 한다.
• Claude: 조사·구현·자체 검토·화면 확인·검증·수정까지 하고 근거 경로와 결과를 짧게 보고한다.
• 나: 방향·취향·범위 확대만 결정한다.

처음 안은 Codex가 검토까지 하는 거였는데, 두 세션이 같은 코드를 두 번 읽는 게 가장 큰 낭비라서 검토도 Claude가 자체 검토로 하고 Codex는 결과만 보게 바꿨다.

10. PR은 게이트 green이면 바로 머지

내가 지금 코드를 볼 시간이 없고, 이 리포는 원본 앱만 안 건드리면 전부 되돌릴 수 있으니 승인 대기는 순수 손실이다.

예외 둘. 원본 앱 리포에 쓰는 것(브랜치·커밋·PR 생성까지 전부 금지, 내가 시켜도 거절), 그리고 게이트 기준을 무르게 하는 변경은 기능 PR과 섞지 말고 별도 PR로 내고 머지 전 보고. 자동 머지가 "게이트를 고쳐서 green 만드는" 경로가 되면 안 되니까.

11. 검토는 모아서 한 번

수정 라운드마다 큰 모델을 재개하던 걸 바꿨다. 두 검토가 다 도착한 뒤 발견을 모아 수정 1회.

태스크마다 풀 리뷰를 하지 않고, 체크리스트에서 ❌인 항목만 리뷰·수정한다. 풀 리뷰는 머지 직전 한 번.

12. 짧고 쉬운 말

결론 한 줄 먼저, 지어낸 용어 금지, 세 가지 선택지 나열 금지, "이해 안 가"면 더 줄인다.

토큰 문제라기보다 내 읽는 시간 문제였는데, 결과적으로 보고 길이가 줄어 출력 토큰도 줄었다.

남길 것

토큰 절약은 모델을 작은 걸로 바꾸는 게 아니었다.

• 읽을 걸 줄이고 (지침 600→109줄, 리포 경량화)
• 다시 하는 걸 줄이고 (검사 범위 축소, 검토 모으기)
• 같은 걸 두 번 읽지 않게 하고 (검토 역할 분리)
• 사실이 죽기 전에 끊는 것 (압축 1회 + 안전 지점에서 세션 릴레이)

그리고 안전 규칙을 무르게 하는 변경은 절약 PR과 반드시 분리한다.

더 봐야 할 것

• 실효 토큰·컨텍스트 사용량은 관측 경로가 없어 미측정이다. 절약됐다는 건 체감이고 숫자가 없다
• 실제 압축이 난 세션에서 후속 세션이 완주한 실적이 아직 없다
• 결론 못 낸 것들은 다음 글에 따로 적었다