앞선 레슨에서 '동시에', '병렬로' 같은 말로 작업을 위임하는 법을 맛봤습니다. 이번엔 그 뒤에서 무슨 일이 벌어지는지, 그리고 나만의 전문 에이전트를 직접 만드는 법까지 깊게 파 봅니다.
서브에이전트의 핵심: 별도의 책상
서브에이전트가 강력한 진짜 이유는 '별도의 컨텍스트(책상)'를 가진다는 데 있습니다. 메인 대화가 A4 한 장이라면, 서브에이전트는 옆방에 따로 책상을 펴고 자기 일만 잔뜩 벌여 처리한 뒤 결과 요약 한 줄만 들고 돌아옵니다. 그 과정에서 뒤진 수십 개 파일 내용은 메인 책상에 올라오지 않습니다. 덕분에 메인 대화가 지저분해지지 않습니다(컨텍스트 오염 방지).
메인 컨텍스트 vs 격리된 서브에이전트 컨텍스트
메인 대화 (내 책상)
- 위임 A, 위임 B로 작업을 나눠 보냄
- 서브가 돌려준 요약 2~3줄만 받음
- 책상이 깨끗하게 유지됨 (오염 방지)
서브에이전트 (독립 책상)
- 옆방에 자기만의 독립 책상을 폄
- 파일 20개·로그 300줄을 다 펼쳐 처리
- 지저분한 탐색은 여기서 끝냄
- 결과 요약만 메인에 올림
지저분한 탐색은 옆방(서브)에서, 메인 책상엔 요약만 올라옵니다.
클로드 코드에 내장된 서브에이전트들
직접 만들지 않아도 클로드 코드는 상황에 맞는 내장 서브에이전트를 알아서 씁니다. 이름과 세부는 버전에 따라 다를 수 있으니 개념 위주로 익히세요.
- 코드 탐색용: 프로젝트에서 특정 코드를 빠르게 찾을 때. 가볍고 빠른 모델(Haiku급)로 검색을 대신해 메인 컨텍스트를 아낀다.
- 계획 수립용: 큰 작업의 단계를 짜는 데 특화. plan 모드와 잘 어울린다.
- 명령 실행용: 여러 셸 명령을 돌려 결과만 가져오는 역할.
- 다목적 실행용: 위 범주에 딱 안 맞는 일반 위임 작업 처리.
/agents로 나만의 에이전트 만들기
대화창에 /agents를 입력하면 커스텀 에이전트를 만들고 관리하는 화면이 열립니다. 여기서 에이전트의 시스템 프롬프트(역할·성격), 사용할 수 있는 도구, 모델, 표시 색상 등을 정할 수 있습니다. 프로젝트 전용으로 만들지, 내 모든 프로젝트에서 쓸지도 선택합니다.
.claude/agents/migration-reviewer.md — DB 마이그레이션 검토 에이전트
---
name: migration-reviewer
description: DB 마이그레이션 SQL을 검토한다. 스키마 변경, 마이그레이션 파일, ALTER TABLE 관련 요청 시 사용.
tools: Read, Grep, Bash
model: sonnet
---
너는 데이터베이스 마이그레이션을 검토하는 신중한 DBA다.
주어진 마이그레이션 SQL을 아래 기준으로 점검하고,
문제를 심각도(높음/중간/낮음)와 함께 목록으로 보고한다.
점검 항목:
- 되돌리기(rollback) 방법이 있는가
- 기존 데이터를 파괴하는 변경(DROP, NOT NULL 추가 등)이 있는가
- 대용량 테이블에 락을 오래 거는 작업인가
- 인덱스 누락으로 느려질 쿼리가 생기는가
절대 스키마를 직접 변경하지 말고, 검토 의견만 제시한다.하위 에이전트엔 가벼운 모델을
서브에이전트의 모델은 기본적으로 Sonnet이나 Haiku를 권합니다. 서브에이전트는 대개 '검색·수집·요약' 같은 한정된 일을 하므로, 매번 가장 비싼 Opus를 붙이면 토큰만 크게 낭비됩니다. 정말 깊은 추론이 필요한 에이전트만 골라서 상위 모델을 지정하세요.
에이전트 파일은 어디에 두나
| 위치 | 공유 범위 | 용도 |
|---|---|---|
| .claude/agents/ | 프로젝트 팀 (Git 공유) | 이 프로젝트의 공통 검토·생성 에이전트 |
| ~/.claude/agents/ | 나 개인의 모든 프로젝트 | 내가 늘 쓰는 개인 에이전트 |
에이전트 활용 패턴
| 패턴 | 설명 | 예시 |
|---|---|---|
| 격리 | 지저분한 탐색을 서브에 맡겨 메인을 깨끗이 | 대규모 코드 검색 |
| 병렬 | 독립 작업 여러 개를 동시에 | 3개 폴더 동시 점검 |
| 체인 | 한 에이전트 결과를 다음 에이전트 입력으로 | 조사 -> 계획 -> 검토 |
| 재개 | 완료한 에이전트를 나중에 다시 불러 이어서 | 리뷰 재실행 |
서브에이전트가 답일까, 메인에서 할까?
- 작업이 독립적인가? (다른 일과 안 엮이면 서브에 맡기기 좋다)
- 메인 컨텍스트를 더럽힐 만큼 자료를 많이 뒤져야 하나? (그렇다면 서브로 격리)
- 결과의 '요약'만 있으면 충분한가? (세부 과정을 메인이 다 볼 필요 없으면 서브)
- 반대로, 계속 대화하며 방향을 미세 조정해야 하나? (그렇다면 메인에서 직접)
한 걸음 더: 에이전트 팀
더 나아가면 '에이전트 팀'도 있습니다. 여러 에이전트가 리더를 중심으로 서로 메시지를 주고받으며 협업하는 방식입니다. 다만 기본 서브에이전트는 자기를 부른 메인하고만 소통하고 서로 직접 대화하지는 않는다는 점을 기억하세요. 팀 협업은 더 복잡한 작업을 위한 고급 주제입니다.
커스텀 에이전트를 만들 때 tools 항목으로 권한을 좁히세요. 예를 들어 '검토만 하는' 에이전트에는 Read, Grep만 주고 Write를 빼면, 실수로 파일을 고치는 사고를 원천 차단할 수 있습니다.
서브에이전트는 메인의 대화 내용을 자동으로 다 알지 못합니다. 별도 책상이기 때문에, 위임할 때 필요한 맥락(어떤 파일, 어떤 목표인지)을 명확히 적어 줘야 합니다. '알아서 이어서 해줘' 식으로 던지면 맥락이 없어 엉뚱한 결과가 나옵니다.
정리하면 서브에이전트는 '메인 책상을 지키는 격리 장치'이자 '전문 역할을 굳혀 두는 도구'입니다. 탐색·병렬·검토는 서브에 맡기고, 방향을 정하는 대화는 메인에서 하세요.