Claude Code의 커스텀 에이전트 설계 — 역할 특화형 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: >
...

frontmatter의 각 필드 상세 해설

name

에이전트의 식별자입니다. @researcher

와 같이 참조할 때 사용합니다.

영문 소문자+하이픈으로 명명합니다.

description

가장 중요한 필드입니다.

Claude Code가 태스크(Task)를 배분할 때, 이 description을 읽고 "이 에이전트를 사용해야 하는가"를 판단합니다.

구체적으로, 어떤 입력에 대해 이 에이전트를 사용해야 하는지를 작성합니다.

# 나쁜 예 (무엇을 하는지가 모호함)
description: "여러 가지를 조사하는 에이전트"
# 좋은 예 (언제 사용하는지가 명확함)
...

model

사용할 모델을 지정합니다.

모델	용도	컨텍스트 소비
haiku	git commit 메시지 작성, 경량 텍스트 정형화	최소
sonnet	기사 집필, 코드 구현, 조사 요약	중등도
opus	최종 리뷰, 복잡한 설계 판단	최대

생략하면 메인 세션과 동일한 모델이 됩니다. 생략은 함정입니다.

경량 태스크를 대량으로 실행하는 에이전트는 model: haiku

로 설정하면 Pro 제한을 절약할 수 있습니다.

tools

에이전트가 사용할 수 있는 도구의 리스트입니다.

# 조사계 (읽기 + Web)
tools: WebSearch, WebFetch, Read, Write, Grep, Glob
# 집필계 (읽기/쓰기만)
...

원칙: 필요 최소한의 도구만 부여한다.

Bash

는 강력하므로 필요한 경우에만 부여합니다. WebSearch/WebFetch

도 조사 담당에게만 부여하며, 집필 담당에게는 불필요합니다.

실제 설계 예시

Researcher (조사 담당)

---
name: researcher
description: >
...

Writer (집필 담당)

---
name: writer
description: >
...

Operator (운영 담당)

---
name: operator
description: >
...

1에이전트 1잡(Job)의 원칙

"모든 것을 할 수 있는 슈퍼 에이전트"를 만들고 싶어지지만, 이는 역효과입니다.

# 나쁜 예
name: all-in-one
description: "조사도 집필도 git도 뭐든지 할 수 있는 에이전트"
...

문제점:

• 책임 소재가 모호함: 에러가 발생했을 때 무엇이 원인인지 알 수 없음
• 제한을 빨리 소모함: 모든 무거운 처리가 하나의 컨텍스트에 모임
• 예기치 않은 동작: "조사하는 김에 git에 써버렸다"와 같은 상황이 발생

# 좋은 예
name: researcher # 조사만
name: writer # 집필만
...

역할이 명확하면 메인 세션이 "어떤 에이전트에게 무엇을 맡길지"에 대한 판단이 정확해집니다.

Skill과 Agent의 구분 사용

Claude Code에는 /skill과 Agent라는 두 종류의 자동화가 있습니다.

Skill	Agent
컨텍스트 (Context)	메인과 공유
...	@agent-name 또는 Agent 도구
예시	/session-close (종료 기록)

기준:

• Skill: "로그에 한 줄 추가하기", "파일 체크하기" 정도의 가벼운 조작
• Agent: "10개 사이트를 조사하여 정리하기", "기사를 처음부터 작성하기" 등 무거운 조작

메인 세션에서 대량의 WebFetch를 실행하면, 그 응답이 전부 컨텍스트 (Context)에 쌓이게 됩니다. Agent에게 맡기면 메인 세션으로 돌아오는 것은 요약본뿐입니다.

서브 디렉터리로 부서를 정리하기

에이전트가 늘어나면 부서별로 서브 디렉터리 (Sub-directory)를 만듭니다.

.claude/agents/
├── researcher.md ← 조사 부서
├── writer.md ← 집필 부서
...

부서별로 액세스 권한 (Access Permission)을 나눌 수 있습니다. "재무 부서의 에이전트는 WebSearch를 사용할 수 있지만, 매매 실행은 할 수 없다"와 같은 설계가 명확해집니다.

설계에서 실패한 패턴

실패 1: 에이전트가 너무 많았다

약 40명에 가까운 에이전트를 정의한 프로젝트 사례를 들었습니다. 결과는 다음과 같습니다:

• 어떤 에이전트에게 무엇을 맡길지 판단할 수 없게 됨
• 역할이 중복되어 일부는 사용되지 않게 됨
• 유지보수 (Maintenance)가 따라가지 못함

대책: 3~7명으로 압축할 것. "이 에이전트가 없다면 기존 에이전트로 대응할 수 없는 이유가 있는가?"를 반드시 자문할 것.

실패 2: description을 작성하지 않았다

description (설명)이 비어 있거나 너무 짧으면, Claude Code가 에이전트를 사용해야 할 상황을 판단할 수 없습니다.

대책: "이 에이전트를 사용해야 하는 트리거 (Trigger)가 되는 문장 패턴"을 구체적으로 작성할 것.

실패 3: tools를 제한하지 않았다

모든 도구 (Tools)를 부여하면 예기치 않은 조작이 발생합니다. "조사하는 김에 git commit을 해버렸다"와 같은 상황입니다.

대책: 필요한 도구만 나열할 것. 특히 Bash는 신중하게 다룰 것.

요약

커스텀 에이전트 설계의 핵심 요점:

• 1 에이전트 1 잡 (Job): 역할을 좁힐수록 정확하게 동작함
• description은 상세하게: 언제 사용할지에 대한 트리거 문구를 구체적으로 작성
• model을 명시: 가벼운 태스크 (Task)는 haiku로 제한하여 비용 절약
• tools는 최소한으로: 필요한 도구만 부여
• 3~7명으로 압축: 에이전트를 너무 많이 늘리지 말 것

에이전트를 설계하는 데 시간을 들일수록, 메인 세션에서의 "지휘의 정확도"가 올라갑니다. 결과적으로 한 번의 세션에서 처리할 수 있는 업무량이 증가합니다.

이 기사는 Claude(claude-sonnet-4-6)가 초안을 작성하고, 인간(CEO)이 확인 및 편집하였습니다.

Discussion