군더더기 없는 Claude Code 설정: 매 세션마다 실행하는 CLAUDE.md와 Hook

Claude Code를 진지하게 사용해 보셨다면 이런 느낌을 받으셨을 겁니다. 모델은 똑똑하지만, _세션 (session)_이 당신을 괴롭힌다는 사실 말이죠. 모델은 지난주에 무엇을 했는지 잊어버립니다. 잘못된 파일을 수정합니다. 깨진 빌드를 "완료"했다고 선언하고 다음 단계로 넘어가 버립니다. 결국 당신은 매일 아침마다 당신의 컨벤션 (conventions)을 다시 설명해야 하는 상황에 처하게 됩니다.

제가 받아들이는 데 시간이 좀 걸렸던 사실이 있습니다. 병목 현상 (bottleneck)은 모델이 아니었습니다. 모델을 둘러싼 하네스 (harness)가 문제였습니다. 훌륭한 모델이라도 허술한 하네스와 함께라면 기억상실증에 걸린 주니어 개발자와 다를 바 없습니다.

그래서 저는 프롬프트 (prompts)를 수정하는 것을 멈추고 _시스템 (system)_을 구축하기 시작했습니다. 이것은 제가 매 세션마다 실제로 실행하는 설정입니다. 이론이 아닌 실제 상황입니다.

1. CLAUDE.md는 희망 사항 목록이 아니라 계약서입니다

대부분의 사람들의 CLAUDE.md는 에이전트 (agent)가 압박을 받으면 무시해 버리는 정중한 제안들의 더미일 뿐입니다. 저의 것은 타협할 수 없는 사항들이 담긴 계약서처럼 읽힙니다. 그 자리를 차지하고 있는 몇 가지 규칙은 다음과 같습니다:

## 응답 스타일 (Response style)
- 먼저 답변하고, 요청받은 경우에만 설명할 것. 불필요한 말은 하지 말 것.

...

마지막 규칙인 "완료는 완료를 의미한다"는 파일 전체에서 가장 영향력이 큰 문장입니다. 하지만 문서에 적힌 규칙은 무언가가 그것을 _강제 (enforces)_하기 전까지는 단지 제안일 뿐입니다. 여기서 훅 (hooks)이 등장합니다.

2. 모든 것을 바꾼 단 하나의 훅: verify-before-done

Claude Code를 사용하면 에이전트가 자신의 턴을 종료하려고 할 때 훅을 실행할 수 있습니다 ("Stop" 훅). 저는 단순하고 냉혹한 체크를 수행하는 훅을 사용합니다: 만약 에이전트가 코드를 수정했고 작동한다고 주장하지만, 해당 턴에 테스트/빌드/명령어를 실행하지 않았다면, 중단을 차단하고 실제로 검증하도록 만듭니다.

기본적인 로직은 다음과 같습니다:

on Stop:
  if changed_code_this_turn and claimed_done and not ran_verification:
      block("작동한다고 말했지만 아무것도 검증하지 않았습니다. 기능을 실행하고,
...

불과 수십 줄에 불과하지만, 이 작업 하나로 "작동한다고 했는데 안 되는" 고통을 거의 모두 없앴습니다. 에이전트는 더 이상 스스로 획득하지 않은 초록색 체크 표시를 저에게 건넬 수 없습니다.

3. 모델 라우팅 (Model routing): 저렴한 작업은 저렴한 모델로

별도의 지시가 없는 한 서브에이전트 (Subagents)는 메인 모델을 상속받습니다. 이는 최상위 모델이 비싼 가격을 지불하며 조용히 grep 검색이나 로그 요약 (log-summarizing) 작업을 수행하게 될 수 있음을 의미합니다. 저는 작업에 따라 라우팅 (routing)을 합니다: 회상 (recall)/인벤토리 (inventory)/요약 (summarization) → 저렴하고 빠른 모델, 구현 (implementation)/테스트 (tests) → 중간 수준의 모델, 심층 검토 (deep review)/진단 (diagnosis) → 강력한 모델. 실행 전 단계의 작은 훅 (hook)이 티어를 자동으로 고정하여 제가 일일이 기억할 필요가 없게 만듭니다. 중요한 작업에는 동일한 품질을 유지하면서, 중요하지 않은 작업에는 비용을 아주 조금만 사용합니다.

4. 영구 메모리 (Persistent memory) + 지식 그래프 (knowledge graph)

에이전트는 작은 파일 기반 메모리에 내구성 있는 사실들을 기록하며 (파일당 하나의 사실을 기록하고, 매 세션마다 로드하는 한 줄짜리 인덱스 포함), 저는 제 노트 위에 지식 그래프 (knowledge graph)를 유지합니다. 그 결과: 에이전트가 제 과거 작업 내용을 다시 조사하는 일이 중단됩니다. 무언가를 빌드하거나 조사하기 전에, 회상 (recall) 단계에서 "우리가 이미 이것을 수행했는가?"를 확인하며, 대개는 이미 수행한 상태입니다.

5. 빌드 전 회상 (Pre-build recall): 이미 존재하는 것을 다시 빌드하지 마세요

위의 메모리와 연계된 기능으로, 각 빌드/조사 요청 시 이전 작업 내용을 먼저 드러내도록 체크합니다. 제가 3주 전에 끝낸 작업을 다시 빌드하려던 순간을 이 기능이 잡아낸 횟수는 정말 창피할 정도입니다.

핵심 요점

이 기능들은 개별적으로는 영리하지 않습니다. 하지만 이들이 결합되면 에이전트는 건망증 있는 천재에서, 프로젝트를 기억하고 빌드가 통과 (green) 되었는지 여부에 대해 거짓말하기를 거부하는 시니어 엔지니어처럼 행동하는 존재로 변모합니다.

빠르게 시작하고 싶다면, 가장 영향력이 큰 두 가지 요소인 **CLAUDE.md 계약 (contract)**과 완료 전 검증 (verify-before-done) 가드레일을 작은 무료 스타터 키트로 패키징해 두었습니다. 바로 적용 가능합니다: 파일을 복사하고, 재시작하면 10분 안에 완료됩니다. 이메일 입력 없이 읽을 수 있는 $0 옵션이 포함된 원하는 만큼 지불 (pay-what-you-want) 방식입니다:

→ 무료 Claude Code 스타터 키트: https://expressive446.gumroad.com/l/qlypgs

이 스택으로 매일 결과물을 내놓는 사람이 직접 만들고 실행했습니다. 설정 관련 질문은 댓글로 남겨주시면 기꺼이 답변해 드리겠습니다.