Claude Code에서의 코드 리뷰, 저는 리뷰용 자체 스킬을 직접 만들어 사용해 왔습니다.

그런데 얼마 전, 오랜만에 공식 /code-review를 실행해 보았더니, 지적 사항이 중요도에 따라 색깔별로 나열되어 있어 무엇부터 수정해야 할지 보는 즉시 알 수 있었습니다.

'이것만으로도 충분하지 않을까?'라는 생각이 들어, 당분간은 공식 명령어로 진행하기로 했습니다.

다만, effort 인자나 --fix, --comment와 같은 옵션을 실제로 측정한 정보는 별로 보이지 않았습니다.

그래서 개인 개발 리포지토리(Repository)의 PR(Pull Request)을 대상으로, effort의 차이, PR에 대한 코멘트 게시, 자동 수정 등을 한 차례 검증해 보았습니다.

가장 큰 결과부터 미리 말씀드리자면, 동일한 diff(차이점)라도 effort에 따라 지적 사항이 1건과 10건으로 나뉘었습니다.

/code-review의 기본 동작

/code-review는 현재 작업 중인 브랜치(Branch)의 diff를 리뷰하는 명령입니다.

대상은 'upstream에 대해 앞서 있는 커밋 + 커밋되지 않은 변경 사항'이며, 인자로 파일 경로, PR 번호, 브랜치 이름, 또는 main...my-feature와 같은 범위를 전달하면 대상을 변경할 수 있습니다.

실행하면 백그라운드에서 서브 에이전트(Sub-agent)가 작동합니다.

별도의 컨텍스트 윈도우(Context Window)를 가지기 때문에, 리뷰 중에도 손에 든 대화를 계속할 수 있으며, 완료되면 결과만 대화창에 전달됩니다.

전달된 지적 사항에는 중요도 마커가 붙습니다. 공식 문서의 정의는 이 3단계입니다.

내가 망가뜨린 부분과 원래부터 있었던 부분이 나누어져 표시되므로, 위에서부터 순서대로 해결해 나가면 되는 정렬 방식입니다.

제가 자체 스킬에서 갈아타기로 마음먹은 계기가 바로 이 표시 방식이었습니다.

검증 조건

실측을 위한 전제를 먼저 말씀드립니다.

주제는 제가 공개하고 있는 주식 스크리닝용 리포지토리인 swing-copilot의 PR이며, 기능 추가를 위한 diff로서는 제법 큰 편입니다.

횟수는 각각 1회이므로, 이후의 숫자는 모두 n=1의 실측치로 읽어주시기 바랍니다.

effort 인자의 실측 비교

/code-review에는 low / medium / high / xhigh / max의 effort를 전달할 수 있습니다.

공식 문서의 설명에 따르면, low와 medium은 '확신도가 높은 지적 사항만 보고(위양성(False Positive)이 적음)', high 이상은 '그물을 넓게 펼침(확신도가 낮은 지적 사항을 포함할 수 있음)'이라는 위치에 있습니다.

동일한 PR에 /code-review low와 /code-review high를 각각 1회씩 실행한 결과는 다음과 같습니다.

건수와 시간뿐만 아니라 실행 형태까지 달라졌습니다.

low는 하나의 백그라운드 에이전트가 빠르게 훑고 끝납니다.

반면 high에서는 Dynamic Workflow(여러 에이전트가 역할을 분담하여 병렬로 실행되는 Claude Code의 메커니즘)가 가동되어, 관점별로 여러 개의 finder와 지적 사항마다 독립적인 verifier가 동시에 작동하고 있었습니다.

high가 완료되었을 때는 "후보로 올라온 27건 중 5건은 검증 단계에서 반증되었기 때문에 보고에 포함하지 않았습니다"라는 내역까지 표시되었습니다.

보고 자체에도 건수 상한이 있으며, 남은 후보들을 랭킹화한 뒤 압축하는 구조이기 때문에 27 - 5 = 22건이 전부 전달되는 것은 아닙니다. 이번에 제 손에 전달된 것이 그 상위 10건입니다.

그물을 넓게 펼치면서 의심스러운 후보는 검증으로 걸러내고, 확신도가 높은 순으로 압축하여 보고한다는 움직임을 화면을 통해 확인할 수 있습니다.

내용의 무게감에도 차이가 있었습니다.

low가 보고한 1건은 '미래의 차이에 대비하는 방어적인 지적'으로, 현시점에서는 실질적인 해가 없는 것이었습니다.

게다가 보고된 행 번호는 :332로, 232행밖에 없는 파일에 존재하지 않는 위치였으며, 메인 세션이 정정 사항을 덧붙이는 모습도 볼 수 있었습니다.

반면 high 등급에서만 포착된 9건에는, 이번 PR에서 추가한 CLI가 읽기 전용(read-only)이라고 명시해 두었음에도 실제로는 DB에 쓰고 있었다는 지적이 포함되어 있었습니다.

이 PR에서 유입된 새로운 버그였기에, 머지(merge) 전에 잡아낼 수 있었던 것은 매우 다행스러운 일이었습니다.

참고로 low 등급의 1건은 high 등급의 10건 중에도 포함되어 있었으므로, 이번 사례에 한해서는 low가 "high의 핵심 내용만을 가장 빠르게 확인하는" 관계가 되어 있었습니다.

--comment을 통한 PR 인라인 코멘트 게시

리뷰 결과를 로컬에서 읽고 끝내는 것이 아니라, GitHub PR에 남겨둘 수도 있습니다.

--comment 옵션을 붙이면 리뷰 지적 사항이 PR의 인라인 코멘트(inline comment)로 게시됩니다.

/code-review high --comment

검증 결과, high가 보고한 10건의 지적 사항 모두가 PR의 해당 행에 인라인 코멘트로 달렸습니다 (10건 중 10건 성공).

요약(summary) 코멘트는 달리지 않고 인라인 코멘트만 생성되므로, PR의 대화 타임라인이 지저분해지지 않습니다.

동작 방식은 리뷰 완료 후 메인 세션이 대상 PR을 자동으로 감지하여, gh 명령어로 한 건씩 게시해 나가는 형태입니다.

셀프 리뷰 결과를 그대로 PR에 남겨둘 수 있으므로, "나중에 수정할 부분"을 리뷰 코멘트로 쌓아두는 방식으로 활용할 수 있습니다.

한 가지 주의할 점이 있습니다.

제 환경(권한 설정을 완화한 auto mode)에서는 확인 절차 없이 공개 PR에 게시하는 단계까지 진행되었습니다.

공개 리포지토리(public repository)에서 테스트할 때는, 지적 사항이 외부로 노출될 수 있는 곳에 남는다는 점을 염두에 두고 사용해야 합니다.

--fix를 통한 자동 수정 적용

지적 사항을 읽고 직접 수정하는 대신, 그 자리에서 바로 수정하게 만드는 선택지도 있습니다.

--fix 옵션을 붙이면 리뷰에서 발견된 지적 사항이 그대로 워킹 트리(working tree)에 적용됩니다.

/code-review high --fix

검증 결과, high가 보고한 10건이 전건 적용되었습니다. 적용 전 확인 프롬프트는 나타나지 않습니다.

즉, --fix를 붙이는 행위 자체가 "수정해도 좋다"는 의사 표시가 됩니다.

적용 방식은 제가 예상했던 "기계적인 패치 적용"보다 훨씬 정교했습니다.

• 수정과 함께 회귀 테스트(regression test)를 추가함
• lint, 테스트 스위트(1753건), 스모크 테스트(smoke test), 문서 빌드를 통과한 후 완료 보고를 함
• 10건 중 1건은 "이 동작은 설계 의도이므로 변경하지 않겠다"고 판단하여, 동작은 유지한 채 탐지 가능성(detectability) 문제만 해결함

지적 사항에 맹목적으로 따르지 않고, 설계의 맥락을 읽어 수정 방법을 선택합니다.

최종 diff는 12개 파일에 +705/−161이었습니다. 자동 커밋(auto commit)은 되지 않으므로, 내용을 확인한 후 커밋하는 흐름으로 진행됩니다.

/review · ultra와의 구분 사용

리뷰 관련 명령어로는 /code-review 외에도 /review <pr>와 /code-review ultra가 있습니다.

공식 문서의 비교표를 바탕으로 대상과 실행 방향을 정리하면 다음과 같습니다.

ultra는 클라우드 샌드박스(sandbox)에서 다수의 리뷰 에이전트를 병렬로 실행하여, 보고 전에 모든 지적 사항을 독립적으로 재현 및 검증하는 모드입니다.

소요 시간은 510분 정도이며, Pro / Max 플랜에는 1회 한정 무료 혜택이 3회 제공되고, 그 이후에는 1회당 525달러의 종량제 과금이 적용됩니다.

저는 아직 실행해 보지 않았기에, 이 부분은 공식 문서의 정보입니다.

제 개인적인 리뷰 방식은 현재 로컬에서 /code-review를 머지 전에 딱 한 번 돌리는 형태로 정착되었습니다.

요약

/code-review는 중요도에 따른 색상 구분으로 작업 순서가 결정되고, effort로 깊이를 선택할 수 있으며, --fix와 --comment를 통해 수정부터 공유까지 단 하나의 명령어로 연결됩니다.

저의 운용 방식은 앞서 언급한 바와 같이 "머지 전에 딱 한 번만 돌리는 것"입니다.

effort(노력) 수준에 무엇을 요구하느냐에 따라 다르겠지만, 실제 측정 결과 high 수준에서만 발견된 지적 사항들의 무게를 고려하면, 토큰(token)과 시간적 여유가 있다면 high를 선택해 두는 것이 안전하다고 생각합니다.

자체 스킬에서 갈아탄 방식은 당분간 더 계속해 볼 예정입니다.

X를 팔로우해 주시면 감사하겠습니다!

AI 주도 개발(특히 Claude Code)의 노하우나 팁(Tips)을 자주 발신하고 있습니다!

Discussion