Claude Code 핵심 기능: CLAUDE.md, 슬래시 명령, 훅, 서브에이전트, MCP

한눈에 요약

Claude Code의 세션은 매번 새 컨텍스트로 시작해요. 프로젝트 규칙은 CLAUDE.md에 적어 두면 이어져요.
슬래시 명령은 세션 안에서 쓰는 제어판이고, 훅은 “항상 실행돼야 하는 일”을 셸 명령으로 고정해요.
서브에이전트는 자기 컨텍스트와 도구 권한을 가진 보조 에이전트, MCP는 외부 도구·데이터를 붙이는 표준이에요.
권한 모드와 계획 모드로 Claude가 얼마나 마음대로 움직일지 정해요. 복잡한 작업은 계획 모드로 시작하세요.
CLAUDE.md는 “강제 설정”이 아니라 컨텍스트예요. 반드시 막아야 하는 건 훅(PreToolUse)으로 해요.

이 튜토리얼로 할 수 있게 되는 것

/init으로 프로젝트용 CLAUDE.md를 만들고 200줄 미만으로 다듬을 수 있어요.
파일을 고칠 때마다 자동으로 포맷하는 훅을 .claude/settings.json에 설정할 수 있어요.
읽기 전용 코드 리뷰어 같은 서브에이전트를 직접 정의할 수 있어요.
MCP 서버를 연결하고, 권한 모드와 계획 모드로 작업의 안전 수준을 조절할 수 있어요.

먼저 알아둘 개념

여덟 가지 기능은 역할이 달라요. 언제 무엇을 쓸지부터 잡고 들어가면 헷갈리지 않아요.

기능	한 줄 설명	이럴 때 써요
CLAUDE.md	세션마다 읽히는 프로젝트 지침 파일	빌드·테스트 명령, 코딩 규칙을 매번 다시 설명하기 싫을 때
슬래시 명령	세션 안에서 `/`로 시작하는 명령	모델 전환, 컨텍스트 정리, 설정 확인
훅(Hooks)	수명주기 특정 시점에 자동 실행되는 셸 명령	“저장 후 항상 포맷”, “이 파일은 절대 수정 금지”처럼 예외 없이 지켜야 할 때
서브에이전트	별도 컨텍스트에서 일하고 요약만 돌려주는 보조 에이전트	로그 분석·코드 탐색처럼 출력이 길어 메인 대화를 어지럽힐 때
MCP	외부 도구·데이터를 연결하는 개방형 표준	Notion 같은 외부 서비스를 Claude Code에서 쓰고 싶을 때
권한 모드	승인 없이 할 수 있는 일의 범위	편집을 자동 승인하거나, 반대로 읽기만 허용할 때
계획 모드	읽기만 하며 계획을 먼저 제안하는 모드	큰 변경 전에 방향부터 검토할 때
스킬	필요할 때 불러 쓰는 지침 묶음(`SKILL.md`)	반복되는 작업 절차를 재사용하고 싶을 때

단계별 따라하기

0/6 완료

/init으로 CLAUDE.md를 만들고 200줄 미만으로 다듬었어요
계획 모드로 작업 계획을 먼저 받아 봤어요
서브에이전트 정의 파일을 만들었어요
자동 포맷 훅을 설정하고 /hooks로 확인했어요
MCP 서버를 하나 연결하고 /mcp로 상태를 봤어요
(선택) 스킬을 하나 만들어 봤어요

CLAUDE.md 만들기

프로젝트 폴더에서 claude를 실행하고 /init을 입력해요. Claude가 코드베이스를 분석해 시작용 CLAUDE.md를 만들어 줘요. 이미 있다면 개선안을 제안해요.
터미널 창
```
cd my-project
claude
```
```
/init
```
이 단계에서 보게 될 화면
/init 실행 후 생성된 CLAUDE.md
공식 도움말에서 이 화면 보기 ↗
실제 화면은 서비스 업데이트에 따라 다를 수 있어요

파일은 200줄 미만으로 유지하는 것을 권장해요. 내용은 이런 식으로 짧고 구체적으로 적어요. (아래는 예시예요.)
```
# 프로젝트 지침

## 명령어
- 개발 서버: `npm run dev`
- 테스트: `npm test`

## 규칙
- 문서는 한국어 존댓말로 쓴다.
- 새 파일을 만들기 전에 기존 파일을 먼저 확인한다.
```
다른 파일을 가져오려면 @path/to/file 구문을, 경로별 규칙은 .claude/rules/를 쓰세요.
계획 모드로 시작하기

복잡한 작업은 코드를 고치기 전에 계획부터 받아 보세요. 계획 모드는 읽기만 하면서 탐색한 뒤 계획을 제안하고, 승인하기 전에는 편집을 막아요. 세 가지 방법으로 켤 수 있어요.
터미널 창
```
claude --permission-mode plan   # 시작할 때
```
세션 중에는 /plan을 입력하거나 Shift+Tab으로 모드를 전환해요.

이 프롬프트를 복사해서 붙여넣으세요
로그인 화면에 “비밀번호 보기” 토글을 추가하고 싶어요. 코드를 고치기 전에 관련 파일을 읽고, 바꿀 파일과 순서를 계획으로 먼저 보여 주세요.

계획을 검토하고 승인한 뒤에 구현으로 넘어가요.
서브에이전트 만들기

.claude/agents/code-reviewer.md 파일을 만들어요. Markdown 본문이 서브에이전트의 시스템 프롬프트가 되고, 필수 필드는 name과 description뿐이에요. 아래는 공식 문서의 예시예요.
```
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
```
tools를 읽기 전용 도구로 제한했기 때문에 리뷰어가 파일을 고칠 수 없어요. 보통은 Claude에게 만들어 달라고 요청하거나 이렇게 파일을 직접 쓰면 돼요.

공식 명령 문서 기준으로 /agents는 현재 안내 문구만 출력해요(v2.1.197 이하는 대화형 마법사였어요). 버전에 따라 동작이 다를 수 있어요.
자동 포맷 훅 설정하기

프로젝트 루트의 .claude/settings.json에 아래를 추가해요. Claude가 Edit 또는 Write 도구를 쓴 뒤마다 편집된 파일에 Prettier를 실행해요. 공식 훅 가이드의 예시이고, jq가 필요해요.
```
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}
```
세션에서 /hooks를 입력하면 등록된 훅을 볼 수 있어요. 훅이 성공해도 대화창에는 아무것도 표시되지 않아서, 파일이 실제로 포맷됐는지로 확인해요.

이 단계에서 보게 될 화면
/hooks로 확인한 PostToolUse 훅
공식 도움말에서 이 화면 보기 ↗
실제 화면은 서비스 업데이트에 따라 다를 수 있어요

무언가를 막고 싶다면 PreToolUse 훅 스크립트가 이유를 stderr로 출력하고 exit 2로 끝나게 하면 돼요. exit 2는 동작을 차단하고, 이유는 이벤트에 따라 Claude에게 피드백으로 전달돼요.
MCP 서버 연결하기

터미널에서 서버를 추가해요.
터미널 창
```
claude mcp add --transport http notion https://mcp.notion.com/mcp
```
세션에서 /mcp를 입력하면 연결 상태를 확인하고 OAuth 인증을 진행할 수 있어요. 안내에 따라 브라우저에서 인증하세요. 로컬 프로그램을 쓰는 stdio 방식은 이렇게 추가해요.
터미널 창
```
claude mcp add --transport stdio airtable --env KEY=... -- npx -y airtable-mcp-server
```
MCP 서버가 가져오는 내용에는 프롬프트 인젝션 위험이 있어요. 출처가 확실한 서버만 연결하세요.

스킬 만들기 (선택)

커스텀 명령은 스킬로 통합됐어요. .claude/skills/deploy/SKILL.md를 만들면 /deploy가 생겨요. 공식 문서의 description만 있는 최소 예시는 이래요.

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

name은 폴더 이름이 기본값이고 모든 필드가 선택이지만, Claude가 언제 쓸지 알 수 있도록 description은 쓰길 권해요.

빠른 참조표

CLAUDE.md 위치

범위	위치
관리자 정책	macOS `/Library/Application Support/ClaudeCode/CLAUDE.md`, Linux `/etc/claude-code/CLAUDE.md`
사용자(모든 프로젝트)	`~/.claude/CLAUDE.md`
프로젝트(팀 공유)	`./CLAUDE.md` 또는 `./.claude/CLAUDE.md`
개인 프로젝트용	`./CLAUDE.local.md` (`.gitignore`에 넣기를 권장)

상위 디렉터리의 파일은 시작할 때 로드되고, 하위 디렉터리의 파일은 그 폴더의 파일을 읽을 때 로드돼요. 서로 덮어쓰지 않고 이어붙여져요. 이 밖에 Claude가 스스로 쓰는 auto memory가 있어요. 로컬 세션에서 기본으로 켜져 있고, 시작할 때 첫 200줄 또는 25KB를 읽어요. /memory에서 켜고 끌 수 있어요.

자주 쓰는 슬래시 명령

명령	용도
`/init`	CLAUDE.md 생성
`/model`	모델 전환
`/clear`	새 대화 시작
`/compact [지시]`	대화를 요약해 컨텍스트 확보
`/context`	컨텍스트 사용량 확인
`/memory`	메모리 파일·auto memory 관리
`/agents`, `/mcp`, `/hooks`, `/skills`	서브에이전트·MCP·훅·스킬 확인
`/permissions`, `/config`	권한과 설정
`/plan`	계획 모드
`/resume`, `/rewind`	이전 세션 재개, 체크포인트로 되돌리기
`/usage` (= `/cost`)	사용량 확인
`/review` (= `/code-review`), `/security-review`	코드·보안 리뷰. `/code-review --max-findings 10`처럼 보고할 지적 개수를 정하고(`all`이면 전부), 고른 값은 `--max-findings default`를 줄 때까지 유지돼요(v2.1.288 이상)
`/teleport`, `/web-setup`, `/schedule`	클라우드 세션 관련 (C13)

전체 목록은 공식 Commands 문서에서 확인하세요.

권한 모드

모드	동작
`default` (Manual)	읽기만 자동 승인
`acceptEdits`	파일 편집과 기본 파일 명령 자동 승인
`plan`	읽기만. 탐색 후 계획을 제안하고 승인 전 편집 차단
`auto`	별도 모델(분류기)이 승인 대신 안전 검사. Anthropic API 직접 연결 등에서는 서버 측 분류기가 기본이에요(아래 설명)
`dontAsk`	미리 승인한 도구만 사용 (CI용)
`bypassPermissions`	격리된 컨테이너·VM 전용

전환은 CLI에서 Shift+Tab, 시작할 때 claude --permission-mode <모드>, 세션 중 /plan이에요. deny 규칙은 bypassPermissions를 포함한 모든 모드에서 차단하고, .env 같은 보호 경로는 auto 모드에서도 자동 승인되지 않아요.

auto 모드 알아 두기 (2026-10-11 기준, 공식 permission-modes 문서와 변경 이력 기준)

시작 조건: v2.1.283 이상에서는 터미널과 VS Code 세션이 모드를 따로 정하지 않으면 auto로 시작해요. --permission-mode나 permissions.defaultMode가 우선하고, 조직이 disableAutoMode로 끄면 Manual로 시작해요. 모델이 auto를 지원하지 않는 경우에도 Manual로 시작해요.
분류기: 직접 Anthropic API 연결에서는 서버가 검사하는 방식이 기본이고, 서버가 검사하지 않는 환경(게이트웨이가 요청을 막는 경우 등)에서는 Claude Code가 자체 분류기 요청으로 대신해요. CLAUDE_CODE_AUTO_MODE_SERVER=0이면 항상 자체 분류기를 써요. 이 경우 분류기 호출이 토큰 사용량에 잡힐 수 있어요.
규칙 보기: /permissions의 Auto mode 탭에서 분류기 규칙을 보고 고칠 수 있어요(v2.1.246 이상). 막힌 동작은 Recently denied 탭에서 r로 수동 승인 재시도를 할 수 있어요.

훅 요약

항목	내용
설정 위치	`~/.claude/settings.json`, `.claude/settings.json`의 `hooks` 블록
이벤트 예	`Notification`, `PreToolUse`, `PostToolUse`, `SessionStart`
matcher	`Edit\|Write`처럼 도구 이름으로 범위를 좁혀요
차단	exit code 2 (사유는 stderr로 출력)
훅 자체가 실패할 때	기본값은 `"onFailure": "continue"`라서 훅이 시작 못 하거나 시간 초과여도 동작이 그냥 진행돼요. 정책 훅이라면 `command`·`http` 훅에 `"onFailure": "block"`을 넣어 실패 시 막으세요(v2.1.295 이상).
확인	`/hooks`

서브에이전트 요약

항목	내용
정의 파일	Markdown + YAML frontmatter. 필수는 `name`, `description`
위치 우선순위	관리 설정 > `--agents` 플래그 > `.claude/agents/` > `~/.claude/agents/` > 플러그인
`model` 값	`sonnet`, `opus`, `haiku`, `fable`, 전체 모델 ID, `inherit`
그 밖의 필드	`effort`, `tools`, `permissionMode`, `memory`, `isolation: worktree` 등
자동 압축	frontmatter와 `--agents`의 `autoCompactWindow`로 서브에이전트가 메인 대화보다 일찍 자동 압축하게 할 수 있어요(v2.1.296 이상)
호출 때 effort	정의의 `effort`와 별개로 Claude가 Agent 도구의 `effort` 매개변수로 이번 호출만 effort를 정할 수 있어요(v2.1.292 이상). `CLAUDE_CODE_EFFORT_LEVEL` 환경변수가 둘보다 우선해요.
내장	Explore(읽기 전용 탐색), Plan, General-purpose, claude(만능 에이전트), statusline-setup, claude-code-guide

플러그인 설치와 평가

명령	용도
`claude plugin install <플러그인> --marketplace <소스>`	마켓플레이스를 아직 추가하지 않았다면 먼저 추가한 뒤 설치해요(v2.1.292 이상). 세션 안에서는 `/plugin install <플러그인> --marketplace <소스>`(v2.1.275 이상)이고, 추가 전에 확인을 물어요.
`claude plugin eval`	플러그인의 eval 케이스를 돌려 점수가 매겨진 결과를 줘요(v2.1.269 이상). 기본은 읽기 전용 도구만 허용하고, `--allow-tools`로 늘려요. `claude plugin eval init`으로 eval 묶음을 만들어요.

MCP 범위

범위	저장 위치	쓰임
local (기본)	`~/.claude.json`	나만, 이 프로젝트에서
project	`.mcp.json`	팀과 공유
user	사용자 설정	내 모든 프로젝트

claude.ai 계정으로 로그인하면 claude.ai/customize/connectors의 커넥터가 /mcp에 자동으로 보여요(Team/Enterprise는 관리자만 추가해요). SSE 방식은 deprecated예요.

자주 막히는 지점

CLAUDE.md에 적은 규칙을 Claude가 가끔 어겨요

원인: CLAUDE.md는 강제 설정이 아니라 컨텍스트로 쓰여요. 파일이 길거나 규칙이 모호하면 더 잘 놓쳐요.
해결: 200줄 미만으로 줄이고 구체적으로 쓰세요. 절대 어기면 안 되는 규칙은 PreToolUse 훅이나 deny 규칙으로 막으세요.

훅을 넣었는데 아무 일도 안 일어나요

원인: matcher가 맞지 않거나, jq·npx가 설치되지 않았거나, JSON 문법이 틀렸을 수 있어요. 성공한 훅은 대화창에 아무것도 보이지 않아요.
해결: /hooks에 훅이 보이는지 확인하고, 파일이 실제로 바뀌었는지 보세요. 도구 이름은 Edit|Write처럼 정확히 쓰세요. Claude가 Bash 명령으로 파일을 바꾸는 경우는 Edit|Write matcher에 잡히지 않아요.

`/agents`를 눌렀는데 마법사가 안 떠요

원인: 현재 버전의 /agents는 안내 문구만 출력해요(v2.1.197 이하는 대화형 마법사).
해결: Claude에게 서브에이전트를 만들어 달라고 요청하거나 .claude/agents/에 파일을 직접 쓰세요.

MCP 서버를 추가했는데 쓸 수 없어요

원인: OAuth 인증이 필요한 서버는 인증을 마쳐야 쓸 수 있어요.
해결: /mcp에서 상태를 확인하고 안내에 따라 브라우저에서 인증을 마치세요.

계획 모드인데 파일이 안 바뀌어요

원인: 정상이에요. 계획 모드는 승인 전 편집을 막아요.
해결: 계획을 검토하고 승인한 뒤 구현으로 넘어가세요. Shift+Tab으로 다른 모드로 바꿀 수도 있어요.

실전 팁

CLAUDE.md는 작게 시작하세요. /init 결과에서 빌드·테스트 명령과 꼭 필요한 규칙만 남기고, 실제로 Claude가 틀린 부분이 생길 때마다 한 줄씩 추가하세요.
“항상”이면 훅, “대체로”면 CLAUDE.md. 판단이 필요하면 프롬프트 기반이나 에이전트 기반 훅도 있어요.
긴 출력은 서브에이전트에 맡기세요. 서브에이전트는 요약만 돌려줘서 메인 대화의 컨텍스트를 아껴요. 서브에이전트에 어떤 모델을 쓸지는 C15. 모델 분담 전략에서 다뤄요.
큰 변경은 계획 모드부터. 방향이 틀렸을 때 비용이 가장 적게 드는 시점이에요.
bypassPermissions는 격리된 환경에서만. 내 컴퓨터의 일반 작업에는 쓰지 마세요.
MCP는 필요한 것만. 연결할수록 관리할 것이 늘고 인젝션 위험도 늘어요.
훅 이벤트 전체 목록과 JSON 스키마는 이 글에서 일부만 다뤘어요. 공식 hooks 레퍼런스를 확인하세요.

다음에 볼 튜토리얼

C12. Claude Code 개요: 터미널·데스크톱·웹 — 설치와 첫 작업
C13. 클라우드 세션 — 내 컴퓨터 없이 클라우드에서 실행하기
C15. 모델 분담 전략 — 서브에이전트에 모델을 나눠 주는 방법
C8. 스킬 — 스킬을 더 깊이
Claude Agent SDK로 나만의 에이전트 만들기 — 코드로 에이전트 만들기
MCP 서버 직접 만들어 Claude에 연결하기 — MCP 서버를 직접 만드는 법
스킬·플러그인 패키지로 만들어 팀에 배포하기 — 플러그인으로 묶어 배포하기

출처

마지막 확인일: 2026년 10월 12일

How Claude remembers your project (CLAUDE.md, auto memory) code.claude.com
Commands code.claude.com
Hooks guide code.claude.com
Custom subagents code.claude.com
Connect Claude Code to tools via MCP code.claude.com
Permission modes code.claude.com
Skills code.claude.com
CLI reference code.claude.com
Plugin commands reference code.claude.com
Claude Code CHANGELOG (v2.1.246, 2.1.288, 2.1.292, 2.1.295, 2.1.296) raw.githubusercontent.com

가격·한도·메뉴 이름은 자주 바뀌어요. 중요한 결정 전에는 위 공식 페이지에서 최신 내용을 다시 확인하세요.