LLM을 어떻게 하면 잘 활용할 수 있을까? (Claude Code 스킬 개발기)

LLM을 어떻게 하면 잘 활용할 수 있을지 오랫동안 고민했다.

CLAUDE.md를 명확하게 작성하면 좋은 협업이 될까? 어느 정도는 맞지만, 세션에서 실제로 무슨 일이 있었는지는 기록되지 않는다.

plan.md로 harness engineering을 하는 방향은 어떨까? 전제 조건을 명확히 하는 데는 좋지만, 결정의 맥락과 이유가 남지 않는다.

Claude Code를 실제로 쓰면서 느낀 건, 내가 필요한 건 세션 중에 일어난 일을 명확히 기록하고 나중에 돌아볼 수 있는 환경이라는 것이었다. 결정이 왜 내려졌는지, 어떤 대안을 왜 버렸는지가 다음 세션의 출발점이 되어야 한다는 생각.

 

그래서 Claude Code skill을 만들어보았다.

1. 해결하고자 한 문제

세션이 끝나면 대화가 사라진다.

git log는 무엇이 바뀌었는지는 보여준다. 하지만 왜 Lua EVAL을 선택했는지, Claude가 내가 놓친 버그를 발견한 순간, 의식적으로 배제한 대안 — 이것들은 전부 증발한다.

토큰 트래커는 비용을 알려준다. 세션 로거는 무슨 대화를 했는지 알려준다. 하지만 누가 실제로 결과를 주도했는지는 아무것도 말해주지 않는다.

2. /collab-proof 가 하는 일

세션이 끝난 후 /collab-proof를 실행하면 git 히스토리와 대화 컨텍스트를 분석해서 이런 기록을 남긴다.

AI 기여도 예시 (HIGH 세션)

**AI contribution**:
  - Identified: 개발자가 놓친 ZCARD와 ZADD 사이의 TOCTOU 구간
  - Suggested: Redis 원자성 검토 후 Lua EVAL 방식 제안
  - Developer-driven: 최종 구현, Lua vs MULTI/EXEC 최종 결정

Claude가 지시를 실행만 한 세션은 솔직하게 기록한다:

**AI contribution**:
  - Developer-driven session. Claude executed instructions.

루브릭이 양쪽 모두 명시하도록 강제한다. 과장도, 축소도 없이.

3. 어떻게 동작하나

3단계 파이프라인이 /collab-proof 실행 시 동작한다.

• Layer 01 — 신호 감지 git log와 git diff를 읽어 이 세션이 기록할 가치가 있는지 판단한다. 새 파일 생성, 4개 이상 파일 수정, 명시적 대안 비교가 있으면 HIGH. 단순 구현이면 침묵한다. 전체 세션의 30~40%만 기록된다.
• Layer 02 — 4-frame 분석 4개의 인지 프레임을 동시에 점수화한다.
  • A: 코드 변경 깊이
  • B: 개발자의 불확실성 신호 (롤백, 방향 전환)
  • C: 명시적 대안 비교 (A vs B)
  • D: AI 기여도 — 여기가 핵심이다.
• Layer 03 — 기록
  • DECISIONS.md: 결정 분기점마다 왜 그 결정을 했는지, 무엇을 버렸는지 기록.
  • WORKLOG.md: D score가 세션마다 누적됨 — 내가 나아지고 있는지 트렌드로 확인.
  • proof.html: 토큰 효율 포함한 자체 포함 HTML (로컬 JSONL 읽기, 추가 API 비용 없음).

💡 Note: 훅은 비동기(Background subshell)로 동작해서 Claude Code를 블로킹하지 않는다.

4. 트레이드오프와 한계

• D score의 주관성: LLM이 루브릭에 따라 평가한 값이다. 같은 세션도 실행할 때마다 조금씩 다를 수 있다. 절댓값이 아닌 '트렌드 지표'로 보는 게 맞다.
• git notes의 제약: 앵커링은 솔로 개발자 기능이다. 팀 환경에서 squash merge를 쓰면 노트가 유실된다.

5. 설치 및 사용법

 외부 의존성 없음. pip install 불필요.

git clone https://github.com/dong7812/collab-proof && cd collab-proof && ./install.sh

이후 Claude Code 세션에서 /collab-proof만 실행하면 된다. SessionEnd 훅을 활성화하면 세션 종료 시 자동으로 실행된다.

• Repository: https://github.com/dong7812/collab-proof

GitHub - dong7812/collab-proof: Claude Code skill that auto-generates AI collaboration evidence — Vela pipeline × ADHD tree-o

간단한 데모 gif

이 스킬을 직접 빌드하고 내 로컬 환경에 적용해 보면서 두 가지 확신이 들었다.

첫째, "기록되지 않은 지식은 부채가 된다."
그동안 AI와 속도감 있게 개발하며 생산성이 높아졌다고 착각했지만, 세션이 끝나고 일주일만 지나면 "내가 왜 이 코드를 이렇게 짰지?"라며 과거의 나와 Claude가 내린 결정을 역공학(Reverse Engineering)하고 있는 나를 발견하곤 했다. `/collab-proof`를 띄워두고 나서야 비로소 AI를 '단순 코딩 대행사'가 아닌, 내 아키텍처 결정을 함께 고민한 '동료'로 대우하고 기록할 수 있게 되었다.

둘째, "좋은 도구는 개발자의 태도를 바꾼다.
`WORKLOG.md`에 쌓이는 D score 트렌드를 보면서 묘한 심리적 변화가 생겼다. AI 기여도가 1.0에 가까운 세션이 많아지면 '내가 너무 생각 없이 Claude에게 다 맡기고 지시만 따랐나?' 하고 반성하게 되고, 반대로 너무 낮으면 'Claude를 단순 타자수로만 쓰고 협업을 못 했구나' 하는 캘리브레이션이 스스로 일어난다. 점수 자체의 완벽함보다, 이 점수를 보며 **"내가 지금 AI와 제대로 협업하고 있는가?"를 주기적으로 자각하게 만드는 것** 자체가 이 스킬의 진짜 가치라는 생각이 든다.

앞으로는 이 누적된 기록들을 바탕으로, 장기적인 협업 트렌드를 시각화하는 `/collab-review` 기능이나, 팀원들과 이 결정을 더 부드럽게 공유할 수 있는 방법을 고민해 볼 예정이다. 결국 AI 시대의 개발자는 '코드를 많이 짜는 사람'이 아니라 '결정의 맥락을 완벽하게 통제하는 사람'이 진정 어울린다고 생각한다.

 

물론 내가 만든 skill에 대한 실효성은 아직 검증되지 않았지만, 여러 방면으로 노력하는 개발자가 되고 싶다...!