프롤로그: 1주일 만에 찾아온 위기

Snapkin을 만든 지 1주일. 세션 끝마다 /snapkin을 치면 AI 에이전트 3마리가 후다닥 달려와서 CLAUDE.md와 LESSONS.md를 정리해주는 — 나름 잘 돌아가는 시스템이었다.

그런데 문제가 생겼다.

대화 3턴 만에 컨텍스트 윈도우가 56% 찼다.

범인은 LESSONS.md. 에이전트들이 착실히 쌓아놓은 60개의 교훈이, 매 세션 시작할 때마다 통째로 로드되고 있었다. "유용한 지식을 쌓을수록 작업 공간이 줄어드는" — 아이러니한 상황.

이건 마치 책을 너무 많이 사서 책상 위에 쌓아둔 나머지, 정작 글 쓸 공간이 없어진 것과 같았다.

1막: 경쟁자에게서 배우다

리모델링을 시작하기 전에, 먼저 이웃집을 구경했다. session-wrap이라는 플러그인 — 같은 "세션 정리"를 하지만 접근 방식이 완전히 달랐다.

Snapkin session-wrap
에이전트 수 3마리 5마리
철학 "내가 알아서 할게" (자동 커밋) "여기 제안서요, 결정은 당신이" (advisory)
파일 권한 엄격 (1 에이전트 = 1 파일) 느슨 (제안만 하고 사용자가 선택)

session-wrap에서 눈에 띈 것:

  • 관심사 분리: 에이전트 하나가 하나만 한다. 문서 업데이트 따로, 자동화 탐지 따로, 학습 추출 따로.
  • Advisory 모델: 자동으로 커밋하는 대신, "이렇게 할까요?"라고 물어본다.
  • 스크립트 검증: 패턴 매칭 같은 단순 작업에 LLM을 쓰지 않는다.

반면 Snapkin의 장점도 있었다. 빠르고, 파일 충돌이 없고, Quick 모드가 있다.

결론: 둘 다 가져가자.

2막: 수술은 5단계

수술 1: "기본값의 힘"

가장 먼저 바꾼 건 기본 모드. /snapkin을 치면 바로 커밋하던 걸, 확인 한번 거치고 커밋하도록 바꿨다.

Before: /snapkin     → 자동 커밋 (위험!)
After:  /snapkin     → 확인 후 커밋 (안전)
        /snapkin auto → 자동 커밋 (명시적 선택)

session-wrap의 advisory 모델에서 배운 것. "자동화의 편리함"과 "확인의 안전함" 사이에서, 기본값은 안전한 쪽이어야 한다.

수술 2: "auditor, 너 일이 너무 많아"

auditor 에이전트는 혼자서 conventions도 업데이트하고, Session Context도 쓰고, Next Entry Point도 검증하고 있었다. 7,600자짜리 프롬프트. 이건 session-wrap처럼 역할을 나눠야 했다.

해법: Session Context는 오케스트레이터가 직접 쓴다.

Session Context는 "오늘 뭐 했고, 다음에 뭐 할 건지" — 기계적으로 채울 수 있는 temporal data다. AI가 "분석"할 필요가 없다. auditor 프롬프트가 56% 축소됐다.

수술 3: "Haiku야, 미안하지만 너 해고"

Validator는 API 키 패턴 검사, 마커 존재 확인, 줄 수 세기 — 전부 grep으로 할 수 있는 일이었다. 그런데 매번 Haiku를 호출하고 있었다.

# 30줄짜리 bash 스크립트가 Haiku를 대체했다
bash scripts/validate.sh 2026-02-14
# → All checks passed. 0 issues.

비용: $0. 시간: <1초. 재현성: 100%.

LLM은 "판단"이 필요한 곳에만 써야 한다. 패턴 매칭은 grep의 영역이다.

수술 4: "프롬프트 다이어트"

Phase 2에서 에이전트를 호출할 때, 프롬프트에 "이렇게 해라" 지침이 들어있었다. 그런데 subagent_type="snapkin:historian"을 쓰면 agents/historian.md가 자동 로드된다. 지침이 두 번 들어가는 셈.

수정 후 프롬프트는 데이터만 전달:

Before: "You are the Historian. Follow these rules... [3000자 지침] + [데이터]"
After:  "[데이터만: git diff + summary + LESSONS.md 전문]"

수술 5: "80줄 룰"

LESSONS.md가 80개 레슨을 넘으면 자동 아카이브. 이건 contents_hub에서 직접 겪은 문제 — 320줄의 레슨이 매 세션마다 로드되어 컨텍스트 절반을 잡아먹는 — 에서 나온 해법이다.

3막: 테스트에서 터진 것들

리모델링은 설계의 절반이고, 나머지 절반은 테스트에서 나온다.

버그 1: historian이 글을 안 썼다

첫 테스트에서 historian이 "10개 레슨을 추가했습니다!"라고 보고했는데, LESSONS.md는 그대로였다. 원인: 프롬프트 경량화 과정에서 LESSONS.md 전문 대신 요약을 전달했다. historian은 전체 파일을 못 봤으니 어디에 뭘 써야 할지 몰랐던 것.

교훈: 데이터 전달 시 "요약으로 충분하겠지"라는 가정은 위험하다. 에이전트는 전문이 필요하다.

버그 2: auditor가 금지구역을 침범했다

auditor에게 "Session Context를 건드리지 마라"고 에이전트 정의에 써놨는데, 떡하니 Session Context를 다시 작성했다. 왜? 프롬프트 데이터에 Session Context 내용이 포함되어 있었으니까. AI는 보이는 걸 고치고 싶어한다.

교훈: "하지 마라"보다 **"보여주지 마라"**가 더 강력한 제어 수단. 프롬프트의 데이터 범위를 제한하는 것이 instructional prohibition보다 효과적이다.

이건 이 세션에서 가장 값진 인사이트였다:

AI 에이전트에게 지시문으로 금지하는 것보다, 입력 데이터에서 제외하는 것이 더 확실한 제어다.

버그 3: validate.sh의 오탐

Key Files 섹션에서 "LESSONS.md"라는 단어를 찾으면 경고를 띄우게 했는데, agents/historian.md — LESSONS.md owner라는 설명 텍스트에서 매칭됐다. 파일 엔트리만 매칭하도록 패턴을 수정.

에필로그: 숫자로 보는 리모델링

지표 Before (v2) After (v3) 변화
auditor 프롬프트 7,600자 ~3,300자 -56%
Phase 2 토큰 ~25K ~15K -40%
Phase 3 비용 Haiku 1회 $0 (bash) -100%
기본 모드 자동 커밋 확인 후 커밋 안전성 ↑
레슨 한도 50개 80개 (+ 아카이브) 유연성 ↑
자동화 분류 [Future] [Future:Skill/Command/Hook] 구체성 ↑

오늘의 교훈 Top 3

1. 기본값은 안전한 쪽으로. 자동화의 편리함보다 확인의 안전함이 먼저다. 빠른 길은 옵션으로 남겨두면 된다.

2. "하지 마라" < "보여주지 마라". AI 에이전트 제어의 가장 확실한 방법은 지시문이 아니라 데이터 범위 제한이다. 보이지 않는 건 고칠 수 없다.

3. LLM은 판단에, grep은 패턴에. 도구의 본질에 맞게 쓰자. API 키 찾기에 Haiku가 필요하진 않다.

v3 리모델링은 끝났지만, 진짜 테스트는 내일부터다. 새 세션에서 캐시를 지우고 /snapkin을 칠 때, 이 모든 변경이 정말 잘 돌아갈까? 그건 다음 이야기.