TL;DR

  • AI 에이전트가 코드를 작성하는 환경에서도 변경 이유를 확인하고 이해를 점검하려면 커밋 설명을 직접 작성해야 함.
  • 긴 커밋 설명을 작성하고 다시 읽는 데 5~10분을 들이며, 유용한 정보를 한곳에 모으고 변경 사항과 그 이유를 설명함.
  • 커밋 설명을 쓰는 과정에서 코드를 다시 살펴보고 결정을 재평가하며, 때로는 더 나은 변경으로 이어짐.
  • AI 에이전트는 프로젝트와 여러 소통 도구에 흩어진 맥락을 놓칠 수 있어, 실제와 다른 변경 이유를 만들어낼 위험이 있음.
  • 에이전트가 맥락을 충분히 얻어도 코드가 설명대로 동작하는지는 직접 확인해야 하며, 이유를 설명할 수 있어야 이해한 변경을 배포할 수 있음.

커밋 설명을 쓰는 과정의 가치

  • AI 시대 이전에는 주요 변경의 커밋 설명이나 본문을 작성하고 빠뜨린 내용이 없는지 다시 읽는 데 약 5~10분을 들였음.
  • 독자가 여러 곳을 찾아다니지 않아도 되도록 유용한 정보를 모두 담고, 무엇이 바뀌었는지와 더 중요하게는 왜 바뀌었는지를 설명하려 했음.
  • ‘무엇이 바뀌었는지’는 대체로 자명한 변경을 요약하지만, ‘왜’를 설명하기 위한 출발점이 됨.
  • 때로는 누군가에게 메시지를 쓰듯 1인칭으로 “이렇게 한 이유는…” 또는 “우리가 …할 때까지 이렇게 하고 있음”이라고 적은 뒤, 변경 이유를 풀어 씀.
  • 이런 설명은 다른 사람이 변경 이유를 이해하는 데 도움이 되며, 특히 미래의 내가 그 이유를 파악하는 데 도움이 됨.
  • 커밋 메시지와 설명을 쓰는 일은 단순한 문서 작성이 아니라 작성한 코드를 되돌아보는 훈련임.
  • 코드를 다시 읽고 변경 사항을 요약하는 과정에서 결정을 재평가하게 되며, 때로는 다른 방식이나 더 나은 변경으로 이어짐.

AI가 작성한 커밋 설명의 위험

  • 에이전트 코딩 시대에는 코드부터 커밋 설명까지 모든 것을 AI가 작성하며, AI가 쓴 코드를 읽어야 하는지와 가독성이 어떤지에 관한 논쟁이 이어짐.
  • 특히 AI가 작성한 커밋 설명을 읽고 이해하는 일이 어렵다고 느낌.
  • 에이전트는 자신이 만든 변경에 대한 커밋 메시지를 작성할 수 있지만, 여러 소통 및 프로젝트 관리 도구에 흩어진 전체 맥락을 모를 수 있으며 일부 맥락은 오프라인에 있을 수도 있음.
  • AI가 변경의 ‘이유’를 모르면 스스로 그럴듯한 이유를 만들어낼 수 있음. 실제 이유와 완전히 다를 수 있어, 나중에 설명을 읽을 때 변경이 이해되지 않는 위험이 있음.
  • 채팅이나 도구를 통해 에이전트에 필요한 맥락을 모두 제공하는 방법은 지어낸 이유 문제를 줄이고, 에이전트가 변경 이유를 명확히 설명하도록 도울 수 있음.

직접 작성하는 커밋 설명

  • 올바른 맥락을 받은 에이전트도 설득력 있는 커밋 메시지를 작성할 수 있지만, 코드가 설명에 적힌 대로 동작하는지는 직접 확인할 수 있음.
  • 그래서 커밋 메시지와 설명을 직접 작성함.
  • AI가 만든 변경을 되돌아보고 모든 것이 의도한 대로인지 확인하는 과정으로 커밋 설명을 작성함.
  • ‘왜’를 설명할 수 없다면 이해하지 못한 무언가를 배포하는 셈이며, 나중에 문제가 생겼을 때 설명하거나 고치기 어려워짐.

설명할 수 없다면 이해한 것이 아님.

  • 커밋 설명은 이때도 사고 도구로 기능함.

임시 결정과 종료 조건

  • “우리가 …할 때까지 이렇게 하고 있음”과 같은 표현은 종료 조건이 있는 임시 결정을 나타냄.
  • 종료 조건은 코드나 다른 도구만으로 AI가 추론하지 못할 수 있음. 너무 당연해 기록할 필요가 없어 보인다는 이유로 문서화하지 않는 경우가 있기 때문임.
  • 커밋 메시지를 직접 쓰면 문장을 완성해야 하므로, 미래의 독자가 해당 변경을 유지할지 판단하는 데 도움이 됨.
  • 에이전트는 코드와 설명을 작성할 수 있지만, 무엇을 배포하는지 이해하는지는 변경 이유를 직접 작성하는 과정에서 확인됨.