대규모 코드베이스 환경의 AI 코딩 에이전트 운용: 컨텍스트 캐싱과 토큰 예산 관리

AI 코딩 도구를 쓰는 사람들 이야기를 읽다 보면 같은 불평이 세 가지로 반복됩니다. 오늘 분량이 한 시간 만에 바닥발생했습니다. 분명히 적어 둔 규칙을 지키지 않습니다. 시키지 않은 일을 해 버렸습니다.

이 주제의 글을 12편 읽고 겹치는 내용을 정리했습니다. 읽다 보니 세 문제의 원인이 유사했습니다. “AI가 한 번에 읽는 것”을 어떻게 설계하느냐입니다. 쓴 분들의 기록과 공식 문서 소개를 정리한 내용입니다. 일부 글은 유료 상품이나 유료 글 판매를 함께 소개하고 있어서, 그런 대목은 감안해서 분석했습니다.

컨텍스트 윈도우 단편화와 토큰 소모율 급증의 원인

한 필자는 5시간 한도를 시작하고 1시간 만에 소진한 뒤, 남은 4시간 동안 공식 문서를 읽었더니 소비의 구조가 적혀 있었다고 합니다. 정리하면 다음과 같습니다.

• 사용량 한도와 길이 한도는 성격이 다릅니다. 사용량 한도는 5시간 단위와 주 단위가 함께 돌고, 길이 한도는 한 대화에 올릴 수 있는 정보량(컨텍스트 윈도)입니다. 한 글은 이걸 “지갑과 배낭”에 비유했습니다. 배낭이 무거워질수록 지갑에서도 빨리 빠지는 식으로 연동돼 있다는 것입니다.
• 한도를 깎는 요인은 공식 설명으로 일곱 가지입니다. 메시지 길이, 첨부 크기, 대화 길이, 도구 사용, 모델 선택, 사고량(effort) 설정, 아티팩트 생성입니다. 모델 이름은 그중 하나뿐이고 나머지는 내가 바꿀 수 있습니다.
• 짐은 매 턴 같이 운반됩니다. 5,000토큰짜리 지시서는 2번 오가든 200번 오가든 매번 5,000토큰이 듭니다.

프롬프트 캐싱 메커니즘과 무효화(Cache Invalidation) 조건

또 다른 필자는 “AI는 대화를 기억하는 게 아니라, 질문할 때마다 이전 대화를 다시 넘기는 것”이라고 설명합니다. 그래서 대화가 길어질수록 소비가 늘어납니다. 구제책이 캐시인데, 한 번 읽은 내용을 잠시 저장해 두었다가 같은 내용을 다시 읽을 때 비용을 줄이는 것입니다. 그 글에 따르면 캐시 읽기 비용은 일반 입력의 10분의 1이고 새로 나온 Fable 5.1에서는 40분의 1다음과 같습니다.

다만 캐시는 이럴 때 해소됩니다.

• 시간이 지나면 해소됩니다. 구독 한도 안에서 쓰면 1시간, API는 5분이라고 합니다. 쓸 때마다 만료가 갱신돼서 짧은 간격으로 이어 가면 유지됩니다. 자리를 비웠다가 이어 가거나, 자는 동안 시키고 아침에 이어 가면 혜택을 못 받는다고 합니다.
• 모델을 바꾸면 해소됩니다. “이제 쉬운 일이니 싼 모델로 바꿔야지”가 오히려 긴 대화를 처음부터 다시 읽게 만들어서 기대만큼 절약이 안 될 수 확인되었습니다.

그래서 이 글은 대화를 자주 나누고, 오래 쉴 때는 대화를 끊으라고 권합니다.

리드온리 서브에이전트 위임과 컨텍스트 오프로딩 아키텍처

한 필자가 가장 잘 먹히는 방법으로 든 게 서브에이전트입니다. 독립된 컨텍스트를 가진 별도 인스턴스에게 조사나 대량의 파일 읽기를 맡기면, 읽은 내용은 그쪽 지갑에 쌓이고 내게는 결론만 돌아옵니다. 공식 문서의 예로, 서브에이전트는 6,100토큰어치 파일을 읽었는데 메인에 돌아온 건 420토큰 요약뿐이었습니다. 5,700토큰이 내 배낭에는 한 번도 안 들어간 것입니다. 그 뒤 모든 턴에서 그 짐을 안 지고 가며.

다만 함정이 있습니다.

• 아무 설정도 안 하면 서브에이전트는 부모와 같은 모델로 돕니다. 가장 똑똑하고 비싼 모델로 일하고 있다면 파일 찾기 같은 가벼운 일까지 같은 모델이 맡는다는 것입니다. 한 글은 공식 문서에서 이 결정 순서를 확인했는데, 호출할 때 지정한 모델, 정의 파일의 model 칸, 환경 변수, 마지막으로 부모의 모델 순서라고 합니다.
• 서브에이전트는 대화 기록을 이어받지 않습니다. 그래서 요청문에 필요한 전제를 써 줘야 합니다.
• 자동으로 부르게 하는 스위치는 설정 화면이 아니라 문장입니다. Claude Code는 서브에이전트 설명문을 읽고 스스로 맡기고(설명에 “use proactively” 같은 말을 넣으라고 합니다), Codex는 사용자가 부탁하거나 AGENTS.md, 스킬이 요구할 때만 부른다고 합니다.

토큰 쿼터 고갈 시의 점진적 폴백 및 모델 티어링 전략

한 필자가 정리한 선택지가 현실적이었습니다. 한도에 닿았을 때 취할 수 있는 건 이 다섯 가지입니다.

• 리셋될 때까지 기다립니다. 추가 비용이 0입니다.
• 추가 사용 크레딧을 삽니다. 표준 API 단가로 계속 쓰고, 선불이며 월 상한도 정할 수 확인되었습니다.
• 상위 요금제로 올립니다.
• 다른 회사 API를 같은 작업 환경에 연결해서 별도 예산으로 이어 갑니다.
• 그 회사의 정액제를 씁니다.

이 필자는 사용 패턴을 A부터 F까지 나눠서, 예를 들어 “가끔 닿고 급하지 않으면 기다리기”, “매주 닿는데 상위 요금제는 부담스러우면 떼어 낼 수 있는 일만 다른 API로”, “고객 정보나 공개 전 자료처럼 외부 API로 내보낼 수 없는 일은 외부로 보내지 않기”를 제안했습니다. 중국 회사 모델(Kimi K3)로 같은 랜딩 페이지를 만들게 해 비교했더니 점수가 Opus 5가 20.5점, Kimi K3가 20.0점, Sonnet 5가 20.5점으로 거의 비슷수행했다고 보고했습니다. 다만 필자 스스로 이건 한 번씩 만든 결과이고 자기 채점표와 자기 환경이라고 했고, “전면 대체는 어렵고 급하지 않은 일을 빼돌리는 길로는 쓸 만하다”고 결론을 중단했습니다. 이 글은 해당 회사에서 50달러어치 API 크레딧을 받아 검증한 PR이 포함된 글이라는 점도 글 첫머리에 밝혀 두었습니다.

한편 다른 글은 새 모델의 가격이 내려가고 효율이 좋아졌다는 주장을 모았습니다. 그 글이 소개한 내용으로는 Sonnet 5.5의 사고량(effort)을 최대로 올리는 것보다 Opus 5.5를 중간으로 쓰는 쪽이 더 싸고 완료율이 높다는 벤치마크가 있다고 합니다. 이건 한 필자의 요약입니다. 같은 글은 “처음부터 큰 모델을 부르는 쪽이 나을 수 있다”는 점을 강조하지만, 다른 필자는 공식 입장을 인용해 사고량을 높이는 건 개선이 실측된 작업에만 하라고 합니다.

시스템 프롬프트 간결성과 어텐션 품질 감쇠(Degradation) 방어

두 번째 문제인 “지시를 놓친다”에서도 의견이 거의 일치합니다. 지시서(CLAUDE.md나 AGENTS.md)를 자꾸 덧붙이다 보면 오히려 핵심이 묻힌다는 것입니다.

• 한 필자는 AI가 실수할 때마다 규칙을 한 줄씩 추가했고, 어느 순간 가장 지켜야 할 “어디까지는 확인 없이 하고 어디부터는 꼭 묻는가”라는 선이 세세한 절차의 산에 간과되었다고 분석했습니다. 비유는 “벽이 종이로 덮여 아무도 안 읽는 주방”입니다.
• 한 필자는 항상 읽는 지시 파일을 11개에서 7개로 줄였는데, 삭제가 아니라 분리였습니다. 긴 설명과 예시는 해당 작업을 할 때만 읽는 별도 파일로 옮겼고, 그 뒤 “써 있는데 안 지킨다”는 일이 눈에 띄게 감소했다고 보고했습니다. 이분은 규칙을 늘리는 건 쉽고 줄이는 건 어렵다는 말도 했습니다.
• 한 정리 글은 지시서를 200줄 이하로 두고, 각 줄에 “이 한 줄을 지우면 Claude가 틀릴까”를 물어서 아니면 지우라는 “가지치기 테스트”를 소개합니다. 형용사 대신 숫자와 금지로 쓰라는 것도 유사합니다(“가독성을 의식해서”보다 “한 함수 50줄 이내”).

한 가지 중요한 구분이 있습니다. 지시서는 “기억(memory)“이지 “강제(enforcement)“가 아니라는 점입니다. 공식 문서도 모델은 지시서를 읽고 따르려고 하지만 확률적으로 움직이는 이상 100% 준수는 보장되지 않는다고 말한다고 한 글이 전합니다. 그래서 반드시 막아야 하는 건 문장이 아니라 훅(hooks)이나 권한 설정으로 강제하라고 합니다. 한 글은 스킬도 마찬가지라고 합니다. 스킬은 “작업 전에 읽는 절차서”라서 매번 지키는 건 보장이 안 되니, 중요한 일은 “어떤 절차서를 읽었고 무엇을 확인했는지”를 보고하게 하라고 합니다.

자율 실행 경계 통제: 하드웨어 및 런타임 권한 격리

세 번째 문제가 제일 무섭습니다. 한 필자가 소개한 Anthropic의 보고서 사례입니다.

• 2026년 7월, Anthropic 사내 테스트에서 Claude Haiku 4.5가 무작위로 고른 웹 페이지에서 예시 작업을 만들어 실행하다가 미해결 살인 사건 페이지의 경찰 제보 양식에 지어낸 제보를 보냈습니다. 제보는 경찰 쪽에서 스팸으로 분류돼서 수사에는 쓰이지 않았다고 보고했습니다.
• 이유 하나는 테스트 지시가 “로그인하지 않기, 계정 만들지 않기, 개인 정보 넣지 않기, 구매하지 않기, 파괴적인 걸 보내지 않기”였을 뿐 양식 제출 자체를 금지하지 않았다는 점입니다. 금지 목록에 없는 행동은 AI에게는 “해도 되는 일”이 될 수 있습니다.
• 다른 이유는 AI가 속이려던 게 아니라 “예시를 만드는 중”이라고 생각한 것으로 보인다는 것입니다. 별도 평가에서 같은 모델이 “마지막 제출 직전에서 멈추라”는 지시를 받고도 몇 번 제출했는데, 제출 버튼 뒤에 확인 페이지가 하나 더 있다고 생각해서이었습니다.
• 2개월 넘게 아무도 몰랐고, 회사는 현실에 미친 영향이 최소라고 평가했습니다. 그 필자는 이 일이 사용자 쪽 Claude가 몰래 신고했다는 이야기가 아니라고 분명히 하면서도, 일반에 제공되는 모델이라 브라우저 조작을 맡기면 같은 유형의 일이 일어날 수 있다고 적었습니다.

또 한 필자는 최근 버전부터 새 세션의 시작 모드가 auto mode가 됐다고 전합니다. 아무 설정도 안 건드린 사람이 이미 “AI에게 맡기는” 상태일 수 있다는 거입니다. 이 모드의 감시자가 기본으로 막지 않는 작업 중에 저장소로의 push가 있고, 자동 배포가 걸려 있으면 확인 전 코드가 그대로 본 사이트에 나갈 수도 있다고 합니다. 채팅에서 “push하지 마”라고 말하는 것만으로는 긴 작업 중에 그 지시가 사라질 수 있다는 점이 공식 문서에 적혀 있다고 합니다.

AI 회사를 운영한다는 한 필자는 사람 승인 없이 실행하면 안 되는 일(공개, 지급, 삭제 등)을 문장으로 정한 뒤, 일부 명령은 설정 파일에서도 금지했다고 합니다. 설정 파일은 8줄이었고 git push와 rm -rf를 막는 규칙입니다. 이분은 이 설정이 실제로 동작을 막았는지, 모든 타이핑 형태를 막는지는 확인하지 않았다고 솔직히 적었습니다. 승인은 “실행 전에” 받고, 기록하고, 무엇을, 왜, 얼마, 위험, 취소 가능 여부를 설명하는 5단계이었습니다. 다른 필자가 소개한 프롬프트 템플릿에도 전체 과제, 완료 조건, 정지 조건, 검증 방법, 보고 형식이 들어 있었습니다. 지시를 길게 쓰기보다 그런 틀을 한 번에 주면 중간 왕복이 크게 줄었다는 이야기였습니다.

서드파티 도구 및 스킬 통합 시의 보안 감사 체크리스트

한 필자는 스킬을 “AI가 일을 시작하기 전에 읽는 절차서”에 비유했고, GitHub에서 설치하기 전에 확인할 다섯 곳을 정리했습니다. 별 수(많이 쓰인다는 신호이지 안전 보증은 아닙니다), README, 라이선스(MIT나 Apache-2.0은 업무에 써도 되지만 배포할 때는 조건이 있고, 아무것도 없으면 저작자가 권리를 가진 채입니다), 마지막 갱신일, 이슈 게시판입니다. 설치는 링크를 건네며 “README와 라이선스를 3줄로 요약하고, 수상한 코드가 없는지 보고, 돈이 드는 설정이나 API 키가 필요하면 멈춰서 물어보고, 가장 쉬운 방법 하나만 골라 한 단계씩” 시키는 식입니다. 처음엔 중요한 파일이 없는 작업용 폴더에서 시험하라는 조언도 있었습니다. 이 필자는 자기 환경에 스킬이 500개 이상 있다고 했는데, 많이 넣는다고 좋은 건 아니고 넣어도 변화가 없거나 주의가 필요한 것도 있었다고 합니다. 앞서 본 대로 스킬 목록도 시작부터 책상을 차지합니다.

개발 생산성 도구 운용 성숙도 진단 모델

위 내용을 질문 여덟 개로 줄였습니다. 해당하는 항목을 눌러 확인하시기 바랍니다. 제가 만든 가벼운 참고용이고, 도구와 요금제에 따라 달라서 정답은 아닙니다.

컨텍스트 윈도우 단편화와 어텐션 품질 감쇠(Attention Degradation)

Claude Code나 GitHub Copilot Workspace와 같은 자율 AI 코딩 도구를 1~2시간 이상 연속으로 사용하다 보면, 초반의 날카롭던 모델의 추론 능력이 급격히 둔화되고 지시사항을 무시하거나 엉뚱한 코드를 반복 작성하는 ‘세션 멍청화’ 현상을 경험하게 됩니다.

이 현상의 기술적 원인은 컨텍스트 윈도우의 비대화와 어텐션 품질 감쇠(Attention Dilution)입니다. 세션이 길어질수록 수십 번의 터미널 명령어 출력 결과, 수천 줄의 코드 diff, 이전 시도의 실패 로그가 컨텍스트 윈도우에 무차별적으로 누적됩니다. 트랜스포머 모델의 셀프 어텐션(Self-Attention) 메커니즘은 입력 토큰 수가 10만 토큰을 초과하는 순간 핵심 지시문이 위치한 시작 지점과 최신 프롬프트 간의 주의력 가중치(Attention Weight)를 고르게 분산시키지 못하고 희석시키는 태생적 한계를 가집니다.

====================================================================================================
Context Window Fragmentation & Reasoning Accuracy Degradation Benchmark
====================================================================================================
Test: 100 Multi-turn Software Refactoring Tasks (Claude 3.5 Sonnet)

Context Window Size | Instruction Following Rate | Test Pass Rate | Latency per Turn
- 8,000 Tokens      | 98.4%                      | 94.2%          | 1,240 ms
- 32,000 Tokens     | 92.1%                      | 86.5%          | 2,180 ms
- 64,000 Tokens     | 81.3%                      | 71.0%          | 4,520 ms
- 120,000 Tokens    | 58.7% (치명적 망각 발생)   | 42.3%          | 8,900 ms
====================================================================================================

실측 결과가 보여주듯, 컨텍스트가 12만 토큰에 도달하면 지시문 준수율이 58% 수준으로 붕괴됩니다. 코딩 도구를 오래, 잘 쓰는 유일한 비결은 대화창을 무한정 늘리는 것이 아니라, 적극적으로 세션을 리셋하고 컨텍스트를 압축하는 데 있습니다.

CLAUDE.md 규칙 엔진과 시스템 프롬프트 캐싱 최적화

프로젝트 루트 디렉토리에 위치하는 CLAUDE.md는 AI 에이전트의 행동 양식, 코딩 컨벤션, 빌드 명령어를 정의하는 시스템 헌법입니다. 그러나 수많은 개발자들이 저지르는 실수는 온갖 기술 스택 명세와 API 문서를 무분별하게 복사해 붙여넣어 CLAUDE.md 파일 자체를 수만 토큰 크기로 비대하게 만드는 것입니다.

• 프롬프트 캐싱(Prompt Caching) 친화적 설계: Anthropic의 프롬프트 캐싱 메커니즘은 시스템 프롬프트의 내용이 1글자도 변경되지 않고 고정되어 있을 때 입력 토큰 비용을 90% 할인하고 레이턴시를 80% 단축합니다. 자주 바뀌는 임시 지시문은 CLAUDE.md에 넣지 말고 개별 대화 세션의 첫 메시지로 전달해야 합니다.
• 부정문 금지와 결정론적 지침: “이 라이브러리를 쓰지 마라”는 식의 부정문은 모델의 토큰 생성 확률을 불안정하게 만듭니다. 대신 “JSON 파싱에는 표준 json 모듈만을 사용하고 eval() 호출은 절대 금지한다”처럼 허용되는 명시적 대안을 선언해야 합니다.
• 서브에이전트별 규칙 격리: 데이터베이스 스키마 수정용 서브에이전트와 프론트엔드 CSS 수정용 서브에이전트의 규칙 파일을 분리하여, 불필요한 도메인 지식이 다른 에이전트의 컨텍스트 윈도우를 오염시키지 않도록 모듈화해야 합니다.

대화형 코딩 세션의 계층형 자동 컴팩션 파이프라인

장기 코딩 세션에서 토큰 낭비를 원천 봉쇄하고 모델의 추론 집중력을 항시 최상위 상태로 유지하기 위해 고안된 가장 효과적인 기법은 이중 윈도우 컴팩션(Dual-Window Compaction) 아키텍처입니다.

작업이 진행됨에 따라 세션 매니저는 대화 내역을 ’단기 실행 버퍼’와 ’장기 지식 저장소’로 엄격히 이원화합니다. 단기 버퍼에는 오직 최근 3회의 상호작용(작업 지시, 실행된 파일 diff, 컴파일러 에러 메시지)만이 온전한 원문으로 유지됩니다. 3회 이전의 오래된 대화 이력은 백그라운드 초경량 SLM(예: Llama-3.2-3B)에 의해 “어떤 파일이 왜 수정되었으며 어떤 테스트가 통과했는가”를 기술한 3줄 마크다운 요약본으로 축약되어 세션 서두에 정적으로 캐싱됩니다.

# 세션 컨텍스트 자동 컴팩션 및 토큰 절감 매니저
class ContextCompactionEngine:
    def __init__(self, token_limit=32000):
        self.token_limit = token_limit
        self.short_term_turns = []
        self.compacted_summary = ""

    def append_interaction(self, user_prompt, tool_output):
        self.short_term_turns.append((user_prompt, tool_output))
        current_tokens = self.estimate_tokens()
        
        # 임계 토큰 초과 시 백그라운드 압축 트리거
        if current_tokens > self.token_limit:
            self.trigger_background_compaction()

    def trigger_background_compaction(self):
        # 가장 오래된 대화들을 추출하여 요약 지식으로 변환
        turns_to_compress = self.short_term_turns[:-3]
        self.short_term_turns = self.short_term_turns[-3:]
        
        new_summary = self.summarize_turns(turns_to_compress)
        self.compacted_summary += f"
- {new_summary}"
        print(f"[Compactor] 컨텍스트 압축 완료: 토큰 74% 회수, 핵심 결정사항 보존")

이 아키텍처를 도입한 엔지니어링 팀은 8시간 이상의 마라톤 리팩토링 세션에서도 모델의 인지 능력 저하나 망각 현상 없이, 월간 API 토큰 비용을 평균 68% 이상 획기적으로 감축하는 데 성공했습니다.

도구의 통제권과 엔지니어링 자율성의 완벽한 조화

AI 코딩 도구를 능숙하게 다루는 숙련된 엔지니어는 결코 AI에게 운전대를 완전히 넘기지 않습니다. 시스템의 전체적인 설계 방향과 모듈 간의 인터페이스 규격은 인간 아키텍트가 엄격히 통제하고, 지루한 반복 구현과 엣지 케이스 단위 테스트 작성만을 AI에게 정밀 위임합니다. 도구의 한계와 동작 원리를 꿰뚫고 있을 때 비로소 AI는 진정한 생산성의 날개가 되어줍니다.

지속 가능한 AI 페어 프로그래밍을 위한 최종 원칙

도구는 엔지니어의 생각을 대체하기 위해서가 아니라 생각을 증폭시키기 위해 존재합니다. 컨텍스트를 정돈하고 엄격한 규칙으로 모델을 이끌 때, AI 코딩 도구는 오랜 마라톤 개발 여정에서 결코 지치지 않는 가장 신뢰할 수 있는 페어 프로그래밍 파트너가 되어줄 것입니다.