[AI] 클로드코드 코드 리뷰 기능 (claude code, /code-review)

/code-review 이란?

• 여러 명의 AI 전문가가 협업하는 멀티 에이전트 오케스트레이션 방식으로 작동하여 코드의 품질과 보안, 논리적 결함을 심층적으로 검토
  • 자율적 분석: 변경된 코드만 보는 것이 아니라, 전체 프로젝트 맥락을 이해하고 리뷰를 수행함
  • 높은 신뢰도: 여러 에이전트가 교차 검증하여 오탐을 줄이고 실질적인 개선안을 제시함

주요 작동 메커니즘 (Agent Teams)

리뷰 명령 시 각기 다른 전문성을 가진 에이전트들이 병렬로 투입됨

• 규정 준수 에이전트: CLAUDE.md에 정의된 스타일 가이드 및 아키텍처 규칙 준수 여부 확인
• 버그 탐지 에이전트: 논리적 오류, 엣지 케이스, 잠재적 메모리 누수 등 탐색
• 컨텍스트 분석 에이전트: git blame 및 히스토리 분석을 통해 과거 수정 의도와의 충돌 여부 검토
• 최종 검증 에이전트: 발견된 이슈들의 우선순위를 정하고 신뢰도가 높은 항목만 필터링하여 보고

주요 기능 및 활용 패턴

기능	상세 설명	비고
CLAUDE.md 연동	프로젝트 특유의 컨벤션을 학습하여 맞춤형 리뷰 수행	"Early return 사용" 등 명시 가능
인라인 피드백	--comment 플래그 사용 시 GitHub PR에 직접 댓글 작성	CI/CD 연동 가능
심층 로직 검토	단순 린터가 잡지 못하는 인증/인가 로직이나 성능 병목 파악	대규모 PR에서 높은 효율

 

컨텍스트 비용 및 효율화 (Context Management)

/code-review는 고성능 분석을 수행하므로 컨텍스트 소모와 비용 관리가 중요함

• 고비용 구조: 프로젝트 전체 정보를 로드하므로 대규모 코드베이스에서는 토큰 소모가 큼
• 최적화 팁: * CLAUDE.md 정제: 리뷰 지침을 핵심 위주로 요약하여 매 요청 시 소모되는 컨텍스트를 줄임
  • 범위 지정: 전체 리뷰 대신 특정 디렉토리나 변경 파일 위주로 범위를 한정하여 실행
  • Subagent 활용: 무거운 분석 작업은 별도 Subagent 루프로 분리하여 메인 세션의 메모리를 보호함

사용방법

• 프로젝트 폴더에 CLAUDE.md라는 파일 생성
• 내용 작성

ex)

"SwiftUI View는 200줄 이하 유지함", "강제 언래핑 금지함"

• 더욱 체계적으로는 아래처럼 작성

# CLAUDE.md

이 파일은 Claude Code가 프로젝트를 이해하고 코드 리뷰를 수행할 때 참고하는 지침 파일입니다.

## 프로젝트 개요

Swift로 작성된 간단한 유저 관리 모듈입니다.
Claude Code의 코드 리뷰 기능 데모를 위해 작성되었습니다.

## 코드 리뷰 기준

코드 리뷰 시 아래 항목을 반드시 점검하세요.

### 보안
- 비밀번호는 절대 평문으로 저장하거나 로그에 출력하지 않습니다.
- 하드코딩된 credentials(비밀번호, API 키 등)은 허용하지 않습니다.
- 민감한 정보는 Keychain 또는 환경변수를 통해 관리합니다.

### 안전성
- 배열 접근 시 반드시 범위(bounds) 체크를 수행합니다.
- 강제 언래핑(`!`)은 사용하지 않으며, `guard let` / `if let`을 사용합니다.
- 외부 입력값은 항상 검증합니다.

### Swift 코드 스타일
- 반복문보다 `filter`, `map`, `first(where:)` 등 고차 함수를 우선 사용합니다.
- `var`보다 `let`을 기본으로 사용합니다.
- 접근 제어자(`private`, `internal`)를 명시합니다.

### 일반 품질
- 함수는 단일 책임 원칙(SRP)을 따릅니다.
- 불필요한 `print` 디버그 로그는 제거합니다.
- 테스트 가능한 구조로 작성합니다.

## 리뷰 명령어

```
/review
```

위 명령어를 실행하면 Claude Code가 이 파일의 기준에 따라 코드를 리뷰합니다.

• 코드리뷰 대상 예제 코드 준비

// UserManager.swift

import Foundation

// 유저 모델
struct User {
    var id: Int
    var name: String
    var email: String
    var age: Int
    var password: String  // 평문 비밀번호 저장
}

class UserManager {
    var users: [User] = []
    var adminPassword = "admin1234"  // 하드코딩된 관리자 비밀번호

    // 유저 추가
    func addUser(id: Int, name: String, email: String, age: Int, password: String) {
        let user = User(id: id, name: name, email: email, age: age, password: password)
        users.append(user)
        print("Added user: \(name), password: \(password)")  // 비밀번호 로그 출력
    }

    // 이메일로 유저 검색
    func findUser(email: String) -> User? {
        for user in users {
            if user.email == email {
                return user
            }
        }
        return nil
    }

    // 나이로 필터링
    func getUsersByAge(minAge: Int, maxAge: Int) -> [User] {
        var result: [User] = []
        for user in users {
            if user.age >= minAge && user.age <= maxAge {
                result.append(user)
            }
        }
        return result
    }

    // 유저 삭제 (인덱스로)
    func deleteUser(at index: Int) {
        users.remove(at: index)  // 범위 체크 없음, 크래시 위험
    }

    // 전체 유저 출력
    func printAllUsers() {
        for i in 0..<users.count {
            print("[\(i)] \(users[i].name) - \(users[i].email) - pw: \(users[i].password)")
        }
    }

    // 유저 수 반환
    func count() -> Int {
        return users.count
    }
}

// 사용 예시
let manager = UserManager()
manager.addUser(id: 1, name: "Alice", email: "alice@example.com", age: 28, password: "secret123")
manager.addUser(id: 2, name: "Bob", email: "bob@example.com", age: 35, password: "qwerty!")
manager.printAllUsers()

let found = manager.findUser(email: "alice@example.com")
print("Found: \(found?.name ?? "없음")")

• 클로드코드에 `/code-review` 입력하면 아래처럼 분석 완료

* 참고

- https://code.claude.com/docs/ko/code-review