본 문서는 Claude Code를 위한 포괄적이고 모듈화된 코드 리뷰 스킬인 "Code Review Skill"에 대해 상세히 설명합니다. 이 스킬은 AI 기반 코드 리뷰를 구조화되고 일관성 있으며 전문가 수준의 프로세스로 전환하는 것을 목표로 합니다.

핵심 방법론 (Core Methodology)

이 스킬의 핵심 방법론은 두 가지 주요 기능으로 구성됩니다: Progressive Disclosure (점진적 공개)와 Four-Phase Review Process (4단계 리뷰 프로세스).

1. Progressive Disclosure (점진적 공개):

이 스킬은 컨텍스트 윈도우(context window) 사용을 최소화하면서 광범위한 가이드를 제공하기 위해 Progressive Disclosure 방식을 채택합니다.

• Core Skill Loading: 스킬 활성화 시 약 190라인의 핵심 스킬 파일인 SKILL.md만 로드됩니다. 이 파일은 코드 리뷰의 전반적인 구조와 지침을 포함합니다.
• On-Demand Language Guides: 특정 언어 또는 프레임워크에 대한 리뷰 요청이 있을 때만 해당 언어 가이드 파일(예: reference/react.md, reference/java.md)이 동적으로 로드됩니다. 각 언어 가이드는 200~1,000라인의 상세한 규칙과 체크리스트를 포함하며, 11개 이상의 언어 및 프레임워크(React, Vue, Java, Python, Go, Rust, C, C++, TypeScript, CSS/Less/Sass, Qt)와 아키텍처 및 성능 리뷰 가이드(architecture-review-guide.md, performance-review-guide.md)를 지원합니다. 이를 통해 불필요한 정보를 로드하여 컨텍스트 윈도우를 낭비하는 것을 방지하고, 필요한 정보만을 효율적으로 제공합니다. 예를 들어, "Review this React component"와 같은 프롬프트가 주어지면 react.md 가이드를 로드하여 React Hooks, Server Components, Suspense 패턴 등을 확인하고, "Security review of this Go service"는 go.md와 security-review-guide.md를 함께 로드합니다.

2. Four-Phase Review Process (4단계 리뷰 프로세스):

이 스킬은 코드 리뷰를 체계적이고 일관된 방식으로 수행하기 위한 명확한 4단계 워크플로우를 제공합니다.

• Phase 1 - Context Gathering (컨텍스트 수집): Pull Request(PR)의 범위, 연결된 이슈, 그리고 코드 변경의 의도를 이해하는 단계입니다. 이는 리뷰어가 변경 사항의 목적과 배경을 정확히 파악하여 전체적인 리뷰 방향을 설정하는 데 중요합니다.
• Phase 2 - High-Level Review (고수준 리뷰): 아키텍처적 영향, 성능 영향, 그리고 테스트 전략 등 코드베이스 전반에 걸친 광범위한 측면을 검토하는 단계입니다. 이 단계에서는 큰 그림에서 잠재적인 문제나 개선 사항을 식별합니다.
• Phase 3 - Line-by-Line Analysis (코드 라인별 분석): 실제 코드 라인을 분석하여 로직의 정확성, 잠재적 보안 취약점, 코드 유지보수성, 그리고 엣지 케이스(edge cases) 처리 등을 면밀히 검토하는 단계입니다. 이 단계에서 가장 세부적인 코드 품질 검사가 이루어집니다.
• Phase 4 - Summary & Decision (요약 및 결정): 리뷰 결과를 구조화된 피드백 형태로 제공하고, PR의 승인 상태를 결정하며, 필요한 후속 조치(action items)를 명확히 정의하는 단계입니다. 이 단계는 리뷰의 결과물을 종합하고 실제적인 결정을 내리는 마무리 과정입니다.

주요 특징 및 세부 사항

• Severity Labeling (심각도 라벨링): 모든 발견 사항은 6가지 심각도 라벨 중 하나로 분류됩니다: blocking (합병 전 필수 수정), important (수정 권고, 상황에 따라 합병 차단), nit (사소한 스타일 또는 선호 문제), suggestion (고려할 만한 선택적 개선 사항), learning (교육적 참고 사항), praise (칭찬).
• Security-First (보안 우선): 각 언어 생태계에 특화된 보안 체크리스트를 포함하여 보안 측면을 강조합니다.
• Collaborative Tone (협력적 어조): 명령 대신 질문을, 강제 대신 제안을 사용하여 건설적인 피드백 문화를 지향합니다.
• Automation Awareness (자동화 인식): 인간의 검토가 필요한 부분과 린터(linters)나 자동화 도구로 처리할 수 있는 부분을 명확히 구분합니다.
• 세부 언어별 하이라이트: 각 언어 가이드는 해당 언어의 최신 버전 및 주요 특징(예: React 19의 useActionState, useFormStatus, useOptimistic; Java 17/21의 Virtual Threads, Spring Boot 3의 ProblemDetail; Rust의 Ownership 및 unsafe 코드 리뷰 요건; Go의 Goroutine lifecycle 및 context.Context 전파; C/C++의 메모리 안전 및 RAII)에 대한 심층적인 지침을 제공합니다.
• 저장소 구조: code-review-skill/ 디렉토리 내에 SKILL.md (핵심 스킬), reference/ (언어별 가이드), assets/ (체크리스트, 템플릿), scripts/ (PR 복잡성 분석기) 등으로 구성되어 체계적인 파일 관리를 보여줍니다.

이 스킬은 클로드 코드 환경에 쉽게 설치하여 git clone 명령으로 직접 사용할 수 있으며, .claude/commands/에 사용자 정의 명령어를 생성하여 특정 리뷰 유형을 자동화할 수도 있습니다.