AI를 활용한 Git 커밋 메시지 생성기 제작 경험과 배운 점

저는 예전에 '버그 수정', '내용 업데이트' 같은 메시지로 커밋하던 개발자였습니다. 그리고 그게 정말 싫었습니다. 모든 pull request마다 커밋 히스토리를 정신없이 다시 써야 했죠. 그래서 AI를 이용해 이 과정을 자동화하기로 결심했습니다. 목표는 너무 창피하지 않게, 제 diff로부터 의미 있고 Conventional Commit 메시지를 직접 생성하는 것이었습니다.

스포일러: GPT 앞에 프롬프트를 던지는 것만큼 간단하지 않았습니다. 제가 겪었던 롤러코스터 같은 과정, 막다른 길들, 그리고 결국 찾아낸 놀랍도록 우아한 해결책이 여기에 있습니다.

실제 문제 (저의 문제)

저는 수십 명의 기여자가 참여하는 중규모 프로젝트를 진행하고 있었습니다. 저희는 Conventional Commits(feat:, fix: 등)를 강제했지만, 저는 계속 게을렀습니다. 매번 diff가 나올 때마다 제 뇌가 코드 모드에서 산문(prose) 모드로 전환되는 것을 원치 않았거든요. 저에게 필요한 도구는 다음 기능을 수행할 수 있어야 했습니다:

• 스테이징된 diff (추가/제거 내용)를 읽기
• 유형(feat, fix, refactor 등) 추론하기
• 짧고 의미 있는 설명을 작성하기
• 오프라인에서 작동하는 것? (이상적이었으나 결국 포기함)

저는 전체 CI 파이프라인을 원한 것이 아니었습니다. git commit 전에 실행할 수 있는 로컬 스크립트를 원했습니다.

처음 시도했던 방법들 (그리고 왜 형편없었는지)

시도 1: raw diff를 이용한 API 호출

git diff --cached | curl -X POST https://api.openai.com/v1/chat/completions -H "Authorization: Bearer $OPENAI_KEY" -d '{"model":"gpt-4", "messages": [{"role":"user", "content": "Generate a conventional commit message for this diff:"}]}'

간단하죠? 결과는... 장황했습니다. 마치 diff를 소설처럼 취급하며 단락을 작성했어요. 게다가 conventional 접두사를 무시하고 그냥 아무 문장이나 적었습니다. 더 많은 지침을 추가해 보기도 했지만, 그러면 존재하지 않는 기능을 환각(hallucinate)으로 만들어냈습니다. 완전히 쓰레기였습니다.

시도 2: 예시를 사용한 프롬프트 엔지니어링

유명한 블로그 포스트에서 프롬프트(prompt)를 복사해 왔습니다. 적절한 Conventional Commits 형식을 갖춘 퓨샷 예시(few-shot examples)를 사용했습니다. 약 60%의 확률로 작동했습니다. 하지만 작은 변경 사항(오타 수정)의 경우에도 여전히 fix: 대신 refactor:를 생성했습니다. 또한 매번 10개의 예시를 포함했기 때문에 토큰(token) 비용이 높았습니다.

시도 3: 로컬 모델 (Llama 3)

Ollama를 사용하여 Llama 3를 실행했습니다. 속도가 느렸고(메시지당 20초), 종종 19세기 소설 스타일로 커밋 메시지를 작성했습니다: "이 커밋에서는 인증 모듈에 대한 개선이 이루어졌습니다…" 팀 단위로 사용하기에는 절대 불가능한 수준이었습니다.

결국 성공한 방법: 3단계 파이프라인 (Three-Step Pipeline)

2주간의 좌절스러운 반복 끝에, 저는 세 가지 부분을 결합한 하이브리드 기술을 결정했습니다:

1. 유형 분류를 우선하는 구조화된 프롬프트 (Structured prompt with type classification first) – 모델에게 메시지를 작성하기 전에 변경 유형을 먼저 분류하도록 요청합니다.
2. 컨텍스트 절단 (Context truncation) – diff의 처음 200줄만 보내거나(또는 파일 이름과 요약만 보냅니다).
3. 검증 + 재시도 (Validation + retry) – 정규 표현식(regex)으로 출력을 확인하고, 실패할 경우 단순화된 프롬프트로 재시도합니다.

다음은 Node.js로 구현한 핵심 코드입니다 (OpenAI SDK를 사용했지만, 채팅 완성(chat completions)을 지원하는 어떤 API로든 교체할 수 있습니다):

import { execSync } from 'child_process';
import OpenAI from 'openai';

...

저는 이것을 Git 별칭(alias)으로 실행합니다:

git config --global alias.aimsg '!node ~/scripts/ai-commit.mjs'

그러면 git aismsg가 제안을 출력합니다. 저는 그것을 복사하여 실제 커밋에 붙여넣습니다. (자동화된 커밋 훅(commit hooks)은 위험합니다. 최종 결정에 있어서는 LLM보다 제 뇌를 더 신뢰합니다.)

배운 점 (고생하며 얻은 교훈)

배운 점 (고생하며 얻은 교훈)

• 토큰 제한(Token limits)이 적입니다. diff는 엄청나게 클 수 있습니다. 잘리면 컨텍스트가 손실되지만, 모델은 종종 여전히 올바른 유형을 추측합니다. 그렇지 않다면 폴백(fallback) 기능이 작동합니다.
• 검증(Validation)은 필수적입니다. 정규 표현식(regex) 검사 없이는 시적인 헛소리를 얻게 됩니다. 그것으로도 충분하지 않아, 때로는 모델이 fix:를 잘못된 위치에 넣는 등 속임수를 쓰기도 합니다.
• 온도(Temperature)가 중요합니다. 0.2는 일관되고 지루한 메시지를 제공하며 – 바로 제가 원하는 것입니다. 높은 온도는 창의적이지만 쓸모없는 출력을 만듭니다.
• 로컬 모델은 (이 용도로) 아직 준비되지 않았습니다. 많은 작업에 훌륭하지만, 커밋 메시지 생성은 엄격한 형식 준수를 요구합니다. GPT-4o-mini는 충분히 저렴하여(백만 입력 토큰당 $0.15) 단 한 번의 호출 비용이 1페니보다 적습니다.

제가 고려했던 트레이드오프 (Trade-offs)

저는 신뢰성을 위해 오프라인 기능을 포기했습니다. 인터넷이 없는 외딴 오두막에 있다면, 제 스크립트는 도움이 되지 않을 것입니다. 로컬 모델로 교체할 수는 있지만, 정확도가 낮을 것으로 예상해야 합니다.

또한 저는 의도적으로 --amend나 자동 커밋을 사용하지 않았습니다. 왜냐하면 AI는 실수를 하기 때문입니다. 만약 제가 실제로는 비즈니스 로직을 변경했는데도

또한, diff(차이점)와 제안 내용을 나란히 보여주는 간단한 TUI (terminal UI)를 구축하여, 커밋하기 전에 수정할 수 있도록 만들고 싶기도 합니다. 하지만 그것은 제가 계속 미루고 있는 주말 프로젝트입니다.

이 방식이 저에게는 잘 맞지만, 사람마다 워크플로 (workflow)는 다릅니다. 여러분은 커밋 메시지 자동화를 시도해 보신 적이 있나요? 비슷한 파이프라인 (pipeline)을 구축하셨나요, 아니면 직접 작성하는 메시지를 고수하시나요? 여러분은 이 문제를 어떻게 처리하는지(혹은 왜 이것이 처음부터 나쁜 아이디어라고 생각하는지) 정말 듣고 싶습니다.