Claude Code 확장 기능 비교 - MCP, Skills, Hooks, Commands 언제 쓸까

Claude Code를 쓰다 보면 이런 말들을 듣게 됩니다.

"MCP 서버 연결해 두면 자동화 끝이야" "SuperClaude 깔아, Skills 다 들어있어" "Sub-agent 써야 진짜 에이전트지"

근데 막상 써보려고 하면 헷갈립니다. CLAUDE.md가 뭐고, Skill이 뭐고, MCP는 또 뭔지. 다 비슷해 보이는데 뭐가 다른 건지...

이 글에서 Claude Code의 커스터마이징 체계를 하나씩 뜯어보겠습니다. 각각이 뭔지, 어떻게 등록하는지, 그리고 언제 쓰는 게 맞는지까지.

먼저 큰 그림부터

Claude Code의 확장 포인트는 크게 7가지입니다. CLAUDE.md와 Slash Commands, Skills, Sub-agents, MCP, Hooks, Plugin 정말 많은 확장 포인트가 있고 같은 모델을 사용해도 어떤 걸 어떻게 사용하냐에 따라 다른 결과물을 마주할 수 있습니다.

CLAUDE.md - 매 세션 자동으로 읽히는 프로젝트 설명서

CLAUDE.md는 Claude Code가 세션 시작할 때 무조건 읽는 파일입니다. 프로젝트 루트에 두면 됩니다.

ChatGPT의 Custom Instructions, Cursor의 .cursorrules와 비슷한 개념입니다. "이 프로젝트는 이렇고, 이렇게 작업해줘"라는 기본 컨텍스트를 주는 겁니다.

Claude Code는 범용 도구입니다. 여러분의 프로젝트가 React인지 Vue인지, TypeScript 쓰는지 JavaScript 쓰는지 모릅니다. 매번 설명하기 귀찮잖아요.

CLAUDE.md에 한 번 써두면, 모든 세션에서 자동으로 알고 시작합니다. 저는 CLAUDE.md에 원격서버의 IP정보를 넣거나 프로젝트 코드 작성 후 빌드 규칙이나 작성된 프로젝트의 깃허브 컨밴션 규칙을 적어놓곤 합니다.

등록 방법

프로젝트 루트에 CLAUDE.md 파일 생성하면 끝입니다.

# 프로젝트 루트에서
touch CLAUDE.md

실전 예시

# 프로젝트: 커머스 어드민 대시보드

## 기술 스택
- Next.js 14 (App Router)
- TypeScript (strict mode)
- Tailwind CSS
- Supabase (Auth, Database, Storage)
- Zustand (상태관리)

## 디렉토리 구조
- `app/` - 페이지 및 라우팅
- `components/` - 재사용 컴포넌트
- `hooks/` - 커스텀 훅
- `lib/` - 유틸리티 함수
- `types/` - TypeScript 타입 정의

## 코딩 컨벤션
- 컴포넌트는 화살표 함수로 작성
- Props 타입은 컴포넌트 파일 상단에 정의
- 서버 컴포넌트 기본, 클라이언트 필요시 'use client' 명시
- 한글 주석 사용

## 주의사항
- .env.local 파일 절대 커밋 금지
- API 키 하드코딩 금지
- 커밋 전 `pnpm lint` 필수

Slash Commands - 자주 쓰는 프롬프트를 명령어로 저장

터미널에서 /로 시작하는 명령어입니다. 자주 쓰는 프롬프트를 저장해 두고 호출하여 사용할 수 있습니다.

/review          # 코드 리뷰 실행
/test            # 테스트 작성
/commit          # 커밋 메시지 생성

"staged 파일 리뷰해 줘. 버그 가능성, 성능 이슈, 컨벤션 위반 체크하고 수정 제안해 줘."이런 걸 매번 입력할 필요 없이 한 번 등록해 두면 /review만 치면 됩니다.

두 가지 종류가 있습니다

1. 내가 직접 만드는 커스텀 명령어

.claude/commands/에 마크다운 파일로 등록합니다. /review, /commit 같은 거요.

2. 플러그인/프레임워크가 제공하는 명령어

SuperClaude 같은 프레임워크를 설치하면 따라오는 명령어들입니다.

/sc:build --react --tdd      # SuperClaude의 빌드 명령어
/sc:analyze --code           # SuperClaude의 분석 명령어
/sc:scan --security          # SuperClaude의 보안 스캔

플러그인 명령어는 /플러그인명:명령어 형태로 네임스페이스가 붙습니다. 충돌 방지용이에요.

SuperClaude, BKIT 같은 프레임워크들이 결국 하는 일이 뭐냐면, 잘 짜여진 Slash Commands + Skills + Agents를 한 번에 설치해 주는 겁니다.

직접 등록하는 방법

# 프로젝트 루트에서
mkdir -p .claude/commands
touch .claude/commands/review.md

.claude/commands/ 폴더에 마크다운 파일로 만듭니다.

실전 예시

# .claude/commands/review.md

---
description: 스테이지된 파일 코드 리뷰
---

현재 git에 staged된 파일들을 리뷰해줘.

체크 항목:
1. 버그 가능성 - null 체크, 에러 핸들링, 엣지 케이스
2. 성능 이슈 - 불필요한 렌더링, 메모리 누수, N+1 쿼리
3. 컨벤션 위반 - 네이밍, 폴더 구조, 타입 정의
4. 보안 취약점 - XSS, SQL Injection, 민감 정보 노출

각 항목별로 문제 있으면 코드 위치와 수정 제안 알려줘.

# .claude/commands/commit.md

---
description: 컨벤셔널 커밋 메시지 생성
---

staged된 변경사항 분석해서 Conventional Commit 형식으로 커밋 메시지 만들어줘.

형식: <type>(<scope>): <description>

타입:
- feat: 새 기능
- fix: 버그 수정
- refactor: 리팩토링
- docs: 문서
- style: 포맷팅
- test: 테스트
- chore: 기타

한글로 작성하고, 50자 이내로.

~/.claude/commands/에 두면 글로벌 명령어가 됩니다 (모든 프로젝트에서 사용)
$ARGUMENTS로 인자를 받을 수 있습니다: /review components/Button.tsx
플러그인 명령어가 마음에 안 들면 같은 이름으로 덮어쓸 수 있습니다.
Claude Code에서 /만 치면 사용 가능한 명령어 목록이 자동완성됩니다.

Skills - Claude가 상황에 맞게 자동으로 꺼내 쓰는 전문 지식

Skills는 Claude가 자동으로 감지해서 적용하는 전문 지식 패키지입니다.

예를 들어 "엑셀 파일 만들어줘"라고 하면, Claude가 알아서 Excel Skill을 로드하고 .xlsx 파일을 제대로 생성합니다.

Slash Command와 뭐가 다른가요

트리거 주체가 다릅니다.

Slash Command: 내가 /review 쳐서 실행
Skill: Claude가 "이 작업은 Excel Skill 필요하겠다" 판단해서 실행

Skills는 Claude가 작업 맥락을 보고 "아, 이건 내가 아는 그 패턴이다" 하고 적용하는 겁니다.

등록 방법

.claude/skills/ 폴더에 디렉터리로 만들고, 그 안에 SKILL.md 파일을 둡니다.

mkdir -p .claude/skills/api-design
touch .claude/skills/api-design/SKILL.md

실전 예시

# .claude/skills/api-design/SKILL.md

---
description: REST API 설계 및 구현 가이드
globs:
  - "app/api/**/*.ts"
  - "pages/api/**/*.ts"
---

# API 설계 Skill

이 프로젝트의 API 설계 원칙입니다.

## 엔드포인트 네이밍
- 복수형 명사 사용: `/users`, `/products`
- 케밥 케이스: `/order-items`
- 동사 지양: `/get-user` X → `/users/:id` O

## 응답 형식
```json
{
  "success": true,
  "data": { ... },
  "error": null
}

## 에러 처리
- 400: 잘못된 요청 (validation 실패)
- 401: 인증 필요
- 403: 권한 없음
- 404: 리소스 없음
- 500: 서버 에러

## 필수 구현 사항
- Zod로 입력 검증
- try-catch로 에러 래핑
- 적절한 HTTP 상태 코드 반환

globs로 특정 파일 패턴에서만 활성화되게 할 수 있습니다.
Skill은 보조 파일을 포함할 수 있습니다. 템플릿, 스크립트 등을 같은 폴더에 두면 됩니다.
Anthropic이 기본 제공하는 Skills도 있습니다 (Excel, Word, PowerPoint 등) 클로드 웹에서는 설정에서 해당 기능을 활성화하기만 하면 바로 사용할 수 있습니다. 깃허브에서 공식 Claude Skills를 공개해 놓은 자료도 있습니다.

Sub-agents - 별도 컨텍스트에서 작업하는 보조 에이전트

Sub-agent는 메인 Claude와 별도의 컨텍스트에서 작업하는 분신입니다.

메인 Claude가 "야, 너는 저거 조사해와. 나는 이거 할게"라고 시키는 거죠.

예를 들어 "리서치해줘"라고 하면 Claude가 이것저것 찾아보면서 컨텍스트가 길어집니다. 나중에 "아까 그거 기반으로 코드 짜줘"라고 하면, 리서치 내용이 컨텍스트를 다 차지하고 있어서 핵심을 놓칠 수 있습니다.

Sub-agent한테 리서치 시키면, 결과만 가져오고 과정은 버립니다. 이런 식으로 컨텍스트가 오염되는 현상을 예방할 수 있습니다.

등록 방법

.claude/agents/ 폴더에 마크다운 파일로 만듭니다.

mkdir -p .claude/agents
touch .claude/agents/researcher.md

실전 예시

# .claude/agents/researcher.md

---
description: 기술 리서치 전문 에이전트
model: claude-sonnet-4-20250514
tools:
  - WebSearch
  - WebFetch
  - Read
---

# 리서처 에이전트

당신은 기술 리서치 전문가입니다.

## 역할
- 공식 문서에서 정확한 정보 수집
- 최신 버전 및 변경사항 파악
- 베스트 프랙티스 조사

## 작업 방식
1. 먼저 공식 문서 확인
2. GitHub 이슈/디스커션에서 실제 사례 조사
3. 핵심 내용만 요약해서 보고

## 결과물 형식
- 한 페이지 이내로 요약
- 출처 명시
- 코드 예시 포함 (있다면)

model로 특정 모델 지정 가능 (sonnet나 haiku 같은 저렴한 모델로 단순 작업 처리하도록 설정 가능)
tools로 사용 가능한 도구 제한 가능
메인 Claude가 Task 도구로 sub-agent를 호출합니다

MCP - GitHub, DB 같은 외부 시스템 연결 프로토콜

MCP(Model Context Protocol)는 Claude가 외부 시스템과 통신하는 표준 프로토콜입니다.

GitHub, Notion, Slack, 데이터베이스 등에 접근할 수 있게 해주는 "어댑터"라고 보면 됩니다.

많이들 하는 흔한 오해: "자동화 = MCP"

여기서 중요한 걸 짚고 넘어가겠습니다.

"MCP 서버 연결하면 자동화 끝"이라는 건 오해입니다.

MCP는 연결일 뿐입니다. "GitHub에 접근할 수 있다"와 "GitHub 작업을 자동화한다"는 다른 얘기입니다.

자동화를 원한다면:

단순 반복 → Slash Commands
이벤트 기반 자동 실행 → Hooks
복잡한 워크플로우 → Skills + Sub-agents

MCP는 이런 자동화가 외부 시스템 데이터가 필요할 때 쓰는 겁니다.

등록 방법

~/.claude/settings.json 또는 프로젝트의 .claude/settings.json에 설정합니다.

# 글로벌 설정
code ~/.claude/settings.json

# 또는 프로젝트별 설정
code .claude/settings.json

실전 예시

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-token>"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

CLI로 추가하는 방법

# MCP 서버 추가
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# 연결된 MCP 목록 확인
claude mcp list

# 특정 MCP 상세 정보
claude mcp get github

# MCP 제거
claude mcp remove github

필요한 MCP만 연결하세요. 많으면 Claude가 쓸데없이 호출 시도하고 초반 컨텍스트에서도 mcp 도구를 올려놓기 때문에 토큰 사용량이 많아질 수 있습니다.
MCP 서버는 로컬에서 실행됩니다. 보안에 주의하세요.
공식 MCP 서버 목록: https://github.com/modelcontextprotocol/servers

Hooks - 특정 이벤트에 자동 실행되는 스크립트

Hooks는 특정 이벤트가 발생했을 때 자동으로 실행되는 스크립트입니다.

Git의 pre-commit hook과 비슷합니다. "커밋 전에 린트 돌려서 문법 검사해라", "파일 저장할 때 포맷팅해라" 같은 겁니다.

파일 저장 시 자동 포맷팅
커밋 전 자동 검사
세션 시작 시 환경 체크
Claude 응답 후 후처리

등록 방법

.claude/settings.json에 설정합니다.

{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "node .claude/hooks/pre-write-check.js"
      }
    ],
    "postToolUse": [
      {
        "matcher": "Write",
        "command": "npx prettier --write $FILE_PATH"
      }
    ],
    "userPromptSubmit": [
      {
        "command": "node .claude/hooks/context-injection.js"
      }
    ]
  }
}

Hook 종류

Hook	실행 시점
userPromptSubmit	사용자가 프롬프트 제출할 때
preToolUse	Claude가 도구 사용하기 전
postToolUse	Claude가 도구 사용한 후
stop	Claude가 응답 완료할 때

실전 예시

// .claude/hooks/pre-write-check.js

const fs = require('fs');
const path = process.env.FILE_PATH;

// .env 파일 수정 방지
if (path && path.includes('.env')) {
  console.error('ERROR: .env 파일은 직접 수정할 수 없습니다.');
  process.exit(1);
}

// 특정 디렉토리 보호
const protectedDirs = ['node_modules', '.git', 'dist'];
if (protectedDirs.some(dir => path?.includes(dir))) {
  console.error(`ERROR: ${path}는 보호된 경로입니다.`);
  process.exit(1);
}

process.exit(0);

Hook은 동기적으로 실행됩니다. 무거운 작업은 피하세요.
matcher로 특정 도구에만 적용할 수 있습니다.
exit code 0이 아니면 작업이 중단됩니다.

Plugins - Commands, Skills, Hooks를 묶어서 배포하는 패키지

Plugins는 위에서 설명한 모든 것(Commands, Skills, Agents, Hooks, MCP 설정)을 하나로 묶어서 배포하는 방식입니다.

SuperClaude, BKIT 같은 프레임워크가 Plugin 형태로 배포됩니다.

Plugins는 팀에서 같은 설정을 공유하거나, 커뮤니티에서 만든 좋은 설정을 가져다 쓸 때 유용합니다.

등록 방법

# 마켓플레이스에서 설치
claude plugin install 

# GitHub에서 직접 설치
claude plugin install --url https://github.com/user/my-plugin

# 로컬 플러그인 테스트
claude --plugin-dir ./my-plugin

직접 만들기

mkdir my-plugin
cd my-plugin
mkdir .claude-plugin

// .claude-plugin/plugin.json
{
  "name": "my-plugin",
  "description": "우리 팀 전용 Claude Code 설정",
  "version": "1.0.0",
  "author": {
    "name": "My Name"
  }
}

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # 플러그인 메타데이터
├── commands/             # Slash Commands
│   └── review.md
├── skills/               # Skills
│   └── api-design/
│       └── SKILL.md
├── agents/               # Sub-agents
│   └── researcher.md
└── hooks/                # Hook 스크립트
    └── pre-write-check.js

Plugin 안의 commands는 /plugin-name:command 형태로 호출됩니다.
플러그인끼리 충돌 방지를 위해 네임스페이스가 붙습니다.

총 정리: 언제 뭘 써야 하나?

기능	용도
CLAUDE.md	프로젝트 기본 정보 알려주기
Slash Commands	자주 쓰는 프롬프트 저장
Skills	특정 작업에 전문 지식 적용
Sub-agents	병렬 작업, 컨텍스트 분리
MCP	GitHub, DB 등 외부 연동
Hooks	파일 저장 시 자동 포맷팅
Plugins	위 설정들 팀과 공유

저작자표시 비영리 변경금지 (새창열림)

먼저 큰 그림부터

CLAUDE.md - 매 세션 자동으로 읽히는 프로젝트 설명서

등록 방법

실전 예시

Slash Commands - 자주 쓰는 프롬프트를 명령어로 저장

두 가지 종류가 있습니다

직접 등록하는 방법

실전 예시

Skills - Claude가 상황에 맞게 자동으로 꺼내 쓰는 전문 지식

Slash Command와 뭐가 다른가요

등록 방법

실전 예시

Sub-agents - 별도 컨텍스트에서 작업하는 보조 에이전트

등록 방법

실전 예시

MCP - GitHub, DB 같은 외부 시스템 연결 프로토콜

등록 방법

실전 예시

CLI로 추가하는 방법

Hooks - 특정 이벤트에 자동 실행되는 스크립트

등록 방법

Hook 종류

실전 예시

Plugins - Commands, Skills, Hooks를 묶어서 배포하는 패키지

등록 방법

직접 만들기

총 정리: 언제 뭘 써야 하나?

티스토리툴바