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

AI 요약

글쓴이는 큰 변경을 할 때 커밋 설명을 5~10분 동안 작성하고 다시 읽곤 했습니다. 변경 내용을 한곳에 모아 독자가 여러 곳을 뒤지지 않게 하고, 무엇을 바꿨는지보다 왜 바꿨는지를 기록하려는 목적이었습니다. 때로는 “이렇게 하는 이유는…”이나 “다음 단계까지는 이렇게 하겠습니다”처럼 1인칭으로 적었습니다. 글을 쓰며 코드를 다시 읽고 결정을 재검토하다 보면 더 나은 변경으로 이어지기도 했습니다.

AI가 쓴 ‘왜’는 실제 이유와 다를 수 있습니다

에이전트가 코드와 커밋 설명을 모두 작성하는 상황에서는 설명의 정확성을 따져야 합니다. AI가 프로젝트 관리 도구나 대화에 흩어진 맥락을 모르면, 변경 이유를 스스로 지어낼 수 있습니다. 에이전트에 필요한 맥락을 제공하면 그럴듯한 설명은 작성하겠지만, 코드가 설명대로 동작하는지 확인하는 일은 여전히 사람 몫입니다.

글쓴이는 그래서 커밋 메시지와 설명은 직접 쓰겠다고 말합니다. 변경을 설명하다 막히면 자신이 무엇을 배포하는지 제대로 이해하지 못했을 가능성이 있습니다. 설명을 쓰는 일은 AI가 만든 코드를 되짚고 의도와 맞는지 확인하는 절차입니다. 나중에 문제가 생겼을 때 변경 이유를 설명하고 고치는 데에도 도움이 됩니다.

임시 결정과 종료 조건도 기록합니다

“다음 단계까지는 이렇게 하겠습니다” 같은 문장은 임시 결정과 종료 조건을 드러냅니다. 이런 조건은 코드나 도구에 기록하지 않을 만큼 당연하게 여겨져 누락되곤 합니다. 커밋 설명을 직접 쓰면 문장을 완성하는 과정에서 조건을 명시하게 되고, 미래의 독자는 변경을 유지할지 판단할 근거를 얻습니다. 글쓴이는 AI가 코드를 작성해도, 왜 그렇게 했는지를 적는 순간 자신이 배포 내용을 이해하는지 확인하게 된다고 말합니다.

Hacker News 반응

• @kccqzy — 예전부터 기본 커밋 메시지에 “Why?”와 “How?” 항목을 넣어 변경 이유와 선택한 구현 방식, 검토한 대안을 설명하도록 했습니다. 회사에서 커밋 메시지가 가장 긴 상위 1%에 들 정도로 오래 이 형식을 썼습니다.
  • @sublinear — 간결하게 쓰려면 계층형 글머리표가 좋습니다. 최상위에는 큰 관심사를 적고, 그 아래에는 이유를 짧게 요약한 뒤, 무엇을 했고 하지 않았는지 씁니다. 필요하면 마지막 단계에서 구현 세부 사항을 더합니다. 대부분은 필수 단계 두 개만으로 끝나며, 메시지는 보통 10~15줄을 넘지 않습니다.
• @zahrevsky — 설명을 커밋 메시지에 넣을지 ADR 같은 문서에 쓸지 고민할 때가 있습니다. 문서는 눈에 잘 띄고 어디서나 읽을 수 있습니다. Git 기록은 수정하기 어렵고 특정 커밋과 바로 연결된다는 장점이 있습니다.
  • @mopsi — 나중에 메시지를 읽는 사람은 다른 곳에 정보가 더 있다는 사실조차 모를 수 있습니다. 중요한 내용은 커밋 메시지나 소스 코드 주석처럼 가능한 한 가까운 곳에 두는 편입니다.
• @seunosewa — 다른 계열 LLM으로 커밋을 검토하고 자세한 설명을 작성합니다. 메시지가 의도와 맞지 않으면 직접 검토하는 계기로 삼습니다.
  • @cerved — LLM에 이유를 설명하라고 하면 실제 이유가 아니어도 이유를 만들어냅니다. 코드만 보면 그럴듯한 이유가 여럿 나오지만, 나중에 중요한 것은 정확히 어떤 이유였는지입니다.
• @evnp — AI가 실제 맥락과 동떨어진 설명을 쓰는 것도 위험하지만, 현실과 무관한 설명이 그럴듯하게 들리는 경우는 더 위험합니다.
  • @fphilipe — 전역 AGENTS.md에 커밋 메시지는 변경의 큰 방향과 이유를 설명하고, 이유를 모르면 자신에게 물어보라고 적어뒀습니다. 맥락이 없을 때 실제로 질문하는 편입니다.
• @WD-42 — 글쓰기는 커밋 메시지뿐 아니라 어떤 상황에서든 생각하는 과정입니다. 사람들이 그 점을 잊거나 처음부터 이해하지 못한 건 아닌지 걱정됩니다.
  • @bunderbunder — 에이전트에 구현 전체를 맡기자 세부 사항을 충분히 알기 전에 계획부터 확정하는 폭포수식 개발로 돌아가는 느낌이었습니다. 그 결과 나쁜 결정과 불필요한 기술 부채가 쌓였습니다. 코드를 살피지 않는 엔지니어링 관리자가 된 듯했습니다.
• @pnt12 — 글쓴이의 주장에 동의하지만 저는 글쓰기를 좋아하는 편입니다. 티켓이나 PR 설명을 귀찮아하는 사람에게는 AI가 쓴 글이라도 없는 것보다는 낫습니다.

원문: yedhu.me / 번역·요약: Trawling