[공식문서읽기] Claude Code Agent 완벽 가이드 - AI 서브에이전트로 개발 생산성 높이기

개요

Claude Code Agent는 Anthropic이 제공하는 AI 코딩 어시스턴트 Claude Code의 핵심 기능입니다. 서브에이전트(Subagent)를 활용하면 복잡한 작업을 병렬로 처리하고, 컨텍스트를 효율적으로 관리하며, 특정 도메인에 특화된 AI 어시스턴트를 만들 수 있습니다.

서브에이전트란?

서브에이전트는 특정 유형의 작업을 처리하는 전문화된 AI 어시스턴트입니다. 각 서브에이전트는 다음과 같은 특징을 가집니다:

• 독립적인 컨텍스트 윈도우: 메인 대화와 분리된 자체 컨텍스트에서 실행
• 커스텀 시스템 프롬프트: 특정 작업에 최적화된 지시사항
• 도구 접근 제한: 필요한 도구만 허용하여 안전성 확보
• 독립적인 권한: 작업에 맞는 권한 설정 가능

Claude가 서브에이전트의 설명(description)과 일치하는 작업을 만나면, 해당 서브에이전트에게 작업을 위임하고 결과만 받아옵니다.

이 이미지는 AI가 생성한 이미지로, 글의 내용과 직접적인 관련이 없을 수 있습니다.

서브에이전트를 사용하는 이유

1. 컨텍스트 보존

탐색이나 구현 작업을 메인 대화에서 분리하여 컨텍스트를 깔끔하게 유지할 수 있습니다. 테스트 실행이나 로그 분석처럼 대량의 출력을 생성하는 작업에 특히 유용합니다.

2. 병렬 처리

여러 서브에이전트를 동시에 실행하여 작업 속도를 높일 수 있습니다. 예를 들어, 인증 모듈, 데이터베이스 모듈, API 모듈을 각각 다른 서브에이전트가 병렬로 분석할 수 있습니다.

3. 비용 절감

간단한 작업은 Haiku 같은 빠르고 저렴한 모델로 라우팅하여 비용을 절감할 수 있습니다.

4. 제약 조건 적용

서브에이전트가 사용할 수 있는 도구를 제한하여 안전하게 작업을 수행할 수 있습니다.

내장 서브에이전트

Claude Code에는 자동으로 사용되는 내장 서브에이전트가 포함되어 있습니다.

Explore

코드베이스 검색 및 분석에 최적화된 빠른 읽기 전용 에이전트입니다.

항목	설명
모델	Haiku (빠르고 저지연)
도구	읽기 전용 도구 (Write, Edit 제외)
용도	파일 탐색, 코드 검색, 코드베이스 이해

Claude가 코드베이스를 변경 없이 검색하거나 이해해야 할 때 Explore에 위임합니다.

Plan

플랜 모드에서 컨텍스트를 수집하는 리서치 에이전트입니다.

항목	설명
모델	메인 대화에서 상속
도구	읽기 전용 도구
용도	계획 수립을 위한 코드베이스 조사

General-purpose

탐색과 수정이 모두 필요한 복잡한 다단계 작업을 위한 에이전트입니다.

항목	설명
모델	메인 대화에서 상속
도구	모든 도구
용도	복잡한 리서치, 다단계 작업, 코드 수정

커스텀 서브에이전트 만들기

1. /agents 명령어 사용

가장 쉬운 방법은 /agents 명령어를 사용하는 것입니다:

/agents

이 명령어로 서브에이전트를 생성, 편집, 삭제할 수 있는 인터랙티브 인터페이스에 접근할 수 있습니다.

2. 마크다운 파일로 직접 생성

서브에이전트는 YAML frontmatter가 포함된 마크다운 파일로 정의됩니다.

저장 위치:

• 프로젝트 전용: .claude/agents/
• 사용자 전역: ~/.claude/agents/

기본 구조:

---
name: code-reviewer
description: 코드 품질과 보안을 검토하는 전문가
tools: Read, Glob, Grep
model: sonnet
---

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

Frontmatter 필드 설명

필드	필수	설명
name	O	고유 식별자 (소문자, 하이픈 사용)
description	O	Claude가 언제 이 에이전트를 사용할지 결정하는 설명
tools	X	사용 가능한 도구 목록
disallowedTools	X	차단할 도구 목록
model	X	사용할 모델 (sonnet, opus, haiku, inherit)
permissionMode	X	권한 모드 설정
maxTurns	X	최대 턴 수 제한
skills	X	로드할 스킬 목록
memory	X	영구 메모리 범위 (user, project, local)
hooks	X	라이프사이클 훅 정의

실전 예제: 코드 리뷰어

---
name: code-reviewer
description: 코드 리뷰 전문가. 코드 작성 또는 수정 후 즉시 사용하세요.
tools: Read, Grep, Glob, Bash
model: inherit
---

당신은 고품질 코드와 보안을 보장하는 시니어 코드 리뷰어입니다.

호출 시:
1. git diff로 최근 변경사항 확인
2. 수정된 파일에 집중
3. 즉시 리뷰 시작

리뷰 체크리스트:
- 코드가 명확하고 읽기 쉬운가
- 함수와 변수 이름이 적절한가
- 중복 코드가 없는가
- 적절한 에러 처리가 있는가
- 노출된 비밀번호나 API 키가 없는가
- 입력 검증이 구현되어 있는가
- 테스트 커버리지가 충분한가
- 성능 고려사항이 반영되어 있는가

우선순위별로 피드백 제공:
- Critical (반드시 수정)
- Warning (수정 권장)
- Suggestion (개선 고려)

이슈 수정 방법의 구체적인 예시를 포함하세요.

이 이미지는 AI가 생성한 이미지로, 글의 내용과 직접적인 관련이 없을 수 있습니다.

 

실전 예제: 디버거

---
name: debugger
description: 에러, 테스트 실패, 예상치 못한 동작을 디버깅하는 전문가
tools: Read, Edit, Bash, Grep, Glob
---

당신은 근본 원인 분석 전문 디버거입니다.

호출 시:
1. 에러 메시지와 스택 트레이스 캡처
2. 재현 단계 파악
3. 실패 위치 격리
4. 최소한의 수정 구현
5. 솔루션 검증

각 이슈에 대해 제공:
- 근본 원인 설명
- 진단을 뒷받침하는 증거
- 구체적인 코드 수정
- 테스트 방법
- 예방 권장사항

증상이 아닌 근본 원인을 해결하는 데 집중하세요.

 

 

서브에이전트 활용 패턴

대용량 작업 격리

테스트 실행, 문서 조회, 로그 분석처럼 대량의 출력을 생성하는 작업은 서브에이전트에 위임하세요:

서브에이전트를 사용해서 테스트 스위트를 실행하고
실패한 테스트와 에러 메시지만 보고해줘

병렬 리서치

독립적인 조사 작업은 여러 서브에이전트를 병렬로 실행할 수 있습니다:

인증, 데이터베이스, API 모듈을 각각 별도의 서브에이전트로 병렬 분석해줘

서브에이전트 체이닝

다단계 워크플로우에서는 서브에이전트를 순차적으로 사용할 수 있습니다:

code-reviewer 서브에이전트로 성능 이슈를 찾고,
optimizer 서브에이전트로 수정해줘

영구 메모리 활용

서브에이전트에 memory 필드를 설정하면 대화 간에 지속되는 지식을 축적할 수 있습니다:

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

범위	위치	용도
user	~/.claude/agent-memory/<name>/	모든 프로젝트에서 학습 내용 기억
claude-code ai-agent subagent anthropic 개발도구 자동화 project	.claude/agent-memory/<name>/	프로젝트별 지식, 버전 관리 가능
local	.claude/agent-memory-local/<name>/	프로젝트별 지식, 버전 관리 제외

Agent Teams (실험적 기능)

더 복잡한 협업이 필요한 경우, Agent Teams를 사용할 수 있습니다. 서브에이전트는 단일 세션 내에서 작동하지만, Agent Teams는 여러 개의 독립적인 Claude Code 인스턴스가 서로 조율하며 병렬로 작업합니다.

마무리

Claude Code의 서브에이전트는 개발 워크플로우를 획기적으로 개선할 수 있는 강력한 기능입니다. 핵심 포인트를 정리하면:

1. 집중된 서브에이전트 설계: 각 서브에이전트는 하나의 특정 작업에 뛰어나도록 설계
2. 상세한 설명 작성: Claude가 언제 위임할지 결정하는 기준이 됨
3. 도구 접근 제한: 필요한 권한만 부여하여 보안과 집중력 확보
4. 버전 관리에 포함: 프로젝트 서브에이전트를 팀과 공유

서브에이전트를 잘 활용하면 컨텍스트 관리, 병렬 처리, 비용 최적화를 동시에 달성할 수 있습니다.

---

참고 자료

• Create custom subagents - Claude Code Docs
• Building agents with the Claude Agent SDK
• Claude Code Agent Teams Guide
• Task/Agent Tools - ClaudeLog

이 글은 Claude Code를 활용하여 작성되었습니다.