노모어매뉴얼 수강생 전용 가이드

Claude Code 에이전트 완전 정복

◆

SDK 에이전트 · 서브에이전트 · Agent Teams
세 가지 개념을 단번에 이해하는 입문 가이드

노모어매뉴얼 · 2026

Contents

이런 내용을 배워요

Chapter 01

에이전트란 무엇인가요?

💡 한 줄 요약

에이전트 = AI가 혼자서 판단하고 행동하는 것

일반 챗봇 vs 에이전트

일반 챗봇은 질문하면 답하는 것으로 끝이에요. 하지만 에이전트는 다릅니다.

1

판단 — 지금 뭘 해야 할지 스스로 결정해요

2

행동 — 파일을 읽고, 코드를 고치고, 검색을 해요

3

반복 — 결과를 보고 다음 행동을 또 결정해요

Claude Code가 바로 에이전트예요. "버그 찾아서 고쳐줘"라고 하면 파일을 직접 찾아서 수정까지 해주죠.

Chapter 01

Claude Code vs SDK 에이전트

Claude의 에이전트 기능에는 크게 두 가지 사용 방법이 있어요.

	Claude Code (CLI)	SDK 에이전트
실행 방법	터미널에서 `claude` 입력	내 코드 안에서 호출
사용자	사람이 직접 대화	코드가 자동으로 실행
용도	개발 보조, 일상 작업	자동화, 파이프라인, 제품 개발
비유	내가 직접 Claude에게 부탁	내 앱이 Claude에게 대신 부탁

🎯 핵심 포인트

Claude Code는 여러분이 직접 대화하는 도구고, SDK 에이전트는 여러분의 프로그램이 Claude를 조종하는 방법이에요.

쉽게 말해: 사람 → Claude vs 내 코드 → Claude

Chapter 02

SDK 에이전트 — 코드로 Claude 조종하기

🔧 SDK란?

Software Development Kit — 개발자가 서비스를 내 앱에 연결할 때 쓰는 도구 모음이에요.

SDK 에이전트가 하는 일

내 Python이나 JavaScript 코드 안에서 Claude에게 작업을 맡기고, 그 결과를 받아서 처리할 수 있어요.

①

내 코드가 Claude에게 프롬프트 전달

②

Claude가 파일 읽기, 코드 수정 등 도구 사용

③

작업 완료 후 결과를 내 코드에 반환

언제 쓰나요?

매일 밤 자동 코드 리뷰, CI/CD에서 에러 분석, 내 서비스에 AI 기능 넣기 등에 활용해요.

Chapter 02

SDK 에이전트 설치와 설정

pip install claude-agent-sdk       # Python
npm install @anthropic-ai/claude-agent-sdk  # JS

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="서버 로그에서 에러 찾아서 요약해줘",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Bash"],
        permission_mode="acceptEdits",
    ),
):
    print(message)

주요 옵션	설명
`allowed_tools`	사용 가능한 도구 (Read, Edit, Bash 등)
`permission_mode`	자동 승인 수준 (acceptEdits / bypassPermissions)
`system_prompt`	에이전트의 역할과 성격 정의
`max_turns`	최대 반복 횟수 제한

💡 핵심 흐름

설치 → 프롬프트 작성 → 도구 권한 설정 → 실행

Chapter 03

서브에이전트 — Claude가 Claude를 부른다

"팀장 Claude가 팀원 Claude에게 부탁하는 구조"

서브에이전트의 작동 원리

메인 Claude가 복잡한 작업을 만나면, 전문화된 서브에이전트에게 일부를 위임해요. 1개의 컨텍스트 세션 안에서 일어나는 일이에요.

①

메인 Claude가 작업 접수

②

Task 도구로 서브에이전트 호출

③

서브에이전트 작업 완료 → 요약 결과만 메인에 반환

✅ 장점

메인 컨텍스트를 깔끔하게 유지할 수 있어요. 서브에이전트가 탐색하고 메인은 큰 그림만 봐요.

Chapter 03

서브에이전트 만들고 사용하기

서브에이전트는 마크다운 파일 하나로 정의해요. 설치가 필요 없고 폴더에 파일만 넣으면 돼요.

1

파일 위치: .claude/agents/에이전트이름.md

---
name: code-reviewer
description: 코드 품질을 검토하는 전문 리뷰어
tools: Read, Glob, Grep
---
당신은 시니어 개발자입니다.
코드를 꼼꼼히 검토하고 개선점을 알려주세요.

2

글로벌 등록으로 모든 프로젝트에서 사용 가능

Mac/Linux: ~/.claude/agents/

Windows: C:\Users\사용자명\.claude\agents\

📌 지금 이 대화에서도!

이 ebook을 만들 때도 서브에이전트를 사용했어요. 메인 Claude가 조사 작업을 claude-code-guide 에이전트에게 위임했답니다.

Chapter 04

Agent Teams — 진짜 다중 에이전트

🚀 2026년 신기능

현재 Research Preview (실험 단계)로, 기본적으로 꺼져 있어요.

서브에이전트와 뭐가 다른가요?

서브에이전트는 1개 세션 안에서 순차 실행이에요. Agent Teams는 완전히 달라요.

✦

각자 독립된 컨텍스트 창 — 팀원마다 자신만의 작업 공간

✦

진짜 병렬 실행 — 팀원 A, B, C가 동시에 작업

✦

팀원끼리 직접 소통 — 팀장 없이도 협업 가능

비유: 서브에이전트는 "혼자 멀티태스킹", Agent Teams는 "진짜 팀 프로젝트"

Chapter 04

Agent Teams 활성화하기

설치가 필요 없어요. settings.json에 한 줄만 추가하면 됩니다.

1

설정 파일 열기

Mac/Linux: ~/.claude/settings.json

Windows: C:\Users\사용자명\.claude\settings.json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

2

다음 세션부터 적용돼요. 자연어로 요청하면 끝 → 이 프로젝트를 팀으로 작업하자 — 프론트엔드 1명, QA 1명

✅ 적합한 사용 사례

• 리서치 + 리뷰를 여러 관점에서 동시 진행

• 프론트엔드 / 백엔드 / 테스트를 각각 맡겨서 병렬 개발

• 디버깅 시 여러 가설을 동시에 검증

⚠️

주요 제한사항

실험적 — 세션 재개 불안정, 태스크 상태 지연 가능

세션당 1팀만 가능, 팀원이 또 팀을 만들 수 없음

토큰 비용이 팀원 수만큼 배로 증가 (각자 독립 컨텍스트)

Split pane은 tmux/iTerm2 필요 (Windows는 in-process 모드)

Chapter 05

세 가지를 한눈에 비교해요

	SDK 에이전트	서브에이전트	Agent Teams
누가 쓰나	개발자 (코드로)	Claude 내부	Claude 내부
세션 수	1개	1개	여러 개
실행 방식	코드 제어	순차 위임	진짜 병렬
설정 방법	pip/npm 설치	.md 파일 생성	settings.json 1줄
상태	정식 출시	정식 출시	실험 단계

🎯 언제 무엇을 쓸까요?

내 앱에 AI 기능 추가 → SDK 에이전트

특정 작업 전문가에게 위임 → 서브에이전트

대규모 프로젝트 병렬 처리 → Agent Teams

Summary

오늘 배운 것을 정리해요

1

에이전트 = AI가 스스로 판단하고 행동하는 것. Claude Code가 대표적인 예예요.

2

SDK 에이전트 = 내 코드로 Claude를 자동 조종하는 기반 기술. pip/npm으로 설치해요.

3

서브에이전트 = Claude 안에서 전문 역할을 위임하는 구조. .md 파일 하나로 만들어요.

4

Agent Teams = 여러 Claude가 독립 세션에서 병렬 협업. settings.json 한 줄로 활성화해요.

🌱 다음 단계

서브에이전트부터 시작하세요. .claude/agents/ 폴더에 .md 파일 하나 만들고 바로 활용할 수 있어요!

💸

Agent Teams 쓸 때 주의

팀원 수만큼 토큰 비용이 늘어요. 작은 작업은 서브에이전트가 더 경제적이에요.

◆ ◆ ◆

이 자료가 도움이 되셨나요?

노모어매뉴얼과 함께 AI를 더 쉽게