[AI 활용법 5] Git 워크플로우 — AI에게 커밋을 시키기 전 합의할 것들
원자적 커밋, Conventional Commits, 푸시 전 체크리스트
시리즈 5편. AI에게 코드를 맡기는 순간, 커밋 히스토리 가 가장 빨리 무너진다. 미리 합의해 둘 규칙들.
왜 Git 규칙이 AI 시대에 더 중요해졌나
사람이 키보드로 직접 칠 때는 그 자체 가 자연스러운 속도 제한이었다. 한 번에 30파일을 만지지 않는다.
LLM은 다르다. 한 응답에 50파일이 바뀔 수 있다. 이때 커밋이 하나의 큰 덩어리 로 묶여 들어가면, 다음 주의 디버깅이 지옥이 된다. AI가 빨라질수록 커밋은 더 작아져야 한다.
원자적 커밋(Atomic Commit)
하나의 커밋은 하나의 논리적 변경만 담는다.
좋은 예:
feat(auth): add OAuth PKCE flowtest(auth): cover PKCE error pathsdocs: explain PKCE in README
(세 커밋이다. 하나로 묶지 않는다)
나쁜 예:
feat: PKCE + i18n + button color tweak + a typo
판정 기준 두 가지:
- revert 가능성: 이 변경을 되돌리려고 할 때, 다른 무관한 변경이 같이 사라지는가?
- 리뷰 단위: 다른 사람에게 이 부분만 보여 줄 수 있는가?
Conventional Commits — AI에게 가장 잘 맞는 형식
<type>(<scope>): <subject>
<body — why, not what>
<footer — BREAKING CHANGE: ..., refs #123>
type 값:
| type | 사용처 |
|---|---|
feat |
새 기능 |
fix |
버그 수정 |
refactor |
동작 불변, 구조만 |
perf |
성능 개선 |
test |
테스트만 |
docs |
문서만 |
chore |
빌드/도구/환경 |
style |
포매팅, 세미콜론 |
build / ci |
빌드/CI 설정 |
LLM에게 이 표를 주고 “각 커밋에 type을 붙이고 분리해라”라고 하면, 커밋 분할 자체를 먼저 고민하게 된다 — 이게 가장 큰 효과다.
커밋 메시지의 왜
본문에는 무엇을 했는지 가 아니라 왜 했는지 를 쓴다. 무엇 은 diff에 이미 있다.
fix(api): prevent race condition in session refresh
When two refresh requests arrive within 5ms, the previous code
issued two new tokens and invalidated each other. We now serialize
refresh per session id with a sync.Mutex map.
Refs: #482
LLM은 자연스럽게 무엇 을 잘 쓴다. 왜 를 명시적으로 요구해야 한다.
커밋 메시지는 영문으로
내부 논의가 한국어라도, 커밋 메시지는 영문으로 통일하면:
- 오픈소스 기여 진입 장벽이 낮아짐
git log검색이 깔끔해짐- 자동화(릴리스 노트, changelog 생성)가 쉬워짐
한국어 맥락은 ADR (Obsidian)에 풀어 쓰고, 커밋에서는 ADR 링크로 참조한다.
refactor(core): extract validation layer from controller
See decisions/2026-04-22-validation-layer.md for the rationale.
브랜치 전략 — AI에게도 같은 규칙
main/master에 직접 푸시하지 않는다- 브랜치명:
<type>/<이슈>-<짧은-설명>(예:feat/123-add-oauth) - 한 브랜치 = 한 PR = 한 논리 단위
자율모드에서는 더 강하게: push origin main은 절대 안 됨. AI가 이걸 모르면 사고가 난다.
푸시 전 체크리스트
원격에 푸시하기 직전에 통과해야 하는 것들:
[ ] 빌드·린트·타입 체크 통과
[ ] 관련 테스트 통과
[ ] 시크릿·민감 정보 누출 없음
[ ] README 최신화 여부 확인
[ ] CHANGELOG 업데이트 (필요 시)
[ ] git config user.name/user.email = 본인
[ ] 커밋 메시지에 AI attribution 없음
이걸 PR 템플릿이나 pre-push 훅으로 박아 두면 사람·AI 모두 빠뜨릴 수 없게 된다.
위험한 명령 — 명시적 승인 필수
다음은 사용자의 명시적 승인 없이는 실행 금지:
git reset --hardgit push --force/--force-with-lease- 공유 브랜치
git rebase git branch -D, 원격 브랜치 삭제git clean -fdx- 태그 삭제·덮어쓰기
git push origin main/master
자율모드에서는 승인이 있어도 금지. 되돌릴 수 없는 일 은 사람의 손이 닿아야 한다.
Git Identity — 사람이 작성자다
AI가 만든 커밋이라도 author와 committer는 사람이다.
Co-Authored-By: Claude ...자동 삽입 금지🤖 Generated with Claude Code푸터 금지- GitHub contribution 그래프는 사람의 것
사용자가 명시적으로 “Claude를 공저자로 넣어줘”라고 한 경우에만 추가.
한 줄 요약
AI가 빨라질수록 커밋은 더 작고 더 명확 해져야 한다.
다음 편: AI 활용법 6 — ADR과 의사결정 영속화 이전 편: AI 활용법 4 — 가드레일