Claude Code 확장 기능 정리 — CLAUDE.md, Skills, MCP, Subagents 언제 쓸까?

1. 확장 기능이 왜 필요할까?

기본 Claude Code는 이미 강력합니다. 파일 읽기, 코드 수정, 터미널 명령 실행 등 많은 것을 할 수 있죠.

그런데 실제 개발 현장에서는 이런 상황이 생깁니다.

• "이 프로젝트에서는 항상 pnpm을 써줘" → 매번 말하기 귀찮다
• "배포할 때마다 이 체크리스트를 따라줘" → 반복 작업이 너무 많다
• "슬랙 채널에 알림도 보내줘" → Claude 혼자서는 외부 서비스를 못 건드린다
• "파일 1,000개를 분석해줘" → 대화가 너무 길어져서 기억을 잃는다

이런 한계를 해결하기 위해 확장 기능이 존재합니다.

핵심 에이전트 루프(읽고→수정하고→검증하는 반복) 위에 레이어를 얹는 방식이에요.

┌─────────────────────────────────┐
│  Plugins / Marketplaces         │  ← 패키징 & 배포
├─────────────────────────────────┤
│  Agent Teams                    │  ← 다중 세션 협력
├──────────────┬──────────────────┤
│  Subagents   │  Hooks           │  ← 위임 & 자동화
├──────────────┴──────────────────┤
│  Skills           MCP           │  ← 지식 & 외부 연결
├─────────────────────────────────┤
│  CLAUDE.md                      │  ← 항상 켜진 컨텍스트
├─────────────────────────────────┤
│  핵심 에이전트 루프 (내장 도구)   │  ← 기본 엔진
└─────────────────────────────────┘

---

2. 7가지 확장 기능 한눈에 보기

기능 한 줄 요약 실생활 비유

CLAUDE.md	항상 읽어두는 프로젝트 규칙	사무실 공지판
Skills	필요할 때 꺼내쓰는 지식/절차	업무 매뉴얼
MCP	외부 서비스와 연결	USB 허브
Subagents	별도 작업자에게 위임	팀원에게 맡기기
Agent Teams	여러 팀원이 협력	프로젝트 팀 편성
Hooks	이벤트 발생 시 자동 실행	자동 알람 설정
Plugins	위 기능들을 묶어 배포	앱 설치 패키지

💡 공식 문서 추천: "처음이라면 CLAUDE.md부터 시작하세요. 필요에 따라 다른 기능을 추가하세요."

---

3. CLAUDE.md — 사무실 공지판 📌

CLAUDE.md란?

세션이 시작될 때 Claude가 자동으로 읽는 프로젝트 규칙 파일입니다.

매번 대화를 시작할 때 "이 프로젝트에서는 pnpm 써줘"라고 하는 대신, 한 번 파일에 써두면 Claude가 항상 기억합니다.

# CLAUDE.md 예시

## 패키지 매니저
- npm 대신 반드시 pnpm을 사용하세요

## 커밋 규칙
- 커밋 전에 반드시 테스트를 실행하세요
- 커밋 메시지는 한국어로 작성합니다

## 코딩 스타일
- 들여쓰기는 2칸(space)으로 통일합니다
- 컴포넌트는 함수형으로만 작성합니다

언제 쓸까?

• ✅ "항상 X를 해줘" 규칙
• ✅ 빌드/테스트 명령어
• ✅ 프로젝트 폴더 구조 설명
• ✅ "절대 Y는 하지 마" 규칙

주의사항

⚠️ 200줄 이내로 유지하세요! 너무 길면 컨텍스트를 많이 차지해서 오히려 Claude의 성능이 떨어집니다. 참조 자료는 Skills로 분리하는 게 좋습니다.

파일 구조 팁

프로젝트가 커지면 .claude/rules/ 폴더를 활용하세요.

my-project/
├── CLAUDE.md                  ← 핵심 규칙 (200줄 이하)
└── .claude/
    └── rules/
        ├── frontend.md        ← React 관련 규칙
        ├── backend.md         ← Spring Boot 관련 규칙
        └── database.md        ← DB 관련 규칙

언어별, 디렉토리별로 규칙을 분리하면 해당 파일 작업 시에만 로드되어 효율적입니다.

---

4. Skills — 업무 매뉴얼 📖

Skills란?

Claude가 필요할 때 꺼내 쓸 수 있는 지식이나 워크플로우를 담은 마크다운 파일입니다.

CLAUDE.md와 달리, 세션 시작 시 설명(제목)만 읽고 실제 내용은 필요할 때만 불러옵니다.

Skills의 두 가지 종류

① 참조형 Skill — Claude가 알아서 참고하는 지식

# api-style-guide.md (Skill 파일)
---
name: api-style-guide
description: REST API 엔드포인트 설계 규칙과 응답 형식 가이드
---

## 엔드포인트 규칙
- URL은 소문자와 하이픈 사용: /user-profiles (O), /userProfiles (X)
- 복수형 명사 사용: /users (O), /user (X)
- 버전 포함: /v1/users

## 응답 형식
{
  "success": true,
  "data": { ... },
  "message": "성공"
}

② 호출형 Skill — /명령어로 직접 실행하는 워크플로우

# deploy.md (Skill 파일)
---
name: deploy
description: 프로덕션 배포 전 체크리스트를 실행합니다
---

## 배포 순서
1. 테스트 전체 실행: `pnpm test`
2. 빌드 확인: `pnpm build`
3. 환경변수 확인
4. 스테이징 배포 후 검증
5. 프로덕션 배포

사용자: /deploy
Claude: 배포 체크리스트를 시작합니다.
  ✅ 테스트 실행 완료 (42/42 통과)
  ✅ 빌드 성공
  ⚠️  환경변수 DB_HOST가 설정되지 않았습니다!

CLAUDE.md vs Skills — 뭘 어디에 넣을까?

넣어야 할 내용 위치

"항상 X를 해줘" 같은 규칙	CLAUDE.md
API 문서, 스타일 가이드 참조 자료	Skills (참조형)
배포, 릴리스, 코드 리뷰 등 반복 절차	Skills (호출형)

💡 경험 법칙: CLAUDE.md가 200줄을 넘기 시작하면 참조 자료를 Skills로 빼세요.

---

5. MCP — 외부 서비스 연결 허브 🔌

MCP란?

Claude가 외부 시스템과 소통할 수 있게 해주는 연결 프로토콜입니다.

MCP 없이는 Claude는 프로젝트 파일만 볼 수 있습니다. MCP가 있으면 외부 세계와 연결됩니다.

MCP 없을 때:  Claude ↔ 프로젝트 파일만

MCP 있을 때:  Claude ↔ 프로젝트 파일
                     ↔ 슬랙 채널
                     ↔ 데이터베이스
                     ↔ 브라우저
                     ↔ Google Drive
                     ↔ GitHub 이슈
                     ↔ ...기타 외부 서비스

MCP + Skills 조합 예시

MCP는 연결만 제공하고, Skills는 그 연결을 잘 쓰는 방법을 알려줍니다.

[MCP]   → 데이터베이스에 연결하는 "능력" 제공
[Skill] → "우리 DB 스키마는 이렇고, 자주 쓰는 쿼리는 이거야" 지식 제공

→ 결합하면: DB에 연결해서 우리 팀 방식대로 쿼리를 작성!

주의사항

⚠️ MCP 서버는 컨텍스트를 먹습니다. 사용하지 않는 서버는 연결 해제하세요.
/mcp 명령으로 서버별 컨텍스트 비용을 확인할 수 있습니다.

---

6. Subagents — 부하 직원에게 위임하기 🤝

Subagents란?

별도의 컨텍스트(기억 공간)에서 독립적으로 작업하고, 결과 요약만 메인 Claude에게 보고하는 보조 AI입니다.

[메인 Claude]
     │
     ├─ "파일 200개 분석해서 문제점 찾아줘" ──→ [Subagent]
     │                                              ├─ 파일 1 읽기
     │                                              ├─ 파일 2 읽기
     │                                              ├─ ... (200개)
     │                                              └─ 요약 작성
     │
     ←─ "발견된 문제: 3가지 (보안 이슈 1, 성능 이슈 2)"
          (200개 파일 내용은 메인 Claude 메모리에 없음!)

언제 Subagents를 쓸까?

• ✅ 파일을 대량으로 읽어야 할 때
• ✅ 메인 대화를 깔끔하게 유지하고 싶을 때
• ✅ 여러 작업을 병렬로 처리할 때

병렬 Subagents 예시

/audit 명령 실행
     │
     ├──→ [보안 검토 Subagent] ─ 보안 취약점 분석
     ├──→ [성능 분석 Subagent] ─ 병목 구간 찾기
     └──→ [테스트 커버리지 Subagent] ─ 미테스트 코드 탐색
              ↓ (세 작업이 동시에 실행!)
     [메인 Claude] ← 세 가지 요약 결과 취합

---

7. Agent Teams — 프로젝트 팀 구성하기 👥

Agent Teams란?

여러 Claude Code 세션이 서로 직접 소통하며 협력하는 구조입니다.

Subagents와 헷갈리기 쉬운데, 핵심 차이는 이렇습니다.

Subagents Agent Teams

관계	상하 관계 (주인 ↔ 부하)	수평 관계 (팀원들)
소통 방식	결과만 메인에게 보고	팀원끼리 직접 대화
비용	저렴	비쌈 (각자 Claude 인스턴스)
적합한 경우	단순 작업 위임	토론/협력이 필요한 복잡한 작업

Subagents 선택: 빠르고 집중된 작업, 결과만 중요할 때
Agent Teams 선택: 팀원들이 결과를 공유하고 서로 검토하고 의견을 나눠야 할 때

⚠️ 현재 실험적 기능이며 기본 비활성화 상태입니다.

---

8. Hooks — 자동 알람과 트리거 ⚡

Hooks란?

특정 이벤트가 발생하면 자동으로 실행되는 결정론적 스크립트입니다.

"결정론적"이란 AI가 판단하지 않고, 항상 같은 결과가 나오는 스크립트라는 뜻입니다.

파일 편집 완료 이벤트 → Hook 실행 → ESLint 자동 검사
커밋 시도 이벤트 → Hook 실행 → 테스트 자동 실행
중요 파일 수정 이벤트 → Hook 실행 → Slack 알림 발송
세션 시작 이벤트 → Hook 실행 → 환경 변수 체크

Hooks의 큰 장점

컨텍스트 비용이 0입니다! Claude AI를 거치지 않고 스크립트가 직접 실행되기 때문입니다. Claude의 기억 공간을 전혀 차지하지 않아요.

언제 Hooks를 쓸까?

• ✅ 파일 저장 후 자동 린팅
• ✅ 커밋 전 자동 테스트
• ✅ 코드 변경 시 팀 슬랙 알림
• ✅ 세션 시작/종료 시 로깅

---

9. Plugins — 기능 묶음 패키지 📦

Plugins란?

Skills + Hooks + Subagents + MCP를 하나로 묶어서 설치/배포할 수 있는 단위입니다.

my-team-plugin/
├── skills/
│   ├── deploy.md          ← /my-team-plugin:deploy
│   └── code-review.md     ← /my-team-plugin:code-review
├── hooks/
│   └── pre-commit.sh      ← 커밋 전 자동 실행
└── mcp/
    └── server.json        ← Slack 연결 설정

💡 플러그인 Skill은 네임스페이스됩니다. /deploy 대신 /my-team-plugin:deploy 형태로 호출되어, 여러 플러그인이 충돌 없이 공존할 수 있습니다.

언제 Plugins를 쓸까?

• ✅ 여러 프로젝트에 동일한 설정을 재사용할 때
• ✅ 팀 전체가 같은 워크플로우를 쓸 때
• ✅ Claude Directory(마켓플레이스)에 공유하고 싶을 때

---

10. 헷갈리는 기능 비교표

① Skills vs Subagents — 뭐가 달라?

측면 Skills Subagents

정의	재사용 가능한 지식/절차 파일	격리된 컨텍스트를 가진 작업자
핵심 이점	컨텍스트 간 콘텐츠 공유	컨텍스트 격리 (결과만 반환)
적합한 경우	참조 자료, 호출 가능한 워크플로우	대용량 파일 처리, 병렬 작업

② CLAUDE.md vs Skills — 뭘 어디에 넣어?

넣을 내용 CLAUDE.md Skills

항상 기억해야 할 규칙	✅	❌
빌드/테스트 명령어	✅	❌
API 참조 문서	❌	✅
배포 체크리스트	❌	✅
로드 시점	항상 (세션 시작)	필요할 때만

③ MCP vs Skills — 둘 다 뭔가 추가하는 거 아닌가?

MCP Skills

역할	외부 서비스 연결 "능력" 제공	그 능력을 잘 쓰는 "지식" 제공
예시	DB에 연결하는 드라이버	우리 팀 DB 스키마와 쿼리 패턴

→ 결론: 둘은 함께 써야 시너지가 납니다.

---

11. 컨텍스트 비용 이해하기

각 기능이 Claude의 메모리(컨텍스트 윈도우)를 얼마나 차지하는지 알아야 효율적으로 사용할 수 있습니다.

기능 로드 시점 컨텍스트 비용

CLAUDE.md	세션 시작, 항상	🔴 높음 (매 요청마다)
Skills	세션 시작 시 설명만, 사용 시 전체	🟡 낮음 (설명만 항상)
MCP 서버	세션 시작, 항상	🔴 높음 (도구 정의 포함)
Subagents	온디맨드, 격리된 컨텍스트	🟢 없음 (메인과 분리)
Hooks	이벤트 발생 시	🟢 없음 (외부 실행)

컨텍스트 절약 팁

# 현재 컨텍스트 사용량 확인
/context

# MCP 서버별 비용 확인
/mcp

# 대화 압축 (포커스 지정 가능)
/compact focus on the API changes

Skills 컨텍스트 완전히 숨기기: 사용자가 직접 호출할 때만 쓰는 Skills에는 disable-model-invocation: true를 설정하세요. 호출 전까지 컨텍스트 비용이 0이 됩니다.

---
name: deploy
description: 프로덕션 배포 체크리스트
disable-model-invocation: true   ← 이 설정!
---

---

12. 초보자 권장 시작 순서

모든 기능을 한꺼번에 사용할 필요가 없습니다. 단계적으로 늘려가세요.

✅ 1단계: CLAUDE.md 작성
   → 프로젝트 기본 규칙, 빌드 명령어, 코딩 컨벤션 기록

✅ 2단계: Skills 만들기
   → 자주 반복하는 작업(배포, 코드 리뷰 등)을 매뉴얼화

✅ 3단계: MCP 연결
   → 필요한 외부 서비스 추가 (슬랙, DB 등)

✅ 4단계: Hooks 설정
   → 반복 자동화 (린팅, 테스트 등)

⬜ 5단계: Subagents 활용
   → 대용량 작업, 병렬 처리가 필요해질 때

⬜ 6단계: Agent Teams / Plugins
   → 팀 협업, 설정 공유가 필요해질 때

---

13. 마무리

Claude Code의 확장 기능을 한 줄로 요약하면:

기본 기능이 "무엇을 할 수 있느냐"라면, 확장 기능은 "어떻게 더 잘 할 수 있느냐"입니다.

핵심 정리:

• CLAUDE.md: 항상 기억해야 할 규칙. 200줄 이내로 유지
• Skills: 온디맨드 지식과 워크플로우. 컨텍스트 효율적
• MCP: 외부 서비스 연결. Skills와 함께 써야 시너지
• Subagents: 대용량 작업 위임. 메인 컨텍스트 보호
• Agent Teams: 복잡한 협력 작업. 실험적 기능
• Hooks: AI 없이 자동 실행. 컨텍스트 비용 0
• Plugins: 설정 묶음. 팀 공유/재사용에 최적

처음엔 CLAUDE.md 하나만 잘 써도 생산성이 크게 올라갑니다. 익숙해지면 Skills를 추가하고, 그다음 MCP와 Hooks를 붙여가는 방식을 추천합니다. 🚀

---

📌 참고 문서: Claude Code 확장하기 공식 한국어 문서