클로드 코드 서브에이전트 사용법: 리뷰와 조사 역할을 나눠 맡기는 팁

TL;DR

오늘의 AI 활용 팁

클로드 코드 서브에이전트는 Claude Code 안에서 특정 역할을 맡는 보조 AI 작업자입니다.

Anthropic 공식 문서 기준으로 서브에이전트는 별도 컨텍스트 창, 전용 시스템 프롬프트, 도구 접근 권한, 독립 권한 설정을 가질 수 있습니다.

초보자는 처음부터 여러 에이전트에게 대규모 수정을 맡기기보다, 읽기 전용 코드 리뷰어나 조사 담당자처럼 결과만 요약해 돌려주는 역할부터 만드는 것이 안전합니다.

핵심 3줄 요약

• 핵심 1
  클로드 코드 서브에이전트는 검색, 조사, 리뷰처럼 메인 대화를 어지럽히기 쉬운 작업을 별도 컨텍스트에서 처리하게 해줍니다.
• 핵심 2
  처음 만들 때는 /agents 관리 화면에서 개인용 또는 프로젝트용 범위를 고르고, Read, Grep, Glob 같은 읽기 중심 도구만 허용하는 방식이 안전합니다.
• 핵심 3
  agent teams는 여러 Claude Code 세션이 직접 협업하는 실험 기능이고, 서브에이전트는 단일 세션 안에서 결과를 요약해 돌려주는 역할에 더 가깝습니다.

이 글에서 다룰 내용

클로드 코드 서브에이전트란?

클로드 코드 서브에이전트는 Claude Code 안에서 특정 작업을 전담하도록 만든 보조 AI 작업자입니다. Anthropic 공식 문서는 서브에이전트를 특정 유형의 작업을 처리하는 전문 AI 어시스턴트로 설명합니다.

중요한 점은 컨텍스트 분리입니다. 코드베이스 전체를 훑거나 로그를 길게 조사하거나 여러 파일을 검색하는 일은 메인 대화의 맥락을 금방 가득 채웁니다. 서브에이전트는 그런 탐색을 자기 컨텍스트에서 처리하고, 메인 대화에는 필요한 요약만 돌려줄 수 있습니다.

한 문장 정의

클로드 코드 서브에이전트는 Claude Code 안에서 특정 역할과 도구 권한을 부여해 조사, 리뷰, 디버깅 같은 반복 작업을 별도 맥락에서 처리하게 하는 기능입니다.

서브에이전트는 단순한 프롬프트 저장소가 아닙니다. 공식 문서 기준으로 각 서브에이전트는 이름, 설명, 시스템 프롬프트, 사용할 도구, 모델, 권한 모드, 메모리, 배경 실행 여부 같은 설정을 가질 수 있습니다. 그래서 "리뷰만 하는 담당자", "보안 위험만 찾는 담당자", "문서 출처만 확인하는 담당자"처럼 역할을 좁히기 좋습니다.

누가 쓰면 좋은가?

이 팁은 Claude Code를 한 번씩 써본 뒤, 반복되는 조사와 검토를 더 깔끔하게 나누고 싶은 사람에게 유용합니다.

• 코드 수정 전에 관련 파일만 먼저 찾고 싶은 개발자
• pull request나 기능 변경을 항상 같은 기준으로 검토하고 싶은 팀
• 보안, 성능, 테스트, 문서 품질을 따로 확인하고 싶은 리더
• 긴 로그, 빌드 결과, 여러 설정 파일을 메인 대화에 전부 붙이고 싶지 않은 사람
• 감자나라ai님처럼 자동화 원고, 상태 파일, 발행 스크립트, 검증 결과를 단계별로 나눠 확인하는 운영자

한 줄 정리

메인 대화가 "조사 내용"으로 너무 길어져서 최종 판단이 흐려진다면, 그 조사 업무는 서브에이전트 후보입니다.

언제 쓰면 좋은가?

서브에이전트는 결과만 필요하고 중간 탐색 과정은 길어도 되는 작업에 잘 맞습니다.

좋은 사용 상황은 다음과 같습니다.

1. 특정 폴더에서 관련 파일을 찾고 요약만 받고 싶을 때
2. 수정 후 코드 리뷰를 별도 역할에게 맡기고 싶을 때
3. 보안, 성능, 접근성, 테스트처럼 관점이 다른 검토를 분리하고 싶을 때
4. 긴 로그나 검색 결과가 메인 대화를 차지하지 않게 하고 싶을 때
5. 팀 프로젝트에서 같은 리뷰 기준을 반복 적용하고 싶을 때

반대로 한 번만 할 짧은 질문, 사람이 아직 기준을 정하지 못한 작업, 같은 파일을 여러 역할이 동시에 고치는 작업에는 서브에이전트보다 메인 대화가 낫습니다.

실전 팁

처음에는 "수정 담당자"보다 "읽기 전용 리뷰어"를 먼저 만드세요. 안전하게 효과를 확인한 뒤에 도구 권한을 넓히는 편이 좋습니다.

시작 전 확인해야 할 기준

첫째, 어떤 역할인지 한 문장으로 좁혀야 합니다. "도와주는 에이전트"는 너무 넓습니다. "변경된 파일을 읽고 보안 위험과 테스트 누락만 찾는 리뷰어"처럼 역할과 결과물이 분명해야 합니다.

둘째, 도구 권한을 보수적으로 정해야 합니다. Anthropic 문서는 서브에이전트가 기본적으로 메인 대화의 도구를 상속할 수 있고, tools 또는 disallowedTools 설정으로 접근 권한을 제한할 수 있다고 설명합니다. 초보자는 처음에 읽기 도구만 허용하는 방식이 안전합니다.

셋째, 개인용과 프로젝트용 범위를 구분해야 합니다. 공식 문서 기준으로 개인용 서브에이전트는 사용자 폴더에 저장되어 여러 프로젝트에서 쓸 수 있고, 프로젝트용 서브에이전트는 프로젝트 안의 .claude/agents 폴더에 저장해 팀과 함께 관리할 수 있습니다.

넷째, 모델과 비용을 생각해야 합니다. 공식 문서는 서브에이전트마다 모델을 지정하거나 메인 대화 모델을 상속할 수 있다고 안내합니다. 빠른 탐색은 가벼운 모델, 복잡한 설계 리뷰는 더 강한 모델처럼 나눌 수 있습니다.

다섯째, 권한 모드를 쉽게 높이지 않아야 합니다. 공식 문서는 bypassPermissions 같은 권한 모드를 주의해서 쓰라고 안내합니다. 파일 수정, 명령 실행, 외부 도구 사용이 섞이면 사람이 검토해야 할 지점이 늘어납니다.

주의

서브에이전트를 만든다는 것은 "AI에게 더 많은 자유를 준다"가 아니라 "AI가 맡을 역할과 권한을 더 명확히 제한한다"에 가깝습니다.

리뷰와 조사 역할을 나눠 쓰는 순서

1단계: 반복되는 작업 하나를 고릅니다

먼저 매번 반복되는 작은 작업을 고르세요.

예를 들어 다음과 같은 작업이 좋습니다.

• 수정한 파일에서 테스트 누락 찾기
• 새 기능과 관련된 기존 파일 목록 찾기
• README와 설정 파일의 불일치 찾기
• 보안상 민감한 변경 후보만 요약하기
• 긴 로그에서 실패 원인 후보만 정리하기

처음부터 "전체 프로젝트를 알아서 개선해줘"처럼 넓게 맡기면 서브에이전트의 장점이 줄어듭니다.

2단계: /agents 화면에서 새 에이전트를 만듭니다

Claude Code에서 /agents 명령을 실행하면 서브에이전트를 관리하는 화면을 열 수 있습니다. 공식 문서 기준으로 이 화면에서 사용 가능한 에이전트를 보고, 새 에이전트를 만들고, 기존 설정과 도구 접근을 편집할 수 있습니다.

초보자라면 직접 파일을 쓰기보다 /agents 화면에서 시작하는 편이 안전합니다. 이름, 설명, 도구, 모델, 색상 같은 항목을 단계적으로 확인할 수 있기 때문입니다.

3단계: 개인용인지 프로젝트용인지 고릅니다

개인용 서브에이전트는 여러 프로젝트에서 반복해서 쓸 수 있습니다. 예를 들어 "문서 리뷰어", "로그 요약 담당자", "테스트 누락 점검 담당자"처럼 범용 역할은 개인용으로 둘 수 있습니다.

프로젝트용 서브에이전트는 해당 저장소의 규칙을 알아야 할 때 좋습니다. 예를 들어 특정 서비스의 보안 규칙, 테스트 명령, 배포 전 체크리스트를 포함해야 한다면 프로젝트 안에 두고 팀이 함께 관리하는 편이 낫습니다.

4단계: 설명문에 발동 조건을 분명히 씁니다

Claude Code는 서브에이전트의 description을 보고 언제 위임할지 판단할 수 있습니다. 그래서 설명문에는 역할과 사용 조건이 들어가야 합니다.

나쁜 예:

코드를 잘 봅니다.

좋은 예:

변경된 파일을 읽고 보안 위험, 테스트 누락, 사용자 데이터 처리 문제만 찾아 요약하는 읽기 전용 리뷰어입니다.

이렇게 쓰면 메인 Claude가 "이 작업은 리뷰어에게 맡기면 되겠다"라고 판단하기 쉽습니다.

5단계: 도구를 읽기 중심으로 제한합니다

처음 만드는 리뷰어는 Read, Grep, Glob처럼 읽기 중심 도구만 허용하는 편이 좋습니다. 공식 문서 예시도 읽기 전용 리뷰어를 만들 때 읽기 도구만 남기는 흐름을 안내합니다.

파일을 직접 수정해야 하는 역할은 나중에 만드세요. 먼저 읽기 전용으로 품질을 확인하고, 결과가 일관적이면 작은 수정 권한을 가진 서브에이전트로 확장하는 편이 안전합니다.

6단계: 첫 실행은 명시적으로 호출합니다

자동 위임을 기대하기보다 처음에는 직접 호출하세요.

예를 들어 "code-reviewer 에이전트를 사용해서 최근 변경 파일을 읽고 위험한 부분만 요약해줘"처럼 말합니다. 공식 문서도 새 서브에이전트를 저장한 뒤 특정 에이전트를 사용하라고 요청해 실행해보는 흐름을 안내합니다.

7단계: 결과가 충분히 짧고 판단 가능한지 확인합니다

좋은 서브에이전트 결과는 길고 화려한 보고서가 아닙니다. 메인 대화가 다음 결정을 내릴 수 있도록 정리된 요약이어야 합니다.

다음 항목을 확인하세요.

1. 어떤 파일을 봤는지
2. 무엇이 위험한지
3. 심각도는 어느 정도인지
4. 사람이 다음에 무엇을 확인해야 하는지
5. 수정이 필요한지, 단순 참고인지

핵심 인사이트

서브에이전트의 성공 기준은 "많이 일했는가"가 아니라 "메인 대화가 더 짧고 정확한 결정을 내리게 했는가"입니다.

바로 쓰는 요청 문장

리뷰용:

코드 리뷰어 서브에이전트를 사용해서 최근 변경 파일을 읽어줘. 보안 위험, 테스트 누락, 사용자 데이터 처리 문제만 찾아서 심각도 순으로 요약해줘. 파일을 수정하지 말고, 수정 제안은 사람이 검토할 수 있게 구체적으로 적어줘.

조사용:

조사 담당 서브에이전트를 사용해서 이 기능과 관련된 파일을 찾아줘. 메인 대화에는 파일 목록, 각 파일의 역할, 수정 후보 여부만 요약해서 돌려줘. 확실하지 않은 추측은 따로 표시해줘.

로그 분석용:

로그 분석 서브에이전트를 사용해서 실패 원인 후보를 세 가지 이하로 좁혀줘. 원인마다 근거가 되는 로그 줄의 의미를 설명하고, 바로 실행할 확인 명령 후보를 제안해줘. 직접 명령을 실행하기 전에는 멈춰줘.

문서 검수용:

문서 리뷰어 서브에이전트를 사용해서 README와 설정 파일 설명이 서로 맞는지 확인해줘. 오래된 명령, 빠진 환경 변수, 사용자가 헷갈릴 표현만 찾아줘. 문장 다듬기는 하지 말고 문제 목록만 줘.

실전 팁

첫째, 서브에이전트 이름은 기능보다 역할로 짓는 것이 좋습니다. test-gap-reviewer, security-reviewer, docs-consistency-checker처럼 결과 기준이 드러나는 이름이 관리하기 쉽습니다.

둘째, 한 서브에이전트에 너무 많은 역할을 넣지 마세요. 보안 리뷰, 성능 리뷰, 문서 리뷰, 테스트 설계를 한 에이전트에 다 넣으면 다시 큰 프롬프트가 됩니다. 역할을 작게 나누면 결과도 비교하기 쉽습니다.

셋째, 메인 대화에는 최종 판단을 남기세요. 서브에이전트가 찾은 내용은 근거 자료입니다. 최종 수정 여부, 테스트 실행 여부, 배포 여부는 메인 대화에서 사람이 확인하는 구조가 안전합니다.

넷째, 팀 규칙은 프로젝트용으로 저장하세요. 공식 문서에 따르면 프로젝트 서브에이전트는 .claude/agents 폴더에 둘 수 있고, 버전 관리에 포함해 팀이 함께 개선할 수 있습니다. 개인 취향과 팀 기준을 섞지 않는 것이 좋습니다.

다섯째, agent teams와 혼동하지 마세요. 공식 문서는 agent teams가 실험 기능이며 기본적으로 비활성화되어 있고, 여러 Claude Code 세션이 직접 소통하며 작업한다고 설명합니다. 반면 서브에이전트는 단일 세션 안에서 특정 역할이 일하고 결과를 메인 대화로 돌려주는 흐름입니다.

주의할 점

가장 큰 위험은 권한을 너무 빨리 넓히는 것입니다. 읽기 전용 리뷰어가 충분히 잘 작동하는지 확인하기 전에는 파일 수정, 명령 실행, 외부 MCP 도구 접근을 넓히지 마세요.

두 번째 위험은 같은 파일을 여러 역할이 동시에 고치게 하는 것입니다. 보안 리뷰어, 성능 리뷰어, 문서 리뷰어가 모두 같은 파일을 수정하면 충돌과 판단 누락이 생길 수 있습니다. 처음에는 "찾기와 요약"만 맡기고, 실제 수정은 메인 대화에서 하나씩 진행하세요.

세 번째 위험은 과도한 병렬화입니다. Anthropic의 agent teams 문서는 여러 작업자가 독립적으로 움직이면 토큰 사용량과 조정 비용이 커진다고 설명합니다. 서브에이전트도 마찬가지로, 작고 반복적인 작업부터 시작하는 것이 좋습니다.

네 번째 위험은 설명문이 모호한 상태로 자동 위임을 기대하는 것입니다. description이 흐리면 Claude가 언제 써야 할지 판단하기 어렵습니다. "언제 호출할지"와 "무엇을 돌려줄지"를 구체적으로 써야 합니다.

주의

서브에이전트는 검토 책임을 없애는 기능이 아닙니다. 특히 파일 수정, 터미널 명령, 배포, 인증 정보, 고객 데이터가 관련되면 사람이 최종 확인해야 합니다.

서브에이전트와 Skills, Hooks, agent teams는 어떻게 다른가?

Skills는 반복 지침과 절차를 패키지로 저장하는 방식입니다. 예를 들어 "워드프레스 원고 검수 절차"처럼 작업 기준을 문서화하는 데 좋습니다.

Hooks는 특정 이벤트 뒤에 자동으로 명령이나 검사를 실행하는 구조입니다. 예를 들어 파일 수정 후 포맷터나 테스트를 돌리는 자동화에 가깝습니다.

서브에이전트는 역할을 가진 보조 작업자입니다. 같은 기준을 읽고, 제한된 도구로 조사하고, 결과를 요약해 돌려주는 흐름에 맞습니다.

agent teams는 여러 독립 Claude Code 세션이 팀처럼 직접 소통하는 실험 기능입니다. 공식 문서 기준으로 기본 비활성화 상태이며, 복잡한 병렬 탐색이나 여러 가설 검증처럼 조정 비용을 감수할 만한 작업에 맞습니다.

한 줄 정리

기준을 저장하려면 Skills, 이벤트 자동화를 하려면 Hooks, 역할을 나눠 조사와 리뷰를 맡기려면 서브에이전트, 여러 세션이 서로 토론해야 하면 agent teams를 검토하세요.

자주 묻는 질문

Q1. 클로드 코드 서브에이전트는 초보자도 써도 되나요?

네, 다만 처음에는 읽기 전용 리뷰어나 조사 담당자처럼 안전한 역할부터 시작하는 편이 좋습니다. 파일을 직접 고치거나 명령을 실행하는 역할은 결과 품질과 권한 구조를 이해한 뒤에 넓히세요.

Q2. 서브에이전트가 자동으로 실행되나요?

공식 문서 기준으로 Claude는 서브에이전트의 설명과 작업이 맞으면 위임할 수 있습니다. 하지만 처음 만든 에이전트는 "이 에이전트를 사용해줘"라고 명시적으로 호출해 결과를 확인하는 편이 안전합니다.

Q3. 개인용과 프로젝트용 중 무엇을 골라야 하나요?

여러 프로젝트에서 반복할 범용 역할은 개인용이 좋습니다. 특정 저장소의 규칙, 파일 구조, 테스트 기준을 알아야 하는 역할은 프로젝트용이 좋습니다.

Q4. 서브에이전트와 agent teams는 같은 기능인가요?

아닙니다. 서브에이전트는 단일 Claude Code 세션 안에서 별도 컨텍스트로 일하고 결과를 메인 대화에 돌려주는 방식입니다. agent teams는 여러 Claude Code 세션이 직접 소통하고 작업 목록을 공유하는 실험 기능입니다.

Q5. 서브에이전트에 파일 수정 권한을 줘도 되나요?

가능은 하지만 처음부터 권장하지 않습니다. 읽기 전용으로 리뷰 품질을 확인한 뒤, 정말 필요한 경우에만 좁은 범위의 수정 권한을 주는 편이 안전합니다.

Q6. 클로드 Skills 글과 이 글은 무엇이 다른가요?

Skills는 반복 지침과 절차를 저장하는 방법에 가깝고, 서브에이전트는 그 지침을 바탕으로 특정 역할을 맡아 별도 맥락에서 일하는 작업자에 가깝습니다. 예를 들어 "리뷰 기준"은 Skill이 될 수 있고, 그 기준으로 변경 파일을 읽는 "리뷰 담당자"는 서브에이전트가 될 수 있습니다.

출처

마무리

클로드 코드 서브에이전트 사용법의 핵심은 AI에게 일을 더 많이 맡기는 것이 아니라, 역할과 권한을 더 작게 나누는 것입니다. 메인 대화는 최종 판단과 실행 결정을 맡고, 서브에이전트는 조사, 리뷰, 로그 분석, 문서 검수처럼 맥락을 많이 쓰는 보조 작업을 맡는 구조가 가장 안정적입니다.

처음에는 읽기 전용 리뷰어 하나만 만들어 보세요. 변경 파일을 읽고 위험한 점만 요약하게 한 뒤, 그 결과가 실제 판단에 도움이 되는지 확인하면 됩니다. 이 작은 흐름이 안정되면 보안 리뷰어, 테스트 누락 점검자, 문서 일관성 검수자처럼 역할을 하나씩 늘려갈 수 있습니다.