Claude Code 사용법: 서브에이전트의 작동 원리와 활용 시점

서브에이전트는 Claude에 위임하는 하나의 함수와 같습니다. Claude가 작업을 넘기면 사용자가 볼 수 없는 별도 창에서 처리하고, 정돈된 답변 하나만 반환합니다. 제대로 활용하면 여러 시간 이어지는 Claude Code 세션의 일관성을 지키는 가장 강력한 수단이 됩니다. 반대로 잘못 쓰면 아무런 이득 없이 토큰만 소모하고 지연 시간만 늘어납니다. 이 글에서는 실제 작동 방식과 정의 파일, 그리고 서브에이전트를 써야 할 때를 판단하는 현실적인 기준까지 모두 다룹니다.

Claude Code 사용법, 20초 만에 이해하기

서브에이전트는 격리된 자체 컨텍스트에서 독립적인 보조 작업을 수행한 다음, 짧은 요약을 메인 대화에 반환합니다. 개념은 이것이 전부입니다. 서브에이전트가 해결하려는 문제도 하나뿐입니다. 에이전트 세션이 길어지면 grep 결과, 빌드 로그, 한 번 읽고 다시 보지 않는 파일 같은 잡음이 쌓이고, 결국 모델이 실제 작업보다 주변 정보를 정리하는 데 더 많은 주의를 쓰게 됩니다.

이처럼 잡음이 많은 작업을 서브에이전트로 옮기면 불필요한 정보는 그쪽에만 남습니다. 메인 스레드에는 결론만 들어옵니다. 따라서 올바른 이해 방식은 ‘AI 엔지니어 팀의 협업’이 아니라 반환값이 있는 컨텍스트 정리입니다. 이 관점만 잡으면 서브에이전트와 관련된 나머지 판단도 훨씬 쉬워집니다.

서브에이전트는 실제로 어떻게 작동합니까?

서브에이전트는 자체 컨텍스트 창에서 실행되며, 사용자 지정 시스템 프롬프트와 지정된 툴 접근 권한, 독립적인 권한 설정을 가집니다. Claude가 서브에이전트의 역할 설명과 맞는 작업을 만나면 이를 위임하고, 서브에이전트는 독립적으로 처리한 뒤 결과를 반환합니다. 이것이 공식 정의이며, 여기서 중요한 부분은 자체 컨텍스트 창과 결과 반환입니다.

대부분의 설명이 놓치는 핵심이 있습니다. 서브에이전트는 아무것도 없는 상태에서 시작합니다. 지금까지의 대화 기록이나 Claude가 이미 읽은 파일, 이미 호출한 스킬을 볼 수 없습니다. Claude는 작업을 요약한 짧은 위임 메시지를 작성해 전달하고, 서브에이전트는 자체 시스템 프롬프트와 작업 디렉터리 같은 기본 환경 정보만으로 일을 시작합니다. 전체 Claude Code 시스템 프롬프트까지 받는 것은 아닙니다. 작업이 끝나면 메인 대화로 돌아오는 것도 요약뿐입니다.

이러한 격리는 장점과 비용을 동시에 만듭니다.

• 장점: 읽어 본 열두 개의 파일, 실패한 grep, 살펴본 로그처럼 장황한 중간 과정이 메인 컨텍스트에 전혀 들어오지 않습니다. 잡음 없이 답만 받을 수 있습니다.
• 비용: 이미 확보했던 컨텍스트도 서브에이전트가 다시 수집해야 합니다. 대화 기록을 알아야 이해할 수 있는 작업이라면 처음부터 시작하는 서브에이전트는 헤맬 수밖에 없습니다.

서브에이전트를 정의하는 파일

사용자 지정 서브에이전트는 YAML 프런트매터가 포함된 Markdown 파일입니다. 프런트매터는 설정에 해당하고, Markdown 본문은 서브에이전트의 시스템 프롬프트가 됩니다. 필수 필드는 name과 description, 두 개뿐입니다.

---
name: code-reviewer
description: Reviews code for quality and best practices. Use immediately after writing or modifying code.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. When invoked, run git diff to see recent
changes, focus on modified files, and review for clarity, naming, error
handling, exposed secrets, input validation, and test coverage. Group your
feedback by priority: critical issues, warnings, then suggestions.

이것만으로 완전하게 작동하는 서브에이전트가 됩니다. description은 단순한 장식이 아닙니다. Claude는 이 내용을 읽고 언제 위임할지 판단합니다. 따라서 “코드를 검토하며, 코드를 작성하거나 수정한 직후 바로 사용”처럼 적으면 적절한 순간에 서브에이전트가 호출되지만, “코드 도우미”처럼 모호하게 쓰면 활용되지 않은 채 남기 쉽습니다. 전문 인력을 채용하는 공고처럼 역할 설명을 작성해야 합니다.

파일을 직접 작성할 필요는 없습니다. Claude Code의 /agents 명령을 실행하면 서브에이전트 관리용 탭 인터페이스가 열립니다. Running 탭에서는 실행 중이거나 최근 완료된 서브에이전트의 목록을 보고 열거나 중지할 수 있고, Library 탭에서는 서브에이전트를 만들고 수정하고 정리할 수 있습니다. 한 가지 기억할 점은 서브에이전트가 세션 시작 시 로드된다는 사실입니다. 디스크에서 파일을 직접 수정했다면 세션을 다시 시작해야 변경 사항이 반영됩니다. /agents 인터페이스에서 만들거나 수정한 서브에이전트는 즉시 적용됩니다.

서브에이전트 파일은 어디에 두며, 충돌하면 무엇이 우선합니까?

같은 서브에이전트 파일도 저장 위치에 따라 동작이 달라집니다. 위치는 누가 사용할 수 있는지, 이름이 겹칠 때 어떤 정의가 이기는지를 결정합니다.

이름이 같은 서브에이전트가 둘 이상이면 우선순위가 높은 위치의 정의가 적용됩니다. 관리형 정의가 프로젝트보다 우선하고, 프로젝트는 사용자 정의보다 우선합니다. 프로젝트 서브에이전트는 현재 작업 디렉터리부터 상위 경로를 따라가며 검색되며, v2.1.178부터는 이름이 충돌할 경우 작업 디렉터리에서 가장 가까운 정의가 적용됩니다. 세션에만 쓰는 방법도 있습니다. Claude Code를 시작할 때 --agents 플래그로 서브에이전트를 JSON 형태로 전달하면 디스크에 저장하지 않고 해당 세션에서만 사용할 수 있습니다. 자동화 스크립트나 빠른 테스트에 유용합니다.

실무 기준은 간단합니다. 이 코드베이스의 리뷰나 테스트 방식을 담은 서브에이전트라면 .claude/agents/에 두고 버전 관리에 포함해 팀 전체가 공유하는 편이 맞습니다. 개인적인 작업 방식을 반영한 서브에이전트라면 ~/.claude/agents/에 두어 모든 프로젝트에서 사용하면 됩니다.

Claude Code 설정의 핵심: 모델과 툴

실제 효과를 좌우하는 프런트매터 필드는 두 가지입니다. 이 둘을 제대로 조정해야 서브에이전트가 흥미로운 기능을 넘어 비용 대비 효율적인 도구가 됩니다.

모델. model 필드에는 별칭(sonnet, opus, haiku, fable)이나 claude-opus-4-8 같은 전체 모델 ID, 또는 inherit를 지정할 수 있습니다. 생략하면 기본값은 inherit이며, 메인 대화와 같은 모델을 사용한다는 뜻입니다. 눈에 잘 띄지 않지만 예산을 크게 좌우하는 설정입니다. “코드베이스를 grep으로 검색하고 결과를 요약하라”는 일만 하는 서브에이전트에 최상위 모델은 필요하지 않습니다. model: haiku로 설정하면 반복 작업은 더 저렴하고 빠른 모델이 맡고, 메인 세션에서는 Opus로 판단이 필요한 작업을 계속할 수 있습니다.

툴. 기본적으로 서브에이전트는 메인 대화가 가진 모든 내부 툴과 MCP 툴을 상속합니다. 접근 범위는 두 필드 중 하나로 좁힐 수 있습니다. tools는 허용 목록으로 지정된 툴만 열어 주고, disallowedTools는 거부 목록으로 지정된 툴을 제외한 나머지를 허용합니다. 파일을 절대 변경해서는 안 되는 리서치 서브에이전트라면 tools: Read, Grep, Glob, Bash를 지정해 물리적으로 편집을 막을 수 있습니다. 단순히 정돈을 위한 설정이 아니라 실제 안전 경계입니다. 읽기 전용 리뷰어는 검토 중인 파일을 실수로 다시 쓸 수 없습니다.

알아둘 만한 설정이 하나 더 있습니다. isolation: worktree를 지정하면 서브에이전트가 저장소의 격리된 복사본인 임시 git worktree에서 실행됩니다. 변경 사항이 없으면 해당 worktree는 자동으로 정리됩니다. 서브에이전트가 작업 트리에 영향을 주지 않은 채 위험한 시도를 해보게 하고 싶을 때 유용합니다.

서브에이전트는 언제 사용하고, 언제 피해야 합니까?

GitHub 설정 파일만 늘어놓는 글들이 건너뛰기 쉬운 부분이지만, 실제로 시간과 비용을 아끼려면 이 판단이 가장 중요합니다. 서브에이전트는 공짜가 아닙니다. 따라서 질문은 “여기에 쓸 수 있는가?”가 아니라 “격리로 얻는 이득이 비용보다 큰가?”여야 합니다.

서브에이전트의 구조상 적합하지 않은 경우도 분명합니다.

• 반복적인 의견 교환. 작업을 자주 다듬어야 하고 사용자의 판단이 계속 개입해야 한다면 메인 대화에 두는 편이 낫습니다. 위임하면 피드백 흐름이 끊깁니다.
• 컨텍스트를 공유하는 단계. 기획, 구현, 테스트가 앞 단계의 내용을 이어받는 흐름이라면 하나의 스레드에서 처리해야 합니다. 각각 아무것도 모른 채 시작하는 세 서브에이전트로 나누면 안 됩니다.
• 빠르고 작은 수정. 오타 하나를 고치려고 서브에이전트를 띄우면 수정 자체보다 준비 비용이 더 큽니다.
• 응답 속도가 중요한 작업. 서브에이전트는 처음부터 컨텍스트를 모으느라 시간이 걸립니다. 답이 당장 필요할 때는 메인 대화에서 바로 처리하는 편이 빠릅니다.

서브에이전트와 스킬·포크·에이전트 팀의 차이

Claude Code에는 작업을 구성하는 방법이 이제 네 가지 있으며, 서로 혼동하기 쉽습니다. 차이는 모두 컨텍스트에 있습니다.

가장 많이 헷갈리는 구분은 스킬과 서브에이전트입니다. 둘 다 ‘저장된 전문 지식’처럼 느껴지기 때문입니다. 스킬은 메인 대화의 컨텍스트 안에서 실행되는 재사용 지침이므로 현재 진행 중인 일을 모두 볼 수 있습니다. 서브에이전트는 정반대입니다. 의도적으로 격리되며 전달받은 작업 외에는 아무것도 보지 못합니다. Claude가 사용자와 계속 작업하면서 정해진 스타일을 적용하게 하려면 스킬을 씁니다. 잡음 많은 조사를 보이지 않는 곳에서 처리한 뒤 결과만 보고받으려면 서브에이전트를 씁니다.

포크는 그 중간에 해당하는 유용한 선택지입니다. 지금까지의 대화 전체, 즉 같은 시스템 프롬프트와 툴, 모델, 메시지 기록을 상속하므로 다시 설명할 필요가 없습니다. 다만 포크에서 실행한 툴 호출은 메인 컨텍스트에 들어오지 않고 최종 결과만 반환됩니다. 이름이 지정된 서브에이전트에 필요한 배경 설명이 지나치게 많다면 포크를 사용합니다. 포크 모드는 CLAUDE_CODE_FORK_SUBAGENT 환경 변수로 활성화해야 합니다.

강력한 고급 기능과 그 한계

최근 추가된 두 기능은 서브에이전트의 활용 범위를 크게 넓히지만, 각각 주의해야 할 경계가 있습니다.

중첩. Claude Code v2.1.172부터는 서브에이전트가 자체 서브에이전트를 생성할 수 있습니다. 리뷰어 서브에이전트가 발견한 항목마다 검증자를 보내도 중간 출력은 모두 내부에 남고, 최상위 서브에이전트의 요약만 사용자에게 도착합니다. 한계는 고정되어 있습니다. 중첩은 다섯 단계까지만 가능하고 설정으로 바꿀 수 없으며, 다섯 번째 단계의 서브에이전트에는 Agent 툴이 제공되지 않아 더 이상 생성할 수 없습니다. 이 제한에는 이유가 있습니다. 깊은 단계에서 작업이 연쇄적으로 늘어나면 순식간에 대규모 에이전트가 실행되어 토큰 비용이 치솟을 수 있습니다. 깊이는 목표가 아니라 예산으로 다뤄야 합니다.

메모리. memory: project 또는 user, local을 추가하면 서브에이전트가 세션을 넘어 계속 읽고 쓸 수 있는 영구 메모리 디렉터리를 갖게 됩니다. 프로젝트 메모리를 사용하는 코드 리뷰어는 시간이 지날수록 팀의 규칙과 반복되는 문제를 기록하므로 사용할수록 더 정교해집니다. 버전 관리로 공유할 수 있는 project가 권장 기본값입니다. 메모리를 켜면 Claude Code가 시작 시 서브에이전트의 시스템 프롬프트에 MEMORY.md의 처음 200줄 또는 25KB를 주입하므로 이 파일은 잘 정리된 상태로 유지해야 합니다.

좋은 출발점은 역할이 분명한 서브에이전트 하나를 만드는 것입니다. 읽기 전용 code-reviewer가 대표적인 예입니다. 이를 .claude/agents/에 넣어 버전 관리에 포함하고 변경할 때마다 실행합니다. 효과가 확인되면 더 저렴한 모델을 쓰는 리서치 서브에이전트를 추가합니다. 성과를 내는 팀은 에이전트 서른 개를 돌리지 않습니다. 각자 한 가지 역할을 제대로 수행하는 세 개를 운영합니다. 먼저 코딩 툴 자체를 고르는 중이라면 판단 기준이 다릅니다. Codex와 Claude Code, Cursor 비교와 더 폭넓은 최고의 AI 코딩 에이전트를 참고할 수 있습니다.

Claude Code를 실제 출시 워크플로에 연결하고 있다면 이 글에서 필요한 핵심 대부분을 다뤘습니다. 뉴스레터 구독에서 출시 당일의 과장 대신 현장에서 작동하는 설정을 받아볼 수 있습니다.