변경한 코드를 읽기 전용 검토 전담에게 맡기기 (Claude Code 서브에이전트)
리뷰를 맡겨도 하던 대화가 길어지지 않고, 검토 전담은 읽기만 하므로 리뷰 중에 코드가 바뀔 걱정이 없습니다.
검토 기준을 담은 code-reviewer 정의 파일을 하나 만들고, 필요하면 Claude Code를 다시 시작합니다. 이후 최근 변경을 검토해 달라고 하면 검토 전담이 따로 읽고 결과만 돌려줍니다.
준비
- Claude Code가 설치된 프로젝트 폴더
- 검토할 코드 변경분
1. 저장 위치 선택
팀과 함께 쓰려면 프로젝트의 .claude/agents/(버전 관리 대상)에, 내 모든 프로젝트에서 쓰려면 ~/.claude/agents/에 둡니다. 이름이 겹치면 프로젝트 쪽이 우선합니다.
2. code-reviewer 정의 파일 작성
.claude/agents/code-reviewer.md에 아래 내용을 저장합니다. 직접 써도 되고 Claude에게 맡겨도 됩니다. 본문이 서브에이전트의 시스템 프롬프트가 되며, 머리말에는 name과 description 두 칸이 꼭 있어야 합니다.
---
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. 최근 변경 검토 요청
@-멘션을 쓰면 그 서브에이전트가 확실히 실행됩니다. 서브에이전트는 대화 기록을 보지 못하므로 검토 범위를 메시지에 적습니다.
@"code-reviewer (agent)" 최근 변경한 인증 관련 코드 검토해 줘품질·보안·모범 사례 기준의 구체적인 지적이 돌아옵니다. git status로 파일이 바뀌지 않았는지도 확인합니다.
5. 자동 위임 설정 (선택)
description에 'use proactively' 같은 문구를 더하면 Claude가 알맞은 작업에서 스스로 맡깁니다. 세션 전체를 검토 전담으로 시작하려면 아래 명령을 씁니다.
claude --agent code-reviewer이 세션에서 파일 수정 도구가 막히는지 확인합니다.
주의
- 서브에이전트는 빈 컨텍스트에서 시작합니다. 대화 기록을 보지 못하므로 필요한 내용은 맡길 때 함께 전달합니다.
- agents 폴더에 첫 파일을 만든 직후,
--add-dir로 더한 폴더의 에이전트를 고친 경우,--disable-slash-commands로 시작한 세션은 다시 시작해야 반영됩니다. - 머리말 필드 이름은 camelCase로 정확히 적습니다. 모르는 필드는 오류 없이 무시됩니다.
- 직접 만든 서브에이전트들의 description 합이 15,000 토큰을 넘으면 시작할 때 경고가 나옵니다. 설명은 짧게 쓰고 자세한 내용은 본문에 둡니다.
/agents는 최신 버전에서 안내만 출력하고, v2.1.197 이하에서는 만들기 마법사가 열립니다.
댓글