Claude Code로 코드 리뷰를 운영하기 — 「작성하게 하는 것」뿐만 아니라 「검토받는」 사용법

Claude Code를 「코드를 작성하게 하는 상대」로만 사용하고 계시지는 않습니까? 사실 또 하나의 강력한 사용법이 있습니다. 바로 코드 리뷰(Code Review) 역할입니다.

• 1인 개발이라 내 코드를 리뷰해 줄 사람이 없다
• 리뷰를 부탁하고 싶지만, 상대방의 시간을 뺏는 것이 미안하다
• 셀프 리뷰(Self-review)는 하고 있지만, 자신의 실수는 스스로 알아차릴 수 없다
• 리뷰 관점(보안, 테스트 누락, 에러 핸들링)을 매번 망라할 자신이 없다

이럴 때 Claude Code를 리뷰 역할로 돌리면, **작성 전·작성 후 모두에서 「또 하나의 눈」**을 얻을 수 있습니다. 이 기사에서는 리뷰 운영의 구체적인 방법을 정리합니다.

단순히 "이 코드를 리뷰해 줘"라고 부탁하면, 별다른 내용 없는 일반론적인 답변이 돌아오기 쉽습니다. 리뷰의 질은 관점을 명시하는 것으로 크게 달라집니다.

공식 문서에서도 리뷰용 스킬의 예로 다음과 같은 관점이 언급되어 있습니다.

리뷰에서 살펴봐야 할 관점 (예)
├─ 코드의 구성·구조
├─ 에러 핸들링 (Error Handling)
...

즉, "무엇을 봐주길 원하는지"를 먼저 전달하는 것이 요령입니다. 다음과 같이 요청하면 막연한 리뷰가 구체적으로 변합니다.

이 변경 사항을 리뷰해 줘. 특히 다음 관점에서 봐줘:
① 에러 핸들링 (Error Handling) 누락
② 입력값의 유효성 검사 (Validation) 부족
...

리뷰에서 가장 효과적인 것은 「변경한 부분만」으로 좁히는 것입니다. 프로젝트 전체를 읽게 하면 토큰 소비도 늘어나고 논점도 흐려집니다.

변경 내용에 집중하게 하려면, 커밋되지 않은 차이점(diff)을 보여주는 것이 간편합니다.

git diff 내용을 리뷰해 줘.
변경한 부분에만 집중해서, 추가·수정한 코드에
버그나 놓친 부분이 없는지 확인해 줘. 기존 코드에 대한 일반론은 필요 없어.

공식 문서에는 "커밋되지 않은 변경 사항을 요약하고 리스크를 파악한다"는 스킬 예시가 있으며, 프론트매터(Frontmatter) 내에서 !git diff HEAD와 같이 차이점을 가져온 후, 리스크(에러 핸들링 누락, 하드코딩된 값, 업데이트가 필요한 테스트)를 지적하도록 하는 구성이 제시되어 있습니다. 이를 모방하여, 차이점을 전달하고 관점을 붙여 리뷰를 시키는 것이 기본 형태입니다.

리뷰는 코드가 완성된 후에만 하는 것이 아닙니다. 구현에 들어가기 전에 방침을 리뷰하게 하면 재작업(rework)을 근본적으로 줄일 수 있습니다.

사용자 등록 기능을 구현하고 싶어. 아직 코드는 쓰지 마.
먼저 구현 방침을 불렛 포인트로 작성하고, 그 방침 자체의 문제점
(보안, 확장성, 기존 설계와의 정합성)을 스스로 지적해 줘.
...

"만들기 전에 스스로 지적도 하게 하면", 명백한 설계 실수를 착수 전에 없앨 수 있습니다. 작성한 뒤에 리뷰하는 것보다 훨씬 적은 비용으로 수정할 수 있습니다.

같은 대화 맥락 속에서 "작성한 본인이 그대로 자기 채점을 한다"고 하면, 아무래도 관대해지기 마련입니다. 더 엄격하게 보고 싶을 때는, 리뷰를 별도의 문맥에서 수행하게 하는 것이 효과적입니다.

이 차이점을, 이 코드를 처음 보는 리뷰어로서 엄격하게 봐줘.
"자신이 작성한 것"이라는 전제는 버리고,
받아들일 수 없는 점이나 질문하고 싶은 점을 사양 말고 제기해 줘.

"작성자"가 아니라 "처음 보는 리뷰어"라는 입장을 명시하는 것만으로도 지적의 날카로움이 달라집니다. 구현 과정에서 길게 이어졌던 대화는 한 번 /clear를 한 뒤, 차이점만 전달하여 리뷰를 시키면 더욱 객관적인 시각을 가질 수 있습니다.

리뷰는 지적하는 것으로 끝내면 아깝습니다. 지적 → 수정 → 재리뷰까지 순환시켜야 합니다. 다만 한꺼번에 전부 수정하게 하지 않는 것이 요령입니다.

방금 언급한 지적 사항 중 ①과 ②만 먼저 수정해 줘.
③(설계와 관련된 지적)은 영향 범위가 크니까,
수정하기 전에 어떻게 수정할지 방침을 먼저 제시해 줘. 확인한 후에 착수해.

경미한 지적은 모아서 수정하고, 설계와 관련된 무거운 지적은 방침 확인 단계를 거칩니다. 이 선을 그어두면 리뷰 결과를 안전하게 반영할 수 있습니다.

단계	할 일	요령
1. 설계 리뷰	착수 전에 방침을 내놓게 하고, 문제점도 스스로 지적하게 함	쓰기 전에 없앤다
2. 차이점 리뷰	git diff로 한정하고, 관점을 전달하여 리뷰	변경 사항에만 집중
3. 객관적 리뷰	「처음 보는 리뷰어」로서 엄격하게 보게 함	/clear 하여 입장을 바꿈
4. 반영	경미한 것은 모아서 수정, 무거운 것은 방침 확인을 거침	한꺼번에 전부 수정하지 않음

편리한 한편, Claude Code의 리뷰가 만능은 아닙니다.

• 지적이 항상 옳은 것은 아니다. 빗나간 지적도 섞여 있다
• 도메인 특유의 업무 규칙이나 명문화되지 않은 전제는 파악하지 못할 때가 있다
• 「문제 없음」이라는 답변이 돌아오더라도, 그것이 안전을 보장하는 것은 아니다

리뷰는 어디까지나 놓치는 부분을 줄이기 위한 보조입니다. 최종적인 판단과 책임은 인간 측에 있다는 전제하에 사용하면, 과신으로 인한 사고를 피할 수 있습니다. 관점을 전달하여 셀프 리뷰 (Self-review)의 정밀도를 끌어올리는 정도의 거리감이 적당합니다.

• Claude Code는 「작성 대상」뿐만 아니라 「리뷰 역할」로도 사용할 수 있다
• 리뷰는
  • 관점을 명시하면 질이 올라간다 (에러 핸들링 (Error handling), 보안 (Security), 테스트 누락 등)
  • 차이점 (git diff) 에 집중하고, 착수 전의 설계 리뷰 (Design review) 도 조합하면 재작업이 줄어든다
  • 지적 사항은 경미함과 무거움을 나누어 반영한다. 최종 책임은 인간 측에 둔다

우선은 **「git diff를 관점과 함께 리뷰하게 하기」**부터 시작해 보세요. 혼자 하는 개발이라도 「또 하나의 눈」이 생기는 것만으로도, 놓치는 부분에 대한 체감이 상당히 달라집니다.

리뷰 관점이나 개발 진행 방식은 CLAUDE.md나 스킬 (Skill) 에 형식을 작성해 두면, 매번 처음부터 지시하지 않아도 됩니다. 제가 사용하고 있는 스킬을 무료로 공개하고 있습니다.

무료 스타터 (GitHub · CC BY 4.0):

CLAUDE.md 설계 · 계획 우선 개발 (PIV, Plan-First Development) · AI 커밋 전략 · 애자일한 프롬프트 설계의 4가지 스킬이 일본어와 영어로 포함되어 있습니다. 계획 우선 개발 (PIV)은 「착수 전 리뷰」의 사고방식과 궁합이 좋으므로, 설계 리뷰를 습관화하는 토대로 사용할 수 있습니다. 우선 무료 리포지토리 (Repository) 에서 시도해 보세요.

최신 팁은 X에서도 발신하고 있습니다: @k___n___t_1125