금요일 저녁에 올라온 PR을 월요일 아침에야 열어봅니다. 변경 파일 열두 개, 500줄. 꼼꼼히 보려면 한 시간, 대충 훑고 승인하면 5분. 대부분은 후자를 고르고, 그렇게 넘어간 코드에서 3주 뒤에 장애가 납니다. AI 코드리뷰는 이 둘 사이에 있는 선택지입니다. 사람이 보기 전에 기계가 1차로 훑어서 명백한 문제를 걸러내면, 리뷰어는 설계 판단처럼 사람만 할 수 있는 곳에 시간을 쓸 수 있습니다. 이번 글에서는 실제로 쓸 만한 리뷰 프롬프트와, 그걸 명령 한 줄로 자동화하는 방법을 정리합니다.
그냥 “리뷰해줘”가 실패하는 이유
코드를 붙여넣고 “리뷰해줘”라고 하면 대부분 이런 답이 돌아옵니다. “변수명을 더 명확하게 하면 좋겠습니다”, “주석을 추가하는 것을 권장합니다”, “에러 처리를 고려해 보세요.” 틀린 말은 아니지만 어느 코드에나 해당되는 말이라서 아무 도움이 안 됩니다.
원인은 세 가지입니다.
- 맥락이 없습니다. 이 코드가 무엇을 하려는 건지, 어떤 제약이 있는지 모르면 일반론밖에 못 씁니다.
- 우선순위가 없습니다. 장애를 내는 버그와 변수명 취향이 같은 무게로 나열됩니다.
- 빈손으로 끝내는 걸 허락하지 않았습니다. “리뷰해줘”라고 하면 지적할 게 없어도 뭔가를 만들어냅니다.
아래 프롬프트들은 전부 이 세 가지를 메우는 방향으로 만들어졌습니다. 목적을 알려주고, 볼 순서를 정해주고, 없으면 없다고 말해도 된다고 허락하는 것입니다.
1. 기본 리뷰 프롬프트
가장 많이 쓰게 될 형태입니다. 붙여넣기 전에 언어와 변경 목적 두 줄만 채우면 됩니다. 이 두 줄이 결과 품질의 절반을 좌우합니다.
아래는 내가 작업한 코드 변경분(diff)이야. 코드 리뷰를 해줘.
언어/프레임워크: Python 3.11 / FastAPI
이 변경의 목적: 로그인 실패 횟수 제한 기능 추가
다음 순서로 봐줘.
1. 동작이 깨지는 버그 (있으면 재현 조건까지)
2. 예외/엣지 케이스 누락
3. 보안 문제
4. 읽기 어려운 부분
각 지적은 [파일:줄번호] 형식으로 위치를 먼저 쓰고,
왜 문제인지 한 줄, 어떻게 고칠지 한 줄로 써줘.
취향 문제(따옴표, 줄바꿈 스타일)는 언급하지 마.
---
(여기에 git diff 결과 붙여넣기)출력 형식을 [파일:줄번호]로 못 박은 게 핵심입니다. 위치를 먼저 쓰게 하면 실제 코드에 근거하지 않은 막연한 지적이 눈에 띄게 줄어듭니다. 위치를 특정할 수 없는 얘기는 애초에 쓰기 어려워지기 때문입니다.
2. 심각도로 분류시키기
지적이 열다섯 개 나와도 어디부터 볼지 모르면 결국 안 봅니다. 앞의 프롬프트 뒤에 이 블록을 덧붙이면 정리된 형태로 나옵니다.
리뷰 결과를 아래 세 단계로 분류해서 줘.
BLOCKER - 머지하면 장애가 나는 것
SHOULD - 이번에 같이 고치는 게 좋은 것
NIT - 알고만 있으면 되는 것
BLOCKER가 없으면 "BLOCKER 없음"이라고 명시해줘.
지적할 게 없는 항목은 억지로 만들어내지 마.마지막 두 줄이 실무에서 제일 중요합니다. “없으면 없다고 말해라”를 넣지 않으면 깨끗한 코드에도 억지 지적을 세 개쯤 만들어냅니다. 그런 리뷰를 몇 번 받으면 팀원들이 결과를 아예 안 읽게 됩니다.
3. 상황별 프롬프트
리뷰의 목적이 다르면 물어보는 방식도 달라져야 합니다. 자주 쓰는 네 가지입니다.
| 상황 | 프롬프트 핵심 문장 |
|---|---|
| 보안 점검 | “입력 검증, 인증/인가, 비밀정보 노출 세 가지만 봐줘. 각 항목에 대해 공격 시나리오를 한 줄로 써줘.” |
| 성능 확인 | “반복문 안에서 일어나는 DB 쿼리나 네트워크 호출이 있는지 찾아줘. 데이터가 1만 건일 때 몇 번 호출되는지 계산해줘.” |
| 남의 코드 파악 | “이 파일이 무슨 일을 하는지 5줄로 요약하고, 이 코드를 고치기 전에 알아야 할 전제 조건을 알려줘.” |
| 리팩터링 검증 | “리팩터링 전후 코드야. 동작이 달라지는 지점이 있는지만 찾아줘. 스타일 개선은 언급하지 마.” |
리팩터링 검증은 특히 효과가 좋습니다. 사람은 “같아 보이는 코드”를 대조할 때 집중력이 빨리 떨어지는데, 조건문 하나가 뒤집힌 걸 잡아내는 건 기계가 훨씬 잘합니다.
4. 명령 한 줄로 자동화하기
매번 diff를 복사해서 붙여넣는 게 번거롭다면 터미널에서 바로 넘길 수 있습니다. Claude Code CLI는 -p 옵션으로 프롬프트를 받아 결과만 출력하고 끝나므로, 파이프로 연결하면 됩니다.
# 아직 커밋하지 않은 변경분을 리뷰
git diff | claude -p "다음 diff를 리뷰해줘. 버그와 예외 누락 위주로, [파일:줄] 형식으로."
# 특정 브랜치가 main에서 갈라진 뒤의 변경분 전체를 리뷰
git diff main...HEAD | claude -p "$(cat .review-prompt.txt)"
# 결과를 파일로 남기기
git diff main...HEAD | claude -p "$(cat .review-prompt.txt)" > review.mdgit diff main...HEAD는 브랜치가 갈라진 시점 이후의 변경만 뽑아줍니다. 점 두 개(..)를 쓰면 그 사이 main에 들어온 남의 커밋까지 섞여 들어오니, 리뷰 목적이라면 점 세 개를 쓰세요.
프롬프트가 길어지면 파일로 빼두고 커밋 전에 돌리는 스크립트를 만들어 둡니다.
#!/bin/bash
# review.sh - 커밋 전 셀프 리뷰
DIFF=$(git diff --staged)
if [ -z "$DIFF" ]; then
echo "스테이징된 변경이 없습니다. git add 먼저 하세요."
exit 1
fi
echo "$DIFF" | claude -p "$(cat .review-prompt.txt)" | tee review.md
echo ""
echo "리뷰 결과를 review.md에 저장했습니다."chmod +x review.sh로 실행 권한을 준 뒤 ./review.sh로 씁니다. 윈도우라면 Git Bash나 WSL에서 그대로 동작합니다. 커밋 훅(pre-commit)에 넣고 싶은 유혹이 들지만, 리뷰는 몇십 초가 걸리는 작업이라 커밋할 때마다 기다리게 되면 곧 --no-verify로 건너뛰게 됩니다. 필요할 때 직접 부르는 편이 오래 갑니다.
5. 저장소 규칙을 기억시키기
팀마다 지적해야 할 것과 넘어가도 되는 것이 다릅니다. 매번 프롬프트에 적는 대신 저장소 루트에 CLAUDE.md를 두면 Claude Code가 자동으로 읽습니다.
# 이 저장소의 리뷰 기준
## 반드시 지적할 것
- DB 세션을 열고 닫지 않는 코드
- 사용자 입력을 검증 없이 쿼리에 넣는 코드
- 외부 API 호출에 timeout이 없는 코드
- 로그에 이메일, 전화번호, 토큰을 그대로 찍는 코드
## 지적하지 말 것
- 포매터(black)가 처리하는 스타일 문제
- legacy/ 폴더 아래 코드 (단계적으로 걷어내는 중)
## 이 프로젝트의 관례
- 예외는 app/errors.py의 정의된 클래스만 사용
- 모든 라우터 함수는 async“지적하지 말 것”을 명시하는 게 생각보다 큰 차이를 만듭니다. 포매터가 이미 처리하는 스타일 문제를 매번 다섯 줄씩 늘어놓으면, 정작 중요한 지적이 그 사이에 묻힙니다. 걷어내는 중인 레거시 폴더도 빼두지 않으면 리뷰 결과의 대부분이 그쪽 얘기로 채워집니다.
6. 리뷰에서 테스트로 이어가기
리뷰에서 “이 경우가 처리 안 됐다”는 지적이 나오면, 고치기 전에 그 상황을 재현하는 테스트부터 만드는 게 낫습니다. 다만 테스트 코드를 바로 써달라고 하면 그럴듯한데 실제로는 아무것도 검증하지 않는 테스트가 나오기 쉽습니다. 한 단계 끊어서 물어보세요.
이 함수에 대한 테스트를 짤 건데, 코드를 써주기 전에
테스트해야 할 케이스 목록을 먼저 뽑아줘.
정상 케이스 / 경계값 / 예외 상황으로 나눠서,
각 항목이 왜 필요한지 한 줄씩 붙여줘.
내가 목록을 확인하고 나면 그때 코드로 만들어줘.케이스 목록을 먼저 받으면 빠진 것과 불필요한 것을 사람이 판단할 수 있습니다. 목록 단계에서 “빈 문자열이 들어올 때”를 빼라고 하면 그만인데, 코드가 다 나온 뒤에는 지우는 것도 일이 됩니다.
주의할 점
- AI 리뷰는 승인이 아닙니다. 통과했다고 머지해도 되는 게 아니라, 사람이 볼 것을 줄여주는 도구입니다. 최종 판단은 여전히 리뷰어의 몫입니다.
- 맥락 밖의 코드는 못 봅니다. diff만 주면 그 함수를 호출하는 다른 곳에서 무슨 일이 일어나는지 모릅니다. 인터페이스가 바뀌는 변경이라면 호출부 파일도 같이 주세요.
- 사내 코드를 외부로 보내는 일입니다. 회사 규정과 계약 조건을 먼저 확인하세요. 개인 프로젝트가 아니라면 이게 첫 번째 관문입니다.
- 확신에 찬 오답이 나옵니다. 존재하지 않는 함수 이름이나 실제로는 문제없는 코드를 단호하게 지적하기도 합니다. 지적받은 줄은 직접 열어서 확인하는 습관을 들이세요.
- 긴 diff는 잘라서 주세요. 수천 줄을 한 번에 주면 앞부분만 자세히 보고 뒤로 갈수록 대충 넘어가는 경향이 있습니다. 파일 단위나 기능 단위로 나누는 편이 정확합니다.
마무리
오늘 할 수 있는 가장 작은 일은, 지금 작업 중인 브랜치에서 git diff를 뜬 뒤 이 글의 첫 번째 프롬프트에 붙여넣어 보는 것입니다. 설정할 것도 설치할 것도 없습니다. 결과에서 하나라도 건질 게 있으면 그때 review.sh를 만들고, 팀에서 반복되는 지적이 눈에 보이면 그때 CLAUDE.md에 옮겨 적으면 됩니다.
다음 글에서는 웹사이트 크롤링 시 만나는 403 Forbidden 오류의 원인과 해결법을 다룹니다. 자동화 스크립트를 짜다 보면 가장 먼저 부딪히는 벽입니다.