평소 Claude Code와 같은 코딩 AI를 사용하여 개발하는 분들께 질문드립니다.
"자신이 코딩 AI를 적절하게 사용하고 있다는 것을 사례를 들어 구체적으로 설명할 수 있습니까?"
저의 경우, 제출해야 하는 인사 평가 자료로 이것이 필요했습니다. 하지만 기억력에 자신이 없습니다. 이제는 대부분 자연어 상호작용만으로 이루어지는 작업 하나하나에서 어떤 판단을 했는지, 어떻게 지시했는지 등을 모두 기억하는 것은 불가능합니다.
그래서 저는 **"기억할 수 없다면 기록을 남기면 된다"**라는 답변을 내놓았습니다. 기록해야 할 판단들은 세션 안에 존재하기 때문에, 세션 말미에 불러내는 '통합 회고(統合振り返り) skill'을 만들어 운영해 보는 것이 어떨까 생각하여 실제로 사용해 보기 시작했습니다.
이번 글에서는 이 아이디어 공유를 메인으로 삼아, 해당 skill 자체와 현재까지의 성과를 소개하고자 합니다.
이 skill의 사용법은 매우 간단합니다. '일단 구현을 마쳤다'는 시점에, 해당 세션 내에서 /decision-log를 호출하기만 하면 됩니다. 대략적으로 이 skill이 수행하는 작업들은 다음과 같습니다.
- 세션 내 상호작용으로부터 사전에 정한 관점에서 '판단'에 해당하는 내용을 수집합니다.
- 기술이나 구성 요소의 선정 (채택하지 않은 안과 그 이유도 포함)
- AI가 제시한 안을 그대로 사용하지 않고 변경한 부분
- PR(Pull Request)을 올리기 전에 셀프 리뷰를 진행했는지 여부
- 생성된 코드의 라이선스나, AI에게 제공했던 정보의 기밀성을 확인했는지 여부
이러한 내용들을 모아 월별 회고에 추가합니다.
- 선정된 사항이 있다면 ADR(Architecture Decision Record)도 작성합니다.
그리고 기록 자체와 기록하는 관점들은 skill 정의와는 별도의 디렉터리에 축적하고 있습니다. 저의 경우, 다음과 같은 구성으로 정리했습니다.
~/.claude/skills/decision-log/SKILL.md # 절차만 담음. 무엇을 수집할지는 포함하지 않음
<기록지>/회고 관점.md # 세션의 무엇을, 무엇을 수집할지
<기록지>/회고/<YYYY-MM>.md # 회고 내용 저널. 월별로 추가
...
AI는 '나를 평가해 줘'와 같은 계열의 지시를 하면 대체로 좋은 해석을 내놓아 줍니다. 고민 상담 등이라면 유용하지만, 기록에 있어서는 그렇지 않습니다. 사실 기반으로 작성하도록 철저히 하고, '하지 않은 것은 쓰지 않도록'과 같은 지시가 필요합니다. 반대로 '확인했는지'와 같은 관점을 설정한 경우에는, 특히 언급이 없다고 해서 '하지 않았다'고 단정하는 것도 곤란합니다. 이 부분의 사실 확인은 철저히 할 수 있도록 skill 설계를 진행했습니다.
또한, 지시를 어떻게 받아들이는가도 모델에 따라 다르기 때문에, 성능을 보면서 어떤 모델로 회고 작업을 수행할지 신중하게 고려해야 할 수도 있습니다. 현재까지 Opus 5.5로 몇 번 시도해 봤는데, 본 범위 내에서는 '하지 않은 것을 쓰고 있다'와 같은 경우는 발견되지 않았습니다.
이 skill로는 두 가지 종류의 결과물을 예상하고 있습니다. 하나는 회고 자체의 기록입니다. 기록만 남겨져 있다면, AI에게 읽게 하여 핵심을 추출하는 것은 그리 어렵지 않습니다. 인사 평가용 데이터를 정리하는 것은 나중에 결과물 제출 시점에 진행하면 됩니다.
다른 하나는 ADR(Architecture Decision Record)입니다. 한마디로 설명하자면, '구현상의 설계 판단을 그 경위나 대립안을 포함하여 설명한 문서'라고 할 수 있습니다.
Claude Code 세션에서는 자주 '이 부분은 어떻게 할까요?'와 같은 상호작용이 일어납니다. 그렇게 하고 싶은 결정 문제는 크고 작음이 다양하지만, 그것을 결정하는 판단 자체도 ADR에 남길 가치가 있는 경우가 많습니다. 그래서 이 회고 skill은 그 경위로부터 ADR을 작성하는 기능까지 포함하고 있습니다.
이렇게 만들어진 ADR을 프로젝트 내 리포지토리에서 공유함으로써, 코드라는 현황 값에는 남기기 어려운 과정을 보관하는 효과도 노릴 수 있습니다.
9월 말부터 한 달 정도 운영해 본 결과, 기록한 작업은 5건, 작성된 ADR은 총 10건이 되었습니다.
또한, 저 자신의 과제로는 오랫동안 PR을 올리기 전의 셀프 리뷰가 부족하다고 느꼈습니다. 그래서 회고 관점에는 '셀프 리뷰를 했는지'도 기재했지만, 빠르게 PR을 올리는 흐름에 따라 대체로 리뷰 없이 마무리되었다는 사실이 decision-log를 통해 더욱 명확히 드러났습니다.
그래서 저는 별도의 셀프 리뷰(self-review) 스킬을 만들고, 그것을 통과하지 않으면 PR을 생성할 수 없도록 후크(hook)로 막음으로써, 리뷰라는 작업을 제 의식에 대한 의존으로부터 해방시켰습니다. 자기 개선 자료를 모아주는 것으로서, decision-log는 문제점 발견에 도움이 된 사례라고 할 수 있을 것 같습니다.
세션 정보를 집약하고, 미리 설정한 관점에서의 반성 및 ADR(Architecture Decision Record) 작성을 도와주는 스킬인 decision-log를 소개했습니다. "결국 호출 시점에 회고 타이밍이 의존한다", "compaction 후 정확하게 상호작용을 포착하기 어렵다"와 같은 과제가 보이며 아직 개선할 여지는 있지만, 항상 방치해 두는 정보를 수집하는 데 효과적으로 작동하고 있는 것 같습니다.
여기서 소개한 것 외에도, 인시던트 처리 기록이나 학습 기록 등 다른 내용에서도 같은 유형을 활용할 수 있을 것이라고 생각합니다. "전에 했던 것을 기억나지 않고 기록에도 없다"와 같은 고민이 있다면 꼭 시도해 보세요.
주식회사 신시아(株式会社シンシア)에서는 실무 경험이 없는 엔지니어나 학생 엔지니어 인턴을 채용하여 함께 일하고 있습니다.
※ 신시아에서의 근무 방식은 여기를 참고하세요
주식회사 신시아의 근무 방식과 스토리 - Wantedly
기술력을 함께 높여갈 동료로서, 함께 일하지 않겠습니까? 연락 기다리겠습니다!
