Claude Code 확장 기능 알아보기

Claude Code를 쓰다 보면 CLAUDE.md부터 플러그인, .claude 폴더 내의 skills, rules, hooks, subagents 등 다양한 확장 기능을 접하게 된다.

기능이 워낙 다양하다 보니 어떤 폴더에 어떤 프롬프트를 넣어야 할지, 각 기능의 차이는 무엇인지 너무 헷갈렸다. 이에 공식 문서를 바탕으로 각 확장 기능의 역할과 차이점을 한눈에 보기 쉽게 정리해 보았다.

한눈에 보기

각 확장 기능은 "Claude가 언제, 무엇을, 어떻게 알고 실행하는가" 의 차이로 구분할 수 있다.

기능	핵심 역할	로드 시점	컨텍스트 비용	대표 용도
CLAUDE.md	상시 프로젝트 지침	세션 시작 시 전체 로드	매 요청마다 상시 소모	패키지 매니저, 빌드 명령어, 핵심 컨벤션
Rules	경로별 세부 규칙	세션 시작 또는 경로 매칭 시	조건부 소모 (필요한 범위만)	TypeScript 규칙, API 설계 기준, 테스트 컨벤션
Skills	필요할 때 쓰는 지식 및 워크플로	설명 시작 시, 본문호출 시	호출 전까지 낮음	`/review`, `/deploy`, 도메인 참조 문서
Hooks	이벤트 기반의 확정적 자동화	특정 Lifecycle 이벤트 발생 시	거의 없음	코드 포맷팅, 위험 명령어 차단, 알림 연동
Subagents	독립 컨텍스트 작업자	위임받거나 명시적으로 호출될 때	메인 세션과 완벽히 격리	코드베이스 탐색, 보안 리뷰, 대규모 리서치
Plugins	위 확장 기능의 패키징 및 배포 단위	플러그인 설치 및 활성화 시	포함된 구성 요소에 따라 다름	사내 공용 툴킷, 마켓플레이스 배포

CLAUDE.md

Note

로드 시점: 세션 시작 시 작업 디렉터리부터 상위 디렉터리까지 전체 로드. 하위 디렉터리의 CLAUDE.md는 해당 경로의 파일을 다룰 때 지연 로드.
위치: 프로젝트 범위 ./CLAUDE.md, 사용자 범위 ~/.claude/CLAUDE.md

CLAUDE.md는 Claude가 프로젝트 작업 시 상시 인지해야 하는 정보를 기록하는 파일이다. 쉽게 말해 새로 합류한 팀원이 첫 출근 날 인수인계받을 만한 내용, 즉 코드베이스만 봐서는 바로 파악하기 어려운 맥락을 적는다.

공식 문서가 제시하는 기준 역시 명확하다. "다음 대화 세션에서도 또다시 설명해야 하는 내용"만 CLAUDE.md에 남기는 것이다. 특정 파일에만 적용되는 세부 규칙이나 긴 가이드라인, 간헐적인 배포 절차 등은 Rules나 Skills로 분리하는 편이 적절하다.

예시

# Project Instructions

## 기본 원칙

- 이 저장소는 변경 범위를 요청에 맞게 최소로 유지한다.
- 새 의존성 추가, 공유 패키지(`packages/*`)의 공개 API나 컴포넌트 props 시그니처 변경은 먼저 사용자와 합의한 뒤 진행한다.
- 기존 컨벤션과 다른 방식을 선택할 때는 그 이유를 먼저 설명한다.

로딩 범위와 위치

Claude Code는 작업 디렉터리부터 상위 디렉터리까지의 CLAUDE.md를 읽고, 하위 디렉터리의 CLAUDE.md는 해당 경로의 파일을 다룰 때 지연 로드한다. Turborepo 구조라면 다음처럼 계층을 나눌 수 있다.

repo/
├── CLAUDE.md                 # 전체 모노레포 공통 규칙
├── apps/
│   ├── web/
│   │   └── CLAUDE.md         # 웹 앱 전용 규칙
│   └── blog/
│       └── CLAUDE.md         # 블로그 전용 규칙(문체, frontmatter 등)
└── packages/
    └── ui/
        └── CLAUDE.md         # 공용 UI 컴포넌트 전용 규칙

Rules

Note

로드 시점: frontmatter에 paths가 없으면 세션 시작 시 항상 로드. paths가 있으면 해당 패턴에 맞는 파일을 다룰 때만 로드.
위치: .claude/rules/*.md

Rules는 CLAUDE.md에 담길 지침을 목적에 맞게 나누고, 특정 파일 경로에만 조건부로 적용하는 기능이다. 별도의 실행 시스템이라기보다는 CLAUDE.md를 모듈화하는 방식에 가깝다.

기본 위치는 .claude/rules/ 디렉터리이며, 파일 상단 YAML 프런트매터의 paths 필드로 대상 범위를 설정한다. 예를 들어, 프론트엔드 컴포넌트 전용 규칙은 아래와 같이 정의할 수 있겠다.

---
paths:
  - "src/components/**/*.tsx"
---

# 컴포넌트 규칙

- 아이콘만 있는 버튼에는 `aria-label`을 반드시 추가한다.
- 조건부 렌더링이 깊게 중첩되지 않도록 컴포넌트 조합(composition)을 우선한다.
- vanilla-extract의 `.css.ts` 파일은 해당 컴포넌트와 같은 폴더에 둔다.
- props로부터 파생 가능한 상태는 `useEffect` 대신 렌더링 중에 직접 계산한다.

또한 여러 앱이 공유하는 패키지라면, 앱 코드와는 다른 별도 기준이 필요할 때가 많다. 예를 들어 packages/ui처럼 배포 단위가 되는 패키지에는 다음과 같은 규칙을 둘 수 있다.

---
paths:
  - "packages/ui/**/*.tsx"
---

# 공용 UI 패키지 규칙

- 외부로 export하는 모든 컴포넌트는 Storybook 스토리를 함께 작성한다.
- 공개 props는 JSDoc으로 문서화한다.
- 이 패키지에는 특정 앱에 종속된 비즈니스 로직을 넣지 않는다.

paths를 지정하지 않은 Rule은 세션이 시작될 때 항상 로드되어 CLAUDE.md와 비슷하게 동작한다. 하지만 주제별로 파일을 쪼개어 관리할 수 있어 유지보수성이 크게 향상된다.

만약 CLAUDE.md의 크기가 점점 비대해지고 있다면 컴포넌트 작성 규칙, TypeScript 컨벤션, CI/CD 가이드라인처럼 성격이 뚜렷한 내용부터 Rules로 분리해 옮기는 것을 추천한다.

Skills

Note

로드 시점: description은 세션 시작 시 로드되어 항상 인지됨. 본문은 사용자가 /이름으로 직접 호출하거나, Claude가 작업 맥락과 description을 비교해 관련 있다고 판단할 때 로드.
위치: .claude/skills/<이름>/SKILL.md

Skill은 재사용 가능한 지식이나 참고 자료, 특정 워크플로를 정리해 둔 마크다운 파일이다. 본질적으로는 "필요할 때 꺼내 쓰는 상세 프롬프트" 에 가까우며, 매번 같은 지침을 길게 타이핑하거나 복사해 붙여넣는 번거로움을 줄여준다.

Skill은 크게 두 가지 유형으로 활용할 수 있다.

참조형(Reference): 순차적인 실행 단계 없이, Claude가 작업 중에 참고할 배경 지식을 담는다. 컴포넌트 컨벤션, API 응답 스키마, 디자인 시스템 가이드라인 등이 대표적이다.
작업형(Task): 배포나 스토리북 스토리 생성처럼 순서가 명확한 실행 절차를 담는 워크플로.

다음 두 가지 예시를 통해 각 유형이 실제로 어떻게 구성되는지 살펴보자.

참조형 Skill

프로젝트마다 정해진 컴포넌트 작성 규칙이 있다면, 이를 참조형 Skill로 만들어 새 컴포넌트를 작업할 때마다 자동으로 참고하게 할 수 있다.

---
name: component-conventions
description: 이 프로젝트의 React 컴포넌트 작성 컨벤션을 담고 있다. 새 컴포넌트를 만들거나 기존 컴포넌트를 수정할 때 참고한다.
---

# Component Conventions

- 컴포넌트 파일명은 PascalCase, 폴더명은 kebab-case로 쓴다.
- 스타일은 vanilla-extract로 작성하고, `.css.ts` 파일은 컴포넌트와 같은 폴더에 둔다.
- props 타입은 `ComponentNameProps`로 명명하고 별도로 export한다.
- 서버 컴포넌트를 기본으로 하고, 상호작용이 필요할 때만 `"use client"`를 추가한다.
- 아이콘만 있는 상호작용 요소에는 `aria-label`을 반드시 추가한다.

이 Skill은 컴포넌트 관련 작업이 시작되면 Claude가 description을 읽고 필요성을 판단해 자동으로 불러온다. 매번 프롬프트에 컨벤션을 일일이 붙여넣지 않아도, 새 컴포넌트를 만들 때마다 이 규칙을 알아서 적용하는 것이다. 참조형(Reference)의 특성에 맞게 순차적인 실행 단계 없이 반드시 지켜야 할 기준들로만 구성되어 있다.

Skill 폴더 안에 보조 문서를 함께 두면 SKILL.md 단일 파일 구성보다 훨씬 유연하고 동적인 구조를 만들 수 있다. 예를 들어 component-conventions/ 폴더 내에 실제 컴포넌트 예제 코드를 파일로 분리해 두고, SKILL.md에서 이를 참조하게 하는 방식이다.

작업형 Skill

새 컴포넌트를 만들 때마다 Storybook 스토리 작성 방식을 반복해서 설명하고 있다면, 이 절차도 Skill로 캡슐화할 수 있다.

---
name: storybook-story-writer
description: React 컴포넌트의 props 타입을 분석해 Storybook 스토리를 작성한다. 기본 상태와 주요 variant를 스토리로 만든다.
---

# Storybook Story Writer

1. 대상 컴포넌트 파일과 props 타입 정의를 읽는다.
2. 기존 `*.stories.tsx` 파일의 네이밍과 구조 컨벤션을 먼저 확인한다.
3. 필수 props는 기본값을 채운 `Default` 스토리로, 선택 props 중 의미 있는 조합은 별도 variant 스토리로 나눈다.
4. props 타입을 기준으로 `argTypes`를 생성해 Storybook Controls에서 조작 가능하게 만든다.
5. 이 저장소에서 쓰는 addon(접근성 검사, 다크모드 등)이 있다면 해당 설정을 함께 반영한다.
6. 생성한 스토리 파일 경로와 포함된 variant 목록을 요약해서 보고한다.

이렇게 만들어 두면 새 컴포넌트를 추가할 때마다 스토리 작성 규칙을 매번 설명하지 않고 /storybook-story-writer만으로 동일한 기준의 스토리를 반복 생성할 수 있다. 작업형답게 순서가 있는 실행 단계로 구성되어 있다.

Commands 라는 것도 있던데요?

Command는 /이름으로 실행하는 명령어를 통칭하는 용어다. 두 종류가 있다.

빌트인 명령어: /help, /clear, /model처럼 Claude Code CLI에 하드코딩된 명령어. 사용자가 만들거나 고칠 수 없다.
사용자 정의 명령어: .claude/commands/*.md 파일로 직접 만드는 명령어.

Skill과 Command의 차이

사실 여기에는 명령어 자체의 성격 차이뿐만 아니라, Claude Code의 역사도 얽혀 있다.

과거에는 사용자가 직접 정의하는 Command와 Skill이 서로 분리된 시스템이었다. Command는 단일 파일로 작성해 사용자가 /명령어를 직접 입력해야만 실행되었고, Skill은 폴더 구조로 관리되며 Claude가 대화 맥락을 보고 알아서 불러올 수도 있었다.

현재는 두 시스템이 통합되어 .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md 모두 동일하게 /deploy 명령어를 생성한다. 다만 확장성과 관리 편의성 때문에 새로 작성할 때는 Skill 방식을 공식 권장하며, 둘 사이의 실질적인 차이는 다음과 같다.

비교 기준	Command (`.claude/commands/`)	Skill (`.claude/skills/`)
관리 구조	`.md` 단일 파일	`SKILL.md`와 보조 파일을 포함하는 디렉터리
Claude 자동 로드	미지원 (직접 입력 시에만 실행)	지원 (`description` 기반 자율 판단)
세밀한 호출 제어	미지원	지원 (`disable-model-invocation` 등 옵션 제공)
이름 충돌 시 우선순위	-	Skill이 항상 우선 적용됨

따라서 새로 작성한다면, 굳이 Command로 작성할게 아니라 Skill로 작성하면 될 듯 하다.

Hooks

CLAUDE.md나 Skill에 적힌 지침은 어디까지나 Claude에게 전달하는 권장 사항일 뿐, 시스템 레벨의 강제 규정이 아니다. 예를 들어 "커밋 전에 항상 Biome 포맷팅을 실행하라"고 CLAUDE.md에 명시해도, 이를 실제로 수행할지는 여전히 모델의 판단에 맡겨진다.

예외 없이 무조건 실행되어야 하는 규칙은 프롬프트가 아니라 Hook으로 강제해야 한다. Hook은 수명 주기(Lifecycle) 이벤트가 일어날 때 모델의 자율적 판단을 거치지 않고 확정적으로 실행되는 셸 스크립트, HTTP 요청, MCP 도구 호출, 프롬프트 검증, 또는 Subagent다.

주요 이벤트

이벤트	실행 시점
`SessionStart`	세션 시작 또는 재개
`UserPromptSubmit`	사용자 프롬프트 제출 시
`PreToolUse`	도구 실행 직전
`PostToolUse`	도구 실행 성공 후
`Stop`	Claude 응답 종료 시
`PreCompact`	컨텍스트 압축 전
`SessionEnd`	세션 종료 시

Biome 포맷팅 자동화

Biome을 쓰는 프로젝트라면, 파일 수정 후 자동으로 포맷팅을 적용하는 PostToolUse Hook을 다음처럼 구성한다.

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx biome check --write"
          }
        ]
      }
    ]
  }
}

타입 안전성 강제

TypeScript 프로젝트에서는 수정 직후 타입 오류를 바로 잡아내는 Hook도 유용하다.

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm typecheck --filter=$(jq -r '.tool_input.file_path' | xargs dirname)"
          }
        ]
      }
    ]
  }
}

Subagents

Subagent는 메인 대화 세션과 완전히 분리된 독립 컨텍스트에서 일하는 전문 작업자다. Skill이 "메인 대화에 직접 불러와 사용하는 지식"이라면, Subagent는 "별도 작업실에서 복잡한 일을 처리한 뒤, 최종 요약 결과만 들고 오는 작업 위임" 에 가깝다.

예를 들어 주로 다음과 같은 상황에서 쓸 수 있을 것 같다.

번들 사이즈 분석: 수많은 소스 파일과 빌드 산출물을 하나하나 열람하고 비교해야 할 때
모노레포 의존성 검사: Turborepo 전체 패키지를 탐색하며 순환 참조나 미사용 export를 전수 조사할 때
API 응답 스키마 점검: 여러 API 라우트의 응답 타입과 스키마가 일관되게 작성되었는지 전역으로 검증할 때
접근성(a11y) 병렬 리뷰: 여러 패키지의 컴포넌트 접근성 규칙 준수 여부를 메인 컨텍스트 낭비 없이 검토할 때

---
name: performance-auditor
description: React/Next.js 페이지의 렌더링 성능, 번들 사이즈, 불필요한 클라이언트 JavaScript를 조사한다.
tools: Read, Grep, Glob, Bash
model: sonnet
---

당신은 프론트엔드 성능 감사관이다.

다음을 분석한다:
1. 빌드 산출물을 기준으로 번들 사이즈 회귀 여부
2. 불필요한 "use client" 경계
3. 과도한 데이터 요청을 유발하는 TanStack Query 캐시 설정
4. Turborepo 패키지 전반의 순환 의존성 또는 미사용 export

발견한 문제를 심각도별로 정리해서 보고한다. 파일은 수정하지 않는다.

Skill과 Subagent는 상호 연동이 가능하다. Subagent의 skills 목록에 Skill을 등록해 전용 지식으로 주입할 수도 있고, Skill 프런트매터에 context: fork를 지정해 호출 즉시 별도 Subagent 환경에서 실행되도록 구성할 수도 있다.

그러나 Subagent를 생성할 때마다 고정적인 컨텍스트 및 초기화 오버헤드가 수반된다는 점을 유의해야 한다. 대화 오염 방지나 대규모 조사처럼 격리 환경이 꼭 필요한 작업 위주로 도입하는 것이 효율적이다.

Plugins

Plugin은 Skills, Hooks, Subagents, MCP 서버, LSP(Language Server Protocol) 서버 등을 하나의 단위로 묶어 배포하고 설치할 수 있게 해주는 패키징이다. 완전히 새로운 기능을 만들기보다는, 앞서 살펴본 확장 기능들을 팀이나 커뮤니티에 손쉽게 공유하고 재사용하기 위한 유통 단위에 가깝다.

예를 들어 사내에서 여러 프로젝트를 운영 중이라면, 공통 CI/CD 검증 스크립트와 코드 리뷰 워크플로를 Plugin 하나로 패키징해 각 저장소에 일관되게 배포하고 업데이트할 수 있다.

그래도 겹치는 지점이 헷갈려요

CLAUDE.md vs Rules vs Skills

세 기능 모두 프롬프트 지침을 저장하지만 컨텍스트 로드 방식에서 결정적인 차이가 난다. CLAUDE.md는 세션 시작 시 전체 내용이 상시 로드되고, Rules는 경로 매칭 여부에 따라 조건부로 로드되며, Skills는 관련 작업이 실행될 때만 호출된다.

CLAUDE.md: 매 세션마다 모델이 항상 인지해야 하는 기본 사실
Rules: 특정 경로(프런트엔드 컴포넌트, 특정 패키지) 작업 시에만 한정되어야 하는 규칙
Skills: 컴포넌트 컨벤션 조회나 Storybook 생성처럼 특정 작업을 수행할 때만 꺼내 쓰는 지식 및 절차

Hook vs Skill

둘을 가르는 핵심 기준은 '확정성' 이다. Skill은 Claude가 대화 맥락을 보고 필요성을 스스로 판단해 불러오지만, Hook은 특정 수명 주기 이벤트가 발생하면 모델의 판단 없이 무조건 즉시 실행된다.

CLAUDE.md / Skill: Claude가 상황을 보고 유연하게 판단해서 적용해야 하는가?
Hook: Biome 포맷팅이나 위험 명령어 차단처럼 항상 정해진 시점에 무조건 실행되어야 하는가?

Skill vs Subagent

Skill은 메인 세션에 내용을 직접 불러와 컨텍스트를 공유하는 방식이고, Subagent는 격리된 별도 작업실에서 일을 마친 뒤 요약본만 메인 대화로 반환하는 실행 단위다.

Skill: 컴포넌트 작성 가이드처럼 참조한 지식과 작업 맥락이 메인 대화창에 그대로 유지되어야 할 때
Subagent: 번들 사이즈 분석이나 전역 순환 참조 조사처럼 대량의 탐색 로그로 메인 컨텍스트를 오염시킬 필요가 없을 때

마무리 (과잉 설계 경계하기)

Claude Code에는 여러 확장 기능이 있지만 처음부터 전부 도입할 필요는 없고 말 그대로 확장이므로 필요할 때 하나씩 도입하는 편이 나을 것 같다.

CLAUDE.md, Rules, Skills, Hooks, Subagents, Plugins를 처음부터 완벽하게 갖추려 들면 관리 비용과 복잡도만 커지고, 모델이 발전하면 할 수록 Claude는 대화 중에 “이 내용 기억해 둬”라고 하면 적절한 위치에 규칙을 만들어 주고, 자주 반복하는 작업을 프롬프트로 정리해 Skill로 만들어 달라고 해도 잘 정리해 준다.

전사 공통 설정이 필요한 팀 환경이 아니라면, 처음에는 자연어로 편하게 지시하다가 반복 패턴이 보이거나 제약이 필요한 순간에 하나씩 구조화하는 것도 늦지 않다고 생각한다.

한 번에 다 갖출 필요는 없다. 지금 반복해서 설명하고 있는 규칙이나 절차 하나를 떠올리고, 그 성격에 맞는 기능부터 시작하면 된다. 매번 틀리는 컨벤션이 있으면 CLAUDE.md에 한 줄 넣고, 같은 설명을 세 번째 반복하고 있다면 그때 Skill로 옮겨보자.