pr-review-toolkit 플러그인 사용법: 클로드 코드 PR 리뷰 에이전트 6개, 문제 6개 심은 코드로 없이·있이 비교하니 비용 6배

클로드 코드로 기능을 하나 붙이고 나면, 깃허브에 PR(풀 리퀘스트, 합쳐 달라는 요청)을 올리기 전에 한 번 더 검토를 맡기게 됩니다. pr-review-toolkit(PR 리뷰 툴킷)은 Anthropic 공식 플러그인 디렉터리에 있는 검토 묶음으로, 오류 처리·주석·테스트·타입·규칙 준수를 따로 보는 에이전트 6개가 들어 있습니다. 플러그인은 무료지만 쓸 때 클로드 사용량이 듭니다. 가상 쇼핑몰 주문 코드에 문제 6개를 심고, 같은 검토를 플러그인 없이, 깔아 두기만 하고, 플러그인 명령으로 각 2번씩 맡겨 채점했습니다.

결과부터 보기: 같은 변경, 여섯 번의 검토

영상은 심어 둔 문제, 작업 전 저장소, 플러그인 명령이 부른 에이전트, 채점·사용량 비교, 명령으로만 나온 지적 순서입니다.

직접 눌러 보기: 여섯 번의 리뷰 전문과 검토 대상 변경 열어 보기

따라 해 보기: 요청문과 실습 재료

바꾼 코드가 있는 git 저장소 폴더에서 클로드 코드를 열고, 플러그인을 깐 뒤 아래 명령 하나만 보내면 됩니다. 클로드 코드가 처음이라면 클로드 코드 설치 방법을 먼저 보세요. 실습 재료(zip)에는 문제 6개를 심은 가상 쇼핑몰 저장소, 요청문, 채점 기준, 문제가 실제로 일어나는지 확인하는 스크립트를 넣었습니다.

/pr-review-toolkit:review-pr

좋은 결과라면 지적마다 파일:줄 위치가 붙고, “머지 전에 반드시 고칠 것”, “고치는 게 좋은 것”, “제안”, “잘된 점”으로 나뉘어 나옵니다. 검토만 하고 코드는 고치지 않습니다.

pr-review-toolkit에 들어 있는 것

claude plugin details로 뽑은 구성은 명령(화면에는 Skills로 표시) 1개와 에이전트 6개입니다. 훅·MCP 서버는 없습니다. 에이전트(서브에이전트)는 메인 대화가 일을 떼어 맡기는 별도의 클로드로, 자기 지시문을 따로 갖고 있습니다.

이름	맡는 일 (README 기준)	부를 때 분량
/pr-review-toolkit:review-pr	바뀐 파일을 보고 맞는 에이전트들을 불러 결과를 심각도별로 모음. 뒤에 tests errors처럼 볼 부분을 적을 수 있음	약 1.6k토큰
code-reviewer	CLAUDE.md 같은 프로젝트 규칙 준수, 버그, 코드 품질	약 870토큰
silent-failure-hunter	오류를 삼키는 catch 블록, 알리지 않는 대체 동작, 빠진 오류 기록	약 2.1k토큰
comment-analyzer	주석이 실제 코드와 맞는지, 낡은 주석	약 1.5k토큰
pr-test-analyzer	테스트가 중요한 동작·경계값을 확인하는지	약 1.3k토큰
type-design-analyzer	타입이 스스로 규칙(불변식)을 지키게 설계됐는지, 4개 항목 10점 만점 평가	약 1.5k토큰
code-simplifier	리뷰를 통과한 코드를 읽기 쉽게 다듬음	약 970토큰

깔아 두기만 해도 매 대화에 약 2,035토큰이 들어갑니다. 에이전트 6개의 설명문이 항상 실리기 때문입니다. 같은 이름의 code-simplifier 플러그인과는 에이전트 파일 내용이 다릅니다. code-reviewer와 code-simplifier는 Opus를 쓰도록 정해져 있고, 나머지 넷은 대화의 모델을 그대로 씁니다.

1단계. 플러그인 깔기 (약 1분)

검토할 저장소 폴더에서 터미널에 아래 명령을 실행합니다. claude-plugins-official은 클로드 코드에 처음부터 등록된 공식 플러그인 저장소입니다. --scope local은 이 폴더에서만 켜는 옵션입니다.

claude plugin install pr-review-toolkit@claude-plugins-official --scope local
claude plugin details pr-review-toolkit@claude-plugins-official

이렇게 나오면 성공 ✔ Successfully installed plugin: pr-review-toolkit@claude-plugins-official (scope: local)(플러그인 설치 성공, 범위: 이 폴더). 구성 목록에 Agents (6)과 에이전트 이름 6개가 나옵니다.

• 설치 명령이 플러그인을 찾지 못하면 claude plugin marketplace add anthropics/claude-plugins-official로 저장소를 등록한 뒤 다시 설치합니다.
• 클로드 앱에서는 디렉터리에서 설치합니다(디렉터리 여는 법). 이 글은 클로드 코드 터미널 기준입니다.

필요 없어지면 같은 폴더에서 아래 명령으로 지웁니다.

claude plugin uninstall pr-review-toolkit@claude-plugins-official --scope local

2단계. 실습 저장소로 검토 맡기기 (약 2분)

실습 저장소는 가상 쇼핑몰 “달빛상점”의 주문 코드입니다. main에는 합계·배송비 함수만 있고, feature/coupon-points 브랜치에서 쿠폰과 포인트를 붙이는 중입니다. CLAUDE.md에는 “금액은 정수(원)로만, float 계산 금지”, “외부 서버 호출 실패는 OrderError로 올린다” 두 규칙이 있습니다. 테스트 3개는 모두 통과합니다.

그 변경에 아래 문제 6개를 심었습니다. 에이전트마다 맡은 영역에서 하나 이상 나오게 골랐고, 숨은 검사 스크립트로 여섯 개 모두 실제로 일어나는지 확인했습니다. 채점 기준은 실행 전에 README와 에이전트 지시문에서 뽑아 고정했고, 요청문에는 넣지 않았습니다.

심어 둔 문제	맡는 에이전트
포인트 서버가 죽으면 except Exception: return 0으로 잔액이 0포인트로 보임	silent-failure-hunter
배송 지역표에 없는 곳을 조용히 무료 배송(0원)으로 처리	silent-failure-hunter
적립 함수 주석은 “1회 최대 5,000포인트”인데 코드에 상한이 없음	comment-analyzer
정액 쿠폰이 주문 금액보다 크면 결제액이 음수(주석은 “0원 밑으로 안 내려감”)	pr-test-analyzer · code-reviewer
비율 쿠폰을 쓰면 금액이 소수점이 붙은 float(CLAUDE.md 위반)	code-reviewer
Coupon에 비율·정액을 동시에, 150% 할인도 넣을 수 있음	type-design-analyzer

일곱 번째 채점 항목은 미끼입니다. 회원 등급이 없으면 경고 기록을 남기고 기본 등급을 쓰는 함수로, 주석대로 동작하니 고칠 필요가 없습니다. 이것을 “반드시 고칠 것”으로 올리지 않으면 1점입니다.

	① 플러그인 없음 (1·2)	② 깔아 두기만 (1·2)	③ /pr-review-toolkit:review-pr (1·2)
보낸 요청	PR 올리기 전에 지금 바꾼 거 검토해 줘.	같은 요청	명령만
채점(7개 중)	7 · 7	7 · 7	7 · 7
부른 에이전트	해당 없음	없음 · 없음	5개 · 5개
걸린 시간	1분이 안 걸림	1분이 안 걸림	2분쯤
사용량(API 단가)	0.30 · 0.31달러	0.32 · 0.32달러	2.03 · 1.63달러

여섯 번 모두 코드 파일은 고치지 않았고, 끝에 “원하면 고치고 테스트까지 추가하겠다”고 물었습니다. 해법도 거의 같았습니다. 할인은 정수 퍼센트로 받아 total * pct // 100으로 계산하고 max(0, …)로 하한을 두며, 적립은 min(paid // 100, 5000)으로 바꾸라는 내용입니다.

③은 두 번 모두 code-reviewer, silent-failure-hunter, pr-test-analyzer, comment-analyzer, type-design-analyzer 다섯을 불렀습니다. code-simplifier는 “리뷰를 통과한 뒤 다듬는 단계”라며 부르지 않았습니다. 실행 기록을 보면 에이전트 다섯이 각자 git diff와 같은 파일을 다시 읽고 따로 분석했습니다. 사용량이 늘어난 것은 이 때문으로 보입니다.

실행 기록 · <작업 폴더> · ③ 명령 2회차 최종 답 첫머리(원문 그대로)

# PR 리뷰 요약: `feature/coupon-points`

전문 리뷰 에이전트 5개를 돌렸습니다. `code-simplifier`는 리뷰를 통과한 코드를 다듬는 단계라서 이번에는 실행하지 않았습니다. ...

결론: **지금 상태로는 머지하면 안 됩니다.** docstring에 적힌 규칙 세 가지(0원 하한, OrderError로 올리기, 5,000P 상한)가 코드에는 없고, CLAUDE.md 규칙도 두 군데에서 어깁니다.

## Critical: 머지 전에 반드시 고칠 것 (4건)
- **[code-reviewer, type-design] 정률 쿠폰이 float 금액을 만듭니다** `shop/order.py:28`, `shop/coupon.py:8`
- **[silent-failure-hunter, code-reviewer] `point_balance`가 오류를 삼킵니다** `shop/order.py:36-37`
...

• 이렇게 나오면 성공 맨 위에 몇 개 에이전트를 돌렸는지와 결론(“머지하면 안 됩니다” 같은 한 줄)이 나오고, 지적마다 [에이전트 이름]과 파일:줄이 붙습니다.
• “바뀐 파일이 없다”고 나오면: 명령은 git diff로 바뀐 파일을 찾습니다. 새로 만든 파일이 아직 git에 안 올라가 있으면 빠질 수 있으니 git status로 먼저 확인합니다.

명령으로만 나온 것

점수는 같았지만, 명령 쪽 리뷰에는 플러그인 없이 한 네 번에 없던 내용이 있었습니다.

• 직접 계산한 근거. 에이전트들이 파이썬으로 경계값을 넣어 보고 -2000, 10000 같은 실제 결과를 적었습니다. 1회차는 1~99% 할인율과 여러 금액 조합을 돌려, 금액을 int()로 자르면 3,658개 조합에서 1원 오차가 난다고 짚었습니다(예: 4,300원에 6% 할인이면 4,042원이어야 하는데 4,041원).
• 테스트 함정. assertEqual(10800.0, 10800)처럼 float와 정수를 비교하면 통과해 버리므로, 금액 테스트에 assertIsInstance(결과, int)를 함께 넣으라는 지적이 두 번 모두 나왔습니다(숫자 예는 회차마다 다름).
• 심각도 정리. Critical(반드시)·Important(고치는 게 좋음)·Suggestions(제안)·잘된 점·다음 순서로 나뉘어, 무엇부터 고칠지 바로 보입니다.

①·②도 같은 경계값을 넣어 보려 했지만, 이번 실험에서 허락한 명령 목록 밖이라 막혔습니다. 그래서 네 번 모두 “아래 값은 코드를 읽고 계산한 것”이라고 밝혔습니다. 반면 ③의 에이전트 안에서는 같은 종류의 명령이 막히지 않고 실행됐습니다. 플러그인 에이전트에 명령 실행을 얼마나 맡길지는 권한 설정을 따로 확인해 두는 편이 좋습니다.

깔아 두기만 하면 쓰이나

README는 “PR 만들기 전”처럼 상황이 맞으면 클로드가 알아서 에이전트를 쓸 수 있다고 적었습니다. 이번에는 깔아 두고 “PR 올리기 전에 지금 바꾼 거 검토해 줘”를 보낸 두 번 모두 에이전트를 부르지 않았습니다. 리뷰 내용은 플러그인 없이 한 것과 같은 수준이었고, 상시로 실리는 설명문 때문에 사용량만 조금 늘었습니다. 쓰려면 명령으로 부르거나 “silent-failure-hunter로 오류 처리 봐 줘”처럼 이름을 대는 편이 확실합니다.

3단계. 필요한 부분만 골라 돌리기 (약 1분)

명령 뒤에 볼 부분을 적으면 그 에이전트만 부릅니다. 아래는 명령 파일에 적힌 사용법으로, 이번에는 인자 없이 전체 검토만 돌렸습니다.

명령	부르는 에이전트
/pr-review-toolkit:review-pr errors	silent-failure-hunter (오류 처리만)
/pr-review-toolkit:review-pr tests errors	pr-test-analyzer, silent-failure-hunter
/pr-review-toolkit:review-pr comments	comment-analyzer
/pr-review-toolkit:review-pr simplify	code-simplifier (리뷰 통과 뒤 다듬기)
/pr-review-toolkit:review-pr all parallel	전부 동시에

사용량이 걱정되면 오류 처리나 테스트처럼 이번 변경에서 걱정되는 부분만 고르는 편이 낫습니다. 명령 파일은 커밋 전에는 code errors, PR 만들기 전에는 all을 권합니다.

이런 사람에게 권합니다

• ✅ 돈이 오가는 코드처럼 실수 하나가 큰 변경을 올리기 전. 에이전트들이 경계값을 직접 돌려 근거를 붙이고, 고칠 순서를 심각도별로 정리해 줍니다.
• ✅ 오류 처리나 테스트처럼 한 부분만 깊게 보고 싶은 사람. errors, tests처럼 골라 부르면 사용량도 줄어듭니다.
• ❌ 작은 변경을 자주 검토받는 사람. 이번 과제에서는 “검토해 줘” 한 줄로도 문제 6개를 다 찾았고, 사용량은 6분의 1쯤이었습니다.
• ❌ 깔아 두면 알아서 쓰일 거라 기대하는 사람. 명령이나 에이전트 이름으로 불러야 쓰입니다.

한계와 주의할 점

• 60줄 남짓한 가상 변경 하나로, 조건마다 두 번씩만 돌렸습니다. 이번에는 모델(Opus 5.5)이 혼자서도 다 찾을 만큼 문제가 드러나 있었습니다. 파일이 수십 개인 변경이나 숨은 문제가 더 깊은 코드에서는 에이전트를 나눠 보는 쪽이 더 많이 찾을 수 있지만, 이번 실험으로 확인한 것은 아닙니다.
• gh(깃허브 CLI)에 로그인돼 있지 않아 원격 PR은 확인하지 못했다고 2회차가 밝혔습니다. 이번 검토는 내 컴퓨터의 바뀐 내용(git diff)만 대상으로 했습니다.
• type-design-analyzer는 타입을 4개 항목 10점 만점으로 매긴다고 README에 적혀 있지만, 최종 리뷰에는 점수 대신 고칠 점만 정리돼 나왔습니다.

대안

방법	다른 점	이럴 때 고르세요
pr-review-toolkit(이 글)	에이전트 6개가 영역을 나눠 검토, 심각도별 정리	중요한 PR을 올리기 전에 여러 면을 따로 보고 싶을 때
말로 요청	이번 실험에서 점수는 같고, 사용량 6분의 1쯤	작은 변경을 자주 검토받을 때
/code-review	클로드 코드 기본 명령, 버그 찾기 위주	플러그인 없이 바로 검토하고 싶을 때
Engineering 플러그인	/engineering:code-review로 보안·성능까지 함께	보안·성능도 같이 보고 싶을 때
claude-security 플러그인	보안 취약점만 깊게	로그인·결제 같은 민감한 코드일 때
commit-commands 플러그인	검토 뒤 커밋·PR 올리기	리뷰를 마치고 바로 올릴 때

자주 묻는 질문

pr-review-toolkit은 무료인가요?

플러그인 자체는 무료(Apache-2.0)입니다. 쓸 때 클로드 사용량이 듭니다. 이번 전체 검토는 한 번에 1.63~2.03달러어치였습니다. 구독 요금제라면 그만큼 사용량 한도에서 빠집니다.

깃허브 PR이 없어도 쓸 수 있나요?

네. 명령은 먼저 git diff로 내 컴퓨터에서 바뀐 파일을 찾습니다. 이번 실험도 PR 없이 커밋 전 변경만으로 돌렸습니다. PR이 있으면 gh pr view로 함께 확인합니다.

명령 이름은 어떻게 치나요?

플러그인 이름을 붙인 /pr-review-toolkit:review-pr로 부릅니다. 공식 문서에 따르면 플러그인 안의 명령은 /플러그인이름:명령 꼴입니다(플러그인 문서). 에이전트는 /agents 목록에서도 볼 수 있습니다.

코드를 고쳐 주기도 하나요?

이번 여섯 번은 모두 검토만 하고 파일을 고치지 않았습니다. 고치는 일은 simplify로 부르는 code-simplifier가 맡고, 명령 파일은 리뷰를 통과한 뒤에 쓰라고 안내합니다.

출처

pr-review-toolkit 플러그인 폴더, README, review-pr 명령 파일, 클로드 코드 플러그인 문서 (모두 2026-10-18 확인, 저장소 별 42,024개)