Claude 심화 9단계 서브에이전트 — AI 팀 꾸리기

 

 

 

 

심화 9단계 서브에이전트 — AI 팀 꾸리기

한 명에게 다 시키지 말고, 역할별 팀원에게 나눠 맡기고 요약만 보고받기

Claude 심화 과정 9/12 · 2026년 9월 기준 · ⏱ 1~2시간 · ★ = 꼭 해볼 것

이번 단계에서 배우는 것 — 서브에이전트 정의는 주로 Claude Code 기능입니다. Cowork도 내부적으로 서브에이전트를 써서 병렬 작업을 합니다.

왜 팀인가

컨텍스트(기억 공간)가 차는 문제와 서브에이전트가 이를 푸는 방식

만들기

★ 대화로 만들기, 파일로 직접 만들기, 예제 3종(리뷰어·테스트·문서)

활용

부르는 3가지 방법, 여러 명에게 동시에 조사 맡기기(병렬)

판단

나눌 때와 나누지 않을 때, 비용 관리

1 왜 팀이 필요할까? — 컨텍스트가 차는 문제

Claude의 대화에는 한 번에 기억할 수 있는 양(컨텍스트)이 정해져 있습니다. 파일 수십 개를 읽고, 로그를 뒤지고, 테스트를 돌리다 보면 금방 가득 찹니다.

팀장 한 명이 자료 조사, 코드 리뷰, 문서 작성까지 혼자 하면 책상이 서류로 뒤덮여 정작 중요한 판단을 못 합니다. 좋은 팀장은 팀원에게 일을 나눠 주고 "결론만 한 장으로 보고해"라고 합니다. 서브에이전트가 바로 그 팀원입니다.

혼자 할 때

조사하며 읽은 파일 수십 개가 전부 메인 대화에 쌓임 → 컨텍스트가 차서 앞 내용을 잊거나 압축이 필요해짐.

서브에이전트에게 맡길 때

★ 팀원은 자기만의 컨텍스트에서 따로 일하고, 메인 대화에는 요약 결과만 돌아옵니다. 메인 대화가 깨끗하게 유지됩니다.

덤으로 얻는 것

역할별로 도구 권한을 좁힐 수 있고(리뷰어는 읽기만), 작업에 맞는 모델을 따로 고를 수 있습니다.

2 이미 있는 팀원 — 기본 제공 서브에이전트

아무것도 만들지 않아도 Claude Code는 필요할 때 기본 팀원을 알아서 부릅니다.

Explore

코드베이스 검색·탐색 전문. 읽기 전용이라 파일을 고치지 않습니다. "이 기능 어디에 구현돼 있어?" 같은 질문에 쓰입니다.

Plan

Plan 모드에서 계획을 세우기 위한 조사 담당. 역시 읽기 전용.

general-purpose

모든 도구를 쓰는 만능 팀원. 조사와 수정이 섞인 복잡한 작업에.

Tip — 작업 중 화면에 에이전트 이름이 잠깐 보인다면 Claude가 팀원에게 일을 넘긴 것입니다. 특정 기본 에이전트를 쓰지 못하게 하려면 권한 설정의 deny 규칙에 Agent(Explore) 처럼 적습니다.

3 나만의 팀원 만들기

방법은 두 가지입니다. 대화로 부탁하거나, 파일을 직접 쓰거나.

방법 ① 대화로

★ "코드 리뷰어 서브에이전트 만들어줘"라고 부탁하면 Claude가 파일을 만들어 줍니다. 가장 쉬운 방법.

방법 ② 파일로

.claude/agents/이름.md 파일을 직접 작성합니다.

/agents

예전에는 만들기 마법사가 열렸지만, 최근 버전에서는 마법사 대신 안내만 표시됩니다. 위 두 방법 중 하나로 만드세요.

코드 리뷰어 서브에이전트를 만들어 줘.
- 이름: code-reviewer
- 파일 위치: .claude/agents/ (팀과 공유할 거야)
- 도구는 Read, Grep, Glob 만 (읽기 전용)
- 버그 → 보안 → 가독성 순서로 지적하고, 심각도를 상/중/하로 표시
- 우리 프로젝트는 Java/Spring + Oracle 이야

파일 위치와 우선순위

.claude/agents/

프로젝트 — 깃에 커밋해 팀과 공유. 이름이 겹치면 여기가 우선.

~/.claude/agents/

개인 — 내 모든 프로젝트에서 사용.

플러그인 agents/

7단계 플러그인에 넣어 배포한 에이전트.

frontmatter(맨 위 설정) 항목

name 필수

에이전트 이름. 소문자와 하이픈 권장(code-reviewer).

description 필수

언제 이 팀원을 부를지. 스킬처럼 Claude가 이걸 보고 자동으로 일을 맡깁니다. 구체적으로 쓸수록 잘 불립니다.

tools

쓸 수 있는 도구 목록. 생략하면 메인 대화의 도구를 물려받습니다. 반대로 빼고 싶은 것만 적는 disallowedTools 도 있습니다.

model

sonnet · opus · haiku · inherit(메인과 같게).

permissionMode

이 팀원의 권한 모드(예: 수정 자동 수락 등).

color

화면에 표시될 색. 여러 팀원이 동시에 일할 때 구분이 쉬워집니다.

그 밖에

maxTurns(최대 반복 횟수) · skills · mcpServers · memory · isolation: worktree(별도 작업 폴더에서 작업) 등.

4 ★ 바로 쓰는 예제 3종

그대로 복사해서 .claude/agents/ 에 저장하면 됩니다. 내용은 내 프로젝트에 맞게 고치세요.

① 코드 리뷰어 — 읽기 전용

파일: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: 코드를 수정한 뒤 품질·보안 관점에서 리뷰할 때 사용. 변경 사항 검토 요청 시 적극적으로 사용.
tools: Read, Grep, Glob
model: sonnet
color: red
---
너는 시니어 코드 리뷰어다. 파일은 절대 수정하지 않는다.

리뷰 순서:
1. 버그 — 널 처리, 예외 처리, 트랜잭션 경계, 경계값
2. 보안 — SQL 인젝션, 하드코딩된 비밀번호·키, 권한 검사 누락
3. 가독성 — 이름, 중복, 너무 긴 메서드

출력 형식:
- 항목마다 [상/중/하] 심각도, 파일:줄, 문제, 고치는 방법 제안
- 마지막에 "머지해도 되는지" 한 줄 결론

② 테스트 작성자

파일: .claude/agents/test-writer.md

---
name: test-writer
description: 새 기능이나 수정한 코드에 단위 테스트를 작성하고 실행할 때 사용.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
color: green
---
너는 테스트 전문 개발자다.

작업 순서:
1. 대상 코드와 기존 테스트 스타일(프레임워크, 폴더 구조, 이름 규칙)을 먼저 확인한다
2. 정상 케이스, 경계값, 예외 케이스를 나눠 테스트를 작성한다
3. 테스트를 실행하고, 실패하면 원인을 분석한다
4. 운영 코드는 고치지 않는다. 버그로 보이면 보고만 한다

보고: 추가한 테스트 목록, 실행 결과(통과/실패 수), 발견한 의심 버그

③ 문서 작성자

파일: .claude/agents/doc-writer.md

---
name: doc-writer
description: README, API 설명, 변경 이력 등 문서를 작성하거나 코드와 문서가 맞는지 점검할 때 사용.
tools: Read, Grep, Glob, Edit, Write
model: sonnet
color: blue
---
너는 기술 문서 작성자다. 독자는 이 프로젝트를 처음 보는 신입 개발자다.

원칙:
- 코드를 직접 읽고 확인한 사실만 쓴다. 추측은 "확인 필요"로 표시한다
- 짧은 문장, 예시 코드 포함, 한국어 존댓말
- 코드 파일은 수정하지 않는다. 문서 파일(.md)만 작성·수정한다

보고: 수정한 문서 목록과 각 문서에서 바뀐 부분 요약

블로그 작업에 응용 — 같은 방식으로 fact-checker(글 속 명령어·메뉴가 공식 문서와 맞는지 확인, 도구는 읽기·웹 검색만)나 proofreader(맞춤법·말투 검수) 에이전트를 만들 수 있습니다. 11단계 종합 프로젝트에서 실제로 씁니다.

5 팀원 부르는 3가지 방법

자연어로

"code-reviewer 에이전트로 방금 고친 코드 검토해줘". description이 잘 쓰여 있으면 말하지 않아도 Claude가 알아서 맡기기도 합니다.

@agent-code-reviewer

@로 콕 집어 부르기. 반드시 그 팀원에게 맡기고 싶을 때.

claude --agent code-reviewer

세션 전체를 그 에이전트로 시작. 리뷰만 하는 세션을 따로 열 때 편합니다.

@agent-code-reviewer 이번 브랜치에서 바뀐 Java 파일을 리뷰해 줘.
특히 MyBatis 매퍼의 SQL 인젝션 가능성을 중점적으로 봐 줘.

6 ★ 따라해 보기 — 여러 팀원에게 동시에 조사 맡기기

서브에이전트의 진짜 힘은 병렬입니다. 서로 관계없는 조사를 여러 명에게 동시에 맡기면 시간도 줄고, 메인 대화에는 요약만 남습니다.

1. 프로젝트 열기

처음 보는(또는 오래된) 프로젝트 폴더에서 Claude Code를 실행합니다.

2. 병렬 조사 요청

"병렬로", "각각 따로"라고 분명히 말하고, 팀원마다 맡을 범위를 나눠 줍니다.

서브에이전트 3개를 병렬로 써서 이 프로젝트를 조사해 줘.
각 에이전트는 파일을 수정하지 말고 읽기만 해.

1) controller 폴더: 어떤 API(URL)가 있는지 목록으로
2) service 폴더: 핵심 비즈니스 로직과 트랜잭션 처리 방식
3) resources 폴더: DB 연결 설정, SQL 매퍼 파일 구조

각자 결과를 10줄 이내로 요약해서 보고하고,
마지막에 네가 세 보고를 합쳐 "이 프로젝트 한 장 요약"을 만들어 줘.

3. 관찰하기

화면에 여러 에이전트가 동시에 도는 것이 보입니다. 끝나면 /context 로 메인 대화의 컨텍스트가 생각보다 적게 찬 것을 확인해 보세요.

# 블로그 글 버전
서브에이전트 2개를 병렬로 써 줘.
1) Claude Code 공식 문서에서 "서브에이전트" 관련 최신 변경 사항 조사
2) 내 초안(advanced-09.html)의 명령어·설정 항목 목록 뽑기
두 결과를 비교해서 초안에서 고쳐야 할 부분만 알려줘.

7 나눌 때와 나누지 않을 때

팀원이 많다고 일이 잘 되는 건 아닙니다. 회의만 늘어나는 팀도 있죠. 기준은 "독립적인가, 얽혀 있는가"입니다.

나누세요 ✔

서로 관계없는 폴더·주제 조사 · 결과만 필요하고 과정은 궁금하지 않은 작업 · 로그·대량 파일 뒤지기 · 권한을 좁혀야 하는 검토(리뷰, 감사) · 같은 형식의 반복 작업 여러 건

나누지 마세요

앞 단계 결과를 보고 다음을 정해야 하는 작업 · 한 파일을 여러 명이 동시에 고치는 작업 · 나와 여러 번 주고받으며 다듬어야 하는 작업 · 금방 끝나는 간단한 질문

애매하면

"이 작업을 서브에이전트로 나누는 게 좋을지 먼저 판단해 줘"라고 Claude에게 물어보세요.

Cowork에서도 — Cowork(데스크톱 앱)도 큰 일을 맡기면 내부적으로 서브에이전트를 여러 개 띄워 병렬로 작업합니다. 파일을 따로 만들지 않아도 "자료 조사와 표 정리를 동시에 나눠서 해줘"처럼 부탁하면 됩니다. 에이전트 정의 파일을 직접 만들고 권한을 세밀하게 정하는 것은 Claude Code 쪽입니다.

8 비용 — 팀원이 많을수록 토큰도 늘어납니다

팀원 한 명 한 명이 각자 파일을 읽고 생각합니다. 3명을 병렬로 쓰면 대략 3명분의 사용량이 나간다고 생각하세요.

model: haiku

★ 파일 찾기·목록 뽑기 같은 가벼운 조사 담당은 Haiku로. 빠르고 저렴합니다.

꼭 필요한 만큼만

에이전트 수를 늘리기 전에 "정말 병렬이 필요한가"를 먼저 생각합니다. 작은 일에 팀을 꾸리면 배보다 배꼽이 큽니다.

/usage

병렬 작업 전후로 사용량을 확인하는 습관을 들이세요. 12단계에서 자세히 다룹니다.

가벼운 조사 전용 팀원 예 — .claude/agents/file-scout.md

---
name: file-scout
description: 특정 키워드·클래스가 어느 파일에 있는지 빠르게 찾을 때 사용
tools: Read, Grep, Glob
model: haiku
---
요청받은 대상을 찾아 "파일 경로:줄 번호 — 한 줄 설명" 형식으로만 보고한다.

9 정리 & 체크리스트

서브에이전트 = 자기 책상(컨텍스트)에서 따로 일하고 요약만 보고하는 팀원. 아래를 모두 해봤다면 9단계 완료입니다.

☐ 개념

서브에이전트가 컨텍스트 문제를 어떻게 줄이는지 설명할 수 있다

☐ 기본 팀원

Explore · Plan · general-purpose 의 차이를 안다

☐ 만들기

★ 대화로 하나, 파일로 하나 — code-reviewer 등 예제를 .claude/agents/ 에 만들었다

☐ 호출

자연어, @agent-이름, claude --agent 세 가지로 불러 봤다

☐ 병렬

3개 팀원에게 동시에 조사를 맡기고 요약을 합쳐 받아 봤다

☐ 판단 · 비용

나눌 때와 나누지 않을 때를 구분하고, 가벼운 조사는 model: haiku 로 두었다

6~9단계로 플러그인 상자에 들어갈 부품(스킬·명령어·훅·에이전트)을 모두 만들어 봤습니다. 다음 단계에서는 이 팀이 내가 없어도 정해진 시간에 알아서 일하도록 자동화합니다.

이전 글: 심화 8단계 커스텀 명령어와 훅(Hook) · 다음 글: 심화 10단계 자동화 — 내가 없어도 일하는 Claude
공식 문서: 서브에이전트 · 플러그인 · 비용 관리