클로드 코드 서브에이전트 완전정복 (총 9편) | 1편 Claude Code란? 단순 CLI가 아닌 에이전트 플랫폼의 이해

시리즈: 클로드 코드 서브에이전트 완전정복 (총 9편) | 1편

Claude Code란? 단순 CLI가 아닌 에이전트 플랫폼의 이해

Claude Code를 터미널 도구로만 쓰고 있다면 전체 기능의 10%도 활용 못 하고 있는 거예요. 이 글에서 Claude Code가 에이전트 플랫폼인 이유와 CLAUDE.md, MCP, Hooks, SDK 네 가지 핵심 구성요소를 쉽게 풀어 드려요.

Summary

• Claude Code는 단순 CLI가 아니라 규칙, 확장, 자동화, 에이전트를 모두 갖춘 통합 플랫폼이에요
• CLAUDE.md(규칙), MCP(확장), Hooks(자동화), SDK(에이전트 실행) 네 기둥이 핵심이에요
• 이 네 가지가 결합될 때 비로소 "운영 가능한 에이전트"가 완성돼요
• 서브에이전트를 제대로 이해하려면 이 플랫폼 구조부터 잡아야 해요

이 글의 대상

• Claude Code를 설치했지만 터미널 명령어 수준에서 머물고 있는 분
• AI 코딩 도구가 "에이전트"라는 게 무슨 뜻인지 궁금한 분
• 서브에이전트 시리즈를 시작하기 전에 기초를 탄탄히 다지고 싶은 분

목차

• CLI 도구와 에이전트 플랫폼의 차이
• Claude Code 플랫폼의 네 기둥
• CLAUDE.md — 에이전트의 행동 규칙
• MCP — 외부 세계와 연결하는 확장 체계
• Hooks — 이벤트 기반 자동화
• 에이전트 실행 — SDK와 서브에이전트
• 네 기둥이 만나면 무슨 일이 생기는지
• 핵심 정리
• FAQ
• 참고 자료
• 다음 편 예고

---

CLI 도구와 에이전트 플랫폼의 차이

한 줄 요약: CLI는 명령을 실행하는 도구이고, 에이전트 플랫폼은 판단하고 행동하는 시스템이에요.

우리가 흔히 아는 CLI 도구는 "내가 시킨 것만" 해요. git commit이라고 치면 커밋하고, npm install이라고 치면 패키지 설치하고. 입력 → 출력, 끝이죠.

그런데 에이전트 플랫폼은 달라요. 목표를 주면 스스로 판단해서 여러 단계를 밟아 나가거든요. 파일을 읽고, 분석하고, 코드를 고치고, 테스트까지 돌리는 일련의 과정을 알아서 진행하는 거예요.

구분	CLI 도구	에이전트 플랫폼
동작 방식	명령 → 실행 → 결과	목표 → 판단 → 다단계 실행
판단 주체	사람	AI (사람이 감독)
컨텍스트	단일 명령 범위	프로젝트 전체
확장성	플러그인/별칭	규칙, 도구, 자동화, 에이전트
자율성	없음	설정에 따라 조절 가능

Claude Code는 터미널, IDE(VS Code 등), 웹/데스크톱 앱 등 여러 인터페이스에서 동작하는데, 어디서 쓰든 이 에이전트 플랫폼 구조는 동일하게 적용돼요.

---

Claude Code 플랫폼의 네 기둥

한 줄 요약: 규칙(CLAUDE.md), 확장(MCP), 자동화(Hooks), 에이전트 실행(SDK/서브에이전트)이 Claude Code의 핵심 구성이에요.

Claude Code를 "에이전트 플랫폼"이라고 부를 수 있는 건 이 네 가지 축이 있기 때문이에요.

┌─────────────────────────────────────────┐
│           Claude Code 플랫폼             │
│                                         │
│  ┌───────────┐  ┌───────────┐          │
│  │ CLAUDE.md │  │    MCP    │          │
│  │  (규칙)   │  │  (확장)   │          │
│  └───────────┘  └───────────┘          │
│  ┌───────────┐  ┌───────────────┐      │
│  │   Hooks   │  │ SDK/에이전트   │      │
│  │ (자동화)  │  │   (실행)      │      │
│  └───────────┘  └───────────────┘      │
└─────────────────────────────────────────┘

각각이 뭔지 하나씩 살펴볼게요.

---

CLAUDE.md — 에이전트의 행동 규칙

한 줄 요약: CLAUDE.md는 에이전트에게 "이 프로젝트에서는 이렇게 행동해"라고 알려주는 규칙 파일이에요.

사람이 회사에 입사하면 업무 매뉴얼을 받잖아요. CLAUDE.md가 바로 그 매뉴얼 역할을 해요. 프로젝트 루트에 이 파일을 두면 Claude Code가 자동으로 읽고 따라요.

담을 수 있는 내용 예시를 보면:

• 코딩 컨벤션 (예: "변수명은 camelCase로 써줘")
• 프로젝트 구조 설명 (예: "src/는 소스, tests/는 테스트야")
• 배포 절차 (예: "main 브랜치에 직접 푸시하지 마")
• 커밋 메시지 규칙
• 금지 사항

CLAUDE.md는 프로젝트 루트, 홈 디렉토리, 하위 폴더 등 여러 계층에 둘 수 있어서 상황에 맞는 규칙을 유연하게 적용할 수 있어요.

---

MCP — 외부 세계와 연결하는 확장 체계

한 줄 요약: MCP(Model Context Protocol)는 Claude Code가 외부 도구나 서비스와 소통할 수 있게 해주는 표준 연결 방식이에요.

Claude Code가 아무리 똑똑해도 혼자서는 Jira 티켓을 읽거나, Slack에 메시지를 보내거나, DB를 조회할 수 없잖아요. MCP가 이 문제를 해결해 줘요.

MCP 서버를 연결하면 Claude Code가 쓸 수 있는 도구가 늘어나는 거예요. 마치 스마트폰에 앱을 설치하는 것처럼요.

MCP 활용 예시	설명
Git 서버 연결	PR 생성, 리뷰 코멘트 작성
DB 연결	스키마 조회, 쿼리 실행
문서 도구 연결	Notion, Confluence 읽기/쓰기
모니터링 연결	로그 조회, 메트릭 확인

---

Hooks — 이벤트 기반 자동화

한 줄 요약: Hooks는 Claude Code의 특정 동작 전후에 자동으로 스크립트를 실행시키는 장치예요.

Git hooks를 써본 적 있다면 감이 올 거예요. 커밋 전에 린트를 자동으로 돌리듯, Claude Code에서도 특정 이벤트에 맞춰 자동화를 걸 수 있어요.

예를 들면:

• 파일을 수정하기 전에 백업 생성
• 도구를 호출할 때마다 로깅
• 특정 패턴의 코드가 생성되면 경고
• 작업 완료 후 자동으로 테스트 실행

Hooks가 있으면 에이전트가 "알아서" 하되, 위험한 행동에는 자동으로 안전장치가 걸리는 거죠.

---

에이전트 실행 — SDK와 서브에이전트

한 줄 요약: SDK로 Claude Code를 프로그래밍 방식으로 실행하고, 서브에이전트로 역할을 분리해서 복잡한 작업을 처리할 수 있어요.

여기가 이 시리즈의 핵심이에요. Claude Code는 단순히 대화형으로만 쓰는 게 아니라, SDK를 통해 다른 시스템에서 프로그래밍 방식으로 호출할 수 있어요. CI/CD 파이프라인에 넣거나, 스케줄러로 정기 실행하거나 하는 게 가능하다는 거죠.

그리고 서브에이전트는 메인 에이전트가 특정 작업을 별도의 전문가에게 위임하는 구조예요. "너는 코드 리뷰만 해", "너는 테스트 작성만 해"처럼 역할을 나눠서 각자 독립적인 컨텍스트에서 일하게 하는 거죠.

서브에이전트에 대한 자세한 내용은 2편부터 본격적으로 다룰 거예요.

---

네 기둥이 만나면 무슨 일이 생기는지

한 줄 요약: 네 기둥이 결합되면 "규칙을 알고, 도구를 쓰고, 자동화되고, 역할을 나눠서 일하는" 운영 가능한 에이전트가 돼요.

각 기둥을 따로 보면 그냥 기능이에요. 하지만 합쳐지면 이야기가 달라져요.

실제 시나리오를 하나 그려볼게요:

1. CLAUDE.md에 "PR은 반드시 테스트를 포함해야 해"라는 규칙이 있어요
2. MCP로 GitHub이 연결되어 있어서 PR을 읽고 쓸 수 있어요
3. 코드 변경 후 Hooks가 자동으로 테스트를 돌려요
4. 서브에이전트가 코드 리뷰를 담당하고, 다른 서브에이전트가 문서 업데이트를 담당해요

이게 하나의 흐름으로 돌아가는 거예요. 사람은 "이 기능 구현해줘"라고 말하면 되고, 나머지는 에이전트 플랫폼이 알아서 처리하는 거죠. 이것이 Claude Code를 "에이전트 플랫폼"이라고 부르는 이유예요.

---

핵심 정리

1. Claude Code = CLI 도구가 아니라 에이전트 플랫폼
2. 네 기둥: CLAUDE.md(규칙) + MCP(확장) + Hooks(자동화) + SDK/서브에이전트(실행)
3. CLAUDE.md는 에이전트의 행동 매뉴얼, MCP는 외부 연결, Hooks는 자동 안전장치
4. 네 기둥이 결합될 때 비로소 "운영 가능한 에이전트"가 완성됨
5. 서브에이전트를 이해하려면 이 플랫폼 구조를 먼저 잡는 게 필수

---

FAQ

Q. Claude Code는 무료로 쓸 수 있어요?

A. Claude Code 자체는 Anthropic의 API를 사용하는 구조예요. Pro/Team/Enterprise 요금제에 따라 사용 가능 범위가 달라지고, API 호출 비용이 발생해요.

Q. CLAUDE.md를 안 만들어도 Claude Code는 작동하나요?

A. 네, 작동은 해요. 하지만 프로젝트 맥락을 모르는 상태에서 일하는 거라 결과물의 질이 크게 떨어져요. 사람한테 아무런 업무 안내 없이 "알아서 해"라고 하는 것과 비슷하죠.

Q. MCP 서버는 직접 만들어야 하나요?

A. 직접 만들 수도 있지만, 이미 다양한 커뮤니티 MCP 서버가 공개되어 있어요. GitHub, Slack, 데이터베이스 등 주요 서비스용은 이미 만들어진 걸 가져다 쓰면 돼요.

Q. Hooks가 없으면 에이전트가 위험한 행동을 할 수도 있나요?

A. Claude Code는 기본적으로 권한 시스템이 있어서 위험한 도구 사용 시 사용자에게 확인을 요청해요. Hooks는 거기에 더해 자동화된 안전장치를 추가하는 거예요. 둘 다 쓰는 게 가장 안전하죠.

Q. 에이전트 플랫폼이면 사람이 아예 안 봐도 되는 건가요?

A. 아니에요. 현재 단계에서는 사람의 감독이 필수예요. 자율성 수준을 조절할 수 있는데, 처음에는 매 단계 확인하는 것부터 시작해서 신뢰가 쌓이면 점차 자율성을 높이는 게 권장돼요.

Q. 터미널 외에 어디서 쓸 수 있어요?

A. VS Code 같은 IDE 확장, 웹 인터페이스, 데스크톱 앱 등 다양한 환경에서 사용할 수 있어요. 어떤 인터페이스를 쓰든 CLAUDE.md, MCP, Hooks, 서브에이전트 구조는 동일하게 적용돼요.

Q. 기존에 쓰던 AI 코딩 도구(Copilot 등)와 뭐가 달라요?

A. 일반적인 AI 코딩 도구는 코드 자동완성이나 단일 작업에 초점을 맞춰요. Claude Code는 프로젝트 맥락을 이해하고, 여러 단계의 작업을 자율적으로 수행하며, 역할을 분리해서 처리할 수 있다는 점에서 근본적으로 달라요.

---

참고 자료 (References)

데이터 출처

출처	설명	링크
Claude Code Overview	Claude Code 플랫폼 전체 구조와 기능 소개	공식 문서
Claude Code 서브에이전트 문서	서브에이전트 개념과 사용법 공식 가이드	공식 문서
Claude Code Hooks	Hooks 기반 이벤트 자동화 가이드	공식 문서
Anthropic 자율 에이전트 블로그	Claude Code 자율 에이전트 운영 관련 블로그	블로그 포스트

핵심 인용

"When you combine project rules, extensions, automation, and agent execution, Claude Code becomes an operational agent platform — not just a coding assistant."
— Claude Code Overview 핵심 취지 요약

---

다음 편 예고

[2편] 서브에이전트 개념 이해 — 독립 컨텍스트와 역할 분리의 핵심

• 서브에이전트의 공식 정의와 6가지 구성요소를 정리해요
• 독립 컨텍스트에서 돌아가야 하는 이유를 알아봐요
• "서브"라는 이름이 위계가 아니라 책임 범위 제한인 이유를 풀어봐요