세션마다 10k 토큰을 공짜로 되돌려받는 법 — 코딩 에이전트의 컨텍스트 경제학

컨텍스트 윈도우가 100만 토큰(1M)까지 늘어났다고 해서 “와, 이제 토큰 걱정 끝났다!” 싶었는데, 이상하게 에이전트 돌리다 보면 금방 멍청해지고 토큰은 미친 듯이 닳아 없어진다. (내 기분 탓인가??)

최근 r/ClaudeCode에서 눈이 번쩍 뜨이는 꿀팁을 하나 건졌다. Claude Code 세션을 새로 켜자마자, 내가 프롬프트 한 글자 치기도 전에 시스템 기본 툴 정의문으로만 무려 20k(2만) 토큰이 허공에 날아가고 있었다는 충격적인 사실이다. 그리고 그 황금 같은 토큰의 절반 이상이 다름 아닌 ‘Artifact(웹 게시용 아티팩트)’ 도구 설명문 때문이란다.

쓰지 않는 도구에 토큰을 내고 있다

터미널에서 백엔드나 앱 코드만 만지는 엔지니어 입장에서 웹 미리보기용 아티팩트 도구는 쓸 일이 1도 없다(터미널 CLI에서 웹 뷰 띄워서 뭐 하겠는가). 그런데도 에이전트는 세션이 열릴 때마다 이 무거운 도구 정의를 시스템 프롬프트에 꼬박꼬박 얹어서 토큰을 태우고 있었던 거다.

끄는 방법은 아주 간단하다. 아래 셋 중 하나만 골라잡으면 된다.

// settings.json
{ "enableArtifact": false }

CLI 실행할 때 플래그로 --disallowed-tools Artifact를 넘기거나, 쉘 프로필에 환경변수 CLAUDE_CODE_DISABLE_ARTIFACT=1을 박아둬도 된다. 설정 딱 한 줄로 매 세션마다 10,000토큰이 내 주머니로 고스란히 돌아온다.

“고작 10k 토큰 아껴서 뭐 하냐”고 코웃음 칠 수도 있다. 하지만 현업 개발자들의 실전 경험을 떠올려보자. 모델의 공식 스펙이 1M 컨텍스트라 해도, 환각 없이 뇌를 팽팽하게 굴리는 실질적인 골든타임(Smart Zone)은 기껏해야 200k 남짓이다. 그렇다면 저 10k는 전체 뇌 용량의 무려 5%에 해당한다. 시작부터 뇌세포 5%를 끄고 들어갈 이유가 전혀 없다.

주석도 결국 컨텍스트 비용이다

비슷한 시기에 레딧을 달군 또 다른 불만도 맥락이 똑같다. Opus 5 같은 최신 모델이 코드에 주석을 아주 수다쟁이처럼 남겨둔다는 거다. 사소한 변경점 하나에도 그 시점의 대화 맥락과 변명을 장황하게 주석으로 때려 박아서, 나중에 코드만 읽는 동료 개발자 입장에선 그야말로 시각적 소음(Noise)이다.

댓글창에서 공유된 해결책이 아주 명쾌하다. 설계와 의사결정의 역사는 CHANGELOG.md나 커밋 로그로 분리하고, 코드 안의 인라인 주석은 현재 상태의 ‘왜(Why)’만 짧게 남기도록 강제하는 거다. 아예 CLAUDE.md 파일에 “코드 내 장황한 주석 작성 전면 금지, 문서는 docs/ 아래에만 남길 것”이라고 룰을 못 박아둔 시니어도 있었다.

핵심은 명확하다. 주석조차도 전부 다음 세션에서 모델이 읽어야 할 ‘컨텍스트 비용’이라는 사실이다. 필요 없는 주석 한 줄 한 줄이 나중에 모델의 연산 속도를 갉아먹고, 토큰 요금 고지서를 불리고, 결국 모델을 멍청하게 만드는 부메랑으로 돌아온다.

왜 이 얘기가 지금 나오는가

주말 사이 로컬 LLM 씬의 흐름을 봐도 결론은 똑같다. Qwen 3.8 27B 같은 소형 모델들이 생각(Reasoning) 과정을 길게 뿜어내며 성능을 쥐어짜다 보니, 컨텍스트 140k만 넘어가도 24GB VRAM이 꽉 차서 비명을 지른다.

VRAM이 곧 컨텍스트고, 컨텍스트가 곧 돈인 세계다. 그래서 로컬 유저들은 양자화 옵션을 깎고, “계획 수립 → 단위 구현 → 문서화 → 새 컨텍스트 세션에서 리셋”이라는 극한의 컨텍스트 다이어트 루프를 설계한다. 클라우드 유저가 안 쓰는 도구를 끄는 것이나 로컬 유저가 세션을 쪼개는 것이나, 본질은 완전히 같다.

컨텍스트 윈도우가 아무리 태평양처럼 넓어져도, 진짜 실력은 ‘얼마나 컴팩트하게 정리하느냐’에서 갈린다. 집이 넓어졌다고 쓰레기를 거실 한가운데 쌓아둘 수는 없지 않은가. 내 세션에 어떤 도구를 올리고 어떤 잡음을 쳐낼지는 이제 온전히 엔지니어의 아키텍처 설계 몫이다.

정리

settings.json 딱 한 줄만 건드려도 매 세션 10k 토큰을 공짜로 돌려받는다.

Claude Code를 매일 켜놓고 사는 개발자라면 지금 당장 설정 파일을 열어보자. 안 쓰는 도구 쳐내고, 불필요한 주석 다이어트만 시켜줘도 에이전트의 응답 템포와 똑똑함이 확 달라지는 걸 바로 체감할 수 있다(공짜 토큰 10k는 못 참는다).