서론

지난번, 「Anthropic 공식 플러그인 『code-review』로 PR 리뷰를 자동화하기」에서 code-review 플러그인을 소개했습니다. 그것은 1개의 커맨드로 5개의 에이전트가 병렬 리뷰를 수행하고, 신뢰도 점수(reliability score)로 필터링한 지적 사항을 자동으로 PR 코멘트로 게시하는 「전자동형」 플러그인이었습니다.

pr-review-toolkit

은 동일한 「PR 리뷰」를 다루지만, 접근 방식이 다릅니다. 관점마다 특화된 6체의 에이전트를 준비하여, 필요한 관점만 선택해서 사용하는 「분업형」 툴킷입니다. GitHub로의 자동 게시(posting)는 수행하지 않으며, 로컬에서의 깨달음을 얻는 데 사용하는 이미지입니다.

pr-review-toolkit이란

pr-review-toolkit

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

코멘트의 정확성·테스트 커버리지(test coverage)·에러 핸들링(error handling)·타입 설계·코드 품질·코드의 간결함이라는 6가지 관점에 각각 특화된 에이전트와, 이들을 한꺼번에 호출하는 슬래시 커맨드(slash command)가 1개 수록되어 있습니다.

설치

/plugin install pr-review-toolkit@claude-plugins-official
/reload-plugins

README와의 차이점에 대하여: 공식 README의 설치 절차는 /plugins 커맨드를 통한 검색 및 설치를 안내하고 있지만, 현재의 Claude Code에서는 /plugin install <name>@<marketplace>가 올바른 절차입니다. 본 기사는 현재의 플러그인 설치 플로우를 기준으로 하고 있습니다.

사용법

두 가지 기동 방법이 있습니다.

1. 자연어로 호출하기

각 에이전트는 description에 「어떤 때에 사용하는가」가 정의되어 있으며, Claude가 대화의 문맥으로부터 proactive하게 (자동으로) 해당 에이전트를 기동합니다.

2. 슬래시 커맨드로 호출하기

/pr-review-toolkit:review-pr [관점]

관점을 생략하면 all (적용 가능한 모든 에이전트)이 실행됩니다. 관점을 지정하여 범위를 좁히는 것도 가능합니다.

/pr-review-toolkit:review-pr tests errors

6개의 에이전트

「모델」 열의 「상속」은 에이전트 정의에서 model: inherit가 지정되어 있음을 나타냅니다. 판단의 폭이 넓은 code-reviewer와 code-simplifier만이 명시적으로 Opus 고정으로 되어 있으며, 나머지 4개는 메인 스레드가 사용 중인 모델을 그대로 이어받습니다.

code-reviewer

CLAUDE.md 준수 체크와 버그 검출을 수행합니다. 스코어링(scoring) 기준은 다음과 같으며, code-review 플러그인의 임계값(80)과 동일한 개념이 채택되었습니다.

code-simplifier

code-simplifier

다른 5개의 에이전트가 "지적하고 끝내는" 방식인 것과 달리, 이 에이전트는 지적에 그치지 않고 코드를 직접 다시 작성하는 것을 전제로 설계되었습니다. 정의에는 "You operate autonomously and proactively, refining code immediately after it's written(당신은 자율적이고 주도적으로 작동하며, 코드가 작성된 직후 즉시 코드를 개선합니다)"라고 명시되어 있어, 리뷰라기보다는 자동 리팩터링 (Refactoring) 에이전트에 가까운 성격을 띱니다. 중첩된 삼항 연산자를 피하거나, function 키워드를 우선하는 등 프로젝트의 규약 (CLAUDE.md)에 따라 코드를 다시 작성합니다.

comment-analyzer

반대로 이 에이전트는 명시적으로 "조언만 수행"하도록 정의되어 있습니다. "IMPORTANT: You analyze and provide feedback only. Do not modify code or comments directly.(중요: 당신은 분석하고 피드백만 제공합니다. 코드나 코멘트를 직접 수정하지 마십시오.)"라고 되어 있어, 코드 변경은 수행하지 않고 지적 사항만 반환합니다. 같은 "코드에 손을 대는지 여부"에 대해서도 에이전트마다 역할이 명확하게 나뉘어 있다는 점을 파악해 두면 용도에 맞게 사용하기 쉽습니다.

pr-test-analyzer

코드 커버리지(Code Coverage)가 아닌 동작(Behavioral) 커버리지를 중시합니다. "10=절대 필수"부터 "1=있어도 없어도 좋은 개선"까지의 중요도에 따라 각 지적 사항을 등급화하며, 100% 커버리지와 같은 형식적인 지표는 추구하지 않습니다.

silent-failure-hunter

빈 catch 블록, 에러를 무시하는 fallback, 너무 넓은 범위의 예외 catch 등 "사일런트 장애 (Silent Failure)"를 겨냥한 에이전트입니다. "Silent failures are unacceptable(사일런트 장애는 용납될 수 없습니다)"라는 원칙을 내걸고, CRITICAL/HIGH/MEDIUM으로 심각도를 분류합니다.

type-design-analyzer

새롭게 추가된 타입의 설계를 캡슐화(Encapsulation), 불변 조건(Invariant) 표현, 유용성, 강제성이라는 4가지 축으로 각각 1~10점까지 평가합니다. "Types should make illegal states unrepresentable(타입은 잘못된 상태를 표현 불가능하게 만들어야 한다)"라는 설계 사상에 기반한 리뷰를 수행합니다.

/review-pr 명령의 내부 동작

• git diff --name-only로 변경된 파일을 확인 - 인자로 관점이 지정되어 있으면 그것을 사용하고, 없으면 변경 내용으로부터 적용할 에이전트를 자동 판정

  • 항상 적용: code-reviewer
  • 테스트 파일이 변경되었다면: pr-test-analyzer
  • 코멘트/문서가 추가되었다면: comment-analyzer
  • 에러 핸들링이 변경되었다면: silent-failure-hunter
  • 타입이 추가/변경되었다면: type-design-analyzer
  • 리뷰 통과 후: code-simplifier

• 순차 실행(하나씩 결과를 확인하며) 또는 병렬 실행(한꺼번에 빠르게)을 선택

• 결과를 Critical Issues / Important Issues / Suggestions / Positive Observations로 집약

• "먼저 치명적인 문제를 수정한다 → 중요한 문제에 대응한다 → 제안을 검토한다 → 수정 후 재리뷰한다"라는 행동 계획을 제시

중요한 주의사항: 이 명령은 gh pr view를 통해 PR의 존재 여부는 확인하지만, gh pr comment와 같이 GitHub에 게시하는 처리 과정은 수행하지 않습니다. 결과는 어디까지나 해당 Claude Code 세션 내에 표시될 뿐이며, code-review 플러그인처럼 PR에 자동으로 코멘트를 남기지는 않는다는 점을 기억해 두시기 바랍니다.

code-review 플러그인과의 차이점

code-review 플러그인과의 차이점

주의할 점

• 6개 에이전트 중 code-simplifier만이 코드를 직접 수정합니다. 의도치 않게 변경되는 것을 원하지 않는 경우, 이 관점만 /pr-review-toolkit:review-pr의 대상에서 제외하거나 개별 호출을 피해주세요. - GitHub에 자동 게시되지 않기 때문에 gh CLI 인증은 필수적이지 않습니다 (내용: review-pr 명령어 내에서 PR 존재 확인 용도로 사용됨). - 각 에이전트의 평가 기준(점수/중요도/심각도)은 관점마다 다른 척도이므로, 여러 에이전트의 결과를 나란히 비교할 때는 척도의 차이에 주의해야 합니다.

요약

pr-review-toolkit은 '하나의 에이전트에게 전부 맡기는 것'이 아니라, '관점별로 전문가를 활용하는' 설계의 플러그인입니다. code-review 플러그인이 목표하는 '오탐지를 줄이고 자동 게시하는' 효율화와는 대조적으로, 여기서는 개발자가 관점을 선택하며 능동적으로 사용하는 도구입니다.

CLAUDE.md가 정비된 프로젝트일수록 효과가 높다는 점은 code-review와 공통적이지만, pr-review-toolkit은 나아가 '형 설계', '코멘트의 구식화', '사일런트 장애'와 같이 단발적인 자동 리뷰로는 포착하기 어려운 관점까지 파고든 것이 특징입니다.

참고 링크

Discussion