Claude Code에서 조사 계열의 태스크(코드베이스 파악, 라이브러리 비교, 로그 분석 등)를 던지면, 메인 대화 컨텍스트 (Conversation Context)가 파일 내용으로 채워져 금방 버거워진다. 이 해결책이 바로 **서브 에이전트 (Sub-agent)**이다. 조사를 별도의 컨텍스트를 가진 자식 에이전트에게 분담시키고, 메인 측에는 결론만 반환하게 하는 메커니즘이다.

이 기사에서는 .claude/agents/에 커스텀 서브 에이전트를 직접 제작하여 병렬 조사를 수행하기까지의 절차와, 본인이 실제로 겪었던 3가지 문제점을 정리한다.

• 예상 독자: Claude Code를 일상적으로 사용하며, 컨텍스트 압박이나 조사 속도 저하로 어려움을 겪고 있는 사람

• 전제 환경: Claude Code v2.x (2026년 6월 시점), macOS / Linux 모두 가능

• 서브 에이전트 기능 자체의 과금은 일반적인 토큰 소비와 동일 (자식 에이전트의 분량도 소비된다는 점에 주의)

• .claude/agents/<name>.md에 frontmatter (name / description / tools) + 본문 (시스템 프롬프트)를 작성하는 것만으로 커스텀 서브 에이전트를 만들 수 있다.

• description이 위임 판단의 재료가 되므로, "언제 사용하는지"를 구체적으로 적지 않으면 자동으로 호출되지 않는다.

• 독립된 조사는 하나의 메시지 내에서 여러 개를 기동하면 병렬 실행된다. 직렬로 던지면 몇 배 더 느리다.

프로젝트 직하에 .claude/agents/dep-checker.md를 만든다. 예시로 "의존 라이브러리의 이용 장소를 조사하는" 전용 에이전트:

---
name: dep-checker
description: 지정된 라이브러리가 코드베이스의 어디에서·어떻게 사용되고 있는지 조사한다. 의존성 삭제·교체·업그레이드의 영향 범위를 알고 싶을 때 사용한다.
...

Claude Code 세션 내에서 /agents를 실행하면 정의된 에이전트 목록이 나온다. 여기에 dep-checker가 나와 있다면 OK. 나오지 않는다면 frontmatter의 YAML이 깨져 있는 경우가 많다 (후술).

명시적으로 지명하는 것이 확실하다:

dep-checker 서브 에이전트를 사용해서, axios의 이용 장소를 조사해줘

병렬로 처리하고 싶을 때는 한 번의 메시지로 묶어서 의뢰한다:

서브 에이전트를 병렬로 사용하여, axios / lodash / moment 3개를 각각 별도의 에이전트로 조사해줘

내 환경에서는 3개 라이브러리 조사가 직렬일 때는 약 4분, 병렬일 때는 약 90초였다. 각각의 결과가 요약되어 메인 대화로 반환되므로, 메인 컨텍스트는 거의 소비되지 않는다.

1. description이 너무 짧으면 자동으로 호출되지 않는다

처음에 description: 의존 관계를 조사함이라고만 적었더니, "axios의 이용 장소를 알려줘"라고 부탁해도 Claude가 스스로 Grep을 시작해 버려 서브 에이전트가 호출되지 않았다.

원인: Claude는 description을 읽고 "이 태스크를 위임해야 하는가"를 판단한다. 너무 짧은 설명은 판단 재료가 되지 않는다.

회피책: description에는 "무엇을 하는가"에 더해 "언제 사용하는가"를 적는다. 위의 예시처럼 "~를 알고 싶을 때 사용한다"까지 포함하면, 지명하지 않아도 자동으로 위임되게 되었다.

2. tools를 명시하지 않으면 파일을 편집할 수 있다

frontmatter의 tools:를 적지 않고 운용했더니, 조사 전용으로 만든 에이전트가 파일을 편집 (Edit) 하고 있었다.

원인: tools를 생략하면 메인 에이전트와 동일한 툴 세트 (Edit나 Write 포함)를 사용할 수 있는 사양이다.

회피책: 조사 계열 에이전트는 tools: Read, Grep, Glob, Bash와 같이 읽기 계열로 명시적으로 제한한다. 읽기 전용으로 해두면, 병렬로 몇 개를 실행하더라도 작업 트리 (Working Tree)를 망가뜨릴 걱정이 없어진다.

3. 서브 에이전트의 작업 과정을 확인할 수 없다

서브 에이전트가 실제로 무엇을 읽었는지·어떤 명령어를 입력했는지는 메인 대화에 표시되지 않는다. 반환되는 것은 최종 리포트뿐이다. 처음에 "정말로 모든 파일을 조사한 것인가?"를 검증할 수 없어 곤란했다.

회피책: 시스템 프롬프트 측에서 "조사한 파일 수와 검색 쿼리를 결과 서두에 반드시 작성할 것"이라고 출력 규약 (Output Contract)을 정해둔다. 결과의 자기 신고 방식이 되긴 하지만, 커버리지 (Coverage)의 타당성은 판단할 수 있게 된다.

이 메커니즘의 본질은 서브 에이전트(Sub-agent)마다 독립적인 컨텍스트 윈도우(Context Window)가 할당된다는 점에 있다. 메인(Main) 측은 '의뢰문 + 최종 리포트'만을 보유하므로, 10개의 파일을 읽는 조사를 3개 동시에 실행하더라도 메인의 소비는 수백 토큰 내외로 끝난다. 반대로 말하면, 자식(Child) 측에서 읽은 내용을 메인이 직접 참조할 수는 없으므로, '나중에 사용할 정보는 반드시 리포트에 포함하도록 한다'는 설계가 필요하다.

.claude/agents/<name>.md 의 frontmatter + 시스템 프롬프트(System Prompt)로 커스텀 서브 에이전트를 정의할 수 있다. - description에는 '언제 사용하는지'까지 작성한다. 이것이 자동 위임(Automatic Delegation)의 정밀도를 결정한다.

• tools는 명시적으로 제한한다. 생략 시 모든 도구(All tools)를 상속받으므로 조사 용도로는 위험하다.
• 독립적인 태스크는 1개의 메시지에 모아서 의뢰하여 병렬화한다.
• 결과만 반환된다는 전제하에, 출력 계약(Output Contract, 무엇을 보고하게 할 것인가)을 프롬프트에 작성한다.