AI가 커밋 메시지로 PR 설명을 작성한다면, 그것은 버그입니다

요약 (TL;DR) — 커밋 메시지는 당신의 _의도 (intentions)_를 설명합니다. 디프 (diff)는 _실제 (reality)_를 설명합니다. 브랜치가 유지되는 동안 이 둘은 서로 어긋나게 되며, 대부분의 AI PR 설명 도구들은 잘못된 정보를 요약합니다. 좋은 PR 에이전트는 디프 (diff)를 읽어야 합니다. 여기 그 설계 방식과 바로 시작할 수 있는 무료 에이전트가 있습니다.

거짓말을 하는 PR 설명

작년에 한 리뷰어가 제 PR에 대해 다음과 같이 메시지를 보냈습니다: "설명에는 속도 제한 (rate limiting) 기능이 추가된다고 되어 있는데, 디프 (diff)를 보니 세션 토큰을 해싱하는 방식도 변경되었네요. 의도된 것인가요?"

의도된 것이었습니다. 저는 같은 브랜치에서 두 가지 작업을 모두 수행했습니다. 하지만 제 PR 설명에는 속도 제한에 대해서만 언급되어 있었습니다. 왜냐하면 커밋 메시지를 기반으로 설명을 생성했기 때문이며, 제 커밋 메시지는 wip, rate limit middleware, fix, fix again, tweak와 같았습니다. 토큰 해싱 변경 사항은 fix again이라는 메시지 아래에 숨어 있었습니다. 제 설명을 작성한 도구는 제 커밋을 충실히 요약했고, 제 커밋은 제가 실제로 수행한 일의 절반을 충실히 숨겼습니다.

리뷰어가 이를 잡아냈습니다. 하지만 PR 설명의 핵심 목적은 리뷰어가 디프 (diff)를 보고 직접 변경 사항을 재구성할 필요가 없어야 한다는 것입니다. 그것은 제가 했어야 할 일이었습니다.

커밋은 의도이고, 디프 (diff)는 실제입니다

커밋 메시지로부터 PR 설명을 생성할 때 발생하는 핵심적인 문제는 다음과 같습니다: 커밋 메시지는 당신이 그것을 타이핑하는 순간에 자신이 무엇을 하고 있다고 믿었는가에 대한 기록입니다. 이는 변경 사항이 완료되기 전, 종종 생각의 중간 단계에서, 그리고 빈번하게 fix 또는 address review comments와 같은 형태로 작성됩니다. 이는 특정 시점의 의도를 (부실하게나마) 포착할 뿐입니다.

베이스 브랜치(base branch)에 대한 디프 (diff)는 다릅니다. 그것은 _이것이 머지(merge)될 때 실제로 무엇이 변경될 것인지_에 대한 완전하고, 현재적이며, 사실적인 진술입니다. 이름이 바뀐 모든 함수, 변경된 모든 반환 형태 (return shape), 모든 마이그레이션 (migration), 모든 실수로 들어간 console.log — 이 모든 것이 디프 (diff)에 들어 있으며, 디프 (diff)는 머지되는 대상 그 자체이기에 결코 거짓말을 하지 않습니다.

AI 도구가 당신의 커밋 메시지 (commit messages)를 의역할 때, 그것은 요약을 요약하는 것입니다. 즉, 당신이 작업을 마치기도 전에 급하게 작성한 요약을 다시 요약하는 것이죠. 쓰레기가 들어가면 그럴듯하게 들리는 쓰레기가 나옵니다 (Garbage in, plausible-sounding garbage out). 설명 자체는 읽기에 괜찮을지 모릅니다. 하지만 그것은 사실이 아닙니다.

PR 에이전트는 디프 (diff)를 읽어야 합니다

해결책은 당황스러울 정도로 간단합니다. 에이전트가 git log가 아니라 git diff <base>...HEAD를 읽게 하는 것입니다. 하지만 당신이 신뢰할 수 있는 PR 에이전트와 의미 없는 내용만 채워 넣는 에이전트를 가르는 몇 가지 설계 선택 사항이 있습니다.

다음은 그 형태의 예시입니다 (이것은 실제 Claude Code 서브 에이전트이며, 정확한 문구보다 구조가 더 중요합니다):

---
name: pr-surgeon
description: "풀 리퀘스트 (pull request)를 열거나 푸시하기 직전에 사용하십시오. 다음을 읽습니다."
...

그 안에는 실질적인 작업을 수행하는 세 가지 요소가 있습니다:

1. "디프 (diff)가 진실의 원천이다. 커밋 메시지는 거짓말을 한다." 이 단 하나의 지침이 전체 논지입니다. 에이전트는 문맥 파악을 위해 커밋을 읽는 것은 허용되지만, 반드시 디프 (diff)와 대조하여 확인해야 하며 디프 (diff)를 신뢰해야 합니다. 이것이 바로 저의 토큰 해싱 (token-hashing) 변경 사항을 잡아냈을 방법입니다. 커밋에서 언급하든 안 하든, 그 내용은 디프 (diff)에 들어있기 때문입니다.

2. "만약 한 가지 이상의 일을 수행한다면, 명시적으로 말하라." 에이전트도 사람처럼 깔끔하고 단일 목적을 가진 이야기를 제시하고 싶어 합니다. 정직한 PR 에이전트는 범위를 모호하게 뭉뚱그리는 대신 범위 확장 (scope creep)을 드러냅니다. "리뷰어에게 알림 (Note to reviewer)" 헤딩은 토큰 해싱 (token-hashing) 변경 사항이 강제로 드러나게 되었을 지점입니다.

3. "이유(Why) — 찾을 수 없다면, 물어라. 지어내지 마라." 이것은 환각 (hallucination) 방지 가드레일입니다. 디프 (diff)는 무엇이 변했는지는 알려주지만, 왜 변했는지는 거의 알려주지 않습니다. 성능이 낮은 에이전트는 그 공백을 자신감 넘치는 허구로 채웁니다 ("이 리팩터링 (refactor)은 유지보수성을 향상시킵니다"). 좋은 에이전트는 그 간극을 인정하고 당신에게 질문합니다. 왜냐하면 지어낸 근거는 빈칸보다 더 나쁘기 때문입니다.

모두가 건너뛰는 섹션: 테스트 계획 (test plan)

대부분의 PR (Pull Request) 설명은 — 사람이 쓰든 AI가 쓰든 — "무엇이 바뀌었는가"에서 멈춥니다. 하지만 리뷰어에게 가장 가치 있는 PR 설명의 부분은 바로 **테스트 계획 (test plan)**입니다. 즉, 변경 사항이 주장하는 대로 작동하는지 확인하기 위한 구체적이고 실행 가능한 체크리스트입니다.

"로컬에서 테스트 완료" 같은 말은 아닙니다. 그것은 노이즈일 뿐입니다. 진짜 테스트 계획은 다음과 같은 모습이어야 합니다:

- [ ] `npm run test:rate-limit` 통과
- [ ] 10초 동안 `/api/login`을 6회 호출 — 6번째 호출 시 429 반환
- [ ] 배포 후에도 기존 세션 토큰이 여전히 유효함 (강제 로그아웃 없음)

마지막 줄이 바로 Diff (차이점)를 읽는 에이전트는 생성할 수 있지만, 커밋을 요약하는 에이전트는 절대 생성할 수 없는 종류의 내용입니다. 왜냐하면 토큰 해싱 (token-hashing) 변경 사항이 Diff 안에 있으므로, 에이전트는 리뷰어에게 기존 세션이 유지되는지 확인하라고 말해야 한다는 것을 알 수 있기 때문입니다.

직접 만들거나, 무료 버전을 시작하세요

이 패턴은 모든 "변경 사항 요약" 에이전트에 일반화됩니다: 의도를 나타내는 산출물(커밋 메시지, 티켓 제목, 본인의 기억)이 아니라, 현실을 나타내는 산출물(Diff, 스키마, 빌드된 결과물)을 읽으십시오.

시작점이 필요하다면, 제가 MIT 라이선스로 무료 공개한 Claude Code 에이전트가 집중력 있는 에이전트의 구조를 위한 좋은 템플릿이 될 것입니다. 도구 범위 지정 (tool scoping), 고정된 출력 형식, 명시적인 거부 규칙 등을 포함합니다:

üëâ github.com/allcanprophesy-ops/claude-code-shipping-coach

cp shipping-coach.md ~/.claude/agents/

이것은 PR 작성기라기보다는 머지 전 검사기 (pre-merge checker)에 가깝지만, 동일한 뼈대 위에 구축되었습니다. 잘 구조화된 에이전트 파일 하나를 읽는 것이 그 어떤 이론보다 더 많은 것을 가르쳐 줄 것입니다. 위에서 스케치한 pr-surgeon 에이전트와 몇몇 다른 에이전트들(regression-sentinel, test-gap-hunter)은 처음부터 직접 만드는 것이 싫다면 해당 리포지토리의 README에서 링크를 통해 확인할 수 있습니다. 하지만 솔직히 말씀드리면: 먼저 무료 버전을 읽어보고 결정하세요.

여러분이 리뷰했거나 작성했던 최악의 PR 설명은 무엇이었나요? 저는 "커밋 요약"이 잘못된 사례들을 수집하고 있습니다. 댓글로 남겨주세요.