Community라이팅 & 에디팅github.com

코드 리뷰 스킬

Gregory Brown의 'Effective Code Reviews' 방법론을 기반으로 한 외부-내부, 위험 기반 코드 리뷰 자동화 스킬입니다.

코드 리뷰 스킬란 무엇인가요?

이 스킬은 Gregory Brown의 'Effective Code Reviews' (Programming Beyond Practices, 2015) 방법론을 Claude AI 어시스턴트 내에서 구현한 코드 리뷰 도구입니다. 외부-내부(outside-in) 접근 방식과 위험 기반(risk-driven) 접근 방식을 결합하여, 문제 검증(Phase 1)부터 리스크 평가 및 출력(Phase 6)까지 6단계의 체계적인 프로세스를 따릅니다. 리뷰어가 코드 한 줄을 읽기 전에 해당 변경 사항이 실제 문제를 해결하는지, 프로젝트 전체 가치를 높이는지 확인하도록 유도합니다. 또한 빌드 통과 여부, 테스트 변경 사항, 적용 범위 평가 등을 단계별로 검사하며, 각 변경 유형(버그 수정, 새 기능, 개선 등)에 맞는 위험 기반 테스트 기대치를 적용합니다. 재리뷰 시에는 이전 리뷰 스레드를 자동으로 확인하고 분류하여 중복된 우려를 방지하며, CI 통합(GitHub Actions 워크플로우 자동 생성) 및 프로젝트별 규칙 설정을 지원합니다. Claude Code, Cursor, Codex 등 다양한 플랫폼에서 사용할 수 있도록 설계되었으며, 프로젝트 규칙 파일(.claude/rules/)과 연동하여 동작합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add Agilefreaks/claude-skills

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

코드 리뷰 스킬은(는) 무엇을 하나요?

Gregory Brown의 "효과적인 코드 리뷰(Effective Code Reviews)" (Programming Beyond Practices, 2015)에 기반한 외부-내부, 위험 기반 코드 리뷰 방법론입니다.

플랫폼 통합 및 프로젝트별 검사는 프로젝트의 규칙 파일에 별도로 정의됩니다.


설정

설정, 구성, 온보딩 또는 이 스킬에 대한 규칙 파일 생성을 요청받으면:

  1. 이미 구성된 내용을 파악하기 위해 기존 프로젝트 규칙 (.claude/rules/, CLAUDE.md)을 모두 읽습니다. 이미 프로젝트 구성에 있는 규칙, 명령어 또는 검사를 중복해서 생성하지 마십시오.
  2. 프로젝트의 이슈/PR 연결 규칙, CI 구성, 린터/포매터 설정, 코드 리뷰 플랫폼 표시기를 검사합니다.
  3. 각 스킬별 결정 사항에 대해 대화형 선택 항목을 사용자에게 제시하며, 각 옵션에 대한 선택 대화 상자를 사용합니다:
    • 컨텍스트 수집 — PR에 대한 관련 이슈 또는 티켓을 찾는 방법 (브랜치 이름 지정, PR 본문 키워드, 작업 관리 통합)
    • 빌드 확인 — 빌드 통과 여부 확인 방법 (CI 상태 확인, 특정 명령어)
    • 코딩 규칙 — 스킬 기본값을 넘어서는 프로젝트별 검사 (아키텍처 규칙, 린터에 의해 이미 적용되는 스타일 규칙)
    • 출력 형식 — 리뷰 출력을 위한 사용자 정의 구조 또는 기본 제공 형식 사용
    • 게시 방법 — 리뷰 게시 방법 (GitHub PR 댓글, 인라인 댓글, stdout)
    • 재리뷰 스레드 처리 — 재리뷰 시 자신의 이전 발견 스레드를 처리하는 방법: 답변 및 해결 (기본값 — 스레드 내에서 답변하고 수정되거나 답변된 스레드는 해결), 답변만 (스레드 내에서 답변하지만 해결은 사람에게 맡김), 또는 요약만 (이전 스레드를 건드리지 않음; 요약에만 상태 보고)
    • CI 통합 — 모든 PR에서 이 리뷰를 자동으로 실행하는 GitHub Actions 워크플로우를 생성하겠다고 제안합니다. .github/workflows/ 디렉토리가 아직 없더라도 항상 질문하십시오 — 이것이 프로젝트의 첫 번째 워크플로우일 수 있습니다. 모델 선택 항목 제시: Opus (권장) / Sonnet / 건너뛰기. 기본값: Opus.
  4. 사용자의 선택 사항만 포함된 .claude/rules/code-review.md를 작성합니다. 사용자가 기본값을 수락한 결정 사항은 생략합니다 — 스킬의 기본 제공 동작이 이를 처리합니다.
  5. 사용자가 CI 통합을 선택한 경우: a. assets/code-review.yml (이 스킬에 포함됨)을 워크플로우 템플릿으로 읽습니다. b. 사용자가 다른 모델을 선택한 경우 --model opus를 --model <선택한-모델>로 대체합니다. c. .github/workflows/code-review.yml이 프로젝트에 이미 존재하는 경우, diff를 보여주고 덮어쓰기 전에 확인을 요청합니다. d. 워크플로우를 .github/workflows/code-review.yml에 작성합니다 (.github/workflows/가 없으면 생성합니다). e. 사용자에게 CLAUDE_CODE_OAUTH_TOKEN을 저장소 시크릿으로 추가하라고 알립니다:
    • 로컬에서 토큰 생성: claude setup-token
    • GitHub 저장소 → 설정 → 시크릿 및 변수 → Actions → 새 저장소 시크릿에 추가

인간에게 위임할 사항 (CI 통합): 사용자는 CLAUDE_CODE_OAUTH_TOKEN 시크릿을 직접 추가하고 브랜치 보호 규칙이 액션이 리뷰 댓글을 게시할 수 있도록 허용하는지 확인해야 합니다. 설정에서 이를 확인하거나 구성할 수 없습니다.

사용자가 모든 기본값을 수락하고 선택한 사항이 없으면, 규칙 파일이 필요하지 않음을 확인하고 중단합니다.


단계 0: 이전 리뷰 상태 (재리뷰)

리뷰를 시작하기 전에, 이미 어떤 논의가 있었는지 확인합니다.

이 변경 사항에 대한 기존 리뷰 대화를 수집합니다:

  • 모든 인라인 토론 스레드, 답변 및 해결/미해결 상태 포함 — 자신의 것과 인간 리뷰어의 것 모두.
  • 자신의 이전 리뷰 요약 (숨겨진 마커로 식별 가능 — 6단계 참조).

프로젝트에 플랫폼 게시 메커니즘이 정의되어 있으면 이를 사용하여 상태를 가져옵니다. 플랫폼 메커니즘이 구성되지 않은 경우 (예: 리뷰가 stdout으로 전송되는 경우), 첫 번째 리뷰로 간주하고 요약에 이전 리뷰 상태를 확인할 수 없었다고 기록합니다.

이전 리뷰 상태가 없으면 첫 번째 리뷰입니다 — 1단계로 진행하고 6단계의 재리뷰 단계를 건너뜁니다.

모든 스레드를 읽되, 자신의 스레드에만 행동합니다. 인간 리뷰어의 스레드는 리뷰에 정보를 제공합니다 — 인간 리뷰어가 이미 제기한 우려 사항을 답변 여부와 관계없이 다시 제기하지 마십시오. 자신의 스레드는 게시하는 각 발견 사항에 포함된 숨겨진 마커(6단계 참조)로 식별하며, 게시 계정으로 식별하지 마십시오 — 계정은 CI와 로컬 실행 간에 다릅니다.

자신의 이전 발견 사항 각각을 분류하고 그 처분을 리뷰의 나머지 부분에 반영합니다:

  1. 수정 푸시됨 — 작성자가 응답하여 코드를 변경했습니다. 현재 diff에서 수정 사항을 확인합니다. 실제로 수정됨: 스레드에서 확인했다고 답변하고(예: "<리비전>에서 수정 확인됨") 스레드를 해결합니다. 수정되었다고 주장했지만 실제로 수정되지 않음: 아직 부족한 점을 설명하는 답변을 남기고 스레드를 열어둡니다.
  2. 답변됨 — 작성자가 발견 사항을 설명하거나 반박했습니다. 작성자의 응답은 권위적입니다; 다시 제기하지 마십시오. 이를 인정하는 답변을 작성하고 스레드를 해결합니다.
  3. 여전히 열림 — 응답 없음, 수정 없음. 중복 댓글을 게시하지 마십시오. 스레드를 건드리지 않고 새 요약의 "이전 발견 사항" 아래에 나열합니다.

이 리뷰의 진정한 새로운 발견 사항은 6단계에서 평소와 같이 게시됩니다.

프로젝트에서 재리뷰 스레드 처리 모드(설정 참조)를 구성한 경우 이를 따릅니다 — 일부 팀은 스레드 해결을 인간에게 맡깁니다. 기본값은 답변 및 해결입니다.

인간에게 위임할 사항: 분쟁 중재 — 작성자가 반박하는 경우, 이 스킬은 물러납니다; 논쟁이 된 사항이 여전히 중요하다면 인간 리뷰어가 결정을 내려야 합니다. 자동 리뷰어가 스레드를 해결할 수 있는지 여부는 팀 규칙에 달려 있습니다 — 인간이 소유합니다 (설정을 통해 구성).


단계 1: 문제 검증

여기서 시작합니다 — 코드 한 줄을 읽기 전에.

두 가지 질문을 합니다:

  1. 이 코드가 실제로 해결하려는 문제를 해결하는가?
  2. 이 개선 사항을 릴리스하면 프로젝트 전체의 가치가 높아지는가?

둘 중 하나라도 '아니오'라면 — 중단합니다. 코드를 리뷰하지 마십시오. 무엇을 구축할지 결정하는 사람에게 연락하여 논의합니다. 프로덕션에서 살아남지 못할 코드를 리뷰하는 것은 시간 낭비입니다.

이러한 질문에 답변하기 위해: 연결된 이슈 또는 티켓, 지원 문서 및 관련 토론을 읽습니다. 프로젝트에서 관련 이슈 또는 티켓을 찾는 방법(작업 관리 통합, 브랜치 이름 지정 규칙)을 정의한 경우 이를 따릅니다. 이슈가 없거나 통합이 구성되지 않은 경우 PR 제목과 설명을 진실의 원천으로 사용합니다. diff가 설명된 내용을 그럴듯하게 다루고 있는지 확인합니다.

인간에게 위임할 사항: 실제로 기능을 실행하고 사용자 관점에서 작동하는지 확인하는 것. 명시된 문제와 diff 간의 논리적 정렬은 검증할 수 있습니다. 인간이 실제로 작동하는지 확인해야 합니다.


단계 2: 빌드 및 실행 가능성

  • 빌드가 통과되었는가? 그렇지 않으면 리뷰를 일시 중지합니다. 빌드가 깨지면 신뢰할 수 없습니다. 새 변경 사항이 올바르게 작동하더라도 다른 것이 깨질 수 있습니다. 빌드 실패가 무해하다고 가정하지 마십시오.
  • 코드가 작성자 컴퓨터 외부 어딘가에서 실행되고 있는가? 프로덕션 환경이 이상적입니다; 스테이징 환경 또는 다른 개발자 컴퓨터도 허용 가능한 스모크 테스트입니다.
  • 코드를 실행하기 위해 누군가에게 도움을 요청해야 했는가? 그렇다면 문서가 누락되었거나 설정을 자동화해야 하거나 — 또는 둘 다입니다.

프로젝트에서 빌드 상태 확인 방법(CI 시스템, 상태 확인)을 정의한 경우 이를 사용합니다. 그렇지 않으면 변경 컨텍스트에서 사용 가능한 빌드 표시기를 확인합니다.

인간에게 위임할 사항: 로컬 또는 스테이징에서 코드를 실행하고, 사용할 사람의 관점에서 기능을 시험해보고, 유용성, 오류 처리 또는 놀라운 동작에 대한 우려를 제기하는 것.


단계 3: 테스트 감사

수정되거나 삭제된 테스트는 위험 신호입니다 — 다른 것보다 먼저 조사하십시오.

기존 테스트에 대한 변경 사항이 보이면 속도를 늦추십시오. 이유를 질문하십시오: 왜 수정되었는가? 의견을 형성하기 전에 이유를 이해하십시오.

많은 수정 사항은 비교적 무해합니다 — 잘못된 동작에 대한 테스트 제거, 테스트 세분성 변경, 또는 이 PR이 대체하는 것으로 교체. 이 중 어느 것도 본질적으로 위험하지는 않지만, 생각이 필요합니다. 핵심 질문은: 이 수정 사항이 코드베이스의 다른 부분이 의존하는 계약을 변경하는가?

  • 격리되고 자체 포함된 코드에 대한 테스트 변경 = 상대적으로 안전
  • 공유되거나 재사용되는 코드에 대한 테스트 변경 = 더 높은 위험; 명시적 정당성 필요

diff만으로 질문에 답할 수 없으면 잠시 멈추고 작성자에게 물어보십시오. 이러한 대화는 공유된 이해를 구축하고 잘못된 가정이 실제 문제를 일으키기 전에 표면화합니다.


단계 4: 적용 범위 평가

변경 사항을 분류한 다음 위험에 적합한 기대치를 적용합니다. 통과하는 테스트 스위트는 그것이 설명하는 동작만큼만 좋습니다 — 테스트를 검토하는 프로세스를 자동화할 수는 없습니다.

버그 수정

모든 버그 수정에는 회귀 테스트가 수반되어야 합니다. 최소한 버그 보고서에 설명된 경로를 따르는 하나의 고급 승인 테스트 — 내부 실패의 직접적인 트리거가 아닌 실제 사용자가 취할 수 있는 작업에 매핑됩니다.

단위 테스트는 복잡하거나 심각한 경우 승인 테스트를 보완하여, 나중에 무언가 깨졌을 때 더 세분화된 피드백을 제공해야 합니다.

또한 탄광 속의 카나리아 패턴을 찾으십시오: 이 버그가 진정으로 고유한가, 아니면 더 깊고 광범위한 문제의 신호인가? 코드베이스의 다른 곳에 유사한 패턴이 있는지 확인하십시오. 있다면 티켓을 작성하십시오 — 지금 모두 수정할 필요는 없지만 표면화하는 것이 주요 기여입니다.

새 기능

제로 테스트 사고 실험을 적용합니다: 다음 조건이 모두 충족되면 최소한의 테스트 적용 범위가 허용됩니다:

  1. 변경 사항이 거의 전적으로 새 코드로 구성되며, 인프라, 프레임워크, 라이브러리 및 일반 데이터 액세스 객체에만 의존함
  2. 새 기능이 자체 영역(자체 페이지, 네임스페이스 또는 엔드포인트)으로 격리됨
  3. 새로운 시스템 차원의 부작용을 도입하지 않음 (변경된 종속성, 구성 또는 공유 리소스에 대한 부하 없음)
  4. 로드맵에서 다른 기능을 위한 빌딩 블록으로 사용될 계획이 없음
  5. 다른 기능을 함께 묶는 워크플로우 체인의 중간 단계가 아님
  6. 실패가 외부로 탈출하여 다른 곳에서 불안정을 일으킬 수 없음
  7. 상상할 수 있는 모든 실패가 이해 관계자에게 수용 가능하고 심각한 피해를 초래하지 않음
  8. 테스트를 나중에 허용할 수 없는 비용이나 지연 없이 작성할 수 있음

충족되지 않는 각 조건에 대해, 해당 위험을 구체적으로 해결하는 테스트를 기대합니다. 실패가 허용되고 완전히 격리되며 나중에 테스트하기 쉬운 기능은 큰 위험이 아닙니다. 기존 워크플로우에 연결되고, 다른 곳에서 실패를 일으킬 수 있으며, 또는 그 위에 구축될 기능은 그렇지 않습니다.

개선: 추가 기능

기존 기능과 함께 존재하는 새 코드. 위의 새 기능 기준을 적용한 다음 더 나아갑니다: 기존 기능 옆에 있기 때문에 실패 격리가 주요 관심사입니다.

추가 기능의 실패가 기존 기능을 중단시킬 수 있는가? 최악의 실패 시나리오를 생각해 보십시오. 엣지 케이스와 경계 조건이 다루어졌는가?

개선: 확장

기존 구성 요소를 재사용하여 기존 동작을 기반으로 구축합니다. 새 코드를 평가하기 전에 재사용되는 항목에 대한 소규모 감사를 수행합니다:

  • 재사용되는 구성 요소에 테스트가 있는가?
  • 비즈니스 및/또는 코드 수준에서 문서화되었는가?
  • 재사용을 염두에 두고 설계되었는가, 아니면 원래 목적을 넘어 확장되고 있는가?
  • 최근 또는 해결되지 않은 버그 보고서에 나타났는가?
  • 변경될 가능성이 얼마나 되는가? 변경되면 이 확장이 깨질 것인가?

이 작업에 몇 분 이상을 소비할 필요는 없습니다 — 사고 실험이지 심층 조사가 아닙니다. 그러나 알려지고 계산된 위험이 항상 놀라움보다 낫습니다. 추적할 가치가 있는 항목에 대한 티켓을 작성하십시오.

개선: 정제

기존 시스템 동작을 수정합니다. 가장 높은 위험 범주. 먼저 위의 확장 리뷰의 모든 것을 적용합니다. 그런 다음 더 나아갑니다.

수정 중인 코드에 의존하는 모든 기능을 찾으십시오. 각 종속 항목은 잠재적으로 영향을 받습니다. 이상적으로는 각각을 전체 리뷰 프로세스에 통과시키겠지만 실제로는 거의 불가능합니다. 최소한: 종속 항목을 식별하고, 해당 테스트가 여전히 유효한지 확인하고, 인간 리뷰어가 수동으로 테스트할 수 있도록 전체 목록에 플래그를 지정합니다.


단계 5: 프로젝트별 검사

프로젝트에서 코딩 규칙, 아키텍처 패턴 또는 스타일 규칙을 정의하는 경우, diff에 적용하고 위반 사항을 확인합니다.

프로젝트 규칙이 정의되지 않은 경우, diff 내의 일관성 없는 이름 지정, 변경으로 인해 도입된 죽은 코드, 명백한 중복, 시스템 경계에서의 누락된 오류 처리, 보안 문제(정리되지 않은 입력, 하드코딩된 시크릿, 지나치게 광범위한 권한)를 확인합니다.

프로젝트에서 플랫폼별 게시 메커니즘(리뷰 게시 방법, 인라인 댓글 형식 등)을 정의한 경우 다음 단계에서 이를 따릅니다.


단계 6: 위험 평가 및 출력

위험 수준 할당:

  • 낮음 — 격리된 변경, 공유 코드 건드리지 않음, 테스트가 깨끗하고 변경 유형에 적합함
  • 중간 — 기존 동작 또는 공유 코드를 건드리지만, 잘 테스트되었고 종속성이 이해됨
  • 높음 — 종속 항목이 있는 공유 구성 요소 수정, 변경 유형에 대해 테스트가 변경되거나 누락됨, 보안 또는 인증 관련

리뷰 요약 생성에는 다음이 포함됩니다:

  • 컨텍스트: PR이 무엇을 하는지, 어떤 문제를 해결하는지
  • 좋은 점
  • 발견된 우려 사항 (일반 및 줄 수준, 해당하는 경우)
  • 재리뷰 시: 새 우려 사항 전에 각 이전 발견 사항과 상태(해결됨(수정 확인됨), 답변됨(작성자 응답 수락됨), 또는 여전히 열림)를 나열하는 이전 발견 사항 섹션. 첫 리뷰에서는 이 섹션을 생략합니다.
  • 위험 수준 및 근거

인간 리뷰어를 위한 요약 생성 — 구조화된 형식으로, 인간 리뷰어가 집중해야 할 사항을 명확히 전달합니다.

프로젝트에서 출력 형식을 정의한 경우 이를 사용합니다. 그렇지 않으면 다음 구조를 사용합니다:

## 코드 리뷰: [PR 제목]

**위험 수준:** [낮음/중간/높음]

### 컨텍스트
[PR 설명 및 해결하는 문제]

### 좋은 점
- [좋은 점 목록]

### 우려 사항
[일반 및 줄 수준 우려 사항]

### 이전 발견 사항 (재리뷰 시에만)
- [#파일:줄] [상태: 해결됨/답변됨/열림] — [요약]

---
*리뷰 ID: [고유 식별자]* <!-- 리뷰-ID: ... -->

인간에게 위임할 사항: 모든 우려 사항이 실제로 유효하고 조치가 필요한지 최종 판단하는 것. 이 스킬은 코드 냄새와 불일치를 식별합니다. 인간 리뷰어가 컨텍스트, 비즈니스 우선 순위 및 팀 규칙에 따라 결정합니다.

관련 스킬