Checkup

Claude Code를 오래 쓰면 같은 교정을 반복하게 된다 — "그렇게 말고", "지난번에도 말했잖아". 이 스킬은 쌓인 대화 기록에서 그 반복을 찾아 CLAUDE.md로 승격시키는 정기검진이다.

원칙 하나가 전체를 지배한다: 원본 transcript를 그대로 읽지 않는다. 세션 기록은 수 MB짜리 JSONL이라 직접 읽으면 컨텍스트가 즉시 터진다. 압축은 로컬 스크립트(토큰 0)가 하고, 판단에 필요한 것만 읽는다.

0. 상태 읽기

cat ~/.claude/checkup-state.json   # {"last_run": "<ISO8601>"}

파일이 없으면 최초 실행이다. 분석 범위를 사용자에게 확인한다(기본 제안: 최근 7일). 전체 기록을 한 번에 돌리면 3단계 서브에이전트 비용이 커지므로, 최초 실행이 수십 세션 이상이면 최근 것부터 나눠 돌리자고 제안한다.

1. 새 세션 수집 + 다이제스트 (토큰 0)

last_run 이후 수정된 대화 transcript를 고른다. 서브에이전트 로그(*/subagents/*)와 현재 세션 자신은 제외한다.

find ~/.claude/projects -name '*.jsonl' -not -path '*/subagents/*' -newermt "<last_run>"

각각을 이 스킬의 스크립트로 압축한다. 출력은 임시 디렉토리(예: /tmp/checkup-<날짜>/).

python3 <이 스킬 디렉토리>/scripts/digest.py <transcript.jsonl> <출력.md>

다이제스트에는 사용자 발화 전부, 각 발화 직전 assistant 답변의 꼬리, 도구 에러만 남는다. 수 MB 세션이 수십 KB로 줄어든다. 사용자 발화가 2건 미만인 다이제스트는 버린다. 남은 게 0개면 여기서 종료하고 그렇게 보고한다.

주의 두 가지: resume된 세션은 파일이 이어 쓰이므로 이전 실행에서 이미 본 발화가 다시 다이제스트될 수 있다 — 중복 후보는 승격 판단 단계에서 걸러진다. 다이제스트에 API 키·토큰 같은 시크릿 패턴이 보이면 그 줄은 서브에이전트에 보내기 전에 지운다.

2. 교훈 후보 추출 — 병렬 서브에이전트

다이제스트를 서브에이전트당 10~15개로 묶어 병렬로 보낸다. 메인 컨텍스트는 후보 목록만 받는다. 각 서브에이전트에게 주는 지시의 핵심:

다이제스트 파일들에서 "다음 세션부터 다르게 행동해야 할 교훈 후보"를 추출하라. 후보 = 사용자의 교정, 반복된 마찰, 선호 표현, 좌절 신호. 사실 나열이 아니라 행동 교정 재료만. 각 다이제스트의 사용자 발화 전수를 하나씩 후보 여부 판정할 것 — "좀 이해되게 말해봐" 같은 짧은 발화가 최고 가치 후보다, 길이로 거르지 말 것. 후보마다: 한 줄 요약 + 근거 발화 원문 인용 + 세션 파일명.

3. 승격 판단 — 자동 반영 금지

후보 목록만 읽고 판단한다. 원본 transcript와 다이제스트 전체 재독은 금지.

기각 기준:

• 기존 CLAUDE.md가 이미 커버하는 내용 (중복)
• 그 세션에서만 유효했던 일회성 지시
• 코드나 저장소 문서가 이미 기록하고 있는 사실

살아남은 교훈은 CLAUDE.md 반영안(추가/수정할 정확한 문구)으로 정리해 사용자에게 제안한다. 승인 없이 CLAUDE.md를 고치지 않는다. 여러 세션에서 반복된 교훈일수록 우선순위가 높다 — 반복 횟수를 근거로 함께 제시한다.

마무리

~/.claude/checkup-state.json의 last_run을 이번 실행 시작 시각으로 갱신하고 보고한다: 분석한 세션 수, 후보 수, 제안한 교훈 수와 기각 사유 분포. 임시 다이제스트는 지워도 된다.