requesting-code-review

개요

이 스킬이 하는 일

requesting-code-review 스킬은 변경 사항이 메인 브랜치에 반영되기 전에, AI 코드 리뷰 서브에이전트에게 검토를 요청하는 명확하고 반복 가능한 워크플로우를 정의합니다. Git 기반 프로젝트에 맞춰 설계되었으며, 다음을 도와줍니다:

• 작업·기능 단위 및 머지 전에 언제 리뷰를 요청할지 결정
• Git SHA와 요구사항을 이용해 리뷰어에게 정확한 컨텍스트를 전달
• 리뷰어의 초점을 개인 세션 히스토리가 아닌 코드 diff에 집중
• 피드백을 심각도별로 분류해, 지금 고쳐야 할 것과 나중에 해도 될 것을 구분

핵심적으로 requesting-code-review는 일찍, 자주 리뷰해 문제를 코드베이스 전반으로 퍼지기 전에 잡는 데 초점을 둡니다.

대상 사용자

다음과 같은 경우 이 스킬이 잘 맞습니다:

• Git으로 개발하고, 기능 브랜치나 PR을 자주 생성하는 개발자
• AI 코드 리뷰를 구조화되고 반복 가능한 방식으로 요청하고 싶은 사람
• code-reviewer 같은 전용 서브에이전트를 사용하는 subagent-driven 개발 방식을 쓰는 팀
• 정확성, 아키텍처, 테스트, 스펙 정합성 등 프로덕션 준비도를 중요하게 생각하는 경우

특히 이런 상황에 유용합니다:

• 신뢰할 수 있는 안전망이 필요한 개인 개발자
• 전담 코드 리뷰어가 없는 소규모 팀
• 커밋 히스토리와 diff가 사실상의 단일 소스인 프로젝트

적합하지 않은 경우

다음에 해당하면 requesting-code-review는 최선의 선택이 아닐 수 있습니다:

• Git을 사용하지 않거나 커밋 SHA에 접근할 수 없는 경우
• 특정 변경 사항의 리뷰가 아니라 일반적인 코드 생성이나 리팩터링 도움을 원하는 경우
• 리뷰 대상 변경에 대해 명확한 계획, 스펙, 요구사항을 제공할 수 없는 경우

이런 상황이라면, 리뷰 중심 워크플로우보다는 일반적인 코딩/플래닝 스킬을 사용하는 편이 더 적합할 수 있습니다.

해결하는 문제

일관된 리뷰 프로세스가 없으면, 개발자는 종종 다음과 같은 문제를 겪습니다:

• 중요한 마일스톤에서 리뷰 요청을 깜빡함
• 리뷰어에게 제공하는 컨텍스트가 너무 적거나, 반대로 세션 히스토리를 과도하게 공유함
• 피드백이 구조화돼 있지 않아, 무엇부터 어떻게 고쳐야 할지 애매함

requesting-code-review 스킬은 다음과 같은 방식으로 이 문제들을 해결합니다:

• 필수 및 선택적 리뷰 체크포인트를 정의
• 리뷰 입력값( Git range, 요구사항, 요약)을 표준화
• 전용 code-reviewer 서브에이전트와 연동해 심각도 기반 피드백을 반환

---

사용 방법

설치

obra/superpowers 저장소에서 requesting-code-review 스킬을 설치하려면 Skills CLI를 사용합니다:

npx skills add https://github.com/obra/superpowers --skill requesting-code-review

이 명령은 스킬 정의와 함께 code-reviewer 서브에이전트 템플릿을 포함한 지원 파일들을 가져옵니다.

설치 후, 스킬 디렉터리를 열어 아래 파일들을 먼저 훑어보세요:

• SKILL.md – 코드 리뷰 요청용 상위 설명 및 워크플로우 단계
• code-reviewer.md – 실제 코드 리뷰를 수행하는 에이전트 프롬프트/템플릿

핵심 워크플로우 한눈에 보기

requesting-code-review 워크플로우는 세 가지 주요 단계로 구성됩니다:

1. 리뷰 시점 결정
   • subagent-driven 워크플로우에서 각 작업이 끝난 후
   • 큰 기능 구현을 마친 후
   • 메인 브랜치에 머지하기 직전
2. 리뷰 컨텍스트 준비
   • BASE_SHA와 HEAD_SHA로 Git 커밋 범위를 캡처
   • 무엇을 구현했고, 어떻게 동작해야 하는지 요약
   • code-reviewer.md에 정의된 placeholder를 채움
3. 리뷰 실행 및 피드백 반영
   • superpowers:code-reviewer 서브에이전트를 호출
   • Critical 이슈는 즉시, Important 이슈는 진행 전 수정하고, Minor 이슈는 기록해둠

1단계: 적절한 리뷰 시점 찾기

SKILL.md 기준으로, requesting-code-review는 다음과 같이 사용합니다:

필수 체크포인트:

• subagent-driven 개발에서 각 작업(task) 이후
• 주요 기능을 완료한 직후
• 메인 브랜치(예: main, master)에 머지하기 전

선택이지만 가치 있는 체크포인트:

• 문제에 갇힌 느낌이 들어 새로운 관점이 필요할 때
• 리팩터링 전, 현재 동작에 대한 기준선을 잡고 싶을 때
• 복잡한 버그를 수정한 후, 회귀나 새로운 문제가 없는지 확인할 때

이 시점들에 스킬을 습관적으로 트리거하면, 리뷰가 ‘나중에 생각해보자’가 아니라 자동화된 프로세스의 일부가 됩니다.

2단계: Git 커밋 범위 캡처

리뷰어에게는 깨끗하고 범위가 명확한 diff가 필요합니다. Git SHA를 사용해 범위를 지정하세요:

BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
HEAD_SHA=$(git rev-parse HEAD)

• BASE_SHA는 이전 커밋 또는 origin/main의 최신 커밋처럼, 출발점이 되는 커밋을 가리켜야 합니다.
• HEAD_SHA는 여러분의 최신 작업이 포함된 커밋을 가리켜야 합니다.

브랜치 전략에 맞게 HEAD~1을 조정하거나 다른 기준 커밋을 사용할 수 있지만, 리뷰받고 싶은 변경 사항을 정확히 포함하는 범위여야 합니다.

3단계: 리뷰 요청 템플릿 준비

code-reviewer.md 파일은 Code Review Agent와 대화하는 형식을 정의합니다. 여기에 있는 placeholder를 서브에이전트를 실행하기 전에 직접 채워야 합니다.

주요 placeholder:

• {WHAT_WAS_IMPLEMENTED} – 방금 구현하거나 변경한 내용을 간결하게 설명
• {PLAN_OR_REQUIREMENTS} – 구현이 충족해야 하는 스펙, 티켓, 비즈니스 요구사항
• {BASE_SHA} – diff의 시작 커밋 SHA
• {HEAD_SHA} – diff의 끝 커밋 SHA
• {DESCRIPTION} – 변경 셋의 짧은 요약 (예: "Add verification function and tests for user signups")
• {PLAN_REFERENCE} – 계획 또는 요구사항 문서에 대한 참조

자신의 도구 체인에서 이 placeholder들을 채운 뒤, Task tool을 사용해 superpowers:code-reviewer 서브에이전트를 호출하세요.

4단계: code-reviewer 서브에이전트 호출

Git SHA와 템플릿을 모두 채웠다면:

1. superpowers 프레임워크에서 설명된 대로, 오케스트레이션 환경의 Task tool을 type superpowers:code-reviewer로 사용합니다.

2. placeholder가 실제 값으로 치환된 code-reviewer.md 내용을 전달합니다.

3. 에이전트가 지정된 범위의 Git diff에 접근할 수 있도록 합니다:

   git diff --stat {BASE_SHA}..{HEAD_SHA}
   git diff {BASE_SHA}..{HEAD_SHA}
   

   템플릿에는 리뷰어가 BASE_SHA와 HEAD_SHA 사이의 변경 사항에만 집중하도록 이러한 명령이 포함됩니다.

이 스킬의 설계 덕분에, 리뷰 에이전트는 세션 히스토리나 불필요한 컨텍스트가 아닌 커밋과 diff라는 작업 결과물만 보게 됩니다.

5단계: 피드백 해석 및 처리

code-reviewer.md 템플릿은 에이전트에게 다음을 검토하도록 지시합니다:

• 코드 품질 (관심사 분리, 에러 처리, 중복 제거, 엣지 케이스 처리 등)
• 아키텍처 (설계, 확장성, 성능, 보안)
• 테스트 (커버리지, 통합 지점, 테스트 품질)
• 요구사항 충족 여부 (스펙 정합성, 스코프 크립 방지, 문서화된 breaking change)
• 프로덕션 준비도 (마이그레이션, 하위 호환성, 문서화)

피드백은 다음과 같이 분류됩니다:

• Critical (Must Fix) – 버그, 보안 문제, 데이터 손실 위험, 기능이 깨지는 문제
• Important (Should Fix) – 아키텍처 문제, 빠진 기능, 취약한 에러 처리, 테스트 부족
• Minor (Nice to Have) – 스타일, 최적화, 문서 개선

SKILL.md에서 제안하는 워크플로우는 다음과 같습니다:

• Critical 이슈는 계속 진행하기 전에 즉시 수정
• Important 이슈는 추가 작업이나 머지 전에 수정
• Minor 이슈는 나중 정리 또는 후속 태스크로 기록
• 리뷰어가 문맥을 놓쳤거나 잘못 판단한 경우, 근거를 들어 반박

이런 식의 트리아지를 따르면, AI 피드백이 추상적인 제안 목록이 아니라 실행 가능한 액션 리스트로 바뀝니다.

사용 예시 패턴

일반적인 requesting-code-review 사용 흐름은 다음과 같습니다:

1. 기능 브랜치에서 "Task 2: Add verification function"을 완료합니다.

2. SHA를 캡처합니다:

   BASE_SHA=$(git rev-parse origin/main)
   HEAD_SHA=$(git rev-parse HEAD)
   

3. code-reviewer.md의 placeholder를 다음처럼 채웁니다:

   • {WHAT_WAS_IMPLEMENTED} = "Verification function for user email flow"
   • {PLAN_OR_REQUIREMENTS} = 티켓/요구사항에 대한 링크 또는 요약
   • {BASE_SHA}와 {HEAD_SHA} = Git에서 가져온 값
   • {DESCRIPTION} = "Implement email verification and add tests for edge cases"

4. Task tool을 사용해 superpowers:code-reviewer 서브에이전트를 호출합니다.

5. Critical, Important, Minor로 그룹화된 구조화된 피드백을 받습니다.

6. Critical과 Important 이슈를 해결하고, 필요하다면 머지 전 한 번 더 프로세스를 실행합니다.

---

자주 묻는 질문 (FAQ)

requesting-code-review는 GitHub 저장소에서만 사용할 수 있나요?

아닙니다. requesting-code-review 스킬은 GitHub 전용이 아니라 Git 기반입니다. 커밋 SHA와 git diff 명령에 의존하기 때문에, BASE_SHA와 HEAD_SHA만 제공할 수 있다면 GitHub, GitLab, Bitbucket, 자체 호스트 등 어떤 Git 리모트와도 함께 사용할 수 있습니다.

전체 개발 세션 히스토리를 공유해야 하나요?

그럴 필요 없습니다. requesting-code-review의 핵심 설계 원칙 중 하나는 리뷰어가 받는 컨텍스트를 필요 최소한으로 좁히는 것입니다. 구현 내용, 요구사항, Git diff만 전달하고, 일반적인 세션 히스토리나 내부적인 사고 과정은 비공개로 유지됩니다. 리뷰어는 실제 코드 변경에만 집중하게 됩니다.

워크플로우에서 언제 requesting-code-review를 트리거해야 하나요?

requesting-code-review는 다음 시점에 사용하는 것을 권장합니다:

• subagent-driven 개발에서 각 작업이 끝난 후
• 큰 기능을 완성한 직후
• 메인 브랜치에 머지하기 전

또한 막혔다고 느껴질 때, 대규모 리팩터링 전에, 복잡한 버그 수정 후에 실행해 숨은 리스크를 조기에 발견하는 용도로 사용할 수 있습니다.

기존 Pull Request 리뷰와는 어떻게 연동되나요?

requesting-code-review는 기존 사람 기반 PR 리뷰를 대체하는 것이 아니라 보완합니다. 예를 들어:

• PR을 열기 전에 스킬을 실행해 기본적인 문제를 먼저 잡을 수 있습니다.
• 사람 리뷰어와 병행 사용해 리뷰 범위와 일관성을 높일 수 있습니다.
• 스킬의 피드백 분류(Critical/Important/Minor)를 PR 코멘트 구조에 그대로 적용할 수 있습니다.

이 스킬은 Git range를 중심으로 설계되어 있어, PR 기반 워크플로우에 자연스럽게 녹아듭니다.

code-reviewer 에이전트의 동작을 커스터마이즈할 수 있나요?

가능합니다. code-reviewer.md 파일은 자유롭게 수정 가능한 템플릿입니다:

• 코드 품질, 아키텍처, 테스트, 보안에 대한 체크리스트를 조정
• 도메인 규칙, 성능 예산 등 프로젝트 특화 항목 추가
• 심각도 레벨이나 섹션 구성을 바꾸고 싶다면 출력 포맷을 수정

단, 리뷰가 집중적이고 실행 가능하게 유지되도록, 명확한 작업 지시, Git range, 심각도 카테고리라는 핵심 구조는 유지하는 것이 좋습니다.

리뷰어가 잘못된 제안을 한다면 어떻게 해야 하나요?

이 스킬은 리뷰어가 틀리거나 문맥이 부족하다고 느낄 때 근거를 들어 반박하도록 명시적으로 권장합니다. 리뷰 결과를 절대적인 판정이 아닌, 강력한 제안 정도로 다루세요. 제약 조건을 설명하거나, 트레이드오프를 해명하고, 필요하다면 계획 문서를 보완해 다음 리뷰가 더 잘 맞도록 만들 수 있습니다.

requesting-code-review가 테스트나 코드 변경도 대신 생성해 주나요?

아닙니다. 이 스킬의 목적은 생성이 아닌 리뷰입니다. 다음과 같은 일을 도와줍니다:

• 특정 변경 사항에 대해 타깃이 명확한 리뷰를 요청
• 품질, 아키텍처, 테스트 측면에서 구조화된 피드백 받기

수정사항 구현과 테스트 작성은 여전히 개발자의 책임입니다. 다만, 다른 코딩/테스트 생성 스킬과 조합해 도구 체인에 통합해 사용할 수 있습니다.

빠르게 시작하려면 어떻게 해야 하나요?

1. 스킬을 설치합니다:

   npx skills add https://github.com/obra/superpowers --skill requesting-code-review
   

2. SKILL.md를 읽어 리뷰 체크포인트를 이해합니다.

3. code-reviewer.md를 검토해 에이전트의 체크리스트와 출력 포맷을 파악합니다.

4. 다음 작업이나 기능 개발을 진행한 뒤, BASE_SHA와 HEAD_SHA를 캡처하고 superpowers:code-reviewer 서브에이전트를 호출합니다.

이후에는 템플릿과 워크플로우를 팀의 작업 습관과 품질 기준에 맞게 다듬어, requesting-code-review가 자연스러운 개발 프로세스의 한 부분이 되도록 만들면 됩니다.