code-reviewer

code-reviewer 스킬 개요

code-reviewer 스킬이 하는 일

code-reviewer 스킬은 Code Review 작업을 위한 구조화된 PR 및 diff 리뷰 워크플로입니다. 한 줄짜리 “이 코드 리뷰해줘” 프롬프트에 의존하는 대신, 변경된 파일을 수집하고, diff를 확인하고, 로컬 프로젝트 패턴을 이해한 다음, 정확성, 보안, 성능, 테스트, 유지보수성 같은 구체적인 범주로 변경 사항을 검토하도록 에이전트를 유도합니다.

code-reviewer를 설치하면 좋은 사람

이 code-reviewer skill은 일반적인 프롬프트보다 더 일관된 리뷰 결과를 원하는 개발자, 테크 리드, AI 보조 리뷰어에게 특히 잘 맞습니다. 정기적으로 pull request를 검토하거나, 심각도 기준으로 이슈를 정리하고 싶거나, 로직 문제와 고위험 보안 이슈를 함께 다루는 반복 가능한 체크리스트가 필요하다면 특히 유용합니다.

사용자가 실제로 해결하려는 일

대부분의 사용자가 원하는 것은 단순한 “피드백”이 아닙니다. 실제로는 다음에 답할 수 있는 리뷰를 원합니다. 무엇이 바뀌었는가, 무엇이 위험한가, 어떤 점이 merge를 막아야 하는가, 무엇은 나중으로 미뤄도 되는가, 그리고 각 판단을 뒷받침하는 근거는 무엇인가. code-reviewer 워크플로는 컨텍스트 수집과 분석을 분리해 이 목적에 맞게 설계되어 있어, 일부 코드 조각만 보고 얕은 코멘트를 남기는 일을 줄여줍니다.

이 스킬이 다른 이유

가장 큰 차별점은 리뷰 구조입니다. 이 저장소는 단순히 “코드를 살펴보라”는 넓은 지시로 끝나지 않습니다. 다음이 포함되어 있습니다:

• 단계별 리뷰 프로세스
• 심각도 중심의 출력 형식
• 체크리스트, 코딩 패턴, 보안 리뷰를 위한 집중형 참고 자료
• Git 변경 사항으로부터 리뷰 체크리스트를 생성하는 scripts/review_checklist.py 헬퍼 스크립트

덕분에 code-reviewer for Code Review는 단순 프롬프트보다 실행 가능성이 높고, 팀의 리뷰 규범에 맞게 조정하기도 쉽습니다.

code-reviewer가 특히 잘 맞는 경우

다음과 같은 상황이라면 code-reviewer를 쓰기 좋습니다:

• main 기준의 branch diff가 있을 때
• 여러 파일에 걸치거나 횡단적인 변경이 있는 PR일 때
• merge를 막아야 할 이슈와 선택적 개선사항을 구분해야 할 때
• auth, 입력 처리, 데이터 접근처럼 보안 민감한 변경이 있을 때
• 추상적인 베스트 프랙티스만큼 기존 코드베이스의 패턴이 중요한 환경일 때

잘 맞지 않는 경우

다음과 같은 경우 이 스킬의 효용은 상대적으로 떨어집니다:

• 살펴볼 diff나 파일 집합이 없을 때
• 스타일 지적만 원할 때
• 작업이 코드 리뷰가 아니라 아키텍처 설계일 때
• 저장소 컨텍스트를 볼 수 없어 패턴 비교가 불가능할 때
• 실제 요청이 디버깅, 재작성, 기능 기획에 더 가까울 때

code-reviewer 스킬 사용 방법

code-reviewer 스킬 설치 맥락

upstream SKILL.md에는 직접적인 설치 명령이 공개되어 있지 않지만, 이 스킬은 zhaono1/agent-playbook의 skills/code-reviewer 아래에 있습니다. 사용 중인 skills runtime이 저장소 경로나 컬렉션 기준의 GitHub skill 설치를 지원한다면, 해당 저장소에서 설치한 뒤 code-reviewer 스킬을 선택하면 됩니다.

흔히 쓰는 패턴은 다음과 같습니다:

npx skills add https://github.com/zhaono1/agent-playbook --skill code-reviewer

환경에 따라 다른 installer를 쓸 수도 있지만, 핵심 식별자는 스킬 slug인 code-reviewer입니다.

의존하기 전에 먼저 읽어야 할 파일

가장 빠르게 평가하려면 아래 순서대로 읽는 것이 좋습니다:

1. skills/code-reviewer/SKILL.md
2. skills/code-reviewer/README.md
3. skills/code-reviewer/references/checklist.md
4. skills/code-reviewer/references/security.md
5. skills/code-reviewer/references/patterns.md
6. skills/code-reviewer/scripts/review_checklist.py

이 순서가 중요합니다. SKILL.md는 워크플로가 어떻게 활성화되는지 알려주고, references는 어떤 기준으로 리뷰하는지 보여주며, 스크립트는 저장소 근거를 어떤 방식으로 수집하도록 설계됐는지 드러냅니다.

code-reviewer가 잘 작동하려면 어떤 입력이 필요한가

code-reviewer usage는 아래 정보를 줄 때 가장 강력하게 작동합니다:

• 기준 브랜치, 보통 main
• PR의 목적 또는 연결된 티켓
• 변경된 파일 목록 또는 전체 diff
• 특히 신경 쓰는 위험 영역
• 프레임워크나 언어 맥락
• 빠른 검토를 원하는지, merge 차단 수준의 리뷰를 원하는지

이 정보가 없어도 리뷰는 가능하지만, 결과는 더 일반론적으로 흐르기 쉽습니다.

스킬이 리뷰 컨텍스트를 수집하는 방식

이 저장소는 기대하는 리뷰 흐름을 명확하게 드러냅니다:

• git diff main...HEAD --name-only로 변경 파일 확인
• git log main...HEAD --oneline로 커밋 히스토리 확인
• git diff main...HEAD로 실제 diff 확인
• 인접한 문서와 유사 파일을 읽어 로컬 관례 파악

이 점이 중요합니다. 약한 AI 리뷰는 컨텍스트 수집을 건너뛰고 추상적인 베스트 프랙티스로 바로 점프하는 경우가 많습니다. code-reviewer는 실제 변경 사항에 먼저 발을 딛을 때 훨씬 좋아집니다.

실전에서 쓸 만한 code-reviewer 프롬프트 템플릿

다음처럼 프롬프트를 주는 편이 좋습니다:

Review this branch with the code-reviewer skill.

Base branch: main
Goal: add password reset flow for users
Priority areas: security, correctness, test gaps
Constraints: keep current API shape, do not request large refactors
Please classify findings by severity: critical, high, medium, low.
For each finding, cite the file, explain the risk, and suggest the smallest safe fix.

이 방식이 “내 코드 리뷰해줘”보다 나은 이유는 branch 대상, 비즈니스 의도, 리뷰 우선순위, 피드백 형식을 모두 함께 제공하기 때문입니다.

약한 입력 vs 강한 입력

약한 입력:

Review this PR

더 강한 입력:

Use code-reviewer on the diff against main.
Focus on auth flows, input validation, and regression risk.
Check whether tests cover unhappy paths and whether any existing project patterns were broken.
Flag only issues that are actionable before merge unless clearly marked as low severity.

강한 버전은 리뷰 범위를 좁히고, 위험 영역을 명시하고, 어느 정도까지 판단적으로 리뷰할지 알려주기 때문에 출력 품질을 실질적으로 끌어올립니다.

실제 PR 리뷰에 적합한 추천 워크플로

실무적인 code-reviewer guide는 다음과 같습니다:

1. 변경 파일과 diff를 수집한다.
2. PR 설명이나 티켓을 읽는다.
3. 인접 파일을 일부 샘플링해 관례를 파악한다.
4. 범주별로 리뷰한다: 정확성, 보안, 성능, 코드 품질, 테스트, 문서화, 유지보수성.
5. 발견사항을 심각도별로 묶는다.
6. 첫 리뷰에서 중대한 이슈가 나왔다면 고위험 파일에 대해 2차 리뷰를 요청한다.

이 2단계 패턴이 잘 통하는 이유는 1차 패스가 넓은 위험을 발견하고, 2차 패스가 정밀도를 높여주기 때문입니다.

references를 활용해 리뷰를 덜 일반적으로 만들기

일반 프롬프트보다 이 스킬을 선택할 이유로 가장 큰 부분이 바로 보조 파일들입니다:

• references/checklist.md는 리뷰를 체계적으로 유지해 줍니다
• references/security.md는 OWASP 관점의 점검을 추가해 줍니다
• references/patterns.md는 좋은 구현/나쁜 구현의 구체적인 예시를 제공합니다

리뷰가 너무 모호하게 느껴진다면, diff를 분석할 때 이 references 중 하나 이상을 명시적으로 적용하라고 에이전트에 지시하세요.

리뷰 뼈대를 원할 때는 헬퍼 스크립트 사용

이 저장소에는 다음이 포함되어 있습니다:

python scripts/review_checklist.py

현재 Git 상태로부터 기계 생성 체크리스트를 먼저 뽑고, 그다음 에이전트에게 서술형 리뷰를 요청하고 싶을 때 유용합니다. 원시 diff 확인과 완성된 서면 리뷰 사이를 자연스럽게 이어주는 실용적인 다리 역할을 합니다.

실무에서 가장 잘 먹히는 출력 형식

스킬에 다음 형태로 반환해 달라고 요청해 보세요:

• 무엇이 바뀌었는지에 대한 짧은 요약
• merge blocker를 가장 먼저
• 심각도별로 묶은 발견사항
• 파일 단위 참조
• 단순 판정이 아니라 근거 설명
• 주의사항을 포함한 최종 “safe to merge?” 평가

이 출력 형식은 저장소의 심각도 모델과 잘 맞고, 실제 팀 워크플로에서도 리뷰를 바로 활용하기 쉽습니다.

code-reviewer 스킬 FAQ

code-reviewer는 일반적인 리뷰 프롬프트보다 더 나은가

대체로 그렇습니다. 전제는 실제 저장소 컨텍스트가 있어야 한다는 점입니다. code-reviewer의 가치는 마법처럼 분석 깊이가 생긴다는 데 있지 않습니다. 활성화 신호, 단계별 워크플로, 체크리스트 범위, 참고 자료가 결합되면서 리뷰를 더 완전하고 일관되게 밀어준다는 데 있습니다.

code-reviewer는 초보자도 쓰기 쉬운가

네, 다만 한 가지 조건이 있습니다. 초보자라도 컨텍스트는 직접 제공해야 합니다. 이 스킬은 강한 구조를 제공하지만, 요구사항, 의도한 동작, 팀 관례를 아무 정보 없이 추론할 수는 없습니다. 처음 쓰는 사용자라면 PR 목적과 기준 브랜치를 처음부터 함께 적는 편이 훨씬 낫습니다.

code-reviewer는 pull request에서만 작동하나

아닙니다. code-reviewer usage는 로컬 브랜치 diff, 변경 파일 묶음, 혹은 “src/auth/ 안의 코드를 리뷰해줘” 같은 폴더 단위 리뷰 요청에도 맞습니다. 다만 기준 브랜치가 분명하고 그에 대한 diff가 있을 때 가장 강력합니다.

code-reviewer 스킬은 어떤 종류의 문제를 찾나

저장소 근거를 보면 다음 범위를 다룹니다:

• 정확성과 엣지 케이스
• OWASP 스타일 우려를 포함한 보안 이슈
• 불필요한 쿼리나 호출 같은 성능 문제
• 코드 품질과 유지보수성
• 테스트 누락
• 문서화 공백

이처럼 범위가 넓기 때문에, 보안 리뷰 전용이나 스타일 리뷰 전용이 아니라 일반적인 PR 리뷰용으로 적합합니다.

언제는 code-reviewer를 쓰지 않는 편이 좋은가

작업의 핵심이 아래와 같다면 code-reviewer는 건너뛰는 편이 낫습니다:

• 새로운 코드 생성
• 런타임 장애 디버깅
• 대규모 아키텍처 설계
• 포맷팅이나 lint 정리만 수행
• 변경 컨텍스트에 접근할 수 없는 상태에서의 코드 리뷰

이런 경우에는 더 특화된 스킬이나 작업 중심의 직접 프롬프트가 더 잘 맞습니다.

하나의 코딩 스타일만 강제하나

아닙니다. 이 저장소는 변경 사항을 판단하기 전에 유사 파일의 기존 패턴을 먼저 확인하도록 유도합니다. 이는 도입 측면에서 좋은 신호입니다. 로컬 관례와 충돌하는 일반론적 조언을 줄여주기 때문입니다.

code-reviewer 스킬을 더 잘 활용하는 방법

변경 의도를 code-reviewer에 먼저 알려주기

품질을 가장 크게 끌어올리는 방법은 코드가 무엇을 하려는지 설명하는 것입니다. 에이전트가 구현만 볼 때 리뷰 품질은 빠르게 떨어집니다. 티켓 요약, acceptance criteria, 또는 한 단락짜리 의도 설명을 추가해 두면, 스킬이 스타일과 문법만이 아니라 정확성까지 판단할 수 있습니다.

가장 위험한 리뷰 영역을 좁혀서 지정하기

auth, billing, migrations, concurrency가 특히 중요하다면 그렇게 말해 주세요. 이 스킬은 원래 여러 범주를 다루지만, 우선순위를 명시하면 정말 중요한 부분에서 더 깊게 들어갑니다. 특히 큰 PR에서는 범위를 넓게 잡은 리뷰가 쉽게 얕아지므로 더 중요합니다.

패턴 비교가 가능하도록 충분한 저장소 컨텍스트 제공하기

이 저장소는 리뷰어가 기존 관례를 보도록 명시적으로 유도합니다. 비교할 만한 파일이나 모듈을 직접 지정해 주면 더 좋아집니다:

Compare the new handler to the existing patterns in src/api/users/ and src/api/sessions/.
Prefer consistency with those files unless there is a clear bug.

이렇게 하면 false positive가 줄고, 제안도 실제로 채택되기 쉬워집니다.

근거 기반 발견사항만 보고하도록 요청하기

AI 리뷰의 흔한 실패 패턴 중 하나는 추측성 비판입니다. code-reviewer 출력 품질을 높이려면 다음과 같은 규칙을 추가하세요:

Only report an issue if you can point to a specific file change, missing case, or concrete risk. Avoid hypothetical style advice unless it affects maintainability or correctness.

이렇게 하면 리뷰의 신호 대 잡음비가 높아집니다.

큰 리뷰는 여러 패스로 나누기

큰 PR에서 한 번에 모든 것을 요청하지 마세요. 단계별 패스를 권장합니다:

1. 정확성 및 보안
2. 성능 및 유지보수성
3. 테스트 및 문서화

이 방식은 스킬의 범주 구조와도 잘 맞고, 과부하된 단일 요청보다 보통 더 나은 발견사항을 만들어냅니다.

더 작은 수정안까지 제안해 달라고 요청하기

첫 출력이 너무 추상적이라면, 발견사항을 최소 안전 수정안으로 다시 써 달라고 요청해 보세요:

Revise the review. For each high or critical issue, suggest the smallest code change or test addition that would reduce the risk before merge.

이렇게 하면 바쁜 팀에서도 바로 적용할 수 있는 리뷰가 됩니다.

흔한 실패 패턴을 미리 경계하기

code-reviewer skill 출력이 약해지는 가장 흔한 원인은 다음과 같습니다:

• 기준 브랜치를 지정하지 않음
• diff를 제공하지 않음
• 의도한 동작 설명이 없음
• 우선순위 없이 너무 큰 PR만 던짐
• 프로젝트 패턴 참고 정보가 없음
• “전부 다 봐줘”라고 해서 일반론적인 조언만 돌아옴

대부분은 스킬 문제라기보다 입력 문제입니다.

체크리스트와 보안 references를 명시적으로 활용하기

첫 리뷰가 너무 넓고 흐릿하다면, 특정 저장소 reference를 사용해 2차 패스를 요청하세요:

• 완전성을 위해 references/checklist.md
• 민감한 변경 점검을 위해 references/security.md
• 일관성과 안티패턴 탐지를 위해 references/patterns.md

이것은 일상적인 사용에서 code-reviewer guide를 개선하는 가장 쉬운 방법 중 하나입니다.

첫 리뷰 이후 반드시 한 번 더 다듬기

좋은 2차 프롬프트 예시는 다음과 같습니다:

Now re-review only the files with high-severity findings.
Assume the author wants merge-blocking issues only.
Double-check whether each finding is a real defect, a security exposure, or a missing test that hides regression risk.

이 후속 요청은 가치가 낮은 코멘트를 걷어내고 최종 권고를 더 날카롭게 다듬어 주는 경우가 많습니다.

팀 워크플로에 맞게 code-reviewer를 커스터마이즈하기

code-reviewer를 정기적으로 도입할 생각이라면, 팀의 merge 문화에 맞춰 정렬해 두는 것이 좋습니다:

• blocker와 suggestion의 기준 정의
• 기준 브랜치 관례 명시
• 테스트 기대치 포함
• 팀 전용 보안 체크 추가
• 로컬 스타일을 대표하는 파일을 스킬에 지정

이렇게 해야 code-reviewer install이 단순한 프롬프트 지름길이 아니라 실제 워크플로 개선으로 이어집니다.