Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Claude Code에서 역할별 커스텀 에이전트를 설계하고 정의하는 방법을 설명합니다. 독립된 컨텍스트를 가진 서브 에이전트를 통해 메인 세션의 효율성을 높이고, 모델과 도구를 최적화하여 AI 팀을 구성하는 노하우를 다룹니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Claude Code에는 커스텀 에이전트(Custom Agent)를 정의할 수 있는 기능이 있습니다. Researcher
"조사해줘", Writer
"기사를 써줘", Operator
"git commit 해줘"——역할을 가진 AI 팀 멤버를 직접 설계할 수 있습니다.
이 기사에서는 에이전트 정의 파일의 작성 방법과, 실제로 사용하며 알게 된 설계 노하우를 해설합니다.
Claude Code의 UI에서 @에이전트명
이라고 입력하거나, 코드 내에서 Agent 도구를 사용하면 독립된 컨텍스트(Context)를 가진 서브 에이전트(Sub-agent)가 기동합니다.
메인 세션(Main session)과는 별개의 컨텍스트에서 동작하기 때문에:
에이전트 정의는 .claude/agents/
디렉토리에 둡니다.
.claude/
└── agents/
├── researcher.md ← 조사 담당
...
각 파일의 기본 포맷:
---
name: researcher
description: >
...
에이전트의 식별자입니다. @researcher
와 같이 참조할 때 사용합니다.
영문 소문자+하이픈으로 명명합니다.
가장 중요한 필드입니다.
Claude Code가 태스크(Task)를 배분할 때, 이 description을 읽고 "이 에이전트를 사용해야 하는가"를 판단합니다.
구체적으로, 어떤 입력에 대해 이 에이전트를 사용해야 하는지를 작성합니다.
# 나쁜 예 (무엇을 하는지가 모호함)
description: "여러 가지를 조사하는 에이전트"
# 좋은 예 (언제 사용하는지가 명확함)
...
사용할 모델을 지정합니다.
| 모델 | 용도 | 컨텍스트 소비 |
|---|---|---|
haiku | git commit 메시지 작성, 경량 텍스트 정형화 | 최소 |
sonnet | 기사 집필, 코드 구현, 조사 요약 | 중등도 |
opus | 최종 리뷰, 복잡한 설계 판단 | 최대 |
생략하면 메인 세션과 동일한 모델이 됩니다. 생략은 함정입니다.
경량 태스크를 대량으로 실행하는 에이전트는 model: haiku
로 설정하면 Pro 제한을 절약할 수 있습니다.
에이전트가 사용할 수 있는 도구의 리스트입니다.
# 조사계 (읽기 + Web)
tools: WebSearch, WebFetch, Read, Write, Grep, Glob
# 집필계 (읽기/쓰기만)
...
원칙: 필요 최소한의 도구만 부여한다.
Bash
는 강력하므로 필요한 경우에만 부여합니다. WebSearch/WebFetch
도 조사 담당에게만 부여하며, 집필 담당에게는 불필요합니다.
---
name: researcher
description: >
...
---
name: writer
description: >
...
---
name: operator
description: >
...
"모든 것을 할 수 있는 슈퍼 에이전트"를 만들고 싶어지지만, 이는 역효과입니다.
# 나쁜 예
name: all-in-one
description: "조사도 집필도 git도 뭐든지 할 수 있는 에이전트"
...
문제점:
# 좋은 예
name: researcher # 조사만
name: writer # 집필만
...
역할이 명확하면 메인 세션이 "어떤 에이전트에게 무엇을 맡길지"에 대한 판단이 정확해집니다.
Claude Code에는 /skill과 Agent라는 두 종류의 자동화가 있습니다.
| Skill | Agent |
|---|---|
| 컨텍스트 (Context) | 메인과 공유 |
| ... | @agent-name 또는 Agent 도구 |
| 예시 | /session-close (종료 기록) |
기준:
메인 세션에서 대량의 WebFetch를 실행하면, 그 응답이 전부 컨텍스트 (Context)에 쌓이게 됩니다. Agent에게 맡기면 메인 세션으로 돌아오는 것은 요약본뿐입니다.
에이전트가 늘어나면 부서별로 서브 디렉터리 (Sub-directory)를 만듭니다.
.claude/agents/
├── researcher.md ← 조사 부서
├── writer.md ← 집필 부서
...
부서별로 액세스 권한 (Access Permission)을 나눌 수 있습니다. "재무 부서의 에이전트는 WebSearch를 사용할 수 있지만, 매매 실행은 할 수 없다"와 같은 설계가 명확해집니다.
약 40명에 가까운 에이전트를 정의한 프로젝트 사례를 들었습니다. 결과는 다음과 같습니다:
대책: 3~7명으로 압축할 것. "이 에이전트가 없다면 기존 에이전트로 대응할 수 없는 이유가 있는가?"를 반드시 자문할 것.
description (설명)이 비어 있거나 너무 짧으면, Claude Code가 에이전트를 사용해야 할 상황을 판단할 수 없습니다.
대책: "이 에이전트를 사용해야 하는 트리거 (Trigger)가 되는 문장 패턴"을 구체적으로 작성할 것.
모든 도구 (Tools)를 부여하면 예기치 않은 조작이 발생합니다. "조사하는 김에 git commit을 해버렸다"와 같은 상황입니다.
대책: 필요한 도구만 나열할 것. 특히 Bash는 신중하게 다룰 것.
커스텀 에이전트 설계의 핵심 요점:
에이전트를 설계하는 데 시간을 들일수록, 메인 세션에서의 "지휘의 정확도"가 올라갑니다. 결과적으로 한 번의 세션에서 처리할 수 있는 업무량이 증가합니다.
이 기사는 Claude(claude-sonnet-4-6)가 초안을 작성하고, 인간(CEO)이 확인 및 편집하였습니다.
