한국어 코드 리뷰: diff를 읽고 우리 팀 말투로 코멘트를 남기는 법

리뷰가 영어 템플릿에 끌려가는 문제#

리뷰 코멘트가 영어로 나오면 읽는 사람이 한국어로 다시 해석해야 합니다. "This could lead to a null pointer exception"이 아니라 "여기서 null이 들어오면 죽습니다"가 훨씬 빠릅니다. 한국어 팀에서는 리뷰 코멘트도 한국어로 남기는 것이 좋습니다.

문제는 생성된 코멘트를 그대로 PR에 붙이는 일입니다. 틀린 지적이 섞이면 리뷰어의 신뢰가 떨어집니다. 이 페이지에서는 생성 → 분류 → 한국어로 다듬기 → 사람이 거르기 순서로 작업합니다. 목표는 완전 자동 리뷰가 아니라, 우리 팀 말투로 된 리뷰 초안을 빠르게 만드는 것입니다.

검토 범위	명령과 범위	확인할 점
커밋 전	`mirr review` (v0.6.15): 먼저 `git diff HEAD`; 결과가 비면 `git diff --cached`	스테이징·미스테이징 변경을 각각 모두 보여 주는 것은 아님; 비추적 파일 제외. 범위와 한계 자세히 보기
브랜치	`mirr review --base main`: 분기점부터 현재 커밋까지	커밋하지 않은 수정은 포함되지 않음
특정 커밋	`mirr review --commit HEAD`: 해당 커밋의 변경	비교 대상이 의도한 커밋인지 확인

범위는 Mirr 코드 리뷰 문서에 따른 것입니다. main은 예시이므로 실제 기준 브랜치를 확인하세요.

검토할 변경과 한국어 리뷰 기준을 정합니다. 실행 전 선택한 diff와 저장소 문맥이 설정된 모델 제공자에게 전달될 수 있음을 확인하세요. 조직이 승인한 민감하지 않은 합성 콘텐츠를 사용하고 비밀 정보를 제거한 뒤 제공자의 데이터 보관 정책을 확인합니다.
비교 범위를 고르고 mirr review를 실행하기 전에 샌드박스와 파일·명령·네트워크 권한을 설정하고 적용 여부를 확인합니다. Mirr v0.6.15의 일회성 CLI 리뷰 경로에는 실행 중 개별 승인 게이트가 없으므로 승인 요청이 나타난다고 가정하지 마세요. 대화형 작업에서 승인 요청이 나타나는 경우의 확인 방법은 도구와 권한을 참고하세요.
결과의 파일 위치와 실제 diff를 대조하고, 가능한 지적은 재현과 테스트로 확인합니다.
민감 정보와 잘못된 지적을 제외한 뒤 사람이 PR 코멘트 게시를 결정합니다.

대화에서 “리뷰만 해 줘”라고 요청하는 것은 읽기 전용 권한을 강제하지 않습니다. 필요한 경우 운영체제와 서비스 권한도 제한하세요. 외부 서비스에 게시한 내용은 복구로 자동 취소되지 않습니다.

리뷰 기준을 REVIEW.md로 먼저 고정하기#

리뷰 기준을 파일로 고정하지 않으면 생성 결과가 매번 달라집니다. 프로젝트 루트에 REVIEW.md를 만들고 어떤 것을 보고 어떤 말투로 말할지 적습니다.

# REVIEW.md

## 보는 것
- 버그: null, 경계값, 비동기 누락, 타입 불일치
- 일관성: 기존 코드와 다른 에러 처리, 네이밍, 로그 형식
- 테스트: 재현 테스트가 없는 변경, 실패하는 테스트

## 말투
- 한국어, 존경하지만 딱딱하지 않게
- "왜 이렇게 바뀌었는지"를 먼저 설명
- 명령보다 제안: "~하면 어떨까요?"

## 하지 않을 것
- 스타일만 지적하지 않기
- 테스트 없는 추측성 버그 지적하지 않기

이 파일은 팀이 리뷰 기준을 공유하기 위한 예시입니다. REVIEW.md가 자동으로 읽히는지는 확인되지 않았으므로 파일만 만들어 두고 반영되었다고 가정하지 마세요. 필요한 기준을 리뷰 요청에 직접 포함하고 실제 결과를 확인하세요. 민감한 정보는 요청이나 공개 코멘트에 넣지 않습니다.

`mirr review`로 커밋 전 변경 범위 잡기#

실행 전 선택한 diff와 저장소 문맥이 설정된 모델 제공자에게 전달될 수 있습니다. 조직이 승인한 민감하지 않은 합성 콘텐츠를 사용하고 비밀 정보를 제거한 뒤 제공자의 데이터 보관 정책을 확인하세요. 변경 사항을 커밋하기 전에 mirr review를 실행할 수 있습니다.

mirr review

Mirr v0.6.15의 기본값은 먼저 git diff HEAD로 추적 파일의 HEAD 대비 작업 트리 순 차이를 가져옵니다. 스테이징한 변경을 미스테이징 상태에서 되돌리면 두 변경이 상쇄되어, 다른 순 차이가 남아 있는 경우 해당 스테이징 변경이 보이지 않을 수 있습니다. 이 버전은 git diff HEAD 결과가 비어 있을 때 git diff --cached로 다시 확인합니다. 추적되지 않은 새 파일은 두 비교에 포함되지 않습니다. 스테이징·미스테이징 diff 전체를 각각 별도로 살펴보고 비추적 파일도 확인하세요. 특정 브랜치나 커밋을 지정할 수도 있습니다.

mirr review --base main
mirr review --commit HEAD

브랜치 기준 비교에는 커밋하지 않은 수정이 포함되지 않습니다. 무엇을 리뷰할지 먼저 확인하는 일이 중요합니다. 다음 코드 블록은 이 글의 작업에서 실행하지 않은 참고용 CLI 도움말 텍스트입니다. 들여쓰기만 공백으로 통일했으며 실제 리뷰 출력은 아닙니다.

$ mirr --version
mirr v0.6.15
$ mirr review --help
Usage of review:
  -base string
        base branch/commit to diff against (defaults to HEAD — reviews uncommitted working-tree changes)
  -commit string
        review a specific commit (shows changes introduced by that commit)
  -instructions string
        extra review instructions appended to the prompt
  -model string
        provider name override (default: config default_model)

도움말의 -instructions는 추가 지시를 설명하지만, REVIEW.md 자동 로딩이나 특정 결과를 입증하지 않습니다. 설치 버전에 따라 도움말이 다를 수 있습니다.

Mirr v0.6.15의 internal/cli/review.go 구현에서는 선택한 diff가 16,000바이트를 넘으면 앞부분 16,000바이트만 리뷰 요청에 넣는다는 주장이 있으나 미확인입니다. 이 저장소에는 해당 소스와 실행 기록이 없습니다. 다른 버전에서는 다를 수 있습니다. 큰 변경은 검토 가능한 단위로 나누고 전체 스테이징·미스테이징 diff를 사람이 따로 확인하세요. 나눈 뒤에도 각 diff가 한도 안에 있는지 살펴야 합니다.

PR 리뷰 자동화: CI 실행과 게시 권한 나누기#

PR 리뷰 자동화는 PR 이벤트와 실행 대상 커밋을 고정하고, 코드 검사·모델 리뷰·댓글 게시의 권한을 나누는 작업입니다. 이 절의 설계·검증 절차는 GitHub Actions로 구성할 때의 것이지 이 저장소에서 실행한 워크플로가 아닙니다. Mirr의 무인 인증·종료 코드·CI 실행은 아직 검증하지 않았으므로 해당 부분을 확인하기 전에는 자동 게시를 켜지 마세요.

단계	구성할 범위	넘기면 안 되는 권한·자료
PR 검사	`pull_request` 이벤트, 대상 base/head SHA와 테스트 범위 기록. 토큰은 필요한 읽기 권한부터 시작	PR 제목·본문을 셸 코드로 직접 삽입하거나 필요 없는 비밀값 제공
모델 리뷰	조직이 허용한 diff만 전달하고 설치 버전·비대화형 인증·예산·타임아웃 확인	검토되지 않은 fork 코드를 모델 자격 증명이 있는 환경에서 실행
결과 보관	대상 SHA, 파일 위치·근거·미실행 검사와 가린 출력을 정해진 형식으로 보관	외부 리뷰 텍스트를 실행 가능한 스크립트로 취급
게시	신뢰한 게시 코드에서 PR·SHA·검토된 내용과 선택 API의 최소 쓰기 권한 확인	검사 작업에 게시 권한까지 한꺼번에 부여

이벤트가 PR의 head 자체인지 테스트용 merge commit인지 정하고, base/head와 실제 checkout SHA를 기록합니다. 비교에 필요한 기준 이력도 가져오도록 구성하세요. 로컬 기본 리뷰는 PR 범위를 자동으로 뜻하지 않으므로 위 --base·--commit의 실제 비교 범위와 맞춥니다.
기본 검사 작업은 최소 GITHUB_TOKEN 권한과 비밀값 없는 환경에서 구성합니다. GitHub는 fork PR의 pull_request에 기본적으로 읽기 전용 토큰과 비밀값 제한을 적용합니다. 조직·저장소 정책도 확인하고, 자격 증명이 없는 경로에서는 외부 모델 리뷰를 건너뛰었다고 기록하세요.
승인된 모델 리뷰 경로를 별도로 설계합니다. 비대화형 인증·설치 버전·종료 코드가 확인된 경우에만 실행하고 실패·시간 초과·빈 출력은 리뷰 통과로 취급하지 않습니다. 같은 저장소의 PR도 신뢰할 수 없는 코드를 포함할 수 있습니다. REVIEW.md의 자동 적용을 가정하지 말고 필요한 기준을 실제 요청에 전달합니다.
먼저 CI 결과만 사람이 확인하는 방식으로 운영합니다. 게시를 추가할 때는 신뢰한 코드에서 저장소·PR 번호·현재 head SHA가 결과 기록과 같은지, 코멘트가 민감정보를 포함하지 않는지 확인한 뒤 승인합니다. 외부 산출물의 형식·길이를 검증하고 중복 게시도 막으세요.
PR이 새 커밋으로 바뀌거나 인증·검사가 실패하면 이전 리뷰를 최신 결과로 게시하지 않습니다. 게시 권한과 토큰 회수, 잘못 게시한 댓글의 서비스 측 수정·삭제 절차를 따로 검토합니다.

pull_request_target으로 바꾸고 PR 코드를 checkout·실행해 비밀값 제한을 우회하지 마세요. 권한 있는 workflow_run도 다른 작업의 산출물을 신뢰할 수 있는 실행 코드로 취급하면 위험합니다. 근거: GitHub Actions 이벤트, GITHUB_TOKEN 권한, 신뢰할 수 없는 코드와 Actions 보안, pull_request_target 보안(2026-11-02 문서 확인). 실제 Mirr CI 인증·실행, 검토 후 게시와 실패·재실행 출력은 여전히 필요한 별도 증거입니다.

코멘트 구조: 버그·일관성·테스트 3분류#

생성된 코멘트를 그대로 쓰지 말고, 세 가지로 나눕니다.

분류	보는 것	예시
버그	실제로 깨지는 부분	null, 경계값, 비동기 누락, 잘못된 타입
일관성	기존 코드와 다른 처리	에러 처리 방식, 네이밍, 로그 형식, import 순서
테스트	검증이 빠진 부분	재현 테스트가 없는 변경, 실패하는 테스트, 경계값 누락

버그는 재현 가능한 것만 남기고, 일관성은 팀 규칙과 맞는지 확인하고, 테스트는 실제로 돌려 봅니다. 이 분류가 있으면 생성된 코멘트를 빠르게 걸러낼 수 있습니다.

한국어 말투와 팀 용어 사전 만들기#

생성된 코멘트를 한국어로 다듬을 때는 팀에서 쓰는 용어를 먼저 정합니다.

# 우리 팀 용어
- "죽습니다" 대신 "끊깁니다"
- "널" 대신 "null"
- "에러" 대신 "오류"
- "이슈" 대신 "문제"

예를 들어, 생성된 코멘트가 "This may cause an error"라면, 우리 팀 말투로는 "여기서 오류가 날 수 있어요"로 바꿉니다. "Fix the bug"보다 "이 부분을 고치면 어떨까요?"가 낫습니다.

중요한 것은 생성된 문장을 그대로 쓰지 않고, 우리 팀이 실제로 말하는 방식으로 바꾸는 일입니다. REVIEW.md에 적은 기준은 요청에 직접 전달하거나 사람이 검토할 때 참고하세요.

PR에 붙이기 전 사람이 거르는 체크리스트#

생성된 코멘트를 PR에 붙이기 전에 사람이 한 번 거릅니다.

지적이 실제로 재현되는가?
버그·일관성·테스트 3분류로 나눴는가?
한국어 말투가 우리 팀과 맞는가?
테스트를 실행했는가?
틀린 지적은 뺐는가?
변경이 작고 리뷰 가능한가?

이 체크리스트를 통과한 코멘트만 PR에 붙입니다. 생성된 코멘트를 그대로 붙이는 것보다 훨씬 신뢰가 높아집니다.

리뷰 후 검증: 테스트와 재현 절차#

리뷰 코멘트가 맞는지 확인하려면 테스트가 필요합니다.

테스트 방법과 선택 옵션은 저장소의 테스트 도구에 따라 다릅니다. 프로젝트 안내를 확인하고 부작용을 살핀 뒤 관련 테스트를 실행하세요. 테스트가 없다면 재현 테스트를 작성해 확인할 수 있습니다. 여기에는 실제 리뷰 지적이나 테스트 실행 결과가 아직 없으므로 통과 여부를 주장하지 않습니다.

리뷰 후에는 다음을 확인합니다.

지적한 버그를 재현 테스트로 확인했는가?
고친 후에도 테스트가 통과하는가?
코멘트가 실제 변경과 맞는가?
다음에도 같은 지적이 나오는가?

리뷰가 필요 없는 변경#

다음과 같은 작은 변경은 AI 리뷰 대신 사람이 직접 검토하는 방식을 고려할 수 있습니다. 테스트만 추가하는 변경도 오류나 위험이 있을 수 있으므로 팀의 리뷰 정책을 따르세요.

오타와 주석 수정
포맷터가 바꾼 자동 변경
테스트만 추가하는 변경
한 파일 안의 작은 이름 변경

변경의 크기보다 위험과 팀의 기준에 맞춰 검토 깊이를 정하세요.

근거가 있는 한국어 코멘트로 바꾸는 예#

다음은 실제 PR에서 나온 결과가 아닌 편집 예시입니다. “This might break pagination”만 적으면 작성자는 어느 입력이 문제인지 다시 물어야 합니다. “마지막 페이지에서 다음 페이지 토큰이 비어 있는데도 요청을 한 번 더 보내는 경로가 있습니다. 빈 토큰을 받았을 때 멈추는 테스트를 추가하면 어떨까요?”처럼 조건, 현재 코드의 동작, 사용자 영향과 확인 방법을 나누세요. 해당 경로를 아직 재현하지 않았다면 “있습니다” 대신 “이 분기가 호출되는지 확인이 필요합니다”라고 적어야 합니다.

팀 말투를 맞춘다고 확신의 강도를 바꾸면 안 됩니다. 가능성을 확인된 결함처럼 쓰거나 필수 보안 수정을 취향 제안처럼 낮추면 리뷰 의미가 달라집니다. 파일 위치와 비교 커밋을 붙이고, 재현한 입력이 있으면 비식별 형태로 남기세요. 줄 번호는 새 커밋에서 달라질 수 있으므로 함수 이름과 지적한 분기도 함께 적는 편이 유용합니다. 작성자의 의도를 추측하거나 사람을 평가하는 문장 대신 변경된 코드의 관찰과 요구사항 차이를 설명합니다.

리뷰 초안의 항목 수가 많아도 좋은 리뷰라는 뜻은 아닙니다. 같은 원인을 여러 파일에서 반복 지적했다면 대표 위치와 영향 범위를 묶어 전달하세요. 반대로 서로 다른 권한 결함을 “보안 개선 필요” 한 문장으로 합치면 수정 여부를 확인하기 어렵습니다. 게시 전에 각 코멘트가 독립적으로 행동 가능한지, 실제 변경 범위에 속하는지, 이미 해결된 내용을 반복하는지 검토합니다. 사람의 검토와 실제 테스트 없이 코멘트를 생성한 사실만으로 PR이 검증됐다고 표시하지 마세요.

줄 단위 코멘트와 일반 코멘트를 구분하기#

GitHub 안내는 리뷰 코멘트를 diff의 한 줄에 달 수 있고, 여러 줄을 선택해 범위로 달 수도 있다고 설명합니다(GitHub 코멘트 안내). 한국어로 옮긴 지적을 게시할 때 일반 PR 댓글인지 특정 줄에 붙는 리뷰 댓글인지 구분하지 않으면, 같은 문장이 파일과 무관한 위치에 남습니다. 자동 생성 문장은 파일 경로, 줄 번호, 커밋을 함께 기록한 뒤에만 게시 대상으로 넘기세요.

권한이 있는 워크플로에 넣지 말아야 할 조합#

GitHub 보안 안내는 pull_request_target과 workflow_run 트리거가 신뢰할 수 없는 PR 코드의 checkout과 함께 쓰이면 저장소가 보안 침해에 노출된다고 설명합니다(GitHub 보안 안내). 한국어 리뷰 자동화가 모델 자격 증명을 쓴다면, 검토 대상 코드를 실행하는 단계와 댓글을 게시하는 단계를 나눠야 합니다. 이 글의 CI 설계는 그 분리를 전제로 하며, 실제 워크플로 실행은 확인하지 않았습니다.

지적 문장을 세 가지 표지로 나누기#

한국어 리뷰 문장은 확인된 결함, 추정, 질문 가운데 하나로 표시하세요. 확인된 결함에는 재현 명령과 실패 출력을 붙이고, 추정에는 아직 확인하지 않은 조건을 적습니다. 질문은 작성자가 답할 수 있는 사실 하나만 묻습니다. 표지가 없는 문장은 게시 전에 작성자에게 되돌려 보냅니다. 이 기준은 이 글의 검증 절차를 옮긴 것이며 외부 자료의 권고가 아닙니다.

질문에 답이 없으면 같은 줄에 '미확인'으로 남기고, 게시 대상에서 뺍니다.

자주 묻는 질문#

리뷰 코멘트를 한국어로 만들 수 있나요?#

한국어 리뷰를 요청하고 생성된 코멘트를 팀 말투에 맞게 다듬을 수 있습니다. REVIEW.md는 팀 기준을 정리하는 예시이며 자동으로 읽히는지는 확인되지 않았습니다. 결과는 사람이 검토하세요.

리뷰에서 틀린 지적이 나오면 어떻게 하나요?#

생성된 코멘트를 그대로 PR에 붙이지 말고, 버그·일관성·테스트 3분류로 나누어 확인하세요. 틀린 지적은 빼고, 재현 테스트로 확인할 수 있는 것만 남기세요.

CI에서도 쓸 수 있나요?#

PR 이벤트의 대상 커밋을 고정하고 검사·모델 인증·게시 권한을 분리하는 설계 절차를 본문에 정리했습니다. 다만 Mirr의 CI 인증·실행·종료 코드 동작은 아직 검증하지 않았습니다. 해당 검증 전에는 자동 게시를 켜지 말고 사람이 결과를 검토하세요.

영어 코드와 한국어 주석이 섞인 저장소에서도 되나요?#

코드와 오류 메시지를 원문으로 두고 리뷰 설명을 한국어로 요청할 수 있습니다. 팀 용어는 요청에 명시하고 결과가 문맥에 맞는지 사람이 확인하세요.

리뷰만 하고 코드를 고치지는 않나요?#

리뷰만 요청할 수 있지만 요청 문구가 읽기 전용 권한을 강제하지는 않습니다. mirr review는 변경 사항을 검토하는 명령이며 해당 버전의 실행 경로와 권한을 따로 확인해야 합니다.

테스트가 없는 코드도 리뷰할 수 있나요?#

가능합니다. 다만 테스트가 없으면 지적이 정확한지 확인하기 어렵습니다. 먼저 특성화 테스트를 만들고 그다음에 리뷰를 실행하는 것이 좋습니다.

편집 메모#

편집 메모 (2026-11-02): 리뷰 요청과 읽기 전용 권한을 구분하도록 FAQ를 바로잡았습니다. 지적이 실제 코드와 다르면 비교 기준 커밋과 diff 누락·잘림부터 확인하세요. 기존 CLI 도움말은 리뷰 결과가 아닙니다. 영어 초안→한국어 코멘트 diff, 실제 리뷰 실행 화면과 지적 후 테스트 재실행 출력은 아직 없습니다. 기존 2026-10-31 표시는 전체 재검증일로 갱신하지 않았습니다.