서브에이전트 만들기
— 시켜서 만드는 법부터 여러 개 이어 쓰기까지
서브에이전트는 '한 가지 일만 전담하는 보조 AI'예요. 직접 코드를 짤 필요 없이 "이런 역할의 에이전트 만들어줘"라고 시키거나 /agents 메뉴로 클릭 몇 번이면 만들어져요. 여러 개를 만들어 '리서치→작성→검수' 순서로 이어 쓰면 한 번 요청에 분업까지 돌아가요.
그래서 뭐가 좋아지나 — 분업의 힘
리서치·카피·검수를 한 번에 부탁한다고 해볼게요. 만능 하나에게 다 시키느냐, 전담들에게 나누느냐로 결과가 갈려요.
한 AI가 리서치·작성·검수를 뭉뚱그려 처리해요. 리서치가 얕거나, 검수를 대충 넘기거나, 매번 깊이와 형식이 달라져요. 어디서 부실했는지도 안 보여요.
리서처가 출처를 모으고 → 카피라이터가 그 위에 초안을 쓰고 → 리뷰어가 사실·오류를 따로 검수해요. 각 단계가 전담이라 매번 같은 깊이·형식으로 나와요.
서브에이전트란 무엇인가
서브에이전트는 특정 작업만 맡는 별도의 AI예요. 메인 Claude가 모든 걸 한 대화에서 처리한다면, 서브에이전트는 자기 일을 따로 떨어진 자리에서 처리하고 결과만 돌려줘요. 그래서 메인 대화가 어지러워지지 않고, 매번 같은 기준으로 일해요.
한 가지 핵심 원칙이 있어요 — '폴더'가 아니라 '작업 유형'으로 나누는 것이에요. '○○ 프로젝트 에이전트'가 아니라 '리서치 에이전트', '검수 에이전트'처럼요. 그러면 프로젝트가 늘어도 같은 유형의 일은 같은 전담이 처리해서, 에이전트가 무한정 늘지 않아요.
만드는 법 ① — 시켜서 만들기 (가장 쉬움)
비개발자에게 가장 편한 길이에요. 만들고 싶은 역할을 말로 설명하면서 "서브에이전트로 만들어줘"라고 하면, Claude Code가 정의 파일을 대신 만들어줘요.
[ ] 안의 역할만 바꿔 말하면 돼요. Claude가 이름·설명·지침·도구 범위를 정해 파일로 저장해주고, 바로 쓸 수 있어요.
만드는 법 ② — /agents 메뉴로 (클릭 방식)
대화창에 /agents를 입력하면 관리 화면이 떠요. 메뉴를 따라가면 돼요.
/agents입력 → 에이전트 목록(Library) 화면이 떠요.- "Create new agent" 선택 → 저장 위치를 골라요. Personal(
~/.claude/agents/, 모든 프로젝트에서 사용) 또는 Project(.claude/agents/, 이 프로젝트만·팀과 공유). - "Generate with Claude" 선택 → 원하는 역할을 자연스럽게 설명하면, 이름·설명·지침을 자동으로 만들어줘요.
- 도구(Tools) 선택 → 이 에이전트가 뭘 할 수 있을지 정해요. 리서처·리뷰어는 보통 '읽기 전용'이면 충분해요.
- 모델 선택 → 간단한 일은 빠른 모델, 복잡한 일은 강한 모델. 모르면 기본값(Sonnet)으로.
- 저장 → 끝. 바로 쓸 수 있어요.
출처: Claude Code 공식 문서 — code.claude.com/docs/en/subagents (2026년 6월 확인)
만드는 법 ③ — 파일로 직접 (구조 이해용)
①·②로 만들면 결국 아래 같은 파일 하나가 생겨요. 구조만 알아두면 나중에 직접 고치기도 쉬워요. 서브에이전트는 .claude/agents/ 폴더 안의 마크다운(.md) 파일 한 개예요.
--- (윗부분 = 설정)
name: researcher
description: 주제에 대해 신뢰할 출처를 찾아 핵심만 정리한다.
리서치가 필요하면 자동으로 사용해줘.
tools: Read, Grep, WebSearch # 쓸 수 있는 도구만
model: sonnet
--- (아랫부분 = 이 에이전트의 지침)
당신은 리서치 전문가입니다.
- 신뢰할 수 있는 출처를 찾는다
- 핵심만 간결히 요약한다
- 의견은 빼고 사실만 전한다- name — 에이전트 이름(영문·하이픈).
- description — '언제 이 에이전트를 부를지'. 여기에 "자동으로 사용" 같은 말을 넣으면 메인이 알아서 맡겨요(아래 참고).
- tools — 쓸 수 있는 도구만 적어요(안 적으면 전부 허용). 리서처에
Write·Edit를 안 주면 파일을 못 고쳐서 안전해요. - --- 아래 본문 — 이 에이전트의 성격·지침. 메인 규칙은 안 따라오고 이 본문만 봐요.
새 .md 파일을 손으로 추가했으면 Claude Code를 한 번 껐다 켜야 인식해요. /agents나 '시켜서 만들기'로 만들면 바로 잡혀요.
자동으로 맡겨지게 하려면 — description이 핵심
서브에이전트는 두 가지로 호출돼요. 하나는 내가 콕 집어 부르는 것, 다른 하나는 메인이 알아서 맡기는 것이에요. 후자가 진짜 편한데, 비결은 description에 있어요.
- 자동으로 맡기기 — description에 "리서치가 필요하면 자동으로 사용해줘" 같은 말을 넣으면, 내가 "이 주제 좀 알아봐줘"라고만 해도 메인이 리서처에게 넘겨요.
- 콕 집어 부르기 —
researcher 에이전트로 이 주제 조사해줘처럼 이름을 대면 그 에이전트가 나서요.
여러 서브에이전트를 순서대로 이어 쓰기
진짜 힘은 여러 서브에이전트를 이어 붙일 때 나와요. 리서처·카피라이터·리뷰어를 만들어두면, 한 번 요청으로 셋이 차례로 일해요. 따로 코드를 짤 필요 없이 순서대로 말해주면, 메인 Claude가 차례차례 위임하며 조율해요. (참고로 이건 팀원끼리 직접 협업하는 '에이전트 팀'과는 다른, 더 단순한 방식이에요 — 에이전트 팀은 다음 편에서 따로 다뤄요.)
자주 쓰는 묶음이 생기면, 그 조합 자체를 '조율 담당' 에이전트(오케스트레이터)로 묶어둘 수도 있어요. "제안 한 건 통째로 만들어줘" 하면 그 안에서 리서치·작성·검수가 알아서 도는 식이죠. 이건 한 단계 더 나아간 활용이라, 우선은 '순서대로 말하기'부터 익히면 충분해요.
서브에이전트를 처음부터 잔뜩 만들 필요는 없어요. "이 일은 매번 같은 방식으로 하고 싶다" 싶은 게 생길 때 하나씩 만드는 게 좋아요. 그리고 가능하면 도구를 좁게 주세요 — 리서처·리뷰어에게 파일 수정 권한을 안 주면, 실수로 뭔가 망칠 일이 없어 마음이 편해요.
'폴더가 아니라 작업 유형으로'라는 원칙만 지키면, 프로젝트가 아무리 늘어도 에이전트는 몇 개로 충분해요. 리서치는 어느 프로젝트에서나 리서치니까요.