AI 코드 PR 설명, 리뷰어가 바로 보는 7줄 작성법

AI가 고친 코드가 로컬에서 돌아가면 바로 PR 버튼을 누르고 싶어집니다. 그런데 PR 설명 칸이 "버그 수정", "AI가 고침", "테스트 완료" 정도로 비어 있으면 리뷰어는 diff를 처음부터 다시 읽어야 합니다. 특히 AI가 만든 변경은 범위가 넓어 보이기 쉽기 때문에, 리뷰어가 먼저 알아야 할 정보를 짧게 깔아 두는 편이 낫습니다.

오늘 목표는 긴 문서를 쓰는 것이 아닙니다. PR 리뷰 요청 전에 목적, 바뀐 파일, 테스트 결과, 남은 질문을 7줄로 보이게 만드는 것입니다. docs.github.com의 "Helping others review your changes" 문서도 PR이 리뷰어에게 변경 맥락을 제공하고, 작은 범위와 명확한 설명이 리뷰를 쉽게 만든다고 안내합니다. 그러면 초보자가 지금 필요한 것은 멋진 글이 아니라, 리뷰어가 바로 읽을 수 있는 7줄 구조입니다.

첫 30초에는 PR이 해결한 문제를 한 줄로 못 박습니다

PR 설명의 첫 줄은 "무엇을 바꿨다"보다 "왜 이 변경이 생겼다"가 먼저입니다. 리뷰어는 파일 목록을 보기 전에 이 PR이 어떤 문제를 해결하는지 알아야 합니다. AI가 코드를 많이 고쳤더라도 첫 줄이 선명하면 리뷰 범위가 좁아집니다.

나쁜 첫 줄은 이렇게 흐릅니다.

AI로 로그인 관련 코드 수정했습니다.

이 문장은 리뷰어가 무엇을 확인해야 하는지 알려 주지 않습니다. 더 나은 첫 줄은 문제와 결과를 같이 적습니다.

로그인 실패 시 빈 화면으로 멈추던 문제를 에러 메시지 표시 흐름으로 바꿨습니다.

여기에는 세 가지 정보가 들어 있습니다. 원래 문제는 로그인 실패 후 빈 화면입니다. 바뀐 결과는 에러 메시지 표시입니다. 리뷰어가 먼저 볼 곳은 로그인 실패 흐름입니다. 첫 줄은 기능 이름이 아니라 사용자가 겪던 문제와 바뀐 결과를 적어야 합니다.

다음 1분에는 바뀐 파일을 리뷰 순서대로 적습니다

docs.github.com의 PR 리뷰 문서는 리뷰어가 커밋, 바뀐 파일, base와 compare branch 사이의 diff를 보고 토론한다고 설명합니다. 바뀐 파일이 많으면 리뷰어는 파일 트리나 필터로 이동할 수 있지만, 어디부터 봐야 하는지는 작성자가 알려 주는 편이 좋습니다. AI가 만든 변경일수록 이 안내가 더 중요합니다.

PR 설명에는 파일 목록 전체를 붙이지 말고, 리뷰 순서를 적습니다.

리뷰 순서:
1. app/login/page.tsx: 실패 상태 표시 변경
2. src/lib/auth.ts: 로그인 API 오류 처리 정리
3. tests/login-error.test.ts: 실패 케이스 테스트 추가

이렇게 적으면 리뷰어는 package-lock.json이나 자동 포맷 변경보다 중요한 파일을 먼저 봅니다. 바뀐 파일이 2개뿐이면 더 짧게 써도 됩니다.

핵심 파일은 app/login/page.tsx 하나이고, tests/login-error.test.ts는 확인용 테스트입니다.

반대로 AI가 예상보다 많은 파일을 건드렸다면 PR을 바로 올리기 전에 멈춰야 합니다. 설명할 수 없는 파일이 2개 이상 있으면 리뷰 요청보다 변경 범위 정리가 먼저입니다. 그 상태로 PR을 올리면 리뷰어는 코드 품질보다 "왜 이 파일까지 바뀌었는가"를 먼저 묻게 됩니다.

2분째에는 테스트 결과를 명령과 결과로 씁니다

"테스트했습니다"는 리뷰어에게 충분한 정보가 아닙니다. 어떤 명령을 돌렸고, 어떤 결과가 나왔는지를 적어야 합니다. docs.github.com은 PR을 제출하기 전에 자신의 PR을 먼저 검토하고 빌드와 테스트를 해 보라고 안내합니다. 초보자는 이 문장을 PR 설명의 한 줄로 바꾸면 됩니다.

확인:
- npm run test 통과
- npm run build 통과
- 로그인 실패 화면을 브라우저에서 직접 확인

명령이 실패했다면 숨기지 않습니다. 실패한 상태로도 초안 PR을 만들 수는 있지만, 리뷰 요청 문구는 달라져야 합니다.

확인:
- npm run test 통과
- npm run build 실패: 기존 타입 오류 2개가 남아 있어 이 PR 범위 밖으로 분리했습니다.

이 한 줄은 방어 문장이 아닙니다. 리뷰어가 지금 봐야 할 문제와 나중에 봐야 할 문제를 나누는 장치입니다. 통과한 명령, 실패한 명령, 직접 본 화면을 분리해서 쓰면 AI 변경이 더 검토 가능한 상태가 됩니다.

git diff를 AI 요약으로 바꾸고 PR 설명으로 정리하는 흐름 이미지

AI에게 요약을 맡길 때는 diff와 출력 형식을 같이 줍니다

AI에게 "PR 설명 써줘"라고만 말하면 결과가 길어지거나, 실제 diff에 없는 장점을 꾸며낼 수 있습니다. developers.openai.com의 OpenAI 프롬프트 가이드는 원하는 작업, 맥락, 출력 형식을 명확히 주는 방향을 권합니다. PR 설명도 마찬가지입니다. AI에게 diff를 주되, 7줄 형식으로만 요약하라고 제한해야 합니다.

먼저 바뀐 파일과 diff를 준비합니다.

git diff --name-only
git diff

그다음 아래 프롬프트를 씁니다.

아래 git diff를 바탕으로 GitHub PR 설명 초안을 만들어 주세요.

조건:
- 과장하지 말고 diff에 있는 변경만 요약합니다.
- 리뷰어가 먼저 볼 파일 순서를 적습니다.
- 테스트 결과는 내가 적을 수 있도록 빈칸으로 둡니다.
- 7줄을 넘기지 않습니다.
- 위험하거나 확인이 필요한 부분은 마지막 줄에 질문으로 적습니다.

출력 형식:
1. 목적:
2. 사용자에게 보이는 변화:
3. 핵심 파일:
4. 테스트:
5. 위험:
6. 스크린샷:
7. 리뷰 질문:

git diff:
```diff
[여기에 git diff 붙여넣기]


이 프롬프트의 핵심은 "좋은 PR 설명"을 요청하지 않는 것입니다. 원하는 줄 수와 항목을 고정합니다. 그러면 AI가 긴 배경 설명을 만들기보다, 리뷰어가 읽을 수 있는 초안을 냅니다.

## 마지막 30초에는 리뷰어에게 원하는 답을 정합니다

PR 설명의 마지막 줄은 리뷰어에게 묻는 질문입니다. "확인 부탁드립니다"만 쓰면 리뷰어는 전체를 훑어야 합니다. 초보자가 더 잘 쓸 수 있는 질문은 구체적입니다.

```text
리뷰 질문: auth.ts의 오류 분기 위치가 적절한지 먼저 봐 주세요.

또는 화면 변경이 중심이면 이렇게 씁니다.

리뷰 질문: 로그인 실패 메시지가 너무 늦게 보이는지 UX 관점에서 봐 주세요.

AI가 만든 코드에서 특히 조심할 질문은 세 가지입니다.

이 변경이 너무 많은 파일을 건드렸는가.
실패 케이스 처리가 빠졌는가.
테스트가 실제 사용자 흐름을 덮고 있는가.

리뷰 질문은 약점을 숨기는 문장이 아닙니다. 리뷰어가 시간을 어디에 써야 하는지 정하는 문장입니다. 질문이 없으면 리뷰는 전체 점검이 되고, 질문이 있으면 필요한 피드백으로 좁아집니다.

그대로 붙여 넣는 7줄 PR 설명 템플릿

아래 템플릿을 PR 설명 칸에 먼저 붙여 넣고 빈칸을 채웁니다. 7줄을 넘겨도 되지만, 첫 PR 설명은 짧게 유지하는 편이 리뷰가 쉽습니다.

목적: [사용자가 겪던 문제와 해결 결과를 한 줄로]
사용자 변화: [화면, API 응답, 입력 흐름 중 무엇이 달라졌는지]
핵심 파일: [리뷰어가 먼저 볼 파일 1~3개]
테스트: [실행한 명령과 통과/실패 결과]
위험: [AI가 건드린 범위 중 불안한 부분 또는 확인 필요 없음]
스크린샷: [있음/없음, 화면 변경이면 첨부 위치]
리뷰 질문: [리뷰어에게 가장 먼저 봐 달라는 한 가지]

예시는 이렇게 채울 수 있습니다.

목적: 로그인 실패 시 빈 화면으로 멈추던 문제를 에러 메시지 표시로 바꿨습니다.
사용자 변화: 비밀번호가 틀리면 입력창 아래에 실패 메시지가 보입니다.
핵심 파일: app/login/page.tsx, src/lib/auth.ts, tests/login-error.test.ts
테스트: npm run test 통과, npm run build 통과
위험: 인증 로직 자체는 바꾸지 않았고 실패 표시 흐름만 바꿨습니다.
스크린샷: 실패 메시지 화면 1장 첨부했습니다.
리뷰 질문: auth.ts의 오류 분기 위치가 적절한지 먼저 봐 주세요.

이 정도면 리뷰어는 어디부터 볼지 압니다. PR 설명은 코드를 포장하는 글이 아니라, 리뷰가 시작되는 길잡이입니다. AI가 만든 코드일수록 더 길게 설명하기보다 목적, 파일, 테스트, 위험, 질문을 보이게 두는 것이 먼저입니다.

참고 출처

GitHub Docs, Helping others review your changes: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/helping-others-review-your-changes
GitHub Docs, Creating a pull request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
GitHub Docs, Reviewing changes in pull requests: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests
OpenAI API Docs, Prompt engineering: https://developers.openai.com/api/docs/guides/prompt-engineering

AI가 고친 코드 PR, 리뷰어가 바로 보는 7줄 설명법