Claude Code 확장하기

CLAUDE.md, Skills, subagent, hooks, MCP, plugin을 언제 사용해야 하는지 알아보세요.

Claude Code는 코드를 추론하는 모델과 파일 작업, 검색, 실행, 웹 접근을 위한 내장 도구를 결합합니다. 내장 도구는 대부분의 코딩 작업을 처리합니다. 이 가이드는 확장 레이어를 다룹니다: Claude가 아는 것을 커스터마이징하고, 외부 서비스에 연결하고, 워크플로를 자동화하기 위해 추가하는 기능들입니다.

참고:

핵심 에이전트 루프의 작동 방식에 대해서는 Claude Code 작동 방식을 참조하세요.

Claude Code가 처음이신가요? 프로젝트 규칙을 위해 CLAUDE.md부터 시작하세요. 필요에 따라 다른 확장 기능을 추가하세요.

개요

확장 기능은 에이전트 루프의 다양한 부분에 연결됩니다:

• CLAUDE.md 는 Claude가 매 세션마다 참조하는 영구 컨텍스트를 추가합니다
• Skills 는 재사용 가능한 지식과 호출 가능한 워크플로를 추가합니다
• MCP 는 Claude를 외부 서비스와 도구에 연결합니다
• Subagent 는 격리된 컨텍스트에서 자체 루프를 실행하고 요약을 반환합니다
• Agent team 은 공유 작업과 P2P 메시징으로 여러 독립 세션을 조율합니다
• Hooks 는 루프 외부에서 결정론적 스크립트로 실행됩니다
• Plugins 와 marketplaces 는 이러한 기능을 패키징하고 배포합니다

Skills는 가장 유연한 확장 기능입니다. skill은 지식, 워크플로, 또는 지침을 포함하는 markdown 파일입니다. /deploy와 같은 명령으로 skill을 호출하거나, Claude가 관련성이 있을 때 자동으로 로드할 수 있습니다. skill은 현재 대화에서 실행하거나 subagent를 통해 격리된 컨텍스트에서 실행할 수 있습니다.

목표에 맞는 기능 선택

기능은 Claude가 매 세션마다 참조하는 상시 컨텍스트부터, 사용자나 Claude가 호출할 수 있는 온디맨드 기능, 특정 이벤트에서 실행되는 백그라운드 자동화까지 다양합니다. 아래 표는 사용 가능한 기능과 각각이 적합한 경우를 보여줍니다.

기능	하는 일	사용 시점	예시
CLAUDE.md	매 대화마다 로드되는 영구 컨텍스트	프로젝트 규칙, "항상 X 하기" 규칙	"npm 대신 pnpm을 사용하세요. 커밋 전에 테스트를 실행하세요."
Skill	Claude가 사용할 수 있는 지침, 지식, 워크플로	재사용 가능한 콘텐츠, 참조 문서, 반복 작업	/review로 코드 리뷰 체크리스트 실행; endpoint 패턴이 담긴 API 문서 skill
Subagent	요약된 결과를 반환하는 격리된 실행 컨텍스트	컨텍스트 격리, 병렬 작업, 전문 워커	많은 파일을 읽지만 핵심 결과만 반환하는 조사 작업
Agent team	여러 독립적인 Claude Code 세션을 조율	병렬 조사, 새 기능 개발, 경쟁 가설로 디버깅	보안, 성능, 테스트를 동시에 검토하는 리뷰어 생성
MCP	외부 서비스에 연결	외부 데이터 또는 작업	데이터베이스 쿼리, Slack 포스팅, 브라우저 제어
Hook	이벤트에서 실행되는 결정론적 스크립트	예측 가능한 자동화, LLM 미관여	파일 편집 후 ESLint 실행

Plugins 는 패키징 레이어입니다. plugin은 skill, hook, subagent, MCP 서버를 하나의 설치 가능한 단위로 번들링합니다. plugin skill은 네임스페이스가 지정되어(예: /my-plugin:review) 여러 plugin이 공존할 수 있습니다. 동일한 설정을 여러 저장소에서 재사용하거나 marketplace 를 통해 다른 사람에게 배포하려면 plugin을 사용하세요.

유사한 기능 비교

일부 기능은 비슷해 보일 수 있습니다. 구분하는 방법은 다음과 같습니다.

Skill vs Subagent

Skill과 subagent는 서로 다른 문제를 해결합니다:

• Skill은 어떤 컨텍스트에서든 로드할 수 있는 재사용 가능한 콘텐츠입니다
• Subagent는 메인 대화와 별도로 실행되는 격리된 워커입니다

항목	Skill	Subagent
정의	재사용 가능한 지침, 지식, 워크플로	자체 컨텍스트를 가진 격리된 워커
핵심 장점	컨텍스트 간 콘텐츠 공유	컨텍스트 격리. 작업은 별도로 수행되고 요약만 반환
적합한 용도	참조 자료, 호출 가능한 워크플로	많은 파일을 읽는 작업, 병렬 작업, 전문 워커

Skill은 참조 또는 액션이 될 수 있습니다. 참조 skill은 Claude가 세션 전체에서 사용하는 지식을 제공합니다(예: API 스타일 가이드). 액션 skill은 Claude에게 특정 작업을 수행하도록 지시합니다(예: 배포 워크플로를 실행하는 /deploy).

Subagent를 사용하세요 컨텍스트 격리가 필요하거나 컨텍스트 윈도우가 가득 찰 때. subagent는 수십 개의 파일을 읽거나 광범위한 검색을 실행할 수 있지만, 메인 대화는 요약만 받습니다. subagent 작업이 메인 컨텍스트를 소비하지 않으므로, 중간 작업이 보일 필요가 없을 때도 유용합니다. 커스텀 subagent는 자체 지침을 가질 수 있고 skill을 미리 로드할 수 있습니다.

조합이 가능합니다. subagent는 특정 skill을 미리 로드할 수 있습니다(skills: 필드). skill은 context: fork를 사용하여 격리된 컨텍스트에서 실행할 수 있습니다. 자세한 내용은 Skills를 참조하세요.

CLAUDE.md vs Skill

둘 다 지침을 저장하지만 로드 방식과 용도가 다릅니다.

항목	CLAUDE.md	Skill
로드	매 세션, 자동으로	온디맨드
파일 포함 가능	예, @path import로	예, @path import로
워크플로 트리거 가능	아니오	예, /<name>으로
적합한 용도	"항상 X 하기" 규칙	참조 자료, 호출 가능한 워크플로

CLAUDE.md에 넣으세요 Claude가 항상 알아야 하는 내용: 코딩 규칙, 빌드 명령어, 프로젝트 구조, "절대 X 하지 않기" 규칙.

Skill에 넣으세요 Claude가 때때로 필요한 참조 자료(API 문서, 스타일 가이드)이거나 /<name>으로 트리거하는 워크플로(deploy, review, release)인 경우.

경험 법칙: CLAUDE.md를 200줄 이하로 유지하세요. 길어지면 참조 콘텐츠를 skill로 옮기거나 .claude/rules/ 파일로 분리하세요.

CLAUDE.md vs Rules vs Skills

세 가지 모두 지침을 저장하지만 로드 방식이 다릅니다:

항목	CLAUDE.md	.claude/rules/	Skill
로드	매 세션	매 세션, 또는 일치하는 파일이 열릴 때	온디맨드, 호출되거나 관련될 때
범위	전체 프로젝트	파일 경로에 한정 가능	작업별
적합한 용도	핵심 규칙과 빌드 명령어	언어별 또는 디렉토리별 가이드라인	참조 자료, 반복 가능한 워크플로

CLAUDE.md를 사용하세요 매 세션에 필요한 지침: 빌드 명령어, 테스트 규칙, 프로젝트 아키텍처.

Rules를 사용하세요 CLAUDE.md를 간결하게 유지하기 위해. paths frontmatter가 있는 rule은 Claude가 일치하는 파일을 작업할 때만 로드되어 컨텍스트를 절약합니다.

Skill을 사용하세요 Claude가 때때로만 필요한 콘텐츠에, 예를 들어 API 문서나 /<name>으로 트리거하는 배포 체크리스트.

Subagent vs Agent team

둘 다 작업을 병렬화하지만 아키텍처적으로 다릅니다:

• Subagent는 세션 내부에서 실행되며 결과를 메인 컨텍스트에 보고합니다
• Agent team은 서로 통신하는 독립적인 Claude Code 세션입니다

항목	Subagent	Agent team
컨텍스트	자체 컨텍스트 윈도우; 결과가 호출자에게 반환	자체 컨텍스트 윈도우; 완전히 독립
통신	메인 에이전트에게만 결과 보고	팀원이 서로 직접 메시지
조율	메인 에이전트가 모든 작업 관리	자체 조율이 가능한 공유 작업 목록
적합한 용도	결과만 중요한 집중 작업	토론과 협업이 필요한 복잡한 작업
토큰 비용	낮음: 결과가 메인 컨텍스트에 요약되어 반환	높음: 각 팀원이 별도의 Claude 인스턴스

Subagent를 사용하세요 빠르고 집중된 워커가 필요할 때: 질문 조사, 주장 검증, 파일 리뷰. subagent가 작업을 수행하고 요약을 반환합니다. 메인 대화는 깔끔하게 유지됩니다.

Agent team을 사용하세요 팀원이 발견 사항을 공유하고, 서로 도전하고, 독립적으로 조율해야 할 때. agent team은 경쟁 가설로 조사, 병렬 코드 리뷰, 각 팀원이 별도 부분을 담당하는 새 기능 개발에 가장 적합합니다.

전환 시점: 병렬 subagent를 실행하지만 컨텍스트 제한에 도달하거나 subagent끼리 통신해야 할 때, agent team이 자연스러운 다음 단계입니다.

참고:

Agent team은 실험적 기능이며 기본적으로 비활성화되어 있습니다. 설정 및 현재 제한 사항은 agent teams를 참조하세요.

MCP vs Skill

MCP는 Claude를 외부 서비스에 연결합니다. Skill은 해당 서비스를 효과적으로 사용하는 방법을 포함하여 Claude가 아는 것을 확장합니다.

항목	MCP	Skill
정의	외부 서비스에 연결하기 위한 프로토콜	지식, 워크플로, 참조 자료
제공하는 것	도구와 데이터 접근	지식, 워크플로, 참조 자료
예시	Slack 통합, 데이터베이스 쿼리, 브라우저 제어	코드 리뷰 체크리스트, 배포 워크플로, API 스타일 가이드

이들은 서로 다른 문제를 해결하며 함께 잘 작동합니다:

MCP는 Claude에게 외부 시스템과 상호작용하는 능력을 제공합니다. MCP 없이는 Claude가 데이터베이스를 쿼리하거나 Slack에 포스팅할 수 없습니다.

Skill은 Claude에게 해당 도구를 효과적으로 사용하는 방법에 대한 지식과 /<name>으로 트리거할 수 있는 워크플로를 제공합니다. skill에는 팀의 데이터베이스 스키마와 쿼리 패턴, 또는 팀의 메시지 포맷팅 규칙이 담긴 /post-to-slack 워크플로가 포함될 수 있습니다.

예시: MCP 서버가 Claude를 데이터베이스에 연결합니다. skill은 Claude에게 데이터 모델, 일반적인 쿼리 패턴, 다양한 작업에 사용할 테이블을 가르칩니다.

기능이 계층화되는 방식 이해하기

기능은 여러 수준에서 정의할 수 있습니다: 사용자 전체, 프로젝트별, plugin을 통해, 또는 관리형 정책을 통해. 또한 하위 디렉토리에 CLAUDE.md 파일을 중첩하거나 모노레포의 특정 패키지에 skill을 배치할 수 있습니다. 동일한 기능이 여러 수준에 존재할 때 계층화되는 방식은 다음과 같습니다:

• CLAUDE.md 파일은 가산적입니다: 모든 수준이 Claude의 컨텍스트에 동시에 콘텐츠를 기여합니다. 작업 디렉토리와 상위의 파일은 시작 시 로드되며, 하위 디렉토리는 작업할 때 로드됩니다. 지침이 충돌하면 Claude는 판단을 사용하여 조정하며, 일반적으로 더 구체적인 지침이 우선합니다. CLAUDE.md 파일 로드 방식을 참조하세요.
• Skill과 subagent는 이름으로 오버라이드합니다: 같은 이름이 여러 수준에 존재할 때 우선순위에 따라 하나의 정의가 적용됩니다(skill의 경우 managed > user > project; subagent의 경우 managed > CLI flag > project > user > plugin). Plugin skill은 충돌을 피하기 위해 네임스페이스가 지정됩니다. skill 탐색과 subagent 범위를 참조하세요.
• MCP 서버는 이름으로 오버라이드합니다: local > project > user. MCP 범위를 참조하세요.
• Hook은 병합됩니다: 등록된 모든 hook은 출처에 관계없이 일치하는 이벤트에 대해 실행됩니다. hooks를 참조하세요.

기능 조합하기

각 확장 기능은 서로 다른 문제를 해결합니다: CLAUDE.md는 상시 컨텍스트, skill은 온디맨드 지식과 워크플로, MCP는 외부 연결, subagent는 격리, hook은 자동화를 처리합니다. 실제 설정은 워크플로에 따라 이들을 조합합니다.

예를 들어, 프로젝트 규칙에는 CLAUDE.md를, 배포 워크플로에는 skill을, 데이터베이스 연결에는 MCP를, 편집 후 린팅에는 hook을 사용할 수 있습니다. 각 기능은 가장 잘하는 것을 처리합니다.

패턴	작동 방식	예시
Skill + MCP	MCP가 연결을 제공하고 skill이 Claude에게 효과적인 사용법을 가르침	MCP가 데이터베이스에 연결하고 skill이 스키마와 쿼리 패턴을 문서화
Skill + Subagent	Skill이 병렬 작업을 위해 subagent를 생성	/review skill이 격리된 컨텍스트에서 작동하는 보안, 성능, 스타일 subagent를 시작
CLAUDE.md + Skills	CLAUDE.md는 상시 규칙을 보유하고 skill은 온디맨드로 로드되는 참조 자료를 보유	CLAUDE.md는 "API 규칙을 따르세요"라고 하고 skill에 전체 API 스타일 가이드가 포함
Hook + MCP	Hook이 MCP를 통해 외부 작업을 트리거	편집 후 hook이 Claude가 중요한 파일을 수정할 때 Slack 알림을 전송

컨텍스트 비용 이해하기

추가하는 모든 기능은 Claude의 컨텍스트를 일부 소비합니다. 너무 많으면 컨텍스트 윈도우가 가득 찰 수 있지만, 노이즈를 추가하여 Claude의 효율성을 떨어뜨릴 수도 있습니다; skill이 올바르게 트리거되지 않거나 Claude가 규칙을 놓칠 수 있습니다. 이러한 트레이드오프를 이해하면 효과적인 설정을 구축하는 데 도움이 됩니다.

기능별 컨텍스트 비용

각 기능은 서로 다른 로딩 전략과 컨텍스트 비용을 가집니다:

기능	로드 시점	로드되는 내용	컨텍스트 비용
CLAUDE.md	세션 시작	전체 내용	매 요청
Skills	세션 시작 + 사용 시	시작 시 설명, 사용 시 전체 내용	낮음 (매 요청 설명)*
MCP 서버	세션 시작	모든 도구 정의와 스키마	매 요청
Subagent	생성 시	지정된 skill이 포함된 새로운 컨텍스트	메인 세션과 격리
Hook	트리거 시	없음 (외부에서 실행)	0, hook이 추가 컨텍스트를 반환하지 않는 한

*기본적으로 skill 설명은 세션 시작 시 로드되어 Claude가 사용 시기를 결정할 수 있습니다. skill의 frontmatter에서 disable-model-invocation: true를 설정하면 수동으로 호출할 때까지 Claude에게 완전히 숨겨집니다. 이렇게 하면 직접 트리거하는 skill의 컨텍스트 비용이 0으로 줄어듭니다.

기능 로드 방식 이해하기

각 기능은 세션의 다른 시점에 로드됩니다. 아래 탭은 각각이 언제 로드되고 컨텍스트에 무엇이 들어가는지 설명합니다.

CLAUDE.md

시점: 세션 시작

로드되는 내용: 모든 CLAUDE.md 파일의 전체 내용 (managed, user, project 수준).

상속: Claude는 작업 디렉토리에서 루트까지 CLAUDE.md 파일을 읽고, 해당 파일에 접근할 때 하위 디렉토리의 중첩된 파일을 발견합니다. 자세한 내용은 CLAUDE.md 파일 로드 방식을 참조하세요.

팁:

CLAUDE.md를 ~500줄 이하로 유지하세요. 참조 자료는 온디맨드로 로드되는 skill로 옮기세요.

Skills

Skill은 Claude 툴킷의 추가 기능입니다. 참조 자료(예: API 스타일 가이드)이거나 /<name>으로 트리거하는 호출 가능한 워크플로(예: /deploy)가 될 수 있습니다. Claude Code는 /simplify, /batch, /debug 같은 번들 skill을 기본 제공합니다. 직접 만들 수도 있습니다. Claude는 적절할 때 skill을 사용하며, 직접 호출할 수도 있습니다.

시점: skill의 설정에 따라 다릅니다. 기본적으로 설명은 세션 시작 시 로드되고 전체 내용은 사용 시 로드됩니다. 사용자 전용 skill(disable-model-invocation: true)의 경우 호출할 때까지 아무것도 로드되지 않습니다.

로드되는 내용: 모델 호출 가능 skill의 경우 Claude는 매 요청에서 이름과 설명을 봅니다. /<name>으로 skill을 호출하거나 Claude가 자동으로 로드하면 전체 내용이 대화에 로드됩니다.

Claude의 skill 선택 방식: Claude는 작업을 skill 설명과 매칭하여 관련성을 판단합니다. 설명이 모호하거나 겹치면 Claude가 잘못된 skill을 로드하거나 도움이 되는 skill을 놓칠 수 있습니다. Claude에게 특정 skill을 사용하도록 하려면 /<name>으로 호출하세요. disable-model-invocation: true가 설정된 skill은 호출할 때까지 Claude에게 보이지 않습니다.

컨텍스트 비용: 사용 전까지 낮음. 사용자 전용 skill은 호출 전까지 비용이 0입니다.

Subagent에서: Skill은 subagent에서 다르게 작동합니다. 온디맨드 로딩 대신, subagent에 전달된 skill은 시작 시 컨텍스트에 완전히 미리 로드됩니다. subagent는 메인 세션의 skill을 상속하지 않으며 명시적으로 지정해야 합니다.

팁:

부수 효과가 있는 skill에는 disable-model-invocation: true를 사용하세요. 컨텍스트를 절약하고 직접만 트리거되도록 보장합니다.

MCP 서버

시점: 세션 시작.

로드되는 내용: 연결된 서버의 모든 도구 정의와 JSON 스키마.

컨텍스트 비용: 도구 검색 (기본적으로 활성화)은 MCP 도구를 컨텍스트의 최대 10%까지 로드하고 나머지는 필요할 때까지 지연합니다.

안정성 참고: MCP 연결은 세션 중간에 조용히 실패할 수 있습니다. 서버가 연결 해제되면 도구가 경고 없이 사라집니다. Claude가 더 이상 존재하지 않는 도구를 사용하려고 할 수 있습니다. Claude가 이전에 접근할 수 있던 MCP 도구를 사용하지 못하는 것을 발견하면 /mcp로 연결을 확인하세요.

팁:

/mcp를 실행하여 서버별 토큰 비용을 확인하세요. 활발하게 사용하지 않는 서버는 연결을 끊으세요.

Subagent

시점: 온디맨드, 사용자 또는 Claude가 작업을 위해 생성할 때.

로드되는 내용: 다음을 포함하는 새로운 격리된 컨텍스트:

• 시스템 프롬프트 (캐시 효율성을 위해 부모와 공유)
• 에이전트의 skills: 필드에 나열된 skill의 전체 내용
• CLAUDE.md와 git status (부모로부터 상속)
• 리드 에이전트가 프롬프트에서 전달하는 모든 컨텍스트

컨텍스트 비용: 메인 세션과 격리. subagent는 대화 기록이나 호출된 skill을 상속하지 않습니다.

팁:

전체 대화 컨텍스트가 필요하지 않은 작업에 subagent를 사용하세요. 격리로 인해 메인 세션이 비대해지는 것을 방지합니다.

Hook

시점: 트리거 시. Hook은 도구 실행, 세션 경계, 프롬프트 제출, 권한 요청, 압축 등 특정 라이프사이클 이벤트에서 실행됩니다. 전체 목록은 Hooks를 참조하세요.

로드되는 내용: 기본적으로 없음. Hook은 외부 스크립트로 실행됩니다.

컨텍스트 비용: 0, hook이 대화에 메시지로 추가되는 출력을 반환하지 않는 한.

팁:

Hook은 Claude의 컨텍스트에 영향을 줄 필요가 없는 부수 효과(린팅, 로깅)에 이상적입니다.

더 알아보기

각 기능에는 설정 지침, 예시, 구성 옵션이 포함된 자체 가이드가 있습니다.

• CLAUDE.md - 프로젝트 컨텍스트, 규칙, 지침을 저장합니다
• Skills - Claude에게 도메인 전문성과 재사용 가능한 워크플로를 제공합니다
• Subagents - 격리된 컨텍스트에 작업을 위임합니다
• Agent teams - 병렬로 작업하는 여러 세션을 조율합니다
• MCP - Claude를 외부 서비스에 연결합니다
• Hooks - Hook으로 워크플로를 자동화합니다
• Plugins - 기능 세트를 번들링하고 공유합니다
• Marketplaces - Plugin 컬렉션을 호스팅하고 배포합니다