AI(Claude Code)로 개발하면 세션이 끝나는 순간 “오늘 뭘 했고, 어떤 트레이드오프를 고민했고, 어떤 문제를 어떻게 풀었는지”가 휘발된다. 그래서 작업을 스스로 기록하게 만들었다.
트리거는 훅, 내용은 LLM
요구는 단순했다. “작업할 때마다 무엇을 했고 어떤 고민·문제해결을 했는지 한 폴더에 계속 기록해라.” 직관적으로 훅처럼 들린다. Claude Code의 Stop·PostToolUse 훅은 이벤트가 나면 명령을 자동 실행하니까.
그런데 훅은 결정론적 셸 명령이다. git diff는 뽑아도 “왜 A 대신 B를 골랐는지”는 글로 못 쓴다. 그건 LLM의 판단이 필요한 일이다. 그래서 자동 기록은 훅 단독으로 풀 수 없다. 트리거는 훅의 영역이지만, 내용 생성은 LLM의 영역이라 둘을 나눠야 한다. 정답은 훅 하나가 아니라 지침(CLAUDE.md) + 스킬 + 검증 루프 편입이었다.
준수율은 강제력이 아니라 마찰이 정한다
지침만으론 안 지켜진다. 그런데 실패의 진짜 원인은 강제력 부족이 아니라 마찰이었다. 매번 템플릿을 복사하고 날짜·커밋해시·변경파일·스코프를 손으로 채워야 하면, “다음에 쓰지”가 되고 결국 누락된다.
그래서 스킬이 git 컨텍스트를 자동 수집하게 했다. 직전 커밋 해시·제목, 변경 파일을 끌어오고, 변경 경로로 스코프(fe/be/infra)를 추론하고, 날짜 파일명으로 템플릿을 prefill한다. 사람(또는 LLM)은 4요소만 채우면 된다. 무엇을, 어떤 고민, 문제해결, 교훈. 강제 알림을 늘리는 것보다 채우는 마찰을 0에 가깝게 줄이는 쪽이 준수율을 올린다.
새 강제 장치 대신 기존 흐름에 끼운다
그래도 지침은 잊힌다. 강제력은 필요했다. 새 장치를 만드는 대신, 이미 강제로 도는 검증 루프(self-healing-loop)의 종료 조건에 묶었다. “커밋과 worklog 작성(또는 생략 근거)까지 끝나야 루프가 끝난다”로 바꿨다. 새 훅을 또 만드는 것보다, 반드시 도는 흐름에 한 단계 끼우는 게 싸고 확실하다.
Stop 훅으로 매번 “worklog 썼냐”를 띄우는 안도 검토하다 기각했다. 모든 stop에 발동해서 사소한 질문·대화에도 나가 노이즈가 크다. CLAUDE.md 규칙은 “코드 구현 작업”에만 scope되니 더 정밀하다. 무차별 훅보다 정밀한 지침과 마찰 없는 스킬이 실제 준수율이 높다.
기록 경계를 먼저 긋는다
기록 시스템의 흔한 실패는 같은 내용을 여러 곳에 중복으로 쓰는 것이다. 그래서 역할을 못 박았다.
| 대상 | 성격 | 무엇을 |
|---|---|---|
worklog/ | 시간순 개인 저널(gitignore) | 모든 작업을 여기 먼저 |
lessons/ | 팀 공유 재사용 패턴(커밋) | 일반화 가능한 교훈만 |
| 메모리 | 세션 간 사실·선호 | worklog와 중복 금지 |
흐름은 하나다. worklog에 1차로 적고, 가치가 높으면 이력서·블로그용 글이나 팀 교훈으로 승격한다. 경계를 먼저 긋지 않으면 같은 내용을 세 군데에 쓰게 된다.
그래서
자동화 요구를 만나면 먼저 “트리거”와 “내용 생성”을 가른다. 전자는 훅, 후자는 LLM 지침이다. 그리고 준수율은 강제력보다 마찰이 정하니, 강제 알림을 늘리기 전에 채우는 비용을 줄인다. 이 글도 그 시스템이 매 세션 남긴 기록에서 나왔다.