# 변경한 코드를 읽기 전용 검토 전담에게 맡기기 (Claude Code 서브에이전트)
id: claude-code-subagent-code-review · 종류: 워크플로 · 상태: 검수 대기 (사람 확인 전) · 주제: 개발
주소: https://opencurrent.ai/w/claude-code-subagent-code-review
기준일: 2026-11-15 (여기서 고친 날)
도구: Claude Code
평가 점수: 32/100 (확인 없음 · 검수 대기)

리뷰를 맡겨도 하던 대화가 길어지지 않고, 검토 전담은 읽기만 하므로 리뷰 중에 코드가 바뀔 걱정이 없습니다.

설명: 검토 기준을 담은 code-reviewer 정의 파일을 하나 만들고, 필요하면 Claude Code를 다시 시작합니다. 이후 최근 변경을 검토해 달라고 하면 검토 전담이 따로 읽고 결과만 돌려줍니다.

준비물: Claude Code 설치된 프로젝트 폴더 · 검토할 코드 변경분

본문:

## 준비

- Claude Code가 설치된 프로젝트 폴더
- 검토할 코드 변경분

### 1. 저장 위치 선택

팀과 함께 쓰려면 프로젝트의 `.claude/agents/`(버전 관리 대상)에, 내 모든 프로젝트에서 쓰려면 `~/.claude/agents/`에 둡니다. 이름이 겹치면 프로젝트 쪽이 우선합니다.

### 2. code-reviewer 정의 파일 작성

`.claude/agents/code-reviewer.md`에 아래 내용을 저장합니다. 직접 써도 되고 Claude에게 맡겨도 됩니다. 본문이 서브에이전트의 시스템 프롬프트가 되며, 머리말에는 name과 description 두 칸이 꼭 있어야 합니다.

```bash
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
```

### 3. 필요하면 세션 다시 시작

보통 몇 초 안에 반영됩니다. agents 폴더에 처음 파일을 만들었다면 Claude Code를 다시 시작합니다. 프롬프트에 `@`를 입력해 목록에 code-reviewer (agent)가 보이면 준비된 것입니다.

### 4. 최근 변경 검토 요청

@-멘션을 쓰면 그 서브에이전트가 확실히 실행됩니다. 서브에이전트는 대화 기록을 보지 못하므로 검토 범위를 메시지에 적습니다.

```prompt
@"code-reviewer (agent)" 최근 변경한 인증 관련 코드 검토해 줘
```

품질·보안·모범 사례 기준의 구체적인 지적이 돌아옵니다. `git status`로 파일이 바뀌지 않았는지도 확인합니다.

### 5. 자동 위임 설정 (선택)

description에 'use proactively' 같은 문구를 더하면 Claude가 알맞은 작업에서 스스로 맡깁니다. 세션 전체를 검토 전담으로 시작하려면 아래 명령을 씁니다.

```bash
claude --agent code-reviewer
```

이 세션에서 파일 수정 도구가 막히는지 확인합니다.

## 주의

- 서브에이전트는 빈 컨텍스트에서 시작합니다. 대화 기록을 보지 못하므로 필요한 내용은 맡길 때 함께 전달합니다.
- agents 폴더에 첫 파일을 만든 직후, `--add-dir`로 더한 폴더의 에이전트를 고친 경우, `--disable-slash-commands`로 시작한 세션은 다시 시작해야 반영됩니다.
- 머리말 필드 이름은 camelCase로 정확히 적습니다. 모르는 필드는 오류 없이 무시됩니다.
- 직접 만든 서브에이전트들의 description 합이 15,000 토큰을 넘으면 시작할 때 경고가 나옵니다. 설명은 짧게 쓰고 자세한 내용은 본문에 둡니다.
- `/agents`는 최신 버전에서 안내만 출력하고, v2.1.197 이하에서는 만들기 마법사가 열립니다.

주의:
- 서브에이전트는 빈 컨텍스트에서 시작 · 대화 기록을 보지 못하므로 필요한 내용은 맡길 때 함께 전달
- agents 폴더에 첫 파일을 만든 직후, --add-dir로 더한 폴더의 에이전트를 고친 경우, --disable-slash-commands로 시작한 세션은 다시 시작해야 반영
- 머리말 필드 이름은 camelCase로 정확히 · 모르는 필드는 오류 없이 무시
- 직접 만든 서브에이전트들의 description 합이 15,000 토큰을 넘으면 시작 시 경고 · 설명은 짧게, 자세한 내용은 본문에
- /agents는 최신 버전에서 안내만 출력, v2.1.197 이하에서는 만들기 마법사가 열림

출처:
- Create custom subagents https://code.claude.com/docs/en/sub-agents