Claude code Agents란? - 클로드 코드 커스텀 에이전트 구성하기

포스팅 개요

본 포스팅은 Claude Code의 Custom Agents(커스텀 에이전트) 기능에 대해 다루는 글입니다. Claude Code로 복잡한 작업을 하다 보면, 하나의 대화 안에서 코드 탐색, 구현, 테스트, 리뷰를 모두 처리하게 됩니다. 이렇게 하면 컨텍스트 윈도우가 금방 차고, Claude가 앞에서 봤던 내용을 놓치는 경우가 생깁니다.

 

Custom Agents는 이 문제를 해결합니다. 특정 작업을 전담하는 전문 에이전트를 만들어두면, Claude가 해당 작업을 만났을 때 그 에이전트에게 위임합니다. 각 에이전트는 자기만의 컨텍스트 윈도우에서 독립적으로 작동하고, 작업이 끝나면 요약된 결과만 돌려줍니다. 주 대화의 컨텍스트는 깔끔하게 유지되는 것이죠.

 

이 글에서는 Custom Agents의 기본 개념, 구성 방법, 그리고 실전 예제까지 단계별로 살펴보겠습니다. 

본 포스팅은 2026년 3월 기준 Anthropic 공식 문서를 바탕으로 작성되었습니다.

 

• Anthropic 공식 문서 (Sub-agents): https://docs.anthropic.com/ko/docs/claude-code/sub-agents

---

포스팅 본문

그러면 지금부터 Claude Code의 Custom Agents에 대해 하나씩 살펴보겠습니다.

[1]. Custom Agents 기본 개념

Claude Code에서 Subagent(서브에이전트)란, 특정 유형의 작업을 처리하는 전문화된 AI 어시스턴트입니다. 각 Subagent는 자체 컨텍스트 윈도우에서 실행되며, 고유한 시스템 프롬프트와 도구 접근 권한을 가집니다. Claude가 Subagent의 설명(description)과 맞는 작업을 만나면, 해당 Subagent에 작업을 위임하고 결과를 받아옵니다.

쉽게 말하면, 메인 Claude가 "팀장"이고, Subagent들은 각자 전문 분야가 있는 "팀원"인 셈입니다. 팀장이 모든 일을 직접 하지 않고, 적합한 팀원에게 작업을 맡기는 것이죠.

 

[1-1]. 내장 Subagent

Claude Code에는 기본으로 내장된 Subagent가 있습니다. Claude가 상황에 맞게 자동으로 사용합니다.

 

에이전트	모델	도구	용도
Explore	Haiku	읽기 전용	코드베이스 검색, 파일 탐색, 코드 분석. 빠르고 가벼움
Plan	상속	읽기 전용	Plan mode에서 코드베이스 연구. 계획 수립을 위한 정보 수집
General-purpose	상속	모든 도구	탐색과 수정이 모두 필요한 복잡한 다단계 작업

 

"상속"은 주 대화에서 사용 중인 모델을 그대로 쓴다는 뜻입니다. Explore는 빠른 응답이 필요한 탐색 작업에 특화되어 있어 Haiku 모델을 사용하고, 나머지는 주 대화의 모델을 따릅니다.

이러한 내장 Subagent 외에도, 사용자가 직접 Custom Subagent를 만들 수 있는데요. 본 포스팅은 클로드 코드에서 이러한 나만의 서브 에이전트(custom sub agent)를 만드는 방법에 집중합니다.

참고로, Subagent와 별개로 Agent Teams라는 기능도 있습니다. Subagent는 하나의 세션 안에서 주 대화에 결과를 보고하는 구조인 반면, Agent Teams는 여러 독립적인 Claude Code 세션이 서로 직접 메시지를 주고받으며 협력하는 구조입니다. 이 글에서는 Subagent(Custom Agents)만 다루겠습니다.

---

[2]. Custom Agents가 필요한 이유

Custom Agents가 유용한 이유는 크게 4가지로 정리될 수 있습니다.

 

첫째, 컨텍스트를 보존할 수 있습니다.

Subagent가 수십 개의 파일을 읽어도, 주 대화에는 요약된 결과만 전달됩니다. 주 대화의 컨텍스트 윈도우가 불필요한 중간 결과로 채워지는 것을 방지할 수 있습니다.

 

둘째, 도구 접근을 제한할 수 있습니다.

코드 리뷰 에이전트라면 Read, Grep, Glob만 허용하고 Write나 Edit은 차단할 수 있습니다. 실수로 코드를 수정하는 일을 막는 것이죠.

 

셋째, 비용을 절감할 수 있습니다.

단순한 탐색 작업은 Haiku 같은 빠르고 저렴한 모델로 라우팅하고, 복잡한 작업만 Opus나 Sonnet을 사용하도록 설정할 수 있습니다.

 

넷째, 프로젝트 간에 재사용할 수 있습니다.

~/.claude/agents/ 디렉토리에 에이전트를 만들면 모든 프로젝트에서 사용할 수 있습니다. 한 번 잘 만들어두면 어디서든 활용 가능합니다.

 

[2-1]. Skill과 Subagent의 차이

앞선 포스팅에서 다뤘던 Skills(https://lsjsj92.tistory.com/713)와 Custom Agents는 비슷해 보이지만 해결하는 문제가 다릅니다. 두 기능의 차이를 정리하면 다음과 같습니다.

 

구분	Skill	Subagent
정의	재사용 가능한 지침/지식/워크플로우	자체 컨텍스트를 가진 독립 작업자
핵심 이점	컨텍스트 간 내용 공유	컨텍스트 격리, 요약만 반환
실행 위치	주 대화 컨텍스트 (context: fork 제외)	별도의 독립 컨텍스트
적합한 작업	참조 자료, 호출 가능한 워크플로우	대량 파일 읽기, 병렬 작업, 전문화된 워커

 

간단히 말하면, Skill은 "Claude에게 지식이나 워크플로우를 가르치는 것"이고, Subagent는 "Claude에게 전담 팀원을 붙여주는 것"입니다. 둘을 결합할 수도 있는데, Subagent에 Skills를 미리 로드해서 도메인 지식을 갖춘 전문 에이전트를 만드는 식입니다.

---

[3]. Custom Agents 구성 방법

Custom Agent를 만드는 방법을 단계별로 살펴보겠습니다.

 

[3-1]. 저장 위치와 범위

에이전트 파일을 저장하는 위치에 따라 적용 범위와 우선순위가 달라집니다.

 

위치	경로	범위	우선순위
--agents CLI 플래그	실행 시 JSON으로 전달	현재 세션만	1 (최고)
프로젝트 에이전트	.claude/agents/	현재 프로젝트	2
사용자 에이전트	~/.claude/agents/	모든 프로젝트	3
플러그인 에이전트	플러그인의 agents/ 디렉토리	플러그인 활성화 위치	4 (최저)

 

같은 이름의 에이전트가 여러 위치에 있으면, 우선순위가 높은 쪽이 적용됩니다. 보통은 프로젝트 에이전트(.claude/agents/)나 사용자 에이전트(~/.claude/agents/)를 가장 많이 사용합니다. 프로젝트 에이전트는 git에 커밋해서 팀과 공유할 수 있고, 사용자 에이전트는 개인 전용으로 모든 프로젝트에서 쓸 수 있습니다.

 

[3-2]. 에이전트 파일 구조

Subagent 파일은 YAML frontmatter + Markdown 본문으로 구성됩니다. Skills의 SKILL.md와 구조가 비슷합니다.

 

---
name: code-reviewer
description: 코드 품질과 모범 사례를 검토합니다
tools: Read, Glob, Grep
model: sonnet
---

당신은 코드 리뷰어입니다. 호출되면 코드를 분석하고
품질, 보안, 모범 사례에 대한 구체적이고 실행 가능한 피드백을 제공하세요.

 

frontmatter는 에이전트의 메타데이터와 설정을 담고, 본문은 에이전트의 시스템 프롬프트가 됩니다. Subagent는 이 시스템 프롬프트만 받으며, 전체 Claude Code 시스템 프롬프트는 받지 않습니다.

 

[3-3]. 주요 Frontmatter 필드

에이전트 파일에서 사용할 수 있는 주요 필드가 있습니다. name과 description만 필수이고, 나머지는 선택사항입니다.

 

필드	필수	설명
name	O	고유 식별자. 소문자와 하이픈 사용
description	O	Claude가 이 에이전트에 작업을 위임해야 할 때를 판단하는 설명
tools		사용 가능한 도구 목록. 생략하면 주 대화의 모든 도구를 상속
disallowedTools		거부할 도구 목록. 상속된 도구 중 특정 도구만 제외
model		사용할 모델: sonnet, opus, haiku, 또는 inherit(기본값)
permissionMode		권한 모드: default, acceptEdits, dontAsk, bypassPermissions, plan
maxTurns		에이전트가 중지되기 전의 최대 턴 수
skills		시작 시 에이전트 컨텍스트에 로드할 Skills 목록
memory		지속적 메모리 범위: user, project, 또는 local
mcpServers		에이전트에서 사용할 MCP 서버. 이미 구성된 서버 이름 또는 인라인 정의
hooks		에이전트 생명주기에 한정된 hooks
background		true로 설정하면 항상 백그라운드 작업으로 실행
isolation		worktree로 설정하면 임시 git worktree에서 격리 실행

 

[3-4]. /agents 명령으로 만들기

에이전트 파일을 직접 작성하는 것 외에, /agents 명령을 사용해서 대화형으로 만들 수도 있습니다.

 

1. Claude Code에서 /agents를 입력합니다.

2. Create new agent를 선택합니다.

3. User-level(모든 프로젝트) 또는 Project-level(현재 프로젝트)을 선택합니다.

4. Generate with Claude를 선택하고, 에이전트가 어떤 일을 할지 설명합니다.

5. Claude가 시스템 프롬프트와 설정을 생성합니다. e를 눌러 편집기에서 수정할 수 있습니다.

6. 도구, 모델, 색상을 선택합니다.

7. 저장하면 즉시 사용 가능합니다. 세션을 다시 시작할 필요 없습니다.

 

/agents 명령은 에이전트를 만드는 것 외에도, 현재 사용 가능한 모든 에이전트를 조회하거나, 기존 에이전트를 편집/삭제하는 데에도 사용할 수 있습니다.

---

[4]. 예제 1: leesoojin_food 에이전트

첫 번째 예제로 밥을 먹었는지를 전달하는 간단한 에이전트를 만들어보겠습니다.

개발에 몰두하다 보면 식사를 놓치는 경우가 많은데, 이 에이전트가 식사 시간을 알려줍니다.

 

[4-1]. 에이전트 파일 생성

모든 프로젝트에서 사용할 수 있도록 ~/.claude/agents/ 디렉토리에 파일을 생성했습니다.

원하신다면, 프로젝트 경로에 구성해도 됩니다.

 

파일 경로: ~/.claude/agents/leesoojin-food.md

 

---
name: leesoojin-food
description: 개발 작업 중 식사 여부를 확인하는 에이전트. 장시간 코딩 세션이 진행될 때, 사용자가 밥을 먹었는지 확인하고 싶을 때 사용합니다.
tools: Bash
model: haiku
---

당신은 이수진의 건강 관리 도우미입니다.

호출되면 다음 작업을 수행하세요:

1. 현재 시간을 확인합니다 (date 명령 사용)

2. 현재 시간대에 따라 추가 메시지를 제공합니다:
   - 오전 7시 ~ 9시: "아침 식사는 하루의 시작이에요. 간단하게라도 드세요!"
   - 오전 11시 30분 ~ 오후 1시 30분: "점심 시간이에요. 잠깐 쉬면서 식사하세요!"
   - 오후 5시 30분 ~ 오후 7시 30분: "저녁 시간이에요. 오늘도 수고했어요!"
   - 그 외 시간: "간식이라도 챙겨 드세요!"

3. 결과를 간략히 요약하여 반환합니다.

 

[4-2]. 에이전트 설정 설명

각 설정을 살펴보겠습니다.

• name: leesoojin-food - 에이전트의 고유 식별자입니다. Claude에게 "leesoojin-food 에이전트를 사용해서"라고 지시할 때 이 이름을 사용합니다.
• description - Claude가 이 에이전트에 작업을 위임할지 판단하는 기준입니다. 식사 확인, 건강 관련 요청이 들어왔을 때 매칭됩니다.
• tools: Bash - 시간을 확인하기 위해 Bash(date 명령)만 허용합니다. 최소한의 도구만 부여하는 것이 좋습니다.
• model: haiku - 단순한 메시지 전달 작업이므로 가장 빠르고 저렴한 Haiku 모델을 사용합니다.

 

[4-3]. 동작 확인

Claude Code에서 아래와 같이 입력하면 에이전트가 동작합니다.

 

leesoojin-food(식사 여부 확인) 에이전트를 호출하고, 그 결과로 밥은 먹었는가?에 대한 여부를 확인하도록 클로드에서 에이전트를 활용해 동작됩니다.

즉, claude code의 서브 에이전트가 정상적으로 동작됨을 확인할 수 있습니다.

---

[5]. 예제 2: leesoojin_positive 에이전트

두 번째 예제는 응원 메시지를 전달하는 에이전트입니다.

 

[5-1]. 에이전트 파일 생성

파일 경로: ~/.claude/agents/leesoojin-positive.md

 

---
name: leesoojin-positive
description: 개발 작업 중 응원 메시지를 전달하는 에이전트. 에러가 발생하거나 어려운 문제를 만났을 때, 장시간 디버깅을 할 때 proactively 사용합니다.
tools: Read, Grep, Glob
model: haiku
---

당신은 이수진의 응원 도우미입니다.

호출되면 다음 작업을 수행하세요:

1. 현재 작업 상황에 맞는 응원 메시지를 하나 추가합니다:
   - 에러/버그 관련 작업: "버그는 찾으면 이미 반은 해결한 거예요!"
   - 새 기능 구현 중: "한 줄 한 줄이 모여서 멋진 기능이 되는 거예요!"
   - 리팩토링 작업: "더 좋은 코드를 만들려는 노력, 대단해요!"
   - 테스트 작성 중: "탄탄한 테스트가 안정적인 서비스를 만들어요!"
   - 기타: "꾸준히 하는 것 자체가 실력이에요!"

32 결과를 간략히 요약하여 반환합니다.

 

[5-2]. description에서 "proactively"의 의미

이 에이전트의 description에 "proactively 사용합니다"라는 문구가 들어 있습니다. 여기서 "proactively"는 Claude가 인식하는 키워드로, 이 단어가 description에 포함되면 Claude가 관련 상황을 만났을 때 사용자에게 묻지 않고 먼저 이 에이전트를 호출하도록 유도할 수 있습니다. 한국어가 아닌 영어로 적는 이유는 Claude의 시스템이 이 영어 키워드를 직접 인식하기 때문입니다.

예를 들어 디버깅 중에 에러가 계속 발생하는 상황이라면, Claude가 알아서 이 에이전트를 호출해서 응원 메시지를 보내줄 수 있습니다. 물론 항상 자동으로 호출되는 것은 아니고, Claude가 description을 보고 현재 상황과 관련이 있다고 판단했을 때 실행됩니다.

 

[5-3]. 동작 확인

 

중간에 leesoojin-positive(응원 메시지 전달) 이라는 에이전트를 호출한 것을 확인할 수 있습니다.

그리고 Agent "응원 메시지 전달" completed도 보이죠.

클로드 코드를 활용해 상황에 맞게 agent를 호출하도록 서브 에이전트를 설정해두었는데, 잘 호출하고 사용하는 것을 볼 수 있습니다.

---

[6]. 고급 활용법

기본적인 에이전트 생성법을 익혔으니, 좀 더 고급 기능을 살펴보겠습니다.

 

[6-1]. Persistent Memory (지속적 메모리)

memory 필드를 설정하면 에이전트가 대화 간에 유지되는 메모리를 가질 수 있습니다. 에이전트가 작업하면서 발견한 패턴, 규칙, 발견 사항을 기록하고, 다음에 호출될 때 이를 참조하는 것이죠.

 

---
name: code-reviewer
description: 코드 품질과 모범 사례를 검토합니다
tools: Read, Grep, Glob
memory: user
---

코드를 검토하면서 발견한 패턴, 규칙, 반복되는 이슈를
에이전트 메모리에 기록하세요. 이전 리뷰에서 기록한 내용을
참고하여 일관된 리뷰를 제공하세요.

 

memory 범위에 따라 메모리가 저장되는 위치가 달라집니다.

 

범위	저장 위치	사용 시기
user	~/.claude/agent-memory/<agent-name>/	모든 프로젝트에서 학습 유지. 권장 기본값
project	.claude/agent-memory/<agent-name>/	프로젝트별 지식. git으로 팀 공유 가능
local	.claude/agent-memory-local/<agent-name>/	프로젝트별 지식이지만 git에 포함하지 않을 때

 

메모리가 활성화되면, 에이전트의 시스템 프롬프트에 메모리 디렉토리의 MEMORY.md 처음 200줄이 자동으로 포함됩니다. 에이전트는 Read, Write, Edit 도구로 메모리 파일을 직접 관리할 수 있습니다.

 

메모리를 효과적으로 활용하려면, 에이전트에게 "이전 메모리를 확인한 후 작업하세요"라고 지시하거나, "작업이 끝나면 배운 내용을 메모리에 저장하세요"라고 안내하는 것이 좋습니다.

 

[6-2]. Skills 미리 로드

skills 필드를 사용하면 에이전트가 시작될 때 특정 Skill의 전체 내용을 컨텍스트에 주입할 수 있습니다. 에이전트에게 도메인 지식을 미리 제공하는 것이죠.

 

---
name: api-developer
description: 팀 규칙에 따라 API 엔드포인트를 구현합니다
skills:
  - api-conventions
  - error-handling-patterns
---

API 엔드포인트를 구현하세요. 미리 로드된 Skills의 규칙과 패턴을 따르세요.

 

주의할 점은, Subagent는 부모 대화에서 Skill을 상속하지 않는다는 것입니다. 필요한 Skill은 반드시 skills 필드에 명시적으로 나열해야 합니다.

 

[6-3]. CLI로 임시 에이전트 정의

파일을 만들지 않고, Claude Code 실행 시 --agents 플래그로 에이전트를 임시로 정의할 수도 있습니다. 해당 세션에서만 존재하고 디스크에 저장되지 않으므로, 빠른 테스트나 자동화 스크립트에 유용합니다.

 

claude --agents '{
  "quick-reviewer": {
    "description": "빠른 코드 리뷰어",
    "prompt": "코드 품질, 보안, 모범 사례에 집중하여 리뷰하세요.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "haiku"
  }
}'

 

파일 기반 에이전트의 Markdown 본문(시스템 프롬프트)은 JSON에서 prompt 필드에 작성합니다.

---

마무리

이번 포스팅에서는 Claude Code의 Custom Agents 기능에 대해 살펴보았습니다. 

이 글을 포함해서 총 3편에 걸쳐 Claude Code의 핵심 확장 기능을 다뤘습니다. 세 기능의 관계를 간단히 정리하면 이렇습니다.

 

• Rules (CLAUDE.md, .claude/rules/)로 기본 코딩 규칙과 프로젝트 표준을 설정합니다.
• Skills (SKILL.md)로 반복되는 워크플로우를 정의하고, 필요할 때 호출합니다.
• Custom Agents (에이전트 파일)로 전문적인 작업을 독립된 컨텍스트에서 처리합니다.

 

이 세 가지를 적절히 조합하면 Claude Code를 훨씬 효율적으로 활용할 수 있습니다. Rules로 기본 틀을 잡고, Skills로 워크플로우를 자동화하고, Custom Agents로 전문 작업을 위임하는 구조를 만들어보세요.

부족한 글이지만, Claude Code를 더 깊이 활용하는 데 도움이 되셨으면 합니다. 궁금한 점이나 피드백이 있으시면 댓글로 남겨주세요.