← 목록으로

생각을 정리하는 도구로서의 커밋 설명

• 커밋 설명을 직접 쓰는 과정은 코드 변경을 돌아보고 결정을 재검토하는 작업이며, AI가 만든 변경이 의도대로인지 확인하는 데도 도움이 됨
• 커밋 설명은 무엇을 바꿨는지보다 왜 바꿨는지를 남기는 데 중요하며, 동료와 미래의 자신이 변경 이유를 이해할 수 있게 함
• AI 에이전트는 여러 소통 채널과 프로젝트 관리 도구, 오프라인에 흩어진 맥락을 모르면 변경 이유를 지어낼 수 있음
• 에이전트에 충분한 맥락을 제공하면 이유를 지어내는 문제는 줄일 수 있지만, 설명과 실제 코드가 일치하는지는 사람이 검증해야 함
• 직접 이유를 쓰면 배포할 변경을 이해했는지 점검하고, 임시 결정의 종료 조건도 명시해 미래에 그 변경을 유지할지 판단할 근거를 남길 수 있음

커밋 설명을 쓰면서 코드를 다시 생각하기

• AI 도입 전에는 큰 변경의 커밋 본문을 길게 작성하고, 중요한 내용을 빠뜨리지 않았는지 초안을 다시 읽는 데 약 5~10분을 들였음
  • 독자가 여러 곳을 뒤지지 않도록 유용한 정보를 한곳에 모으기 위한 작업이었음
  • 변경 사항 자체는 대체로 코드에서 드러나지만, 이를 요약하는 일이 변경 이유를 설명하는 출발점이 됨
• “나는 이런 이유로 이 작업을 했다”, “우리가 …할 때까지 이렇게 처리한다”처럼 1인칭 메시지로 쓰면 동료와 미래의 자신에게 결정의 이유를 전달하기 쉬움
• 설명을 작성하며 코드를 다시 읽고 변경을 요약하면 결정을 재평가하게 되며, 때로는 다른 변경이나 더 나은 변경으로 이어짐

AI가 작성한 설명의 한계와 직접 쓰는 이유

• 에이전트 코딩 시대에는 코드부터 커밋 설명까지 AI가 작성함
  • AI가 작성한 코드를 읽어야 하는지, 가독성 측면에서 얼마나 어려운지를 둘러싼 논쟁이 있지만, 커밋 설명을 읽고 이해하는 일도 어려울 수 있음
• 에이전트는 변경에 맞는 커밋 메시지를 쓸 수 있어도 전체 맥락을 갖고 있지 않을 수 있음
  • 이유에 관한 정보는 여러 소통 채널과 프로젝트 관리 도구에 흩어져 있거나 오프라인에만 있을 수 있음
  • 실제 이유를 모르는 AI가 나름의 근거를 만들어내면, 나중에 읽었을 때 실제 결정 이유와 달라 앞뒤가 맞지 않을 수 있음
• 채팅이나 도구로 필요한 맥락을 모두 제공하면 지어낸 근거 문제를 해소하고 이유를 명확히 설명하도록 도울 수 있음
  • 다만 설득력 있는 커밋 메시지가 나와도, 코드가 설명대로 동작하는지를 검증하는 일은 사람에게 남음
• 커밋 메시지와 설명을 직접 작성하면 AI가 만든 변경을 돌아보고 의도에 맞는지 확인할 수 있음
  • “왜”를 설명하지 못한다면 이해하지 못한 변경을 배포하는 것이며, 이후 문제가 생겼을 때 설명하거나 수정하기 어려움
• “우리가 …할 때까지 이렇게 처리한다”는 문장에는 임시 결정의 종료 조건이 담김
  • 너무 당연하다고 여겨 어디에도 기록하지 않은 조건은 AI가 코드나 다른 도구에서 추론할 수 없음
  • 직접 문장을 완성하면 그 조건을 명시하게 되고, 미래의 독자가 변경을 유지할지 판단하는 데 도움이 됨
• 에이전트는 코드와 설명을 모두 작성할 수 있지만, 이유를 직접 쓰는 과정에서 자신이 배포하는 변경을 이해했는지 확인할 수 있음