Claude Code 확장하기

Claude Code 확장하기

CLAUDE.md, 스킬, 서브에이전트, 훅, MCP, 플러그인을 언제 써야 하는지 이해합니다. Claude Code는 코드를 추론하는 모델과 파일 연산·검색·실행·웹 접근용 내장 도구를 결합합니다. 내장 도구가 대부분의 코딩 태스크를 다루며, 이 가이드는 확장 레이어(Claude가 아는 것을 커스터마이즈하고 외부 서비스를 연결하며 워크플로를 자동화하는 기능)를 다룹니다.

출처: 공식문서

본문

핵심 에이전틱 루프는 How Claude Code works 참고. Claude Code가 처음이라면 CLAUDE.md로 프로젝트 관례부터 시작하고, 특정 트리거가 생길 때 다른 확장을 추가하세요.

개요

확장은 에이전틱 루프의 다른 부분에 연결됩니다:

  • CLAUDE.md — 매 세션 Claude가 보는 영구 컨텍스트 추가
  • Skills — 재사용 가능한 지식과 호출 가능한 워크플로 추가
  • Code intelligence — 언어 서버 연결로 심볼 수준 탐색·실시간 타입 에러
  • MCP — 외부 서비스·도구 연결
  • Subagents — 격리된 컨텍스트에서 자체 루프를 돌려 요약 반환
  • Dynamic workflows — Claude가 쓴 스크립트로 여러 서브에이전트를 실행해 결과 하나 반환
  • Cross-session messaging — Claude가 한 세션에서 다른 세션으로 메시지 전달
  • Hooks — Claude Code가 수명주기 이벤트에 도달할 때 스크립트·HTTP 요청·MCP 도구 호출·프롬프트·서브에이전트 실행
  • Plugins·marketplaces — 이 기능들을 패키징·배포

스킬이 가장 유연한 확장입니다. 지식·워크플로·지침을 담은 마크다운 파일로, /deploy 같은 명령으로 호출하거나 관련 시 Claude가 자동 로드합니다. 스킬은 현재 대화에서 실행되거나 서브에이전트를 통해 격리된 컨텍스트로 실행될 수 있습니다.

목표에 기능 맞추기

기능은 매 세션 Claude가 보는 상시 컨텍스트부터 사용자·Claude가 호출할 수 있는 온디맨드 능력, 특정 이벤트에 실행되는 배경 자동화까지 다양합니다.

기능 하는 일 사용 시점 예
CLAUDE.md 모든 대화에서 로드되는 영구 컨텍스트 프로젝트 관례, "항상 X 하기" 규칙 "Use pnpm, not npm. Run tests before committing."
Skill Claude가 쓸 수 있는 지침·지식·워크플로 재사용 내용, 참조 문서, 반복 태스크 /deploy가 배포 체크리스트 실행; 엔드포인트 패턴 포함 API 문서 스킬
Subagent 요약 결과를 반환하는 격리 실행 컨텍스트 컨텍스트 격리, 병렬 태스크, 특화 작업자 많은 파일을 읽지만 핵심 발견만 반환하는 연구 태스크
Dynamic workflow Claude가 쓰는, 많은 서브에이전트를 배경에서 실행하는 스크립트 소수 서브에이전트를 넘어서는 작업, 교차 검증이 필요한 발견 코드베이스 전체 감사, 제2 에이전트 세트가 각 발견 검증
Cross-session messaging Claude가 한 세션에서 다른 세션으로 메시지 전달 직접 실행하는 세션이 작업 중 서로의 발견이 필요할 때 한 세션이 자신이 한 변경이 상대가 쓰는 것을 깨뜨린다고 경고
Code intelligence 언어 서버 탐색·진단 타이핑 언어, grep이 느리거나 부정확한 대형 코드베이스 전체 파일 대신 심볼 정의로 점프
MCP 외부 서비스 연결 외부 데이터·동작 DB 쿼리, Slack 게시, 브라우저 제어
Hook 이벤트로 트리거되는 스크립트·HTTP 요청·MCP 도구 호출·프롬프트·서브에이전트 모든 일치 이벤트에서 실행돼야 하는 자동화 파일 편집마다 ESLint 실행
Artifact 세션 출력을 비공개 인터랙티브 웹 페이지로 발행 터미널 텍스트보다 시각적으로 보고 싶은 출력 Claude가 조사하며 갱신되는 인시던트 타임라인

**플러그인**은 패키징 레이어입니다. 스킬·훅·서브에이전트·MCP 서버를 단일 설치 가능 단위로 묶습니다. 플러그인 스킬은 /my-plugin:review처럼 네임스페이스되어 여러 플러그인이 공존할 수 있습니다. 같은 설정을 여러 레포에서 재사용하거나 **마켓플레이스**로 배포하려면 플러그인을 쓰세요.

시간에 따라 설정 구축

모든 것을 처음부터 구성할 필요는 없습니다. 각 기능은 인지 가능한 트리거가 있고, 대부분 팀은 대략 이 순서로 추가합니다:

트리거 추가
Claude가 관례·명령을 두 번 틀림 CLAUDE.md에 추가
태스크 시작에 같은 프롬프트를 계속 입력 사용자 호출 스킬로 저장
같은 플레이북·다단계 절차를 채팅에 세 번째 붙여넣음 스킬로 캡처
Claude가 못 보는 브라우저 탭에서 데이터를 계속 복사 그 시스템을 MCP 서버로 연결
심볼 정의·사용 위치를 찾으려 Claude가 파일을 많이 읽음 언어용 code intelligence 플러그인 설치
부수 태스크가 다시 참조하지 않을 출력으로 대화를 범람 서브에이전트로 라우팅
매번 묻지 않고 항상 뭔가가 일어나길 원함 훅 작성
두 번째 레포가 같은 설정 필요 플러그인으로 패키징

같은 트리거가 이미 가진 것을 언제 갱신할지도 알려줍니다. 반복 실수·반복 리뷰 코멘트는 채팅의 일회성 수정이 아니라 CLAUDE.md 편집입니다. 손으로 계속 조정하는 워크플로는 또 한 번의 수정이 필요한 스킬입니다.

비슷한 기능 비교

스킬 vs 서브에이전트 — 스킬은 어떤 컨텍스트에도 로드할 수 있는 재사용 내용이고, 서브에이전트는 메인 대화와 별개로 실행되는 격리 작업자입니다. | 양상 | 스킬 | 서브에이전트 | | --- | --- | --- | | 정체 | 재사용 가능한 지침·지식·워크플로 | 자체 컨텍스트를 가진 격리 작업자 | | 핵심 이점 | 컨텍스트 간 내용 공유 | 컨텍스트 격리. 작업은 따로, 요약만 반환 | | 컨텍스트 윈도우 영향 | 메인 윈도우에 추가 | 자체 입력·출력 토큰의 별도 윈도우 | | 최적 | 참조 자료, 호출 가능한 워크플로 | 많은 파일 읽기, 병렬 작업, 특화 작업자 |

스킬은 참조형이나 행동형일 수 있습니다. 참조 스킬은 세션 내내 Claude가 쓰는 지식(API 스타일 가이드)을 주고, 행동 스킬은 특정 일을 하라고 합니다(/deploy가 배포 워크플로 실행). 컨텍스트 격리나 컨텍스트 윈도우가 가득 찰 때 서브에이전트를 쓰세요. 서브에이전트는 수십 개 파일을 읽거나 광범위한 검색을 할 수 있지만 메인 대화는 요약만 받습니다. 커스텀 서브에이전트는 자체 지침을 가질 수 있고 스킬을 미리 로드할 수 있습니다. 이 둘은 결합할 수 있습니다: 서브에이전트가 특정 스킬을 미리 로드(skills: 필드)하고, 스킬은 context: fork로 격리 컨텍스트에서 실행될 수 있습니다.

CLAUDE.md vs 스킬 — 둘 다 지침을 저장하지만 로드 방식이 다릅니다. | 양상 | CLAUDE.md | 스킬 | | --- | --- | --- | | 로드 | 매 세션 자동 | 온디맨드 | | 파일 포함 | 가능(@path 임포트) | 가능(@path 임포트) | | 워크플로 트리거 | 불가 | 가능(/<name>) | | 최적 | "항상 X 하기" 규칙 | 참조 자료, 호출 가능한 워크플로 |

Claude가 항상 알아야 하면 CLAUDE.md에(코딩 관례, 빌드 명령, 프로젝트 구조, "절대 X 하지 말 것"), 때때로 필요한 참조 자료(API 문서, 스타일 가이드)나 /<name>으로 트리거하는 워크플로(배포, 리뷰, 릴리스)는 스킬에 두세요. 경험칙: CLAUDE.md를 200줄 미만으로. 늘어나면 참조 내용을 스킬로 옮기거나 .claude/rules/ 파일로 나누세요.

CLAUDE.md vs 규칙 vs 스킬 — 셋 다 지침을 저장하지만 로드가 다릅니다: CLAUDE.md는 매 세션, .claude/rules/는 매 세션 또는 일치 파일이 열릴 때, 스킬은 호출되거나 관련 시 온디맨드. 매 세션 필요한 지침(빌드 명령, 테스트 관례, 아키텍처)엔 CLAUDE.md, CLAUDE.md를 집중시키려면 규칙(paths 프론트매터로 컨텍스트 절약), 때때로만 필요한 내용(API 문서, /<name>으로 트리거하는 배포 체크리스트)엔 스킬.

서브에이전트 vs 다이내믹 워크플로 — 둘 다 메인 대화 밖에서 작업합니다. 서브에이전트는 Claude가 턴마다 무엇이 다음에 실행될지 결정하고, 워크플로는 스크립트가 결정합니다. 서브에이전트는 Claude가 띄우는 작업자로 각자가 자신을 띄운 대화에 요약을 반환합니다. 다이내믹 워크플로는 Claude가 쓰는 스크립트로 많은 서브에이전트를 배경에서 실행하고 결과 하나를 반환합니다. 빠르고 집중된 작업자(질문 조사, 주장 검증, 파일 리뷰)에는 서브에이전트를, 소수 서브에이전트를 넘어서는 작업이나 보기 전 교차 검증이 필요한 발견(코드베이스 전체 감사, 대형 마이그레이션, 여러 각도에서 초안된 플랜)엔 다이내믹 워크플로를 쓰세요. 한 세션에서 다른 세션으로 발견을 전달하려면 cross-session messaging을, 한 번에 여러 Claude를 실행하는 다른 방법은 Run agents in parallel을 참고하세요.

MCP vs 스킬 — MCP는 외부 서비스에 연결하고, 스킬은 Claude가 아는 것(그 서비스를 효과적으로 쓰는 방법 포함)을 확장합니다. | 양상 | MCP | 스킬 | | --- | --- | --- | | 정체 | 외부 서비스 연결 프로토콜 | 지식·워크플로·참조 자료 | | 제공 | 도구·데이터 접근 | 지식·워크플로·참조 자료 | | 예 | Slack 연동, DB 쿼리, 브라우저 제어 | 코드 리뷰 체크리스트, 배포 워크플로, API 스타일 가이드 |

MCP는 외부 시스템용 목적 제작 도구를 주며 연결·인증은 서버가 처리합니다. 스킬은 그 도구를 효과적으로 쓰는 지식과 /<name>으로 트리거하는 워크플로를 줍니다. 스킬이 팀의 DB 스키마·쿼리 패턴, 또는 메시지 포맷 규칙을 담은 /post-to-slack 워크플로를 담을 수 있습니다.

훅 vs 스킬 — 훅은 수명주기 이벤트에서 실행되고, 스킬은 Claude가 적용할 컨텍스트에 로드됩니다. | 양상 | 훅 | 스킬 | | --- | --- | --- | | 실행 | 셸 명령·HTTP 요청·MCP 도구 호출·LLM 프롬프트·서브에이전트 | Claude가 읽고 따르는 지침 | | 트리거 | PostToolUse, SessionStart 같은 수명주기 이벤트 | 사용자가 /<name> 입력, 또는 Claude가 설명을 작업에 일치 | | 결정성 | 이벤트에서 항상 발화. 트리거 보장 | Claude가 지침 해석. 결과는 가변 | | 컨텍스트 비용 | 훅이 출력을 반환하지 않으면 0 | 설명은 매 세션, 전체 내용은 사용 시 로드 | | 최적 | 편집 후 린트, 안전하지 않은 명령 차단, 로깅, 알림 | 추론이 필요한 워크플로, 참조 자료, 다단계 태스크 |

동작이 매번 같은 방식으로 일어나야 하고 Claude의 사고가 필요 없으면 훅을 쓰세요(저장 시 포맷, rm -rf / 거부, 세션 종료 시 Slack 게시). Claude가 단계 적용을 결정해야 하거나 내용이 스크립트보다 지식이면 스킬(/release 체크리스트, API 스타일 가이드, 디버깅 플레이북). 가드레일은 훅에 두세요. CLAUDE.md·스킬의 "absolute .env 편집 금지" 지침은 요청이지 보장이 아닙니다. 편집을 차단하는 PreToolUse 훅이 강제입니다. 규칙이 매번 성립해야 하면 프롬프트 지침이 아니라 훅으로 만드세요. 훅 출력은 컨텍스트에 들어갑니다: 린터를 실행하는 PostToolUse 훅은 결과를 Claude가 읽는 텍스트로 피드백하고, /fix-lint 스킬은 해결 방법을 알려줍니다.

기능 레이어링 이해

기능은 user 전역·프로젝트별·플러그인·관리 정책 등 여러 수준으로 정의할 수 있습니다. 같은 기능이 여러 수준에 있을 때:

  • CLAUDE.md 파일은 가산적: 모든 수준의 내용이 동시에 컨텍스트에 기여. 작업 디렉터리·위의 파일은 실행 시, 하위 디렉터리는 작업하며 로드. 충돌 시 Claude는 판단으로 조화시키되 더 구체적 지침이 보통 우선. how CLAUDE.md files load.
  • 스킬·서브에이전트는 이름으로 재정의: 같은 이름이 여러 수준에 있을 때 우선순위로 하나가 이김(스킬: managed > user > project; 서브에이전트: managed > CLI flag > project > user > plugin). 플러그인 스킬은 네임스페이스. skill discovery, subagent scope.
  • MCP 서버는 이름으로 재정의: local > project > user. MCP scope.
  • 훅은 병합: 소스와 무관하게 일치 이벤트에 등록된 모든 훅이 발화. hooks.

기능 결합

각 확장은 다른 문제를 해결합니다: CLAUDE.md는 상시 컨텍스트, 스킬은 온디맨드 지식·워크플로, MCP는 외부 연결, 서브에이전트는 격리, 훅은 자동화. 실제 설정은 워크플로에 따라 결합합니다.

패턴 동작 방식 예
Skill + MCP MCP가 연결 제공, 스킬이 잘 쓰는 법을 가르침 MCP가 DB 연결, 스킬이 스키마·쿼리 패턴 문서화
Skill + Subagent 스킬이 병렬 작업용 서브에이전트 생성 /audit 스킬이 보안·성능·스타일 서브에이전트를 격리 컨텍스트에서 시작
CLAUDE.md + Skills CLAUDE.md는 상시 규칙, 스킬은 온디맨드 참조 자료 CLAUDE.md가 "API 관례 따르기", 스킬이 전체 API 스타일 가이드
Hook + MCP 훅이 MCP로 외부 동작 트리거 편집 후 훅이 Claude가 중요 파일 수정 시 Slack 알림

컨텍스트 비용 이해

추가하는 모든 기능이 Claude 컨텍스트 일부를 소비합니다. 너무 많으면 컨텍스트 윈도우가 차거나 노이즈가 늘어 Claude가 덜 효과적일 수 있습니다(스킬이 제대로 트리거되지 않거나 관례를 놓칠 수). 이런 트레이드오프를 이해하면 효과적인 설정을 만듭니다.

기능별 컨텍스트 비용

기능 로드 시점 로드되는 것 컨텍스트 비용
CLAUDE.md 세션 시작 전체 내용 모든 요청
Skills 세션 시작 + 사용 시 시작 시 설명, 사용 시 전체 낮음(설명은 요청마다)*
MCP 서버 세션 시작 도구 이름, 전체 스키마는 온디맨드 도구 사용 전까지 낮음
Code intelligence 파일 편집 후 + 온디맨드 편집 후 진단, 조회 시 심볼 위치 낮음. 다른 곳의 파일 읽기 감소
Subagents 생성 시 지정 스킬이 있는 새 컨텍스트, 또는 포크의 부모 대화 메인 세션과 격리
Hooks 트리거 시 없음(외부 실행) 훅이 추가 컨텍스트를 반환하지 않으면 0

*기본적으로 스킬 설명이 세션 시작 시 로드되어 Claude가 언제 쓸지 결정합니다. 스킬 프론트매터에 disable-model-invocation: true를 설정하면 수동으로 호출하기 전까지 Claude에게 완전히 숨깁니다. 직접 작성하지 않은 스킬은 설정의 skillOverrides로 파일을 편집하지 않고 동일하게 합니다.

기능 로드 이해

각 기능은 세션의 다른 지점에서 로드됩니다. CLAUDE.md: 세션 시작, 모든 CLAUDE.md(managed·user·project)의 전체 내용. 200줄 미만 유지, 참조 자료는 온디맨드 로드되는 스킬로. Skills: 스킬은 Claude 도구 키트의 추가 능력으로, 참조 자료(API 스타일 가이드)나 /<name>으로 트리거하는 워크플로(/deploy)일 수 있습니다. Claude Code는 /code-review, /batch, /debug 같은 번들 스킬을 포함합니다. 구성에 따라 달라지며 기본은 설명이 세션 시작, 전체 내용은 사용 시 로드. 모델 호출 가능 스킬은 요청마다 이름·설명을 보고, /<name>으로 호출하거나 자동 로드 시 전체 내용이 대화에 들어갑니다. Claude는 태스크를 스킬 설명에 일치시켜 관련 스킬을 선택합니다. 설명이 모호하거나 겹치면 틀린 스킬을 로드하거나 도움이 될 것을 놓칠 수 있습니다. 사이드 이펙트가 있는 스킬엔 disable-model-invocation: true를 쓰세요. MCP 서버: 세션 시작, 도구 이름·서버 지침 로드. 전체 JSON 스키마는 특정 도구가 필요할 때까지 지연. tool search가 기본 켜짐이라 유휴 MCP 도구는 최소만 소비. /mcp로 연결 상태 확인, /context all로 로드된 도구의 토큰 수 확인. Code intelligence: 파일 편집 후·온디맨드, 편집 후 타입 에러·경고, 심볼 조회 시 정의·참조·타입 정보. LSP 도구는 언어용 code intelligence 플러그인 설치 전까지 비활성. Subagents: 온디맨드. 새 격리 컨텍스트: 에이전트 자체 시스템 프롬프트(Claude Code 시스템 프롬프트 아님), 에이전트 skills: 필드 스킬의 전체 내용, CLAUDE.md·git 상태(내장 Explore·Plan 에이전트는 둘 다 생략), 리드 에이전트가 프롬프트로 넘기는 컨텍스트. 포크는 부모의 지금까지 대화·시스템 프롬프트·도구를 로드. Hooks: 트리거 시. 기본 로드 없음, 메인 대화 밖에서 실행. 훅이 대화에 메시지로 추가될 출력을 반환하지 않으면 0. 사이드 이펙트(린트, 로깅)에 이상적.

더 알아보기

각 기능은 설정·예시·구성 옵션이 있는 자체 가이드를 갖습니다. CLAUDE.md, Skills, Subagents, Dynamic workflows, Cross-session messaging, MCP, Hooks, Plugins, Marketplaces.

더 알아보기