문서는 토큰 청구서를 크게 줄이지 않는다 — 대신 Agent가 헤매는 시간을 줄인다

2026.07.06 게시

이 시리즈는 작성 시점의 기록이다. 현재 기준은 Adaptive Agentic SDD 저장소에 정리해두었다.

문서는 토큰 청구서를 크게 줄이지 않는다 — 대신 Agent가 헤매는 시간을 줄인다

들어가며

실제로 프로젝트를 하면서, 주니어들이 레거시 소스를 제대로 분석하지 않고 바로 작업에 들어가는 경우를 많이 봤다. 이유는 대체로 비슷했다. 불필요하게 남은 코드가 많고, 라인 수가 너무 길고, 주석은 불친절하고, 담당자가 몇 번 바뀌면서 스타일 통일성이 깨져 있었다. 분석하느니 새로 짜는 게 낫겠다는 생각이 드는 것도 이해는 간다.

이 글은 그 반대편 이야기다. 코드를 새로 짤 수 없는 조건(민감 도메인, 다중 데이터소스, 화면 로직까지 얽힌 대형 공용 코드)에서, 코드 대신 문서로 경계를 만들어보면 어떻게 되는지 실제로 해본 기록이다.

이전 글에서는 SDD로 생성된 requirements·plan·backlog 등을 병합 후 지울 임시 산출물과 도메인 옆에 남길 운영 문서로 나누는 기준을 정리했다.

Link - 개발이 끝난 SDD 문서, 지울 것과 도메인에 남길 것

그 글을 작성하던 중 codex 리뷰에서 나온 제안이 이번 실험의 출발점이었다.

먼저 결론부터 말하면, business 문서는 토큰 비용을 극적으로 줄여주지는 않았다. 대신 Agent가 코드를 헤매는 왕복을 줄였고, 뜻밖에도 문서 자체가 현행 코드와 어긋나 있다는 사실을 드러냈다.

이번 실험에서 내가 얻은 결론은 세 가지다.

첫째, 여러 도메인 로직이 하나의 공용 코드에 뒤섞여 있을 때는 문서가 그 경계를 대신 정의할 수 있다. 둘째, Agent용 문서는 친절한 설명서가 아니라, 행동을 바꾸는 사실만 남긴 고밀도 운영 문서여야 한다. 셋째, SDD 산출물을 business 문서로 승격한다는 건 복사가 아니라, 현행 코드를 기준으로 다시 검증하고 쓰는 일이다.

이 글의 숫자는 설계 단계까지의 n=1 관찰이다. 측정 범위는 SDD 등급 판단과 설계 단계까지이며, 실제 코드 수정·빌드·테스트 단계는 포함하지 않았다. 따라서 결론은 “문서가 항상 토큰을 줄인다”가 아니라, “이번 사례에서는 탐색 왕복을 줄이는 신호가 보였다”에 가깝다. cost 역시 참고용 보조 지표로만 본다.

대상은 상품 할인 기능이다.

1. 코드에 경계가 없으면, 문서가 경계를 만든다

처음 원했던 구조는 단순했다. 할인 도메인 아래에 Target 할인 기능이 있고, 그 아래에 controller, service, business 문서가 함께 놓이는 구조였다.

대략 이런 식이다.

discount
└── Target
    ├── controller
    ├── service
    └── business
        └── BUSINESS.md

이렇게 되어 있다면 business 문서를 어디에 둘지 고민할 필요가 거의 없다. 실제 코드가 위치한 비즈니스 도메인 안에 business/BUSINESS.md를 두고, 이 문서를 운영 중에도 계속 갱신되는 현행 로직 설명서로 쓰면 된다.

문제는 해당 프로젝트가 오래된 레거시 구조라는 점이었다. 코드가 비즈니스 도메인 단위로 나뉘어 있지 않았고, 할인 도메인 아래에 여러 기능이 통으로 들어가 있었다. 예를 들면 구조가 이런 식에 가까웠다.

discount
└── controller
    └── TargetFeatureController

실제 로직은 이 안에서 메서드 단위로 나뉘어 있었고, Target 할인 기능만을 위한 독립된 패키지가 따로 존재하지 않았다. controller, service, business 같은 계층을 Target 할인이라는 비즈니스 도메인 아래에 자연스럽게 묶을 수 있는 구조가 아니었다.

그러다 보니 BUSINESS.md를 코드 옆에 둔다고 해도 문제가 남았다. 어느 위치가 “Target 할인 기능의 옆”인지 애매했기 때문이다. 물리적인 패키지 구조는 할인 전체를 기준으로 잡혀 있었고, 내가 문서로 관리하고 싶었던 단위는 그보다 더 작은 비즈니스 로직 단위였다.

그렇다고 이 시점에 코드를 먼저 나누는 건 리스크가 컸다. 오래된 레거시 코드에서 패키지를 옮기는 일은 단순한 파일 이동이 아니다. 의존성, 스캔 경로, 데이터소스, 화면 흐름까지 같이 확인해야 한다. 문서를 정리하려고 시작한 일이 실제 구현 구조 변경으로 번지면 배보다 배꼽이 커질 수 있었다.

그래서 결정한 건 이거다.

코드는 그대로 두고, business 폴더를 만들어 문서에서 먼저 비즈니스 경계를 분리한다.

즉 실제 코드는 아직 discount 아래의 공용 구조에 남아 있지만, 문서는 다음과 같은 지향 구조를 먼저 갖게 한다.

<domain>
└── business
    └── <비즈니스 로직>
        └── BUSINESS.md

코드를 당장 옮기지는 않지만, 문서만큼은 “이 로직이 독립된 비즈니스 단위라면 어디에 있어야 하는가”를 기준으로 배치한다. 이렇게 하면 현재 코드 구조가 비즈니스 경계를 잘 드러내지 못하더라도, Agent는 business 문서를 통해 이 기능의 경계를 먼저 파악할 수 있다.

이번 시도는 여기서 출발했다. 코드 구조 안에 경계가 없으면, 문서가 그 경계를 먼저 정의한다.

2. SDD 산출물과 운영 문서는 다르다

BUSINESS.md 초안을 만드는 과정에서 Agent가 기존 SDD 산출물에 참조 링크를 걸었다. 참고할 만한 배경이 SDD 문서에 많이 있었기 때문에, Agent 입장에서는 자연스러운 선택이었을 것이다.

하지만 나는 그 참조를 끊게 했다. 개발 당시 작성한 SDD 문서는 개발이라는 행위 자체로 목적이 끝난 문서이고, 지금 만드는 business 문서는 운영에서 지속적으로 품질을 유지해야 하는 별개의 문서라고 봤기 때문이다. 링크를 걸어두면 이 새 문서가 “개발 문서의 후속편”처럼 읽힌다. 운영 문서는 독립해서 살아야 했다.

그래서 링크를 전부 제거했다. 두 문서는 이제 서로를 모른다. 그리고 이때 원칙 하나가 같이 정해졌다.

승격은 복사가 아니라, 코드를 근거로 다시 쓰는 것이다.

이 원칙이 나중에 실험을 통해 스스로 어겨졌다는 걸 확인하게 되는데, 그 이야기는 뒤에서 한다.

3. Agent가 읽을 문서의 밀도 기준

초안은 폴더의 성격, 만든 배경, 철학적 설명까지 담느라 230줄 가까이 늘어져 있었다. 사람이 읽기엔 친절해 보였지만, 다시 보니 이상했다.

폴더 성격을 Agent가 알아야 하나? 로직만 파악하게 컴팩트한 게 맞지 않나.

메타 설명은 전부 규칙 문서(project-pr-business-rules.md) 쪽으로 옮기고, 포함 기준을 하나로 좁혔다.

이걸 모르면 로직을 틀리게 건드리는가?

이 기준으로 걸러내니 230줄이 85줄로 줄었다.

사람용 문서와 Agent용 문서는 밀도 기준 자체가 다르다. 사람용 문서는 맥락과 배경을 담아도 된다. 하지만 Agent용 운영 문서는 배경 설명보다 행동을 바꾸는 사실이 중요하다. 어디를 봐야 하는지, 어떤 계산식이 현행인지, 어떤 테이블과 컬럼이 실제 기준인지, 어디를 건드리면 위험한지 같은 정보다.

다시 말해 Agent용 business 문서는 친절한 해설서가 아니다. Agent가 잘못 움직이지 않게 만드는 고밀도 경계 문서에 가깝다.

4. 규칙으로 못박기 — project-pr-business-rules.md

여기까지 나온 결정들(경계 정의 방식, SDD-운영 분리, 밀도 기준)을 매번 다시 판단하지 않도록 루트에 project-pr-business-rules.md를 만들었다. CLAUDE.md/AGENTS.md와 같은 티어의 문서다. 구조는 3계층이다.

  1. 기조 — CLAUDE.md/AGENTS.md, 프로젝트 전체의 원칙
  2. 운영 규칙 — project-pr-business-rules.md, SDD 산출물과 도메인 문서를 어떻게 다룰지
  3. 도메인 지식 — SDD 산출물(이력용, 고정) / business 문서(현행, 갱신 대상)

위로 갈수록 안정적이고, 아래로 갈수록 자주 바뀐다. 이 그라데이션은 나중에 business 문서 자동 갱신을 고민할 때도 중요한 기준이 된다.

5. 효과가 있는지 재보기로 했다

여기까지는 다 정성적인 판단이었다. “이렇게 하니 나을 것 같다”는 감각 말고, 실제로 Agent의 탐색이 줄어드는지 재보고 싶었다.

먼저 측정 끝점을 정해야 했다. 이 팀의 작업 규칙상 SDD 등급 판단과 문서 작성까지가 “1차 depth”다. 코드를 실제로 고치는 건 그다음 단계다. 그래서 설계까지만(design-only) 측정하기로 했다. 코드 수정은 범위 밖이다.

방법은 단순하다. claude -p로 매번 새 세션을 열고, WITH는 BUSINESS.md를 프롬프트에서 가리킨다. WITHOUT은 BUSINESS.md, project-pr-business-rules.md, SDD 문서 세 종류를 전부 숨긴다. 그리고 세션 로그(JSONL)를 파싱해서 새로 처리한 토큰량(FRESH = input + cache_creation), 탐색 명령 수, 툴 호출 수, 턴 수, 비용을 뽑았다.

다시 강조하지만, 이 실험은 전체 개발 사이클 측정이 아니다. SDD 등급 판단과 설계 단계에서 Agent가 얼마나 덜 헤매는지를 본 것이다.

6. 반전: 문서가 틀렸다

측정을 시작하자마자 예상 못 한 일이 벌어졌다. 문서가 있는 조건(T2)에서 Agent가 이렇게 보고했다.

BUSINESS.md의 계산식이 현행 SQL과 어긋난다.

무시하고 넘어갈 수도 있었는데, 실제 SQL을 확인해봤다. Agent가 옳았다. 적용가는 저장값을 그대로 쓰고(반올림 없음), 절삭은 할인가에만 적용되며, 할인 정보는 조회 시 조인되지 않는다는 게 실제 코드였다. BUSINESS.md는 그렇게 적혀 있지 않았다.

원인을 찾아보니 명확했다. BUSINESS.md를 만들 때 기존 as-is 문서에서 내용을 가져왔는데, 그건 쿠폰 로직이 들어가기 이전 상태였다. 브랜치가 SQL을 바꿨는데, 문서는 그걸 따라가지 못한 채로 남아 있었던 것이다.

앞에서 정해놓은 원칙이 “복사하지 말고 코드 기준으로 재작성하라”였다. 그 원칙을 세운 사람이 바로 나였고, 그 원칙을 어긴 것도 나였다. 그리고 그걸 잡아낸 게 다른 사람의 리뷰가 아니라, 토큰을 재보려고 짠 실험 그 자체였다.

규칙을 문서로 적어두는 것과, 그 규칙을 실제로 지키는 것 사이엔 검증 장치 없이는 본인도 못 알아채는 간극이 있다. 이번 실험에서 처음 드러난 건 토큰 절감 효과가 아니라, 문서가 현행 코드와 어긋날 수 있다는 위험이었다.

7. 벤치마크도 쉽게 오염된다

문서를 고치고 나서 같은 조건(T2)을 다시 돌렸는데, 이번엔 다른 문제가 터졌다. 프롬프트에 있던 “작성”이라는 단어를 Agent가 파일 생성으로 해석해서, 실제로 md 파일을 써버렸다. 그 바람에 툴 호출과 토큰이 폭증했고, 비교 자체가 불가능해졌다.

프롬프트에 “어떤 파일도 생성·수정 금지, 표준출력만”이라고 명시적으로 못박았다. 그리고 애초에 코드에 타깃이 불명확했던 T2 태스크를, 실제 코드에 명확한 타깃이 있는 T2′(할인 계산 컬럼 절삭 로직 변경)로 교체했다.

동사 하나, “작성”이라는 단어 선택이 벤치마크 하나를 통째로 망칠 수 있다는 걸 여기서 배웠다.

그리고 이 과정에서 한 가지 문제가 더 나왔다. 측정 대상만 틀릴 수 있는 게 아니었다. 측정 도구도 틀릴 수 있었다.

처음 비용을 계산하던 파서에는 요율 상수 버그가 있었다. Opus 4.8 정규 요율의 3배에 해당하는 값이 박혀 있었고, 리뷰 과정에서 이 문제가 잡혔다. 정규 요율로 다시 계산하니 이 글의 모든 cost 수치는 절대값만 3으로 줄었고, 런 간 비율과 퍼센트 효과는 그대로였다.

다행히 이번에는 균일하게 3배가 곱해진 형태라 상대 비교가 깨지진 않았다. 하지만 위험한 우연이었다. 이번 실험에서 검증이 필요했던 건 문서만이 아니었다. 실험을 측정하는 도구도 검증 대상이었다.

8. 깨끗한 재측정 결과

정리한 조건으로 다시 돌린 결과다. 태스크는 두 개다.

T1 — 로직형: config/save에 특정 설정값의 상한 검증을 추가하는 작업. 요청 문장이 특정 심볼을 직접 부르지 않아서, Agent가 스스로 탐색해야 하는 유형이다.

지표 R1 문서有 R3 문서無 차이
FRESH(탐색 토큰) 54,316 78,183 −30%
Grep 횟수 3 7 −57%
툴 호출 9 12 −25%
turns 20 22 –
approx cost $1.09 $1.18 −8%

T2′ — 심볼형: 할인 계산 컬럼(기본 할인가/예약 할인가)의 절삭 자릿수를 바꾸는 작업. 요청이 컬럼명을 직접 지목하는 유형이다.

지표 R5 문서有 R6 문서無 차이
FRESH 47,348 45,244 +5%
Grep 횟수 3 5 −40%
툴 호출 4 7 −43%
turns 10 17 −41%
approx cost $0.67 $0.84 −20%

R1·R3·R5·R6가 이 글의 “정본” 런이다. R2는 §6에서 다룬 stale 문서 발견 런이고, 그 뒤 이어진 재시도가 §7의 파일쓰기 오염으로 폐기됐다. R4는 그 폐기 이후 건너뛴 것으로 보인다 — 정확한 사유는 원본 실행 로그를 다시 봐야 확정된다.

두 태스크를 나란히 보면 패턴이 하나 보인다. 효과 크기는 요청이 얼마나 “찾아야 하는” 성격인지에 달려 있다.

T1처럼 추상적으로 요청하면 Agent가 코드를 뒤지는 양 자체가 많다. 이때 문서는 탐색 경로를 대신 제공한다. 그래서 FRESH가 30% 줄었고, Grep 횟수도 7회에서 3회로 줄었다.

반면 T2′처럼 요청이 이미 구체적인 심볼을 지목하면, Agent가 어차피 grep 몇 번으로 바로 찾아간다. 그래서 FRESH 토큰량은 줄어들기는커녕 오히려 살짝 늘었다(+5%) — 문서를 읽는 비용 자체가 추가된 것으로 보인다. 다만 이 경우에도 툴 호출 수와 turns는 줄었다. 문서가 “찾는 양”보다 “확인하는 왕복 횟수”를 줄여준 것으로 보인다.

cost도 두 태스크 모두 문서가 있을 때 낮게 나오긴 했다. 하지만 이 글에서 cost는 결론의 중심에 두지 않는다. 같은 조건에서도 답변 깊이와 output 토큰에 따라 비용이 크게 흔들렸기 때문이다. 결론의 근거는 cost보다 FRESH, 탐색 명령 수, 툴 왕복 수 쪽에 둔다.

다시 한번 밝히지만 이건 각 조건당 n=1이다. 이 패턴이 다른 태스크에서도 재현되는지는 아직 보지 않았다.

9. cost는 왜 보조 지표로만 봤나

처음엔 T1 조건을 한 번 더 중복 실행(R1-dup)해서 FRESH가 안정적으로 나오는지 확인해보려고 했다. 결과는 FRESH 54,316 대 55,415로 거의 같았다. 그런데 비용은 $1.09 대 $0.48로 두 배 넘게 벌어졌다. 처음엔 이걸 “지표가 안정적이다”는 증거로 쓰려고 했는데, 오히려 반대였다.

원자료를 뜯어보니 이유가 나왔다. output 토큰이 18,695 대 2,097로 크게 차이 났고, cache_read도 582,607 대 180,210으로 차이가 났다. 이 두 항목의 차이만 정규 요율(output $25/M, cache_read $0.5/M)로 환산해도 약 $0.62가 나와서, 실제 비용 격차($0.61)와 거의 정확히 맞아떨어졌다.

같은 조건인데도 두 런은 산출물의 깊이 자체가 달랐던 것이다. R1은 20턴에 걸쳐 상세하게 답했고, R1-dup은 9턴 만에 간결하게 끝냈다. FRESH(탐색량)는 같았지만, “얼마나 자세히 답했는가”라는 완전히 다른 변수가 비용을 좌우했다.

그래서 이 글에서 cost는 참고용 보조 지표로만 쓴다. 요율 자체는 정정했지만, cost는 문서 효과와 무관한 변수에 쉽게 흔들린다. 문서가 Agent의 탐색을 줄였는지 보려면 비용보다 FRESH, 탐색 명령 수, 툴 왕복 수가 더 직접적인 신호라고 판단했다.

10. codex로 한 번 더 봤다 — 단, 조심스럽게

Claude 하나만 갖고 낸 결과가 도구 특성인지, 문서 자체의 효과인지 궁금해서 codex로도 T1을 한 번 돌려봤다. codex exec -s read-only로 파일 쓰기를 원천 차단하고, 세션 로그에서 토큰과 함수 호출을 파싱했다.

여기서부터는 각 조건이 정말 딱 한 번씩만 돈 결과라, 표현에 더 신경 써야 한다. “이번 사례에서는 비슷하게 나왔다” 정도로만 말할 수 있다.

지표 (WITHOUT÷WITH 비율) Claude(R1/R3) codex(C1/C2)
탐색 명령 ×2.3 ×2.5
툴 왕복 ×1.33 ×1.38
FRESH 토큰 ×1.44 ×1.25

탐색 명령과 왕복 비율은 두 도구에서 비슷한 방향으로 움직였다. FRESH 비율은 토크나이저와 캐싱 방식이 도구마다 달라서 편차가 크고, 그래서 크로스툴로 비교할 땐 행동 카운트(탐색 명령·왕복 수) 쪽이 그나마 덜 흔들렸다.

안전성 쪽도 같이 봤다. 현행 코드와 어긋난 문서를 codex에도 그대로 줬더니, codex도 SQL과 대조해서 불일치를 짚어냈다. 다만 대응 방식은 달랐다. Claude는 불일치를 맨 위에 “먼저 확정 필요”로 올려서 진행을 막았고, codex는 문서 기준으로 일단 설계를 제시한 뒤 하단에 주의 사항으로 덧붙였다.

이 관찰에서 끌어낼 수 있는 건 이 정도다. 이번 사례에서는 두 도구 모두 문서-코드 불일치를 잡아냈다. 하지만 그 불일치에 얼마나 강하게 반응하느냐는 도구마다, 혹은 그날그날 다를 수 있다. 그러니 “Agent가 알아서 현행 코드와 어긋난 문서를 걸러줄 것”에 기대기보다, 애초에 문서가 현행 코드와 어긋나지 않게 관리하는 규칙이 더 중요하다.

11. 아직 못한 것

이번에 실제로 다룬 범위는 이만큼이다. 아래는 이 결과가 아직 대답하지 못하는 질문들이다.

  • 모든 셀이 n=1이라 재현성과 분산을 확인 못 했다. “비슷하게 나왔다”까지만 말할 수 있고 “그렇다”까진 못 간다.
  • 측정 범위가 설계 단계까지라, 실제 코드 수정·빌드·테스트 단계에서 문서가 어떤 효과를 내는지는 안 봤다.
  • 태스크가 로직형·심볼형 두 종류뿐이라 다른 유형에선 다르게 나올 수 있다.
  • cost는 output 깊이와 cache_read 변동에 크게 흔들려서, 이번 글에서는 보조 지표 이상으로 해석하지 않았다.

그리고 이건 이번 결과와 완전히 별개로 남겨두는 건데, PR 완료 시점에 business 문서를 자동으로 승격·갱신하는 아이디어(/business-doc-sync 같은 커맨드)가 있다. 아직 한 번도 시도해본 적 없는 구상 단계다. 여러 도메인이 뒤섞인 공유 코드에 자동으로 뭔가를 심는 건 민감한 편집이라, 자동화의 안전성 자체에 의문이 있다. 이것도 검증 안 된 가설이다. 실제로 해보고 나서 다음 글에서 다룰 생각이다.

남는 것

문서가 토큰을 줄이는지는, 이번엔 딱 한 사례만 봤다. 그런데 이 실험이 알려준 건 그거 말고 따로 있었다. 내가 세운 규칙(“복사 말고 재작성”)을 내가 어겼다는 것, 그리고 그걸 알아챈 게 나 자신도 아니고 리뷰어도 아니고, 토큰을 재보려고 만든 검증 장치였다는 것. 게다가 그 검증 장치 자체도 요율 하나가 틀려 있었다는 것. 검증이 필요한 건 대상만이 아니라 도구도 마찬가지였다.

문서는 청구서를 크게 줄이지 않았다. 대신 Agent가 어디를 봐야 하는지 알려줬고, 불필요한 탐색 왕복을 줄였고, 그 과정에서 문서 자체의 오류까지 드러냈다.

토큰 절감보다 이쪽이 더 값어치 있어 보인다. 코드에 경계가 없을 때 문서가 그 경계를 대신 만들어주고, 문서가 틀렸을 때는 그 틀림 자체를 드러내는 것. 다만 이건 이번 한 사례에서 본 것이고, 매번 이렇게 될지는 아직 모른다.