서브에이전트 — AI 직원

서브에이전트는 메인 에이전트(내가 직접 이야기하는 클로드)가 자기 일 가운데 한 가지를 떼어 맡기는 하위 직원입니다. 실제로는 직원 카드 5칸(이름·역할·도구·모델·지침)이 적힌 문서 파일 하나입니다. 사장이 조사나 검토를 직접 하지 않고 담당 직원에게 맡긴 뒤 보고서만 받아 보듯, 클로드도 일에 맞는 직원을 그 직원만의 별도 공간에서 일하게 하고, 시킨 형식에 맞춘 결과만 받아 옵니다. 검색 기록이나 긴 실행 결과처럼 길게 쏟아지는 중간 내용은 직원 쪽에 남으므로, 메인 에이전트의 기억 그릇(클로드가 한 번에 기억할 수 있는 양)을 채우지 않습니다. 이 기능이 왜 필요한지, 왜 한 명에게 통째로 맡기지 않는지는 「한 명이 아니라 여럿에게 나눠 맡깁니다」 페이지에서 설명합니다.

직원 카드 5칸 — 파일 하나가 직원 한 명

직원 카드는 두 부분으로 나뉩니다. 맨 위에 --- 줄이 두 번 나오는데, 그 사이에 이름·역할 같은 설정을 적습니다. 이 부분을 맨 위 설정 칸(frontmatter)이라고 부릅니다. 그 아래에는 직원이 따를 지시를 보통 문장으로 적습니다. 카드 5칸이 파일에서 어떤 이름으로 적히는지 알아 두면, 클로드가 만들어 온 카드를 검토할 때 어디를 봐야 할지 헷갈리지 않습니다.

중요한 특징이 하나 있습니다. 직원은 지금 대화의 내용을 물려받지 않고, 이 지침과 작업 폴더 같은 기본 정보만 받아 백지에서 일을 시작합니다. 그래서 일을 맡길 때는 필요한 배경을 지시에 함께 적어 줘야 합니다. 예외는 /subtask로 일을 떼어 맡긴 직원입니다. 이 직원은 지금 대화를 통째로 물려받고 일을 시작합니다.

직원은 무엇을 물려받을까요 — 운영 헌법도 읽을까요

“내가 만든 운영 헌법(CLAUDE.md)을 직원도 읽고 지키나, 아니면 직원한테는 매번 따로 다 알려 줘야 하나.” 직원을 처음 뽑고 나면 으레 따라오는 물음입니다. 확실한 것과 직접 확인해야 할 것을 나눠 정리합니다.

운영 헌법을 함께 읽는지는 공식 안내에 나와 있습니다. 내장 직원인 Explore(탐색)와 Plan(계획)은 CLAUDE.md를 건너뛰지만, 기본 직원이든 내가 만든 직원이든 그 밖의 직원은 CLAUDE.md를 함께 읽고 시작합니다. 맡긴 지시만으로 충분한 직원이라면 카드 맨 위 설정 칸에 omitClaudeMd: true를 적어 운영 헌법을 읽지 않게 할 수도 있습니다(v2.1.271 이상). 그래도 확신이 서지 않으면 직원에게 직접 물어 확인하면 됩니다.

# 직원에게 직접 물어 확인하기
code-improver 직원을 불러서 "우리 회사 규칙을 알고 있어? 알고 있다면 규칙 첫 부분을
그대로 옮겨 봐"라고 물어봐. 이때 규칙 내용은 네가 알려 주지 말고, 직원이 스스로
아는 것만 답하게 해 줘. 직원을 실제로 불렀는지와 직원이 뭐라고 답했는지 그대로 보여 줘

돌아온 답이 내가 적어 둔 규칙과 맞으면 읽고 있는 것이고, 모른다고 하거나 엉뚱한 이야기를 하면 안 읽는 것입니다. 이때 직원을 실제로 불렀는지도 함께 확인하십시오. 메인 에이전트는 회사 규칙을 이미 알고 있습니다. 그래서 클로드가 직원을 부르지 않고 대신 답했거나 규칙 내용을 직원에게 미리 알려 줬다면, 확인이 된 것이 아닙니다. 버전이 올라가면서 동작이 달라질 수 있으니, 중요한 일을 맡기기 전에 한 번씩 확인해 두면 마음이 놓입니다.

다만 확인 결과가 어느 쪽이든 실무에서 할 일은 같습니다. 그 직원이 반드시 지켜야 할 것은 직원 카드의 지침 칸에 적습니다. 카드에 적은 지침은 그 직원이 일을 시작할 때 반드시 받는 내용이기 때문입니다.

만들기·관리

말로 선발하기가 정식 방법입니다. 카드를 먼저 보여 달라고 해서 확인한 뒤 승인합니다. 예전의 /agents 관리 화면은 지금 버전에서 제거되었습니다. v2.1.281부터는 이 명령이 /를 입력했을 때 나오는 목록과 /help 목록에서도 빠졌고, 직접 쳐 보면 “말로 시키거나 파일을 직접 고치라”는 안내만 나옵니다. 명단이 궁금하면 “우리 직원 명단 보여 줘”라고 물으면 됩니다. 직접 따라 하는 절차는 따라 하기 3편에 있습니다.

# 말로 선발하기 — 조건을 말로 걸면 카드에 그대로 반영됩니다
읽기 전용 코드 점검 직원을 만들어 줘. 파일을 읽고 개선점만 제안하고,
파일은 못 고치게 하고, 모델은 sonnet으로. 만들기 전에 카드를 먼저 보여 줘.

승인하면 클로드가 직원 폴더에 카드 파일을 만들어 줍니다. 파일을 직접 열어 고쳐도 됩니다. 다만 우리 회사는 카드를 고칠 때도 말로 시키고, 바뀐 내용만 눈으로 확인하는 것을 기본으로 합니다.

두는 곳

• .claude/agents/ — 이 폴더 전용 직원. 저장소(깃으로 기록을 관리하는 폴더)에 함께 올리면 팀원 모두가 같은 직원을 씁니다.
• ~/.claude/agents/(홈 폴더) — 내 컴퓨터 공용 직원. 어느 폴더에서 열어도 출근합니다.

같은 이름의 카드가 두 곳에 다 있으면 프로젝트 폴더(.claude/agents/)의 것이 이깁니다. 홈 폴더의 카드는 밀려납니다. 회사가 사내 모든 컴퓨터에 배포한 관리자용 카드가 있다면 그것이 둘보다 먼저이고, 플러그인이 딸려 보낸 카드가 가장 뒤입니다. 관리자용 카드를 빼면, 작업 폴더에 가까운 카드가 이깁니다.

직원 내보내기 — 잘못 뽑았을 때

직원을 잘못 뽑는 일은 흔합니다. 역할을 너무 넓게 잡았거나, 만들어 놓고 한 번도 부르지 않았거나, 비슷한 직원이 둘이 되어 클로드가 누구에게 맡길지 헷갈려 하는 경우입니다. 정리하는 방법은 싱거울 만큼 간단합니다. 앞서 본 대로 직원의 실제 모습은 직원 폴더 안의 문서 파일 하나이므로, 그 파일을 치우면 그 직원은 없어집니다. 사직서를 받을 일도, 인수인계를 시킬 일도 없습니다.

먼저 말로 시킵니다.

# 말로 내보내기 — 지울 파일을 먼저 확인받습니다
code-improver 직원 이제 안 쓰니 정리해 줘. 지우기 전에 어떤 파일을 지울 건지 먼저 알려 줘.

수동 모드에서는 파일을 지우는 일이라 클로드가 허락을 묻습니다. 어느 파일인지 눈으로 확인하고 승인하십시오. 파일을 직접 찾아 지워도 결과는 같습니다. 다만 공식 안내에는 직원을 없애는 정식 절차가 따로 나와 있지 않습니다. 카드 파일을 치우는 것이 곧 정리입니다.

지우기 전에 네 가지를 확인합니다.

• 권한 규칙 — 권한 규칙에서는 Agent(이름) 형태로 특정 직원을 골라 막아 둘 수 있습니다. 직원은 사라졌는데 그 이름을 가리키는 규칙만 남으면, 나중에 설정을 읽을 때 헷갈리는 찌꺼기가 됩니다.
• 훅이나 다른 직원 카드 — 그 직원을 이어서 부르도록 적어 둔 곳이 있을 수 있습니다. “이 직원 이름을 부르는 설정이 또 있는지 찾아 줘”라고 시켜 함께 정리하면 한 번에 끝납니다.
• 양쪽에 같은 이름이 있는지 — 프로젝트 폴더와 홈 폴더 두 곳에 같은 이름의 카드가 있으면, 한쪽만 지워서는 그 직원이 계속 출근합니다.
• 팀과 공유하는 직원인지 — 프로젝트 폴더의 카드는 저장소에 함께 올라간 파일입니다. 나 혼자 쓰던 것이 아니라면 팀에도 영향이 갑니다.

정리한 뒤에는 세션을 새로 열고 “우리 직원 명단 보여 줘”로 명단을 다시 확인하십시오. 새로 뽑은 직원이 곧바로 안 보일 때 세션을 다시 여는 것과 같은 요령입니다.

만들지 않아도 있는 직원

클로드 코드에는 기본으로 딸려 오는 직원이 몇 명 있습니다. 상황에 맞으면 클로드가 알아서 이들을 씁니다.

Explore와 Plan은 파일을 건드리지 않는 “조사 담당”입니다. 대화 중에 클로드가 이들에게 조사를 맡기는 장면을 보게 되는데, 내가 뽑은 적 없는 이름이 나와도 놀랄 일이 아닙니다.

도구를 주는 두 방식

직원 카드의 도구 칸을 적는 방식은 두 가지입니다.

• tools — 허용 목록. 적은 것만 쓸 수 있습니다. 예를 들어 tools: Read, Grep, Glob이면 읽고 검색만 할 뿐 파일을 고치거나 새로 쓰지 못합니다.
• disallowedTools — 거부 목록. 적은 것만 막습니다. 나머지는 다 물려받되 파일 쓰기·수정만 못 하게 하고 싶을 때 편리합니다.

도구를 적으려면 도구의 정확한 이름이 필요합니다. 직원 카드뿐 아니라 권한 규칙과 훅에서도 같은 이름을 씁니다. 자주 쓰는 내장 도구는 다음과 같습니다. 아래 표의 셋째 칸은 수동 모드에서 묻는지를 적은 것이며, 지금 버전에서 처음 켜면 시작되는 자동 모드에서는 작업 폴더 안의 Write·Edit는 묻지 않고, Bash와 웹 도구는 또 하나의 AI가 사람 대신 판단합니다.

부르는 법 — 네 가지

1. 알아서 맡기기(자동 위임) — 직원 이름을 넣지 않고 일을 시키면 클로드가 요청 내용과 각 직원의 역할(description)을 비교해 알맞은 직원에게 스스로 맡깁니다. 더 적극적으로 맡기게 하려면 역할 칸에 “use proactively(적극적으로 사용)” 같은 문구를 넣어 둡니다.
2. 이름 언급 — 지시에 직원 이름을 넣으면 보통 그 직원에게 맡깁니다.
3. @ 멘션 — 특정 직원을 반드시 쓰게 하려면 @를 입력해 목록에서 골라 부릅니다. 파일을 불러올 때와 같은 방식입니다.
4. claude --agent — 세션 전체를 아예 한 직원으로 시작합니다. 메인 에이전트 자체가 그 직원의 지침·도구 제한·모델을 그대로 이어받습니다.

# ② 이름 언급 — 보통 이 정도면 그 직원이 나섭니다
code-improver 직원을 써서 이 프로젝트의 개선점을 제안해 줘

# ③ @ 멘션 — 반드시 이 직원에게 (목록에서 골라 부르기)
@"code-reviewer (agent)" 최근 변경을 검토해 줘

# ④ 세션 전체를 그 직원으로 시작 (터미널에서)
claude --agent code-reviewer

직원을 부를 때 생각의 깊이(답하기 전에 얼마나 깊이 생각할지 정하는 수준)도 말로 정할 수 있습니다. “이 조사는 생각의 깊이를 low로 해서 직원에게 맡겨 줘”라고 하면 클로드가 그 깊이로 직원을 부릅니다(v2.1.292 이상). 가벼운 조사는 깊이를 낮추면 사용량이 줄어듭니다. 늘 같은 깊이로 일할 직원이라면 카드 맨 위 설정 칸에 effort: low처럼 적어 둡니다.

부르고 나면 직원은 기본으로 백그라운드(화면에 보이지 않게 따로 도는 상태)에서 일합니다. 진행 상황이 지금 대화에 줄줄이 흐르지 않으므로, 입력창 아래 작업 패널이나 /tasks로 들여다봅니다. 그 목록에는 직원마다 어느 모델(머리 등급)로 일했는지 적히고, 카드에 생각의 깊이를 정해 둔 직원은 그 깊이도 함께 적힙니다. 사용량이 많이 나온 직원을 여기서 찾아냅니다. 목록의 System tasks 한 줄은 클로드 코드가 스스로 하는 백그라운드 작업을 한데 묶은 것이고, 그 줄에서 Enter를 누르면 펼쳐 볼 수 있습니다(v2.1.285 이상). 그리고 직원은 자기 밑에 또 직원을 부를 수 있고, 기본으로 3단까지 내려갑니다. 한 명만 불렀는데 사용량이 생각보다 크게 나오는 것은 이 때문입니다.

언제 직원에게 맡길까요

모든 일을 직원에게 넘기는 것이 정답은 아닙니다. 우리가 쓰는 판단 기준은 다음과 같습니다.

활용 패턴 세 가지

① 결과가 긴 일 떼어 맡기기. 테스트 실행, 자료 내려받기, 로그(쌓인 실행 기록) 분석처럼 결과물이 잔뜩 쏟아지는 일에 가장 잘 맞습니다. 길게 쏟아진 결과는 직원 쪽에 남고, 메인 에이전트에게는 요약만 돌아옵니다.

# 실패한 것만 추려 받기
서브에이전트를 써서 테스트를 전부 돌리고, 실패한 것만 오류 메시지와 함께 보고해 줘

② 나눠서 동시에 조사하기. 서로 상관없는 조사라면 직원 여럿을 한꺼번에 불러 동시에 일하게 할 수 있습니다. 각자 자기 영역을 조사하고, 클로드가 결과를 한데 모아 정리합니다.

# 세 영역을 각각 다른 직원이 동시에
인증·데이터베이스·API 세 영역을 별도 서브에이전트로 나눠 동시에 조사해 줘

예시에 개발 용어가 나와도 지시하는 방식은 그대로 옮겨 쓸 수 있습니다. “세 영역을 별도 직원으로 나눠 조사해 줘”는 어느 업종에서든 똑같이 통하는 말입니다.

③ 찾는 직원 → 고치는 직원 잇기. 여러 단계로 된 일은 직원을 순서대로 쓰라고 하면 됩니다. 앞 직원이 결과를 넘기면, 클로드가 필요한 내용을 다음 직원에게 전달합니다. 우리 회사도 글을 쓰는 직원과 검사하는 직원을 반드시 따로 둡니다. 만든 직원이 자기 결과물을 검사하면 제 눈에 좋은 것만 보이기 때문입니다.

# 검토 담당이 찾고, 수리 담당이 고치는 이어달리기
code-reviewer 직원으로 성능 문제를 찾고, 그다음 optimizer 직원으로 고쳐 줘

운영 원칙

• 도구는 필요한 최소한만 줍니다(책 13장).
• 모델 등급은 일의 깊이에 맞게 배정합니다(책 12장). 간단한 일은 저렴한 모델(예: haiku)을 써서 비용을 아낍니다. Haiku 5.5는 기억 그릇이 100만 토큰(AI가 글을 세는 단위)이라 긴 자료도 한 번에 읽습니다. 다만 아주 긴 자료를 한 번에 넣으면 토큰당 값이 올라갑니다.
• 역할(description)을 분명하게 적습니다.
• 하나를 잘하는 직원 여럿이 만능 직원 하나보다 낫습니다.