Claude Code로 코드 리뷰를 한 번에 끝내는 법

/simplify + 서브에이전트, 코드 리뷰를 한 번에 끝내는 법

Claude Code로 코드를 작성하고 나면 항상 따라오는 과정이 있죠. 코드 리뷰입니다. 기능은 동작하지만, 불필요한 복잡도는 없는지, 팀 컨벤션은 지켰는지, 보안 이슈는 없는지 확인해야 해요.

그동안 저는 이 과정을 /simplify와 커스텀 서브에이전트로 따로따로 처리해왔는데요, 이 둘을 한 번에 실행할 수 있는 방법이 있습니다. 세 가지 접근법을 정리해봤어요.

/simplify가 하는 일

/simplify는 Claude Code v2.1.63에 추가된 빌트인 커맨드입니다. 실행하면 git diff로 최근 변경사항을 감지한 뒤, 3개의 리뷰 에이전트를 병렬로 돌려요.

• 재사용성 검토 — 중복 로직, 추출 가능한 공통 코드
• 품질 검토 — 코드 스멜, 네이밍, 구조적 문제
• 효율성 검토 — 불필요한 연산, 최적화 가능한 패턴

세 에이전트가 동시에 돌고, 결과를 종합해서 유효한 이슈는 직접 수정하고 오탐은 건너뜁니다. 설정 없이 바로 쓸 수 있다는 게 장점이에요.

다만 검토 관점이 위 세 가지로 고정되어 있어요. 팀 고유의 컨벤션이나 보안 정책 같은 건 /simplify만으로는 커버하기 어렵습니다.

서브에이전트를 통한 코드 리뷰

팀마다 다른 리뷰 기준이 있잖아요. 이런 기준은 .claude/agents/에 서브에이전트로 정의해두면 됩니다.

.claude/agents/
├── security-reviewer.md
├── convention-checker.md

각 에이전트 파일에는 YAML 프론트매터로 이름, 설명, 사용 가능한 도구, 모델을 지정하고, 본문에 구체적인 리뷰 지침을 작성해요. 이렇게 정의해두면 Claude가 작업 맥락에 따라 자동으로 적절한 에이전트에 위임하거나, @security-reviewer처럼 직접 호출할 수도 있습니다.

핵심은 이 에이전트들이 CLAUDE.md의 규칙을 자동으로 상속받는다는 점이에요. 팀 공통 규칙은 CLAUDE.md에, 리뷰 전용 규칙은 각 에이전트 파일에 분리해서 관리할 수 있습니다.

문제: 두 번 실행 필요

여기까지는 좋은데, 실제 워크플로우에서는 번거롭습니다.

1. /simplify 실행 → 코드 정리 완료 대기
2. 서브에이전트 리뷰 요청 → 결과 대기

매번 두 단계를 수동으로 실행해야 해요. PR 올리기 전에 이걸 빼먹는 날이 생기기 마련이죠.

해결: 하나로 묶는 세 가지 방법

방법 1. 커스텀 슬래시 커맨드 — 명시적으로 실행

.claude/commands/full-review.md 파일 하나를 만들면 됩니다.

# 통합 코드 리뷰

$ARGUMENTS 에 대한 전체 코드 리뷰를 수행합니다.
인자가 없으면 최근 변경사항을 대상으로 합니다.

## Step 1: /simplify 실행

최근 변경 코드에 대해 /simplify를 실행합니다.
코드 재사용성, 품질, 효율성에 대한 자동 정리를 수행합니다.

## Step 2: 서브에이전트 병렬 리뷰

/simplify 완료 후, 아래 서브에이전트들을 병렬로 실행합니다:

1. **security-reviewer** — 보안 취약점 검토
2. **convention-checker** — 팀 컨벤션 준수 여부 확인

## Step 3: 통합 리포트

모든 결과를 종합하여 심각도별로 보고합니다:

- 🔴 Critical — 즉시 수정 필요
- 🟡 Warning — 권장 수정
- 🟢 Info — 개선 제안

이제 터미널에서 이렇게 실행하면 돼요.

/full-review
/full-review src/auth/

커맨드 안에서 여러 독립적 작업을 요청하면 Claude가 서브에이전트를 병렬로 자동 실행합니다. /simplify로 코드를 먼저 정리하고, 정리된 코드에 대해 서브에이전트들이 심층 리뷰를 수행하는 구조예요.

최종 디렉토리 구조는 이렇게 됩니다.

your-project/
├── .claude/
│   ├── commands/
│   │   └── full-review.md        ← 통합 리뷰 커맨드
│   └── agents/
│       ├── security-reviewer.md  ← 보안 전문 에이전트
│       └── convention-checker.md ← 컨벤션 체크 에이전트
├── CLAUDE.md                     ← 팀 공통 규칙
└── src/

.claude/commands/는 git에 커밋할 수 있으니 팀 전체가 동일한 리뷰 프로세스를 공유하게 돼요.

가장 제어가 명확한 방법입니다. 실행 시점을 제가 정하고, 흐름도 눈에 보이거든요.

방법 2. Hooks — /simplify 끝나면 자동으로 이어서 실행

매번 커맨드를 치는 것도 귀찮다면 Hooks를 쓸 수 있어요. Hooks는 Claude Code의 특정 이벤트에 반응해서 외부 스크립트를 실행하는 기능입니다.

아이디어는 간단해요. /simplify가 끝나는 시점을 감지해서, 서브에이전트 리뷰를 자동으로 트리거하는 거예요. .claude/settings.json에 아래처럼 설정합니다.

{
  "hooks": {
    "SubagentStop": [
      {
        "matcher": "code-simplifier",
        "command": "echo '✅ simplify 완료. 서브에이전트 리뷰를 시작합니다.'"
      }
    ]
  }
}

SubagentStop 이벤트는 서브에이전트가 작업을 마칠 때 발생해요. matcher로 code-simplifier를 지정하면 /simplify 내부의 에이전트가 끝났을 때만 반응합니다.

현재 Hooks는 셸 커맨드 실행 수준이라 “알림 → 다음 액션 트리거” 정도의 역할이에요. /simplify 후 자동으로 서브에이전트 리뷰까지 완전히 체이닝하려면 방법 1의 커스텀 커맨드와 조합하는 게 현실적입니다. 다만 Hooks 자체가 계속 발전하고 있는 기능이라, 향후 더 정교한 자동화가 가능해질 여지는 있어요.

방법 3. CLAUDE.md에 정책으로 명시 — 가장 간단한 방법

별도 파일을 만들 필요 없이, CLAUDE.md에 리뷰 정책을 적어두는 방법도 있어요.

## 코드 리뷰 정책

코드 리뷰를 요청받으면 항상 다음 순서를 따릅니다:

1. 먼저 /simplify를 실행하여 코드를 정리합니다.
2. 이후 security-reviewer, convention-checker 서브에이전트를
   병렬로 실행하여 심층 리뷰합니다.
3. 결과를 심각도별로 통합 보고합니다.

Claude는 매 세션 시작 시 CLAUDE.md를 읽어요. 위 규칙이 있으면 “코드 리뷰해줘”라고만 말해도 /simplify → 서브에이전트 리뷰 → 통합 리포트 순서가 자동으로 작동합니다.

장점은 설정이 가장 간단하다는 거예요. 커맨드 파일이나 Hooks 설정 없이 CLAUDE.md 몇 줄이면 됩니다. 단점은 Claude의 판단에 의존한다는 점이에요. 항상 동일한 순서로 실행된다고 보장하기는 어렵습니다. 자연어 지시이기 때문에 세션마다 미묘하게 다를 수 있거든요.

확실한 재현성이 필요하면 방법 1, 간편함이 우선이면 방법 3이 맞아요.

어떤 방법을 선택할까

개인적으로는 방법 3으로 시작해서 방법 1로 정착하는 흐름을 추천해요. 먼저 CLAUDE.md에 정책을 적어서 워크플로우가 맞는지 확인하고, 안정화되면 커스텀 커맨드로 굳히는 식입니다.

주의할 점

병렬로 여러 서브에이전트를 돌리면 토큰 소모가 빠릅니다. Pro 플랜이라면 한 세션에서 복잡한 멀티에이전트 리뷰를 반복 실행하면 금방 한도에 도달할 수 있어요. 리뷰 대상 범위를 적절히 좁히거나, 중요한 PR에만 전체 리뷰를 돌리는 식으로 조절하는 게 현실적입니다.

정리

/simplify는 빠른 1차 정리, 서브에이전트는 팀 맞춤 심층 리뷰. 각자 잘하는 영역이 다릅니다. 이 둘을 묶는 방법은 세 가지예요. 커스텀 커맨드로 명시적으로, Hooks로 자동으로, CLAUDE.md로 간편하게. 팀 상황에 맞는 방법을 골라서 PR 전 리뷰를 한 단계로 줄여보세요.