[Claude] Claude Code(클로드 코드) 고급 사용법 - Skills, MCP, Hooks, Subagents

leevigong 2026. 2. 17. 22:00

이전 글 [Claude] Claude Code(클로드 코드) 설치 및 기본 사용법에 이어 이번에는 스킬스, MCP, 훅, 서브에이전트 등에 대해 알아보자.

Claude Code 고급 사용법

[ Skills - 구) 커스텀 슬래시 커맨드의 상위호환 ]

개발하면서 우리는 무의식적으로 같은 작업을 수없이 반복한다. 가장 대표적인 예시로는 git commit & push, PR 작성, 코드 리뷰 등 이런 반복적인 작업에 대해 프롬프트를 한 번만 작성해두고 명령어 하나로 실행할 수 있다면 훨씬 편할 것이다. Claude Code의 Skills가 정확히 이 문제를 해결한다.

참고로 Claude Code에는 원래 .claude/commands/에 마크다운 파일을 넣어 커스텀 슬래시 커맨드를 만드는 방식이 있었다. Skills는 이 방식의 상위 호환으로, 기존 commands도 여전히 동작하지만 공식 문서에서는 Skills 사용을 권장한다. 가장 큰 차이는 두 가지다. 첫째, Skills는 슬래시 커맨드로 직접 호출할 수 있을 뿐 아니라 Claude가 작업 맥락을 보고 자동으로 로드할 수도 있다. 둘째, 단일 마크다운 파일이 아닌 디렉토리 단위로 스크립트나 참고 문서를 함께 묶을 수 있다.

Skills 만들기

만들고자 하는 스킬을 모든 프로젝트에서 사용할 글로벌 스킬로 만들지, 특정 프로젝트에서만 사용할 로컬 스킬로 만들지 용도에 맞는 디렉토리를 생성하자.

# 프로젝트 전용 스킬
mkdir -p .claude/skills/code-review

# 글로벌 스킬 (모든 프로젝트에서 사용)
mkdir -p ~/.claude/skills/code-review

그리고 이 안에 SKILL.md 파일을 만든다.

이 파일은 YAML 프론트매터와 마크다운 본문, 두 파트로 구성된다.

name 필드는 슬래시 커맨드 이름이 되고, description은 Claude가 자동 로드 여부를 판단하는 기준이 된다.

.claude/skills/code-review/SKILL.md

---
name: code-review
description: 코드 리뷰를 요청할 때 사용. 보안, 성능, 스타일을 종합 검토.
---

코드 리뷰 시 다음 항목을 반드시 점검하세요:
1. TypeScript strict 모드 준수 여부
2. 에러 핸들링 누락
3. 보안 취약점 (SQL 인젝션, XSS 등)
4. 성능 병목 가능성
5. 프로젝트 ESLint 설정 위반

Skills 사용하기

이렇게 만든 스킬은 두 가지 방식으로 사용할 수 있다.

> /code-review @./src/auth/       ← 슬래시 커맨드로 직접 호출
> 이 PR의 변경사항을 리뷰해줘           ← Claude가 description을 보고 자동 로드

"Claude가 작업 맥락을 보고 자동으로 로드할 수도 있다." 라고하였지만, 보안 및 검토가 필요한 민감한 작업은 Claude가 자동으로 실행하면 안 된다. description 아래에 disable-model-invocation: true을 설정하면 사용자가 해당 명령어를 직접 호출해야지만 실행이 된다.

프론트매터 주요 필드

name과 description 외에도 알아두면 유용한 프론트매터 필드들이 있다.

---
name: deploy
description: 프로덕션 배포. 테스트 → 빌드 → 배포 순서로 실행.
disable-model-invocation: true
---

name
소문자, 숫자, 하이픈만 사용 가능하며 최대 64자이다.
description
최대 1024자로, Claude가 이 스킬을 언제 사용할지 판단하는 기준이 되므로 구체적으로 작성해야 한다.
disable-model-invocation: true
Claude가 자동으로 이 스킬을 로드하지 못하게 한다. 사용자가 /deploy처럼 직접 호출해야만 실행된다. 배포, 커밋, Slack 메시지 전송처럼 부작용이 있는 작업에 반드시 설정하자.

보조 파일 활용하기

Skills의 강력한 장점 중 하나는 SKILL.md와 함께 스크립트, 레퍼런스 문서를 같은 디렉토리에 묶을 수 있다는 것이다. 따라서 복잡한 워크플로우도 하나의 스킬 패키지로 관리된다.

.claude/skills/visualize-codebase/

├── SKILL.md # 스킬 정의

├── scripts/

│ └── generate-map.py # 코드베이스 시각화 스크립트

└── reference.md # 추가 참고 문서

[ MCP (Model Context Protocol) - 외부 서비스 연동 ]

코딩하다 보면 코드만 만지는 게 아니다. 협업 프로젝트를 진행하면서 Jira에서 티켓을 확인하고, GitHub에서 이슈를 읽고, Slack에 진행 상황을 공유하고, 데이터베이스를 조회한다. 이런 작업을 하려고 매번 브라우저와 터미널을 왔다 갔다 하고 있다면, MCP가 그 컨텍스트 스위칭을 없애준다.

MCP(Model Context Protocol)은 Claude Code를 외부 서비스와 연결하는 프로토콜이다. 한번 설정해두면 Claude Code 안에서 "GitHub 이슈 #42 내용 확인해줘"라고 말하는 것만으로 이슈 내용을 가져올 수 있고, 구현 후 "PR 올려줘"까지 한 세션 안에서 끝난다.

MCP 서버 추가하기

해당 외부 도구의 MCP 공식문서를 참고하는 것이 가장 좋다. CLI로 간단히 추가할 수 있다.

# GitHub 연동
claude mcp add github --transport stdio -- npx -y @modelcontextprotocol/server-github

설정 파일 직접 편집하기

CLI 대신 설정 파일을 직접 수정하면 더 세밀한 제어가 가능하다. MCP 설정은 프로젝트 범위와 글로벌 범위를 구분해서 넣을 수 있다.

글로벌(모든 프로젝트): ~/.claude.json
팀 공유(프로젝트): 프로젝트 루트/.mcp.json

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

MCP를 활용하면 "GitHub 이슈 읽고 → 구현하고 → PR 생성"과 같은 완전 자동화 워크플로우가 가능해진다.

MCP 상태 확인

세션 중 /mcp 명령어로 연결된 서버들의 상태를 확인할 수 있다.

[ Hooks ]

Claude가 파일을 수정할 때마다 Prettier를 돌려야 하고, 셸 명령어를 실행하기 전에 위험한 명령은 아닌지 확인해야 하고, 테스트 파일이 바뀌면 자동으로 테스트를 돌려야 한다. 이런 걸 매번 "린트 돌려줘", "그거 실행하기 전에 확인해봐"라고 말로 지시하고 있거나 Claude에 작업을 시켜놓고 다른 업무를 하다가 한참 뒤에야 진작 끝난 걸 알아차린 경험이 있을 것이다.

Hooks는 이 문제를 근본적으로 해결한다. Claude의 특정 행동 시점에 셸 스크립트를 자동으로 실행하는 기능으로, Claude가 까먹든 말든 상관없이 확정적으로 동작한다.

글로벌(모든 프로젝트): ~/.claude/settings.json
팀 공유(프로젝트): .claude/settings.json
개인(로컬 프로젝트): .claude/settings.local.json

가장 대표적으로 사용하는 훅에 대해서 2가지 예시를 들어본다

코드 자동 포맷팅 Hook (PreToolUse)

Claude가 Write나 Edit 도구로 파일을 수정하면 자동으로 Prettier를 실행하도록 설정한다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}

커스텀 알림 Hook (Notification)

Claude Code가 사용자의 권한 승인을 기다리거나 60초 이상 입력 대기 중일 때 데스크톱 알림을 받을 수 있다.

sound name "default" 추가하면 이제 알림 뜰 때 소리도 같이 난다.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"입력을 기다리고 있습니다\" with title \"Claude Code\"'"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"입력을 기다리고 있습니다\" with title \"Claude Code\" sound name \"default\"'"
          }
        ]
      }
    ]
  }
}

Hook 이벤트 종류

이벤트발생	시점	용도
PreToolUse	도구 실행 직전	위험한 명령 차단, 입력 수정
PostToolUse	도구 실행 직후	린터/포매터 자동 실행
UserPromptSubmit	프롬프트 제출 시	동적 컨텍스트 주입
Stop	Claude 응답 완료 시	완료 알림, 품질 검증
SubagentStop	서브에이전트 완료 시	서브에이전트 결과 검증
SessionStart	세션 시작 시	환경 변수 로드, 초기 컨텍스트 설정
PreCompact	컴팩션 실행 전	트랜스크립트 백업
Notification	알림 발생 시	Slack/외부 서비스 알림 전송

[ 서브에이전트 (Subagents) ]

Claude와 긴 대화를 하다 보면 컨텍스트 윈도우가 점점 차오른다. 이 상태에서 "이 파일도 분석해줘", "저 로그도 확인해봐"라고 추가 작업을 시키면, 기존에 쌓인 맥락과 섞어있어 성능이 떨어진다. 또한 코드 리뷰, 보안 점검, 성능 테스트 같은 작업을 동시에 진행하고 싶은데, 하나의 대화창에서 순차적으로 처리하면 시간이 너무 오래 걸린다.

서브에이전트는 이런 상황을 위한 기능이다. 무거운 작업이나 독립적인 분석을 별도의 에이전트에게 위임하면, 그 에이전트는 자기만의 깨끗한 컨텍스트에서 작업을 수행하고 결과 요약만 돌려준다. 메인 대화의 컨텍스트는 오염되지 않는다.

서브에이전트 만들기

글로벌(모든 프로젝트): ~/.claude/agents/
팀 공유(프로젝트): .claude/agents/

서브에이전트는 해당 디렉토리에 마크다운 파일로 정의한다. 이 파일의 마크다운 본문이 서브에이전트의 사용자 프롬프트가 아니라 시스템 프롬프트가 된다는 점이 중요하다.

~/.claude/agents/code-reviewer.md

---
name: code-reviewer
description: 코드 품질, 보안, 성능을 종합 리뷰. 코드 변경 직후 즉시 사용.
tools: Read, Grep, Glob, Bash
model: inherit
---

당신은 시니어 코드 리뷰어입니다.

호출되면:
1. git diff로 최근 변경사항 확인
2. 수정된 파일에 집중
3. 즉시 리뷰 시작

리뷰 체크리스트:
- 코드 가독성과 간결성
- 에러 핸들링 누락
- 보안 취약점 (인젝션, XSS, 인증 우회)
- 성능 이슈 (N+1 쿼리, 불필요한 루프)
- 테스트 커버리지

이슈를 심각도별로 정리하세요:
- Critical (반드시 수정)
- Warning (수정 권장)
- Suggestion (개선 고려)

서브에이전트 호출하기

스킬 사용처럼 Claude가 description을 보고 자동으로 위임하거나, 사용자가 명시적으로 지정할 수 있다.

빌트인 서브에이전트

Claude Code에는 이미 내장된 서브에이전트가 있다.

General-purpose: Sonnet 모델을 사용하는 범용 에이전트. 탐색과 수정 모두 가능하며, 여러 단계의 복잡한 작업에 자동으로 위임된다.
Explore: Haiku 모델을 사용하는 빠르고 가벼운 읽기 전용 에이전트. 코드베이스를 탐색하고 검색할 때 자동으로 사용된다. 탐색 결과가 메인 컨텍스트를 오염시키지 않는다.
Plan: 플랜 모드에서 코드베이스를 조사하고 계획을 세우는 연구 에이전트.

/agents 커맨드와 관리

/agents를 입력하면 사용 가능한 모든 서브에이전트(빌트인, 사용자, 프로젝트)를 확인하고, 대화형 인터페이스로 새 에이전트를 생성·편집·삭제할 수 있다.

[ 권한 관리 ]

Claude Code가 편리한 만큼, "이 도구가 내 코드베이스에서 마음대로 뭘 해도 괜찮은 걸까?"라는 불안감도 함께 따라온다. .env 파일을 읽어버리면? rm -rf를 실행하면? 외부 서버에 curl로 뭔가를 보내면?

어떤 명령어는 자동 실행을 허용하고, 어떤 건 매번 확인을 받고, 어떤 건 아예 차단할 수 있게 설정 파일에 권한 체계를 넣으면 된다.

.claude/settings.json

allow: 자동 실행 허용
ask: 실행 전 사용자에게 확인
deny: 완전 차단

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(npm install *)"
    ],
    "deny": [
      "Read(./.env*)",
      "Read(./secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(curl:*)"
    ]
  }
}

참고 문헌

Skills	https://code.claude.com/docs/en/skills
MCP	https://code.claude.com/docs/en/mcp
Hooks 가이드	https://code.claude.com/docs/en/hooks-guide
Hooks 레퍼런스	https://code.claude.com/docs/en/hooks
Subagents	https://code.claude.com/docs/en/sub-agents
Settings (권한 관리)	https://code.claude.com/docs/en/settings

'AI' 카테고리의 다른 글

[AI] 2026년 AI 필수 용어 15가지 - LLM, RAG, 하네스 엔지니어링 (2)	2026.04.04
[Claude] 2026년 Claude(클로드) 모델 비교 - Opus, Sonnet, Haiku 특징 정리 (2)	2026.03.19
[Claude] Claude Code Remote Control - 폰에서 클로드 코드(Claude Code) 실행하기 (0)	2026.02.26
[Claude] Claude Code(클로드 코드)와 Notion(노션) MCP 간단 연동 가이드 (3)	2026.02.13
[Claude] Claude Code(클로드 코드) 설치 및 기본 사용법 (0)	2026.02.13

현재글[Claude] Claude Code(클로드 코드) 고급 사용법 - Skills, MCP, Hooks, Subagents

Leevigong World