서브에이전트: 주의력을 위한 별도의 창

1. 서브에이전트란 무엇이고 왜 필요한가

서브에이전트는 Claude Code가 작업을 넘기는 전문화된 도우미입니다. 자신만의 컨텍스트 창에서 작업을 수행하고 여러분의 세션에 짧은 요약을 반환합니다. 파일 읽기, 검색 및 도구 호출은 해당 컨텍스트에 남아있습니다.

왜 이렇게 할까요? 기본 세션에서 작업할 때 메시지, 읽은 파일, 명령 결과가 모두 하나의 창에서 공간을 차지하는데, 그 크기는 무한하지 않습니다. 창이 채워지면 Claude Code는 기록을 줄이고, 그 과정에서 일부 세부 정보가 사라질 수 있습니다. 서브에이전트를 사용하면 중간 작업을 별도의 창으로 옮기고 기본 대화에는 그 결과만 남겨둘 수 있습니다.

가장 간단한 서브에이전트

처음 실행할 때는 Claude Code에 보내는 일반 메시지로 충분합니다. 서브에이전트를 호출해 달라고 명시적으로 요청하고 그 작업을 설명하세요. 역할 파일을 미리 만들 필요는 없습니다. 이런 작업에는 기본 제공 도우미로 충분합니다. 예를 들어:

서브에이전트를 호출하여 index.html 파일을 읽으십시오.
주요 섹션과 각 섹션의 기능을 간단한 맵으로 작성하게 하십시오.
그런 다음 3-5문장으로 콘텐츠의 간단한 요약을 작성하십시오.
파일을 변경하지 마십시오. 서브에이전트의 답변을 이 세션으로 반환하십시오.

주 에이전트가 도우미에게 작업을 넘기고, 실행이 끝나면 그 답변을 여러분의 대화에 보여 줍니다. 백그라운드로 실행하면 아래쪽 입력 필드 밑에 서브에이전트의 이름과 작업 상태가 표시된 막대가 나타납니다. 클릭하면 서브에이전트 세션이 열려 읽고 있는 내용과 수행하는 작업을 볼 수 있습니다. 작업 도중에 별도의 서브에이전트 실행이 실제로 나타났는지 확인하세요. 일반 텍스트로 한 요청은 Claude의 선택을 이끌 뿐, 그것만으로 위임이 보장되지는 않습니다.

서브에이전트가 받는 것

같은 작업을 고정된 규칙으로 반복해야 한다면 직접 역할을 파일로 정의할 수 있습니다. 이러한 사용자 정의 서브에이전트가 시작할 때 받는 주요 입력은 두 가지입니다:

• 여러분의 구성 파일에 있는 역할 지침 - 전문 분야와 동작 규칙;
• 주 에이전트가 여러분의 요청에 따라 작성하는 작업 설명.

여기에 Claude Code가 공통 배경 정보를 직접 추가합니다. 프로젝트의 CLAUDE.md 파일, git status 스냅샷, 실행 환경 정보입니다. 여러분과 주 에이전트의 대화는 여기에 포함되지 않습니다.

다이어그램에서 중요한 점은 하나입니다. 서브에이전트는 자신의 창에서 작업을 수행하고 기본 대화에는 요약을 반환합니다. 주 에이전트는 중간 읽기와 검색을 모두 불러올 필요가 없습니다. 다만 요약 자체도 기본 컨텍스트에서 공간을 차지합니다.

이러한 분리에는 단점도 있습니다. 요약은 결론에 이르는 전체 과정을 보여 주지 않습니다. 요약만 보면 도우미에게 어떤 데이터가 부족했는지, 무엇을 확인하지 않고 남겼는지 놓칠 수 있습니다. 그래서 응답에는 근거와 한계가 필요하고, 그 결론은 확인하는 것이 좋습니다.

Claude가 모든 것을 기억하지 못하는 이유

컨텍스트 창은 모델이 다음 응답을 준비할 때 사용할 수 있는 정보입니다: 지침, 사용 가능한 대화 기록, 읽은 코드, 명령 결과. 덕분에 에이전트는 여러분이 몇 메시지 전에 논의한 결정을 바탕으로 작업할 수 있습니다. 창에는 제한이 있습니다. 전체 대화를 모든 세부 사항과 함께 영구적으로 저장하지 않습니다.

스크린샷에서 /context 명령은 4k/200k tokens (2%)를 표시합니다. 사용 가능한 200,000개 토큰 중 약 4,000개가 사용 중이라는 뜻입니다. 토큰은 텍스트의 작은 조각입니다: 단어, 단어의 일부 또는 기호. 따라서 200,000개 토큰은 200,000개 단어와 같지 않습니다. 이는 표시된 세션의 창 크기입니다. 다른 모델이나 구성에서는 다를 수 있습니다.

아래에서 공간을 차지하는 것을 볼 수 있습니다: System prompt - 시스템 지침, Memory files - 로드된 메모리 및 규칙 파일, Skills - 스킬에 대한 정보, Messages - 메시지. 여기서는 대화가 거의 없지만 창의 일부는 이미 지침이 차지하고 있습니다. Free space: 196k (98.0%) 줄은 남은 여유 공간을 보여줍니다. 대화, 파일 읽기 및 명령 실행이 진행되면서 사용됩니다.

이어서 코드를 읽는 사용자 정의 리뷰어를 예로 이 메커니즘을 살펴보겠습니다. 리뷰어가 어떤 정보를 받는지, 역할 파일을 어떻게 만드는지 봅니다. 여기서는 새로운 일반 실행에 대해 이야기합니다. 이전 작업을 계속하거나 기록의 복사본을 전달하는 방법은 이 예제에서 필요하지 않습니다.

2. 리뷰어가 프로젝트에 대해 알고 있는 것

별도의 컨텍스트는 도우미가 아무것도 모른다는 의미가 아닙니다. 초기 지침과 프로젝트 접근 권한이 있습니다. 다음은 예제의 사용자 정의 리뷰어가 정보를 받는 방식입니다:

CLAUDE.md는 Claude Code에 대한 일반 지침이 담긴 파일입니다. 예를 들어 소스 코드가 어디에 있는지, 프로젝트에서 어떤 규칙이 채택되었는지 등입니다. 이 검증을 위해 특별히 만들 필요는 없습니다.

여러분의 대화 기록은 자동으로 전달되지 않습니다. 주 에이전트가 이미 app.js를 읽었더라도 그 내용이 리뷰어에게 저절로 생기지는 않습니다. 하지만 파일이 사라진 것은 아니니 도우미가 다시 열면 됩니다.

채팅에서 내린 결정도 마찬가지입니다. 목록에 같은 이름이 두 개 있어도 각각 별도의 구매 항목으로 남아야 한다고 논의했다고 합시다. 삭제를 검증할 때 이것은 중요한 요구사항입니다. 주 에이전트가 이를 작업에 포함하거나, 도우미가 이 내용이 기록된 문서를 읽어야 리뷰어에게 전달됩니다.

3. 역할 파일 만들기

역할 파일은 프로젝트 안의 .claude/agents/reviewer.md에 두겠습니다. 사용자 폴더 ~/.claude/agents/에도 여러 프로젝트에서 쓸 수 있는 역할을 저장할 수 있습니다. ~ 기호는 사용자의 홈 폴더를 나타냅니다. 지금은 프로젝트 버전으로 충분합니다.

Claude Code에 요청하여 파일을 만들 수 있습니다:

페이지 코드를 수정 없이 검사하는 .claude/agents/reviewer.md를 만드십시오.
Read, Grep, Glob만 허용하십시오.
리뷰어는 근거 있는 발견 사항, 검증한 범위
및 한계를 반환합니다. 발견 사항이 없어도 괜찮습니다.
생성된 파일을 보여주십시오.

결과로 평범한 텍스트 파일이 생겨야 합니다. 마법은 없습니다. 아래는 완성된 버전입니다. 에이전트의 응답과 비교하거나 직접 저장해도 됩니다. 같은 이름의 역할이 이미 있으면 필요한 지침을 덮어쓰지 않도록 먼저 내용을 확인하세요.

---
name: reviewer
description: 완성된 페이지의 코드에서 동작 오류를 검사하고 근거 있는 보고서를 반환합니다. 수정 없이 페이지 리뷰를 요청할 때 사용하십시오.
tools: Read, Grep, Glob
---
지정된 파일의 코드를 주어진 요구사항에 따라 살펴보십시오.
파일을 변경하지 마십시오. 페이지 실행을 약속하지 마십시오. 읽기와 검색만 가능합니다.
각 발견에 대해 위치, 예상 동작, 결론 근거,
검증 조건 및 영향을 표시하십시오. 데이터가 부족하면 이를 표시하십시오.
별도로 확인한 사항과 확인하지 않은 사항을 나열하십시오.
지정된 기준에 따른 문제를 찾지 못했으면 그렇게 작성하십시오.

--- 두 줄 사이의 블록을 frontmatter라고 합니다. Markdown 파일 맨 앞에 두는 설정입니다. 여기서 name은 역할의 이름을 정하고, description은 주 에이전트에게 언제 이 역할을 골라야 하는지 설명하며, tools는 사용 가능한 도구를 나열합니다. 그 아래는 평범한 문장으로 쓴 지침입니다.

예제의 세 가지 도구는 코드를 살펴보는 데 필요한 일을 정확히 해냅니다. Read는 파일을 읽고, Grep은 내용을 검색하고, Glob은 이름이나 경로로 파일을 찾습니다. 따라서 리뷰어는 삭제 함수를 찾아 읽을 수 있지만 브라우저에서 페이지를 실행하거나 터미널에서 명령을 실행할 수는 없습니다.

"파일을 변경하지 마세요" 줄은 작업을 설명합니다. tools 필드는 그 작업을 수행할 수단을 제한합니다. 텍스트에 요청만 남기고 도구를 제한하지 않으면 도우미에게 쓰기 권한이 남아 있을 수 있습니다. 완성된 예제에는 두 부분이 이미 들어 있으니 나중에 제한을 추가할 필요가 없습니다.

역할 파일은 스킬과 비슷합니다. 설정과 지침 텍스트로 이루어져 있습니다. 혼동하기 쉽습니다. 하지만 여기서는 검증을 위한 별도의 실행을 설정하고 있습니다. 스킬은 보통 반복 가능한 절차를 현재 대화에 추가합니다. 스킬도 별도의 컨텍스트에서 실행될 수 있기는 하지만요. 두 파일의 겉모습이 아니라 작업을 어떻게 실행해야 하는지를 기준으로 고르세요.

4. 리뷰어 확인 및 호출

디스크에 파일이 생긴 것이 첫 번째 결과입니다. 이제 세션이 이 파일을 인식하는지 확인하겠습니다. 파일을 열고 reviewer 이름, 설명, 도구 줄, 본문을 살펴보세요. 브라우저를 실행하겠다거나 오류를 바로 고치겠다는 약속이 들어 있지 않아야 합니다.

Claude Code의 입력 필드에 @를 입력하고 agent 표시가 붙은 reviewer를 선택하세요. 파일 경로가 붙은 비슷한 항목이 아니라 역할 자체를 골라야 합니다. 목록에서 선택하면 이 작업을 맡을 도우미를 명시적으로 지정할 수 있습니다.

역할이 보이지 않으면 먼저 경로를 확인하세요. 파일은 열려 있는 프로젝트의 .claude/agents/에 있어야 합니다. 그다음은 frontmatter입니다. 구분선 두 줄, 이름, 설명이 모두 있는지 봅니다. Claude Code에 정의 파일 자체를 확인해 달라고 요청해도 됩니다.

Claude Code 문서에 따르면 이미 감시 중인 폴더의 변경 사항은 몇 초 안에 반영됩니다. agents 폴더가 세션을 시작한 뒤에 처음 생겼다면 다시 시작해야 합니다. 현재 세션을 종료한 다음, 같은 프로젝트 폴더에서 일반 터미널로 다음 명령을 실행하세요:

claude --continue

이 명령은 현재 디렉터리의 마지막 대화를 이어 갑니다. 실행 후 @ 목록을 다시 확인하세요. Claude를 시작하는 이 명령은 실행 중인 대화 안이 아니라, 종료한 뒤 터미널에서 입력합니다.

첫 번째 작업으로 장보기 목록 페이지를 예로 들겠습니다. 마크업은 index.html에, 로직은 app.js에 있고 두 파일 모두 프로젝트 루트에 있습니다. 여러분의 프로젝트에서는 경로와 예상 동작을 자신의 것으로 바꾸세요. 목록에서 리뷰어를 선택한 뒤 멘션 뒤에 다음 텍스트를 덧붙입니다:

프로젝트 루트에서 index.html 및 app.js를 살펴보십시오.
항목 추가 및 제거를 확인하십시오: 카운터는 남은 항목 수와 일치해야 합니다.
하나의 기록을 삭제하면 같은 이름의 다른 기록을 삭제해서는 안 됩니다.
파일을 변경하지 마십시오. 코드에 대한 결론과 브라우저에서 확인해야 할 사항을 반환하십시오.

범위가 좁은 검증에 필요한 것은 모두 들어 있습니다. 어디를 볼지, 무엇이 일어나야 하는지, 어떤 결과가 필요한지입니다. 브리프를 별도 파일로 만들 필요는 없습니다. 주 에이전트가 선택된 리뷰어를 위한 작업을 정리해 전달합니다. @로 선택하면 실행자가 정해질 뿐, 여러분의 메시지가 글자 그대로 전달되는 것은 아닙니다.

5. 결과는 어떻게 돌아오는가

요청을 보낸 뒤 리뷰어 실행이 나타났는지 확인하세요. 일반적인 대화형 세션에서는 이런 작업이 백그라운드에서 진행될 수 있습니다. 패널에서 진행 상황을 보면서 대화를 계속할 수 있습니다. /tasks 명령으로 최근에 완료된 것까지 포함해 작업 목록을 볼 수 있습니다.

검증이 끝나면 주 에이전트가 결과를 받아 여러분에게 알려 줍니다. 요약이 너무 짧다면 "리뷰어의 최종 보고서를 전부 보여 주세요"라고 요청하세요. 그러면 발견 사항과 검증의 한계를 정확한 표현 그대로 보관하기가 쉬워집니다.

예를 들어 카운터에 관한 학습용 보고서는 다음과 같을 수 있습니다:

app.js에서 추가 및 제거를 확인했습니다.
removeItem()에서 목록이 다시 그려지지만 이 경로에서 updateCounter() 호출을 찾지 못했습니다.
카운터가 남은 기록 수를 표시할 것으로 예상됩니다.
브라우저에서 검증: 항목 하나 추가, 삭제,
카운터를 빈 목록과 비교합니다.
같은 이름의 기록 삭제는 별도로 확인하지 않았습니다.
브라우저에서 실행하지 않았습니다.

이것은 응답 형식의 예시일 뿐, 여러분의 페이지에서 바로 이런 버그를 찾아 준다는 약속이 아닙니다. 우리 리뷰어는 코드만 읽을 수 있으므로 마지막 줄은 그 능력을 정직하게 밝힌 것입니다. 코드에 대한 결론은 실행하지 않고도 타당할 수 있지만, 그 근거는 확인해야 합니다. 예를 들어 같은 경로에서 다른 함수가 카운터를 업데이트하지는 않는지 봅니다.

지정된 위치를 열어 보거나, 설명된 동작을 브라우저에서 직접 반복해 보세요. 문제가 확인되면 수정을 주 에이전트에게 맡기면 됩니다. 확인되지 않으면 여러분이 관찰한 내용을 알리고 결론을 다시 확인해 달라고 요청하세요. 보고서가 깔끔하게 정리되어 있다고 해서 무엇을 고쳐야 할지가 정해지는 것은 아닙니다.

"지정된 기준에 따른 문제를 찾지 못했습니다"라는 답변도 무엇을 확인했는지가 분명하다면 괜찮습니다. 반면 "삭제 로직이 있는 파일을 찾지 못했습니다"는 부분적인 결과입니다. 먼저 경로를 명확히 해야 합니다. 분량을 채우려고 추측으로 보고서를 채울 이유는 없습니다.

참고로 목록에는 기본 제공 역할인 Explore와 Plan이 보일 수도 있습니다. 이 역할들은 별도의 역할 파일을 만들지 않아도 사용할 수 있습니다.

6. 언제 위임하면 좋은가

첫 검증이 잘되고 나면 모든 작업마다 별도의 도우미를 두고 싶어지기 쉽습니다. 그 마음은 이해가 갑니다. 하지만 새 실행은 뭔가를 더해 줘야 합니다. 독립적인 검토이거나, 세부 과정이 기본 대화에 필요 없는 독립적인 작업이어야 합니다.

서로 이어지는 여러 단계도 서브에이전트에게 맡기는 하나의 작업이 될 수 있습니다. 핸들러를 찾고, 그 호출을 확인하고, 결론을 정리하는 것은 평범한 하나의 작업입니다. 다만 나중에 모두에게 인접 단계의 결과를 다시 설명해야 한다면 단계마다 별도의 도우미에게 나눠 주지는 마세요.

model 필드로 서브에이전트의 모델을 따로 지정할 수 있습니다. 지금은 필요하지 않습니다. 먼저 명확한 역할과 확인 가능한 결과를 얻는 것이 더 유용합니다. 별도의 실행 자체는 더 강하거나 약한 모델을 의미하지 않습니다.

두 번째 역할은 다른 것을 확인해야 합니다

리뷰어 외에도 사용자 시나리오를 확인하기 위해 playtester가 필요하다고 가정해 봅시다. 기존 지침을 복사해 이름만 바꾸면 달라지는 것이 거의 없습니다. 먼저 작업 대상과 결과를 구분하세요:

예를 들어 이 역할은 같은 이름의 구매 항목 두 개 중 하나를 삭제하는 경우만 다룰 수 있습니다. 삭제 후 기록이 하나 남아야 하고 카운터는 1을 표시해야 합니다. 이것은 측정 가능한 작업입니다. "페이지가 좋은지 평가하세요"는 취향에 따른 조언이 끼어들 여지를 너무 많이 남깁니다.

이제 작업을 도구와 맞춰 보세요. 우리 리뷰어처럼 읽기와 검색만 가능하다면 도우미는 브라우저에서 동작을 실행할 수 없습니다. 검증 시나리오를 작성하거나 여러분이 기록한 관찰 내용을 분석할 수는 있습니다. 이것은 검증의 준비나 분석이지, 직접 수행한 playtest가 아닙니다.

같은 이름의 두 구매 중 하나를 삭제하는 검증 시나리오를 준비하십시오.
각 단계마다 작업과 예상 결과를 표시하십시오. 코드를 변경하지 마십시오. 실행을 주장하지 마십시오.
내 관찰 후 예상을 실제와 비교하고
부족한 데이터를 나열하십시오.

직접 실행하려면 사용 가능한 브라우저 도구가 있어야 하고, 실행이 실제로 이루어졌는지도 확인해야 합니다. playtester라는 이름만으로는 부족합니다. 먼저 검증 방법을 정한 다음, 역할 파일에 언제 이 역할을 호출하는지와 정직하게 반환할 수 있는 결과가 무엇인지 적으세요.

7. 여러분의 세션에서는 어떻게 보이는가

이제 여러분에게는 세션이 인식하는 역할 파일과, 그 역할에 맡길 수 있는 짧은 검증이 있습니다. 시작하기에는 이것으로 충분합니다. 비슷한 리뷰어를 미리 열 개씩 모아 둘 필요는 없습니다.

앞으로는 문제가 드러난 층을 고치세요. 중요한 조건이 전달되지 않았다면 작업 설명을 보완합니다. 의심스러운 결론을 받았다면 근거를 확인합니다. 리뷰어가 번번이 너무 일반적인 답변을 반환한다면 역할 지침을 다듬습니다. 파일은 프로젝트에 남으니, 다음 검증은 이 규칙에서 바로 시작할 수 있습니다.

반복되는 작업에는 리뷰어 브리프가 도움이 됩니다. 답변을 받았다면 발견 사항 검증과 수정 방향 선택으로 넘어가세요.