Claude Code 옆에 캐시 레이어 붙이겠다는 발상

Claude Code 한 달 좀 넘게 쓰면서 가장 짜증났던 거. 한 세션 안에서 같은 파일을 두세 번씩 다시 여는 거였음. main.py 한 번 보고, 두 단계 작업 더 하다가, 또 main.py 여는 식. 컨텍스트 압축이 어떻게 굴러가는지는 대충 알지만 "야 너 방금 봤잖아?" 싶은 순간이 꽤 잦더라고요.

이걸 정면으로 들이받겠다는 오픈소스 도구가 하나 돌아다니길래 들여다봤음. 이름은 OpenWolf. 발상 자체가 좀 흥미로워서 정리해 둠.

들어가기 전에 짚고 가는 용어 몇 개#

본문에 자주 나올 단어 몇 개만 짧게 풀이.

• lifecycle hook: Claude Code가 파일 읽기·쓰기 같은 동작을 하기 직전과 직후에 끼어들어 실행되는 스크립트. Anthropic이 공식적으로 PreToolUse, PostToolUse, SessionStart, Stop 같은 이벤트 훅을 열어둠.
• anatomy 파일: OpenWolf가 만드는 프로젝트 인덱스. 파일별로 "이건 뭘 하는 파일이고, 대략 몇 토큰이다"를 한 줄로 정리해 둔 마크다운임.
• cerebrum 파일: 같은 도구가 세션 너머로 누적시키는 메모리. 본인이 했던 교정·컨벤션·하지 말라고 했던 패턴이 차곡차곡 쌓이는 곳.

자, 이 정도면 됐고.

"토큰이 샌다"는 게 진짜 문제인가#

저자가 132세션·20프로젝트에서 측정해 보니까, 전체 파일 읽기의 71%가 같은 세션에서 이미 한 번 읽은 파일이었음. 한 프로젝트에서는 server.ts를 한 세션 안에 네 번 읽었다는 케이스도 있었고요.

본인이 직접 잰 수치는 아닌데, 체감으로는 충분히 그럴 만하다고 봄. Claude Code는 파일을 열기 전엔 안에 뭐가 있는지 모름. 50토큰짜리 한 줄 config인지 2,000토큰짜리 모듈인지 구분 못 하니까 일단 읽고 봄. 이게 누적되면 토큰이 안 새는 게 이상함.

접근 방식: 외부 캐시 + 인덱스#

OpenWolf의 구조는 한마디로 Claude Code 본체에는 손 안 대고, 옆에 캐시·인덱스·룰북을 두는 미들웨어임.

설치하면 프로젝트 루트에 .wolf/ 디렉토리가 생기고, 그 안에 6개의 Node.js hook 스크립트가 박힘. 각 hook은 이렇게 작동함.

• 파일 읽기 직전: anatomy에서 그 파일 한 줄 설명이랑 토큰 추정치를 먼저 주입. 굳이 본문 다 안 읽어도 되는 케이스를 걸러 줌. 그리고 "야 이 파일 12분 전에 이미 읽었어, 그 사이 안 바뀜"도 같이 알려 줌.
• 파일 쓰기 직전: cerebrum에 박혀 있는 do-not-repeat 리스트랑 비교. 예전에 "var 쓰지 마"라고 했으면 그걸 다시 쓰려는 시도를 잡아챔.
• 쓰기 직후: anatomy 인덱스 자동 업데이트. 새로 만든 파일도 한 줄 설명이 붙음.
• 세션 시작·종료: 토큰 원장에 누적 기록.

설치는 npm install -g openwolf 한 번 하고, 프로젝트 루트에서 openwolf init 한 번. 직접 깔아본 건 아니라 의존성 충돌이나 한국 윈도우/우분투 환경 호환은 더 봐야 할 듯요.

80% 절감이라는 수치는 어디까지 믿을 수 있나#

저자가 잰 거 기준으로 한 프로젝트에서 약 80% 토큰 절감, 20프로젝트 평균은 65.8% 절감이라고 함. 좋은 수치인데, 그대로 받아들이긴 좀 그래요.

몇 가지 짚어 볼 만한 거.

• 측정 환경이 본인 도구가 가장 잘 먹히는 케이스로 편향됐을 가능성이 큼. 작은 파일 많고 반복 참조가 잦은 모노레포 류면 효과가 크게 나오는데, 큰 단일 모듈 위주 프로젝트에선 anatomy의 한 줄 설명만으론 부족할 때가 많을 듯.
• 토큰 절감 = 비용 절감인 건 맞는데, 정확도·작업 품질이 어떻게 변했는지 측정값은 따로 안 나옴. 한 줄 설명만 보고 모델이 잘못된 결정을 내릴 가능성은 분명히 존재함.
• 도구 저자가 자기 도구로 직접 잰 수치는 보통 best-case에 가까움. 이건 OpenWolf 한정 얘기가 아니라 일반론.

본인 입장에서 더 의미 있는 건 절감률보다 재방문 파일을 진짜로 안 다시 여느냐 쪽임. 그건 직접 돌려봐야 검증되는 부분.

백엔드 입장에서 좀 의심되는 부분#

이거 결국 외부 캐시·인덱스 레이어인데, 백엔드 짠 사람이라면 본능적으로 떠오르는 질문이 있을 거예요. 캐시 무효화는 제대로 되나?

• Claude Code 외부에서 파일이 바뀌면 어떻게 됨? 다른 에디터로 직접 수정하거나 git pull 같은 거 했을 때, anatomy 인덱스는 post-write hook으로만 갱신되니까 바깥쪽 변경은 stale로 남을 수 있음.
• daemon이 죽거나 hook이 실패하면 모델이 stale 정보로 잘못된 길로 갈 수 있고, 그 실패가 조용히 일어나면 디버깅이 꽤 귀찮을 듯.
• cerebrum의 do-not-repeat 리스트가 쌓이면, 매 세션 시작마다 그 리스트가 prompt에 같이 들어감. 이거 자체가 토큰을 먹음. 절감 효과랑 상쇄되는 지점이 분명히 어딘가 있을 거고, 그게 어디인지 도구가 알려주진 않음.

저자 본인도 cerebrum 적용률이 85~90% 정도라고 인정함. 즉 prompt 기반 강제는 hard guarantee가 아니라 부탁임. nginx의 limit_req처럼 진짜로 막는 게 아니라 "이건 하지 마"라고 모델한테 정중히 말하는 거.

이거 그냥 받아들이고 쓰면 됨. 다만 환상은 안 가지는 게 맞음.

한계#

• 본인은 직접 안 깔아봤음. 위 내용은 공식 readme·코드 구조 기반 추정 + 본인의 Claude Code 사용 경험에 비춘 해석.
• 80% 절감이 본인 환경에서 재현될지는 모름. 절반만 나와도 의미 있긴 함.
• daemon을 pm2로 돌린다는 게 살짝 무거움. 프로젝트별로 백그라운드 프로세스 띄우면 개발 머신 리소스 먹음. 가벼운 프로젝트엔 오버킬일 수도 있음.
• Claude Code 자체의 컨텍스트 압축·캐시가 점점 좋아지면, 이런 외부 미들웨어의 효과 폭은 시간이 갈수록 줄어듬. Anthropic 쪽에서 메모리·인덱스를 본체에 통합하기 시작하면 이 도구의 입지는 애매해질 가능성이 큼. 이건 Claude Code 공식 docs (hooks 레퍼런스)만 봐도 hook 메커니즘 자체가 Anthropic이 의도적으로 열어둔 확장점이라, 미들웨어가 점점 두꺼워지든 본체가 흡수하든 둘 중 하나로 갈 듯.

잡담#

좀 빗나간 얘긴데, 이런 식의 외부 도구가 자꾸 나오는 거 보면 결국 모든 코딩 에이전트의 진짜 차별화는 "컨텍스트를 얼마나 영리하게 관리하는가"로 수렴하는 거 같음. 모델이 어디 회사 거든 별로 안 중요해지는 흐름. 솔직히 본인 체감에서도 모델 자체 성능 차이보다 컨텍스트 관리 차이가 작업 품질을 더 가름. aickyway.com 운영하면서 LLM 호출 코드 만지다 보면 더 그렇게 느껴짐.

마무리#

미들웨어로 토큰 누수를 막겠다는 발상 자체는 영리함. 외부 캐시 + 인덱스 + 룰북이라는 구성은 전형적인 백엔드 패턴이고, 이걸 LLM 에이전트 옆에 그대로 붙인 건 깔끔한 적용임.

다만 80% 절감이라는 헤드라인은 마케팅 톤으로 받아들이고, 본인 환경에서 30~50%만 나와도 의미 있는 절감이라고 보면 됨. 그리고 cerebrum 같은 prompt 기반 강제는 100%가 아니라는 점만 잊지 않으면 됨.

본인은 다음 주 즈음 이거 깔아서 FastAPI 프로젝트 하나에 붙여보고, 토큰 사용량이 진짜로 어떻게 변하는지 측정해 볼 예정. 그 결과는 따로 정리해서 올릴 거고, 그때 직접 잰 수치로 다시 다룸.

다음 글에서는 OpenWolf를 우분투 + FastAPI 환경에서 직접 깔아서 돌려보고, anatomy 인덱스가 실제 한국어 코멘트 섞인 코드베이스에서 얼마나 잘 만들어지는지, 토큰 절감이 마케팅 수치만큼 나오는지 정리해 볼 예정.