계약직 프로젝트에서 클로드 코드(Claude Code)가 계획에 없던 결정(Clerk에 이메일이 빈 게스트 유저를 미리 생성)을 스스로 내렸고, CTO가 이유를 물어도 개발자조차 답을 몰랐어요. 근거는 노트북의 세션 대화 기록(트랜스크립트)에 있었지만 클로드 코드가 기본값으로 30일 뒤 지워버리죠. Grepathy는 이 기록에서 '왜'에 해당하는 결정만 뽑아 브랜치별 마크다운(.ai/why/<브랜치>.md)으로 커밋해 둬서, 나중에 리뷰어·동료·다른 에이전트가 사람에게 묻지 않고도 이유를 찾게 해줘요. 에이전트한테 실시간 로그를 시키지 않고 사후에 추출하며, 푸시를 막거나 스테이징을 건드리지도 않아요. MIT 라이선스에 v1.1.0까지 나온 실동작 도구예요.
용어 풀이
- 트랜스크립트(transcript)
- AI와 주고받은 세션 대화 기록. 클로드 코드는 기본값으로 30일 뒤 삭제해요.
- Clerk
- 회원 인증·유저 관리를 대신 처리해 주는 외부 서비스.
- ADR(Architecture Decision Record)
- 아키텍처 결정과 그 이유·트레이드오프를 남기는 기록 문서.
- 감사(audit)
- 결정이나 변경이 타당했는지 사후에 추적·검증하는 일.
운영자 인사이트
에이전트가 코드를 대신 쓰는 만큼 '누가 그 결정을 감사(audit)하나'가 실무 쟁점이 돼요 — 커밋 메시지나 ADR로는 놓치기 쉬운 중간 결정을 사후에 자동 보존한다는 발상은, 리뷰나 장애 대응 때 맥락을 복원하려는 팀이 살펴볼 만해요.
여러 관점으로 보기
- 도구 소개(GitHub) 세션 기록에서 결정만 뽑아 .ai/why/<브랜치>.md로 커밋해요. 에이전트에게 실시간 로그를 시키는 대신 사후 추출하고, CLAUDE.md 포인터와 훅으로 다음 에이전트가 파일을 고치기 직전에 관련 이력을 주입해요. 푸시를 막거나 스테이징을 건드리지 않고, MIT·TypeScript·별 35개예요. GitHub
- HN 반응 18점에 댓글 39개로 토론이 활발했어요. 'AI 결정을 다 리뷰하면 생산성 이득이 준다'는 회의론과 'CTO가 null 이메일 마이그레이션을 뒤늦게 발견했다'는 공감 사례가 갈렸어요. 작성자는 Grepathy를 붙인 에이전트가 '왜' 질문에 정확히 답한 블라인드 평가 결과를 공개했어요. hn