Claude에 "코드 리뷰해줘"만 입력하는 당신을 위한 프롬프트 작성법

AI 코드 리뷰 도구들이 보편화되면서 많은 개발자들이 활용하고 있지만, 정작 리뷰 품질에 대한 불만도 함께 증가하고 있습니다. "쓸데없는 지적만 잔뜩", "실제 버그는 못 찾고", "이미 고려한 부분을 또 지적" 같은 경험, 한 번쯤 있으시죠?

문제의 핵심은 AI가 부족한 게 아니라 컨텍스트가 부족하다는 점입니다. 이 글에서는 AI 리뷰의 정확도를 실질적으로 높이는 방법을 정리했습니다.

---

1. Intent + Decisions 섹션 제공하기

AI는 코드만 보고서는 왜 이렇게 작성했는지 알 수 없습니다. 의도와 설계 결정을 명시하면 리뷰 품질이 급격히 개선됩니다.

템플릿 구조

## Intent
이 변경의 목적: [무엇을 왜 바꾸는지]

## Decisions
- A 대신 B를 선택한 이유
- 알고 있는 한계점
- 의도적으로 처리하지 않은 케이스

실제 예시

## Intent
사용자 검색 API의 응답 속도를 개선하기 위해 Elasticsearch 도입

## Decisions
- Redis 대신 ES를 선택한 이유: 전문 검색(fuzzy matching) 필요
- 알고 있는 한계점: 실시간 동기화 아닌 5초 지연 허용
- initial indexing 비용은 배치로 주말에 처리 예정

이렇게 컨텍스트를 주면 AI가 "왜 캐시 안 써요?" 같은 이미 고려된 사항을 반복 지적하는 일이 줄어듭니다.

---

2. 리뷰 범위를 명시적으로 지정하기

막연한 요청은 막연한 답변을 낳습니다. 무엇을 중점적으로 볼지 구체적으로 지정하세요.

❌ 나쁜 요청 ✅ 좋은 요청

"이 코드 리뷰해줘"	"N+1 쿼리 문제와 엣지케이스 중심으로 봐줘"
"어때?"	"OWASP Top 10 보안 취약점 관점에서 리뷰해줘"
"개선점 있을까?"	"동시성 이슈와 race condition 위주로 검토해줘"

자주 쓰이는 리뷰 포커스

• 로직 오류: 경계값 처리, null 처리, 예외 상황
• 성능: N+1 쿼리, 불필요한 반복문, 메모리 누수
• 보안: SQL Injection, XSS, 인증/인가 누락
• 가독성: 네이밍, 함수 분리, 주석 필요성
• 테스트 커버리지: 누락된 테스트 케이스 식별

---

3. 관련 파일도 함께 제공하기

변경된 파일만 던져주면 AI는 전체 그림을 볼 수 없습니다. 다음 파일들을 함께 제공하면 정확도가 크게 향상됩니다:

• 호출하는 쪽 코드: 이 함수가 어떻게 사용되는지
• 유사한 기존 구현체: 프로젝트의 기존 패턴 참고
• 관련 테스트 코드: 어떤 케이스를 이미 커버했는지
• 설정 파일: 환경변수, DB 스키마 등

예시

## 변경 파일
- src/services/payment.service.ts (새로 작성)

## 참고 파일
- src/services/order.service.ts (유사한 트랜잭션 처리 패턴)
- src/controllers/payment.controller.ts (이 서비스를 호출하는 컨트롤러)
- tests/payment.test.ts (작성한 테스트)

이렇게 하면 AI가 프로젝트의 컨벤션을 이해하고, 기존 코드와의 일관성도 검토할 수 있습니다.

---

4. 불확실한 지적은 질문 형태로 받기

AI는 때때로 확신 없이 지적합니다. 하지만 단정적으로 표현하면 개발자는 이를 진짜 문제로 오해하게 됩니다.

효과적인 요청 방법

"확실하지 않은 부분은 '이 부분은 X가 맞나요?' 형태로 질문으로 알려줘."

비교

• ❌ "이 코드는 race condition이 발생합니다" → 개발자가 검증해야 할 부담
• ✅ "동시 요청 시 race condition 가능성이 있지 않나요?" → 검토 유도

이 방식으로 **false positive(오탐)**를 줄이고, AI와 개발자 간 신뢰를 높일 수 있습니다.

---

5. 실전 통합 템플릿

위의 모든 원칙을 조합한 실전 템플릿입니다:

다음 코드 리뷰해줘.

## Intent
[변경 목적과 배경]

## Decisions
- [주요 설계 결정 이유]
- [알고 있는 트레이드오프]
- [의도적으로 미처리한 부분]

## 리뷰 포커스
- 로직 오류 및 엣지케이스
- 성능 문제 (특히 N+1 쿼리)
- 보안 취약점 (OWASP 기준)

## 관련 파일
- 변경: src/services/user.service.ts
- 참고: src/services/auth.service.ts, tests/user.test.ts

확실하지 않은 부분은 질문 형태로 알려줘.

---

6. Claude Code의 /review 기능 활용하기

Claude Code를 사용한다면 내장된 리뷰 명령어를 활용하세요:

• /review: 현재 브랜치의 변경사항 자동 분석
• /ultrareview <PR번호>: GitHub PR에 대한 심층 멀티에이전트 리뷰

이 기능들은 git diff를 자동으로 읽고, 변경된 파일들의 컨텍스트를 스스로 수집하기 때문에 위에서 설명한 "관련 파일 제공"을 자동화할 수 있습니다.

---

7. 피드백 루프 만들기

AI 리뷰의 품질은 지속적인 피드백으로 개선됩니다. 리뷰 후 다음을 기록하세요:

• ✅ 실제 버그였던 지적: "nullable 체크 누락 → NPE 발생 가능" → 반영
• ❌ 오해였던 지적: "중복 코드"라고 했지만 의도적 분리 → 피드백
• 🤔 애매했던 지적: "성능 이슈 가능성" → 측정 후 판단

본인의 리뷰 반영률을 추적하면서, 어떤 유형의 요청이 좋은 리뷰를 이끌어내는지 패턴을 찾아가는 것이 중요합니다.

---

검증 및 추가 고려사항

맥락 윈도우 제한

대부분의 AI는 한 번에 처리할 수 있는 토큰(텍스트) 양에 제한이 있습니다. 대규모 PR은 여러 번 나눠서 리뷰하거나, 파일 단위로 쪼개서 요청하는 것이 효과적입니다.

할루시네이션(Hallucination) 주의

AI는 존재하지 않는 라이브러리 메서드나 잘못된 베스트 프랙티스를 제안할 수 있습니다. 특히 최신 프레임워크나 마이너 라이브러리에서 자주 발생하므로, 리뷰 결과를 맹신하지 말고 공식 문서로 교차 검증하세요.

도메인 지식 전달

비즈니스 로직이 복잡한 경우, 도메인 용어와 규칙을 간단히 설명해주면 도움이 됩니다:

## Domain Context
- "정산"은 매월 1일 00:00에 자동 실행
- "파트너사"는 최대 3개까지만 등록 가능
- 환불은 구매 후 7일 이내만 가능

---

마치며

AI 코드 리뷰는 도구입니다. 망치가 좋다고 집이 저절로 지어지지 않듯, 컨텍스트를 얼마나 잘 제공하느냐에 따라 결과물의 질이 달라집니다.

오늘 소개한 방법들을 적용하면 AI 리뷰의 정확도를 체감 가능한 수준으로 끌어올릴 수 있습니다. 특히 Intent + Decisions 명시, 리뷰 범위 지정, 질문 형태 요청은 바로 적용 가능한 실전 팁이니 다음 코드 리뷰 때 꼭 시도해보세요.

---

참고 링크

• AI 리뷰를 신뢰할 수 있을까요?