Claude Code에 서브에이전트 붙이기｜혼자 다 하던 AI에게 팀을 만들어 줬습니다

📌 이 글은 제가 맥미니에서 Claude Code를 쓰면서 직접 세팅한 기록입니다. 개발자가 아니라 퇴근 후에 이것저것 만드는 직장인 입장에서 썼어요. 결론만 궁금하시면 맨 아래 최종 세팅 요약으로 바로 가셔도 됩니다.

Claude Code로 이것저것 만들다 보니 어느 순간 이런 생각이 들더라고요.

"얘 혼자서 조사하고, 코드 짜고, 테스트 돌리고, 검토까지 다 하네?"

대화창은 불타는데 Claude는 괜찮다고 한다

편하긴 한데 문제가 있었습니다. 대화가 길어질수록 앞에서 한 이야기를 잊어버리고, 사용량 한도는 금방 바닥나고, 자기가 짠 코드를 자기가 검토하니 "잘 짰네요"로 끝나는 경우가 많았어요. 그래서 일을 나눠 맡을 서브에이전트를 붙여 봤습니다.

메인이 직접 문서를 뒤지지 않고 docs-researcher에게 맡겼어요. 돌아온 건 요약 보고뿐입니다.

잠깐, 서브에이전트가 뭔가요?

💡 서브에이전트: 메인 Claude가 일을 맡기는 "부하 직원" AI입니다. 각자 자기 대화창(컨텍스트)에서 일하고, 메인에게는 결과 요약만 돌려줍니다.

회사로 치면 이렇습니다.

• 메인 에이전트: 팀장. 저와 대화하면서 전체를 지휘합니다.
• 서브에이전트: 팀원. "이거 조사해 와", "테스트 돌려서 실패한 것만 알려 줘" 같은 일을 받아서 처리합니다.

팀원이 긴 로그나 문서를 다 읽고 요약만 들고 오니까, 팀장(메인)의 머릿속이 깨끗하게 유지되는 게 핵심이에요.

왜 굳이 나눠야 할까?

제가 느낀 장점은 세 가지입니다.

1. 메인 대화가 덜 지저분해집니다. 테스트 로그 수백 줄을 메인이 직접 읽지 않아도 됩니다.
2. 일마다 맞는 모델을 쓸 수 있습니다. 깊이 생각할 일은 비싼 모델, 단순 검색은 빠른 모델에 맡깁니다.
3. "남의 눈"으로 검토할 수 있습니다. 검토는 아예 다른 회사 모델에게 맡겨서 자기 숙제를 자기가 채점하는 일을 막았습니다.

짠 사람도 Claude, 검토한 사람도 Claude

1단계: 서브에이전트 파일 만들기

서브에이전트는 생각보다 단순합니다. ~/.claude/agents/ 폴더에 마크다운 파일 하나를 만들면 끝이에요.

💡 ~(물결표): 맥에서 내 홈 폴더(/Users/내이름)를 줄여 쓰는 기호입니다. 윈도우의 C:\Users\내이름과 같아요.

파일 맨 위에 이름, 설명, 쓸 도구, 모델을 적고 그 아래에 이 팀원이 지킬 규칙을 씁니다. 제가 쓰는 테스트 담당은 대략 이렇게 생겼습니다.

Markdown

---
name: test-runner
description: 테스트, 린트, 빌드를 돌리고 실패한 것만 보고한다. 코드는 고치지 않는다.
tools: Bash, Read, Grep, Glob
model: sonnet
---

테스트를 실행하고, 실패한 항목과 핵심 에러 메시지만 짧게 보고한다.

⚠️ description을 대충 쓰면 안 됩니다. 메인 Claude는 이 설명을 보고 "이 일은 누구한테 맡길까"를 정해요. 설명이 애매하면 일이 엉뚱한 팀원에게 가거나, 아예 아무에게도 안 가요.

🔍 제가 겪은 일: 맥미니 안의 로컬 모델(gemma)에게 일을 넘기는 local-worker라는 팀원을 만들고, Codex(GPT-6 Astra)에게 팀 구성 검토를 맡겼어요. 첫 지적이 이거였습니다.

• 분배 규칙에 이름이 없었어요. CLAUDE.md의 "이럴 땐 누구에게" 목록에 다른 팀원은 다 있는데 local-worker만 빠져 있었어요. 만들어만 두고 일을 줄 근거가 없었던 거죠.
• 맡길 범위가 흐렸어요. description에는 "여러 단계 추론은 맡기지 말 것"이라고 써 놓고, 같은 파일 본문에서는 영어 추론 작업은 해도 된다고 적어 놨더라고요.
• 이름도 모호했어요. "worker"만 봐서는 무슨 일을 하는지 알 수가 없습니다.

이것은... 일꾼(worker)입니까?

그래서 분배 규칙에 넣고, 이름을 하는 일 그대로 text-drafter(요약·분류·번역 초안 담당)로 바꾸고, description에 "로그·테스트 실패 분석, 리뷰, 최종 사실 확인에는 쓰지 말 것"까지 적어 범위를 좁혔어요. 긴 문서 분석 담당도 모델 이름을 딴 astra-analyst에서 longdoc-analyst로 바꿨습니다. 알고 보니 Codex 쪽에서는 이미 Astra가 아닌 다른 모델이 그 일을 하고 있어서, 이름이 틀린 상태였거든요.

지금 제 팀원 7명. 파일 하나가 팀원 한 명이에요.

실제 test-runner 파일 윗부분입니다. effort(노력도)까지 적어 둘 수 있어요.

2단계: 팀 구성하기

몇 번의 삽질 끝에 지금은 이렇게 7명으로 운영하고 있습니다.

팀원	하는 일	누가 일하나
planner	큰 작업 계획 세우기, 위험 찾기	가장 깊게 생각하는 Claude 모델
Explore	코드에서 파일·함수 찾기	Sonnet (빠르고 저렴)
docs-researcher	공식 문서 확인, 출처 붙이기	Opus
test-runner	테스트 돌리고 실패만 보고	Sonnet
adversarial-reviewer	일부러 반대 입장에서 검토	Codex(ChatGPT 쪽 모델)
longdoc-analyst	긴 문서·데이터 분석	Codex(ChatGPT 쪽 모델)
text-drafter	요약, 분류, 번역 초안	맥미니 안의 로컬 LLM(Ollama)

🔍 눈여겨볼 부분은 아래 세 명이에요. 이 셋은 Claude가 직접 일하지 않고 다른 AI에게 일을 넘기는 연결 담당입니다. 그래서 Claude 쪽은 가장 싼 모델(Haiku)로만 돌리고, 실제 일은 ChatGPT Plus 구독분이나 맥미니 안의 무료 모델이 합니다. Claude 사용량을 꽤 아낄 수 있었습니다(지갑이 좋아합니다).

3단계: 언제 누구에게 맡길지 규칙 정하기

팀원을 만들어도 팀장이 일을 안 나눠 주면 소용이 없더라고요.

팀장이 일을 안 나눠 주는 동안의 서브에이전트들

그래서 ~/.claude/CLAUDE.md(Claude가 매번 읽는 규칙 파일)에 분배 규칙을 적어 뒀습니다.

• 큰 작업이나 애매한 작업 → planner가 계획을 세우고, 제가 OK한 다음 시작
• 코드를 고친 뒤 → test-runner
• 중요한 변경을 끝내기 전 → adversarial-reviewer
• 서로 상관없는 작업 여러 개 → 서브에이전트 여러 명이 동시에 처리
• 파일 수정은 메인만 한다 (팀원은 조사하고, 실행하고, 보고만)

📌 마지막 규칙이 은근히 중요합니다. 여러 팀원이 같은 파일을 동시에 고치면 서로 덮어쓸 수 있거든요. 동시에 코드를 써야 할 때는 팀원마다 별도의 작업 공간(git worktree)을 주고, 메인이 하나씩 합치게 했습니다.

4단계: 요금제에 맞춰 모델 세트 바꾸기

중간에 Claude 요금제를 Pro에서 Max로 올렸는데, 그때마다 팀원 7명의 모델을 하나하나 고치는 게 귀찮았어요. 그래서 Pro용·Max용 모델 세트를 파일로 만들어 두고, 스크립트 한 번으로 바꾸게 했습니다.

Terminal

python3 ~/.claude/model-profiles/switch-profile.py status

지금 설정이 Max 세트와 같다고 알려 줍니다. pro나 max를 붙이면 백업한 뒤 한 번에 바꿔요.

💡 주의: 바꾼 설정은 새 세션부터 적용됩니다. 지금 열려 있는 대화는 예전 설정 그대로 일해요. 바꾼 뒤에는 새 대화를 열어야 해요.

🔍 제가 겪은 일: Max 세트로 바꾸고 바로 그 대화에서 확인해 봤어요. docs-researcher에게 "도구 쓰지 말고 네 모델 이름만 답해"라고 시켰더니, Opus여야 할 답이 Sonnet 5.5로 오더라고요.

분명 Max 세트로 바꿨는데요...?

파일에는 Max 값이 제대로 적혀 있는데 말이죠. 스크립트가 고장 난 줄 알고 식은땀이 났는데, 그 대화는 시작할 때 읽어 둔 예전 팀원 정의를 계속 쓰고 있었던 거예요. 새 대화를 열어 같은 질문을 하니 그제야 Opus 5.5로 답했습니다.

같은 질문, 다른 답. 바꾼 대화에서 확인하면 헛걸음합니다.

하나 더 있어요. 처음에는 메인 대화 모델도 세트에 넣으려고 했는데 뺐습니다. settings.json에 opusplan(계획할 땐 Opus, 실행할 땐 Sonnet)을 적어 뒀는데, 데스크톱 앱 입력창 아래 모델 선택기는 계획 모드로 바꿔도 Sonnet 5.5 그대로였거든요. 앱의 선택기는 설정 파일과 따로 움직인다고 보고, 메인 모델은 앱에서 직접 고르기로 했어요.

설정 파일은 Opus, 선택기는 Sonnet. 혼란하다 혼란해

실제로 써 보니

이제 혼자 안 해요

상황	예전 (혼자)	지금 (팀)
테스트 실패 확인	로그 수백 줄이 대화에 쌓임	실패 두 줄만 보고받음
새 도구 설정	기억에 의존해 추측	공식 문서 확인 + 출처
코드 검토	"잘 짰네요"	다른 모델이 문제점 목록을 들고 옴
긴 문서 요약	Claude 사용량 소모	ChatGPT·로컬 모델이 처리

주의사항

• 서브에이전트도 사용량을 씁니다. 사소한 검색 하나에 팀원을 부르면 오히려 손해예요.
• 팀원이 "실패했다"고 보고하면 그대로 받아들이게 했습니다. 메인이 몰래 다른 방법으로 대신 처리하면 뭐가 실제로 됐는지 알 수 없어지거든요.
• 로컬 LLM은 테스트 실패 분석처럼 꼼꼼해야 하는 일에는 쓰지 않습니다. 직접 비교해 보니 실패를 놓치더라고요.

마치며

처음에는 "AI 하나면 되지 팀까지 필요해?" 싶었는데, 써 보니 사람 팀과 비슷했습니다. 역할을 나누고, 규칙을 정하고, 검토는 남에게 맡기는 것. 결국 일 잘하는 팀의 기본이더라고요.

팀 세팅 완료. 참~ 좋다

다음 글에서는 맥미니에 로컬 LLM을 깔아서 Claude 사용량을 아낀 이야기를 해 보겠습니다.

오늘은 여기까지!

최종 세팅 요약

• 서브에이전트 = ~/.claude/agents/의 마크다운 파일 하나 (이름, 설명, 도구, 모델 + 규칙)
• description은 구체적으로 (메인이 이걸 보고 일을 나눔)
• 분배 규칙은 ~/.claude/CLAUDE.md에
• 파일 수정은 메인만, 동시 작업은 worktree로 분리
• 검토는 다른 모델에게, 단순 텍스트 작업은 로컬 LLM에게

· · ·

이 글이 도움이 되셨다면 공유와 댓글 부탁드려요. 비슷하게 세팅해 보신 분들의 팀 구성도 궁금합니다!