가이드라인에는 토큰 예산이 존재한다

우리의 프로젝트 CLAUDE.md는 지난 분기에 4,000 토큰을 넘어섰고, 에이전트(agent)는 몇 달 동안 잘 지켜왔던 규칙들을 놓치기 시작했습니다. 문서 상단의 규칙들이 아닙니다. 중간에 있는 규칙들입니다. 세 개의 다른 지침 섹션 아래에 파묻혀 있는 규칙들, 에이전트가 집중력을 유지한다면 도달할 수 있지만 작업에 깊이 몰입했을 때는 안정적으로 도달하지 못하는 규칙들 말입니다.

만약 그 규칙들 대부분이 그 자리에 있을 만한 이유가 없었다면, 이 이야기는 "파일을 더 짧게 만드세요"라는 결론으로 끝났을 것입니다. 각 규칙에는 그 뒤에 발생한 사건이 있었습니다. 각 규칙에는 그것을 옹호하는 리뷰어가 있었습니다. 가이드라인(harness)은 비대해진 것이 아니라, 정직한 것이었습니다. 그럼에도 에이전트는 여전히 규칙을 놓치고 있었습니다.

제가 도달하기까지 너무 오래 걸렸던 결론은 이것입니다: 가이드라인에는 토큰 예산(token budget)이 있으며, 우리는 그것을 다 써버렸다는 것입니다.

아무도 손익계산서(P&L)에 기재하지 않는 비용

CLAUDE.md의 모든 줄은 컨텍스트(context) 비용을 발생시킵니다. 에이전트는 당신의 작업 특정 컨텍스트(task-specific context)가 도착하기 전, 모든 세션과 모든 창에서 가이드라인을 읽습니다. 4,000 토큰 규모의 CLAUDE.md는 에이전트가 실제로 편집하도록 요청한 파일을 위해 사용할 수 없는 4,000 토큰을 의미합니다.

첫 번째 비용은 명확합니다: 작업을 위한 창(window)이 줄어듭니다. 작은 작업에서는 문제가 되지 않습니다. 하지만 세 개의 파일과 긴 로그를 아우르는 작업에서는 절대적으로 중요합니다. 에이전트는 공간이 부족해지면 컨텍스트(context)를 누락시키기 시작하며, 바로 그때가 모든 규칙이 주의(attention)의 최상단에 있어야 하는 시점입니다.

두 번째 비용은 더 미묘합니다. 에이전트의 주의(attention)는 입력값 전체에 걸쳐 균일하지 않습니다. 가이드라인 상단의 규칙은 중간에 파묻힌 규칙보다 더 안정적으로 작동합니다. 파일의 중간 부분은 핵심적인 규칙(load-bearing rule)이 위치하기에 최악의 장소이며, 또한 규칙들이 기본적으로 축적되는 곳이기도 합니다. 모든 새로운 규칙은 논리적으로 속하는 섹션에 추가(append)되면서 기존의 규칙들을 서서히 중간 부분으로 밀어내기 때문입니다.

세 번째 비용은 사람입니다. 팀은 온보딩(onboarding)할 때, 에이전트의 실패를 조사할 때, 그리고 규칙의 변경을 제안할 때 가이드라인(harness)을 읽습니다. 파일이 길어지면 아무도 처음부터 끝까지 읽지 않습니다. 각 규칙이 왜 존재하는지에 대한 조직적 기억(institutional memory)은 증발하며, 다음 유지보수자는 지도도 없이 3년 동안 축적된 결정 사항들을 읽게 됩니다.

환율 (The exchange rate)

제가 생각하는 방식은 이렇습니다. 각 규칙은 방지된 실수를 대가로 토큰을 교환합니다. 이 환율이 바로 규칙의 가치입니다.

분기당 한 번의 운영 사고(production incident)를 방지하면서 인코딩에 30토큰이 드는 규칙은 유지할 가치가 압도적으로 높습니다. 반면, 에이전트가 결코 생성하지 않는 패턴에 반응하면서, 세 문단에 걸쳐 추론 과정을 설명하느라 150토큰이 드는 규칙은 나쁜 거래입니다.

어려운 점은 대부분의 규칙이 개별적으로는 괜찮아 보인다는 것입니다. 거래의 실체는 예산(budget) 수준에서만 드러납니다. 단일 규칙을 평가하여 유지 여부를 결정할 수는 없습니다. 해당 규칙이 속한 파일의 총 비용과 비교하여 평가해야 하며, 현재 가지고 있지 않은, 주의력(attention)의 최상단에 위치할 한두 개의 규칙과 이 규칙을 바꿀 용의가 있는지 자문해야 합니다.

절제력은 줄(line) 단위가 아닌 예산 단위로 생각하는 것입니다. "이 규칙이 유용한가"가 아니라, "이 규칙을 가질 것인가, 아니면 매 세션마다 소모되는 200토큰의 주의력을 가질 것인가"를 고민하는 것입니다.

네 가지 움직임 (The four moves)

예산을 받아들이고 나면, 가이드라인에는 네 가지 움직임이 가능해지며, 이들은 모두 충분히 활용되지 못하고 있습니다.

통합(Consolidate). 거의 같은 내용을 말하는 두 규칙을 하나로 합쳐 길이를 절반으로 줄이고, 기존에 두 규칙이 모두 적용되던 곳에 적용합니다. 통합 과정은 대개 아무도 눈치채지 못했던 중복성을 드러냅니다. 에이전트는 두 개의 규칙 대신 하나의 규칙을 읽게 되며, 이를 더 일관되게 적용합니다.

압축 (Compress). 세 단락으로 추론 과정을 설명하던 규칙이 두 줄로 규칙을 명시하는 규칙으로 변합니다. 추론 과정은 코드베이스 (codebase) 내의 주석으로 이동하거나, 해당 규칙을 도입한 PR (Pull Request)로, 또는 필요할 때만 로드되는 기능 문서 (feature doc)로 이동합니다. 에이전트 (agent)는 규칙을 적용하기 위해 추론 과정이 필요하지 않습니다. 에이전트에게 필요한 것은 규칙 그 자체입니다.

범위 축소 (Scope down). 프로젝트 루트 (project root)에 있으며 단 하나의 모듈에만 적용되는 규칙은 해당 모듈의 CLAUDE.md로 이동합니다. 토큰 비용 (token cost)은 에이전트가 해당 모듈을 다룰 때만 발생하며, 에이전트가 다른 곳에 있을 때는 발생하지 않습니다. 범위 설정 (scoping) 단계가 이 작업을 다룬다면, 토큰 예산 (token-budget) 프레임워크는 이 이동을 단순히 깔끔하게 정리하는 작업이 아닌 긴급한 작업으로 느끼게 만듭니다.

삭제 (Delete). 기원을 아무도 기억하지 못하고, 에이전트가 해당 패턴을 생성하지 않으며, 삭제해도 동작에 변화가 없는 규칙은 사라집니다. 규칙 생명주기 (rule-lifecycle) 단계가 이러한 규율을 다룹니다. 토큰 예산은 삭제를 선택 사항이 아닌 필수 사항으로 만듭니다.

이 네 가지 움직임은 리팩터링 (refactor)이 아닙니다. 이것은 회계 (accounting)입니다.

인라인 (inline) 방식이 CLAUDE.md보다 나은 경우

규칙이 존재할 수 있는 곳이 하네스 (harness)뿐인 것은 아닙니다. 코드베이스 (codebase)에는 매 세션마다 토큰 비용을 지불하지 않으면서 제약 사항을 인코딩할 수 있는 도구들이 있습니다.

날짜를 어떻게 형식화할지에 대한 규칙은 린트 체크 (lint check)가 될 수 있습니다. 어떤 파일에서 임포트 (import)할지에 대한 규칙은 eslint-plugin-import 또는 그와 유사한 도구에 의해 강제될 수 있습니다. 새로운 컴포넌트가 어느 디렉토리에 들어가야 하는지에 대한 규칙은 생성 명령 (generator command)에 의해 강제될 수 있습니다. 이러한 규칙들은 CLAUDE.md에 존재할 필요가 없습니다. 왜냐하면 제약 사항이 이미 에이전트가 준수할 어딘가에 인코딩되어 있기 때문입니다.

규칙을 추가할 때 제가 수행하는 확인 절차는 다음과 같습니다: 이 규칙을 기계적으로 강제할 수 있는 코드베이스 내의 장소가 있는가? 만약 있다면, 규칙은 그곳으로 갑니다. 하네스 (harness)는 언어적 (linguistic)이어야만 하는 규칙, 즉 린터 (linter)가 볼 수 없는 판단이나 문맥 (context)에 의존하는 규칙만을 담습니다.

하네스는 주의력 (attention)으로 토큰 비용을 지불합니다. 린트 (Lint)는 CI 분 (CI minutes)으로 비용을 지불합니다. 규칙당 비용 측면에서 린트가 더 저렴하며, 그 비용은 다른 모든 규칙에 대해 복리로 쌓이지 않습니다.

예산을 되돌려주는 감사 (Audit)

분기마다 한 번씩, 나는 하네스(harness)를 열어둔 채 한 가지 질문을 품고 앉아 있습니다. '내가 어디에서 과도한 비용을 지불하고 있는가?'

토큰을 가장 많이 소모하는 규칙들은 설명이 가장 긴 규칙들입니다. 다섯 줄의 컨텍스트 (context), 두 줄의 규칙, 세 줄의 예외 케이스 (edge cases). 에이전트 (agent)에게는 그 컨텍스트가 필요하지 않습니다. 그 컨텍스트가 필요했던 것은 규칙이 협의되던 당시의 팀원들이었습니다. 이제 그 컨텍스트는 사장된 무게일 뿐입니다. 압축하십시오.

두 번째로 나쁜 사례는 범위를 제한해야 하는 규칙들입니다. 일반적인 프로젝트 루트의 CLAUDE.md에 있는 규칙의 절반은 단 하나의 모듈에만 적용됩니다. 각 규칙은 에이전트가 해당 모듈 근처에도 가지 않는 세션에서도 매번 토큰 비용을 지불합니다. 범위를 좁히십시오. API 작업에 집중하는 에이전트의 주의력 (attention)이 프론트엔드 규칙을 위해 비용을 지불할 필요는 없습니다.

세 번째 그룹은 가장 단순합니다. 아무도 그 기원을 기억하지 못하고, 에이전트가 그 패턴을 생성하지도 않는 규칙들입니다. 그것들은 삭제하십시오.

매 분기 감사를 통해 800에서 1,500 토큰 사이의 예산이 되돌아옵니다. 에이전트는 더 나아집니다. 팀은 파일을 다시 읽을 수 있습니다.

예산이 책정된 하네스의 형태

하네스 전체를 에디터의 단일 화면에 맞춰야 한다고 상상해 보십시오. 스크롤 없이 말입니다. 어떤 규칙들이 살아남을까요?

이 연습이 인위적으로 들릴 수도 있습니다. 하지만 그렇지 않습니다. 살아남는 규칙들은 가장 많은 일을 하고 있는 규칙들일 것입니다. 삭제될 규칙들은 유용해 보이지만 대부분 관성 때문에 유지되고 있는 규칙들입니다.

실제로 하네스를 한 화면 크기로 줄이지는 않을 것입니다. 이 연습의 목적은 어떤 규칙이 테스트를 통과하는지, 그리고 어떤 규칙이 아무도 정당성을 요구하지 않았기 때문에 살아남아 있는지를 찾아내는 것입니다.

예산이 책정된 하네스 (budgeted harness)는 가장 작은 하네스가 아닙니다. 모든 규칙이 자신의 토큰 값을 해낸 하네스입니다.

설계에 의한 Keystone 예산 컨텍스트

Keystone은 제가 하네스 엔지니어링 (harness engineering)을 위해 구축한 오픈 소스 도구이며, 예산 프레임워크 (budget framing)는 컨텍스트 (context)를 로드하는 방식에 내장되어 있습니다. 이 설계는 하나의 결정에서 시작됩니다: 컨텍스트는 희소한 자원이며, 하네스는 매 순간 무엇이 그 안에 머물지를 선언해야 한다는 것입니다.

Keystone은 하네스를 각각 고유한 예산을 가진 세 가지 계층 (tiers)으로 나눕니다.

상시 가동 가이드 (Always-on guides). 모든 세션에서 로드되는 짧은 규칙 파일들입니다. 0.7.0 버전을 새로 설치했을 때 전체 가이드 레이어 (guide layer)는 53개 파일에 걸쳐 약 28K 토큰을 사용합니다. 이것이 주변 비용 (ambient cost)입니다: 에이전트 (agent)가 작업을 시작할 때마다 매번 확인해야 하는 규칙들입니다.

온디맨드 코퍼스 (On-demand corpus). 규칙 뒤에 숨겨진 추론 과정, 긴 예시들, 역사적 맥락 등은 상시 가동 레이어에 존재하지 않습니다. 이는 가이드가 포워드 링크 (forward-link)를 통해 호출할 때만 에이전트가 로드하는 코퍼스 (corpus) 파일에 위치합니다. 파일당 약 1~3K 토큰을 사용하며, 대부분의 작업에서는 이 파일들에 접근조차 하지 않습니다.

일시적 센서 (Transient sensors). 린트 (Lint) 출력, 테스트 (test) 출력, 감사 (audit) 출력입니다. 이들은 검증 (verification) 단계에서만 컨텍스트에 나타났다가 사라집니다. 검증 사이클당 약 1~5K 토큰을 사용하며, 잔여물을 남기지 않고 신호 (signal)만을 전달합니다.

수치는 예산 프레임워크가 예측하는 방식대로 작동합니다. 새로 설치했을 때의 비용은 200K 컨텍스트 창 (window)의 약 14%, 또는 1M 컨텍스트 창의 약 3%입니다. 모든 코퍼스 파일과 모든 센서를 한꺼번에 불러오는 최악의 전체 감사 (full audit) 시나리오에서도 약 45~55K 토큰 수준에 머뭅니다. 에이전트는 여전히 실제 작업을 위해 대부분의 컨텍스트를 자유롭게 사용할 수 있습니다.

이러한 계층화는 '네 가지 움직임 (four moves)'이 던지는 것과 동일한 질문을 강요합니다: 이 규칙은 어느 계층에 속해야 하는가? 모든 작업에서 실행되는 규칙은 상시 가동 (always-on) 슬롯을 얻을 자격이 있습니다. 분기에 한 번씩 결정을 설명하는 규칙은 링크 뒤에 있는 코퍼스 (corpus)에 속해야 합니다. 검증 중에만 실행되는 체크 (check)는 센서 (sensors)에 머물며 잔여물을 남기지 않습니다.

Keystone은 www.tacoda.dev/keystone에서 확인할 수 있습니다.

이 원칙은 이 포스트 전체가 주장하는 바와 같습니다: 상시 가동 레이어의 모든 토큰은 매 세션마다 비용을 지불하므로, 상시 가동 레이어는 작고, 신중하며, 감사 (audited)되어야 합니다. 이 도구는 규율을 기계적으로 구현한 것입니다.

오늘날 하네스 (harness)를 운영하는 사람에게 내가 해줄 말

여러분의 CLAUDE.md를 여십시오. 에이전트 (agent)가 읽는 방식 그대로, 아래로 내려갈수록 주의력 (attention)이 떨어진다는 가정하에 처음부터 끝까지 읽어보십시오.

교환 비율 (exchange rate)이 가장 나쁜 규칙을 찾으십시오. 아마도 다섯 줄 정도면 설명이 끝나는데, 모듈 (module)에 있어야 할 것이 프로젝트 루트 (project root)에 위치해 있으며, 에이전트가 지난 6개월 동안 한 번도 생성하지 않은 패턴을 막고 있는 규칙일 것입니다. 그것을 압축하거나, 이동시키거나, 삭제하십시오.

이 작업을 규칙 10개에 대해 수행하십시오. 절약된 토큰 (token) 양을 측정하십시오. 그 절약 수치는 여러분을 놀라게 할 것입니다. 에이전트의 동작은 나빠지지 않을 것입니다. 대부분의 경우 오히려 더 좋아질 것입니다. 왜냐하면 살아남은 규칙들은 이전처럼 파묻혀 있을 때보다 더 신뢰성 있게 작동할 것이기 때문입니다.

하네스 (harness)는 공짜가 아닙니다. 토큰 예산 (token budget)은 실재합니다. 규율 (discipline)이란 그 예산을 중요한 것에 사용하는 것입니다.