서론

Pull Request 리뷰는 시간이 많이 걸립니다. 변경 사항이 클수록 놓치는 부분이 늘어나고, 리뷰어에 따라 관점의 차이가 발생하기도 합니다.

code-review

는 그 부분을 보완하는 플러그인입니다. 명령어 하나로 여러 에이전트가 병렬로 PR을 다각도로 분석하며, 신뢰 점수(confidence score)로 걸러낸 지적 사항만을 PR 코멘트로 게시합니다.

code-review란

code-review

는 claude-plugins-official에서 공개된 Anthropic의 공식 플러그인입니다.

/code-review:code-review

를 실행하면, 5개의 Sonnet 에이전트가 병렬로 독립적인 리뷰를 수행하며, 각 지적 사항에 0~100의 신뢰 점수를 부여하여 정밀하게 검토합니다. 80 미만의 지적 사항은 자동으로 제외되므로, 오탐(false positive)이 적은 실용적인 피드백만을 받을 수 있습니다.

설치

/plugin install code-review@claude-plugins-official
/reload-plugins

전제로 GitHub CLI (gh)

의 설치와 인증이 필요합니다:

brew install gh # macOS
gh auth login

사용법

PR 브랜치에서 실행합니다:

/code-review:code-review

이후에는 자동으로 진행됩니다. 완료되면 PR에 코멘트가 게시됩니다.

내부 동작

명령어는 다음 순서로 실행됩니다.

페이즈 1: 사전 체크 (Haiku)

Haiku 에이전트가 PR 상태를 확인하며, 다음의 경우 처리를 스킵합니다:

• 종료된 PR
• 드래프트(Draft) PR
• 자동 생성 등 사소한(trivial) PR
• 이미 자신의 리뷰 코멘트가 있는 PR

페이즈 2: 컨텍스트 수집 (Haiku)

• 리포지토리 내의 CLAUDE.md 파일 수집 (루트 및 PR 변경 파일의 디렉토리)
• PR 변경 내용의 요약(summary) 생성

페이즈 3: 5개 에이전트 병렬 리뷰 (Sonnet)

페이즈 4: 신뢰 점수 산정 (Haiku)

지적 사항마다 Haiku 에이전트가 0~100의 점수를 부여합니다:

CLAUDE.md 유래의 지적 사항에 대해서는, "해당 규칙이 CLAUDE.md에 실제로 명시되어 있는가"를 점수 산정 시 재확인합니다.

페이즈 5: 재체크 → 코멘트 게시 (Haiku)

코멘트 게시 전에도 다시 한번 PR의 적격성을 확인하고, 문제가 없다면 결과를 PR 코멘트로 게시합니다.

코멘트 출력 형식

지적 사항이 있는 경우:

### Code review
Found 3 issues:
1. OAuth 콜백의 에러 핸들링이 누락되었습니다 (CLAUDE.md에 "OAuth 에러는 반드시 처리할 것"이라고 기재되어 있음)
...

지적 사항이 없는 경우:

### Code review
No issues found. Checked for bugs and CLAUDE.md compliance.
🤖 Generated with [Claude Code](https://claude.ai/code)

각 지적 사항에는 파일로의 직접 링크(Full SHA + 행 범위)가 붙기 때문에, 클릭하여 해당 위치로 이동할 수 있습니다.

필터링되는 지적 사항의 예

다음은 의도적으로 스킵됩니다:

• PR 이전부터 존재하던 기존 문제
• 버그처럼 보이지만 실제로는 버그가 아닌 부분
• lint, 타입 체크, 컴파일러가 검출하는 종류의 문제 (CI에서 별도로 체크되므로)
• 테스트 커버리지 부족, 일반적인 문서 품질 등 (CLAUDE.md에 명시되지 않은 한)
• lint ignore 코멘트로 명시적으로 억제된 부분
• PR에서 변경하지 않은 행의 문제

CLAUDE.md와의 연동

이 플러그인은 CLAUDE.md를 「리뷰 기준」으로 활용합니다.

• 루트(Root)의 CLAUDE.md 외에도, 변경된 파일이 포함된 디렉터리의 CLAUDE.md도 참조
• CLAUDE.md에 작성된 규칙 준수 여부 체크를 2개의 에이전트(Agent)가 담당 (#1과 채점 시의 재확인)
• CLAUDE.md가 잘 정비되어 있을수록 리뷰의 정밀도가 향상됨

프로젝트 고유의 코딩 규약, 금지 사항, 주의 사항 등을 CLAUDE.md에 작성해 두면 효과적입니다.

주의 사항

• gh CLI가 필요합니다. 사전에 gh auth login으로 인증을 완료해 주세요.
• GitHub 리모트(Remote)가 설정되어 있는 리포지터리(Repository)에서 사용합니다.
• 규모가 큰 PR은 에이전트가 병렬로 동작하기 때문에 시간이 걸립니다. PR을 작게 분할하는 것이 이상적입니다.
• 신뢰 점수(Confidence Score)의 임계값(기본값 80)은 commands/code-review.md를 편집하여 변경할 수 있습니다.

README와의 차이점에 대하여: 공식 README에는 에이전트 수가 「4개」라고 기재되어 있으나, 구현부(commands/code-review.md)에서는 5개의 Sonnet 에이전트가 정의되어 있습니다. 본 기사는 구현부를 기준으로 합니다.

요약

code-review는 「여러 관점에서 병렬로 리뷰하고, 신뢰 점수로 필터링한다」는 설계를 통해, 오탐(False Positive)을 억제하면서 놓치는 부분을 줄이는 접근 방식을 취하고 있습니다.

CLAUDE.md가 잘 정비된 프로젝트일수록 효과가 높으며, 프로젝트 고유의 규칙을 기준으로 한 리뷰가 자동으로 수행됩니다.

참고 링크

Discussion