Claude Code 완벽 가이드

Part 1: 기초편

Claude Code를 처음 사용한다면 이 파트부터 시작합니다. 설치, CLI 명령어, 슬래시 명령어, 단축키, 입력 모드까지 기본 사용법을 다룹니다.

설치 & 인증

Claude Code는 네이티브 인스톨러로 설치합니다. Windows에서는 PowerShell에서, WSL 환경에서는 bash에서 단일 명령어로 설치가 완료됩니다. 설치 후 claude auth login 으로 인증을 완료하면 바로 사용할 수 있습니다.

사전 요구사항

Git for Windows (Windows 환경 필수)
Claude Pro, Max, Team, Enterprise 또는 Console 계정

0/2 완료

설치 절차

Git for Windows 설치

Claude Code는 내부적으로 Git Bash를 사용합니다. 아직 설치하지 않았다면 Git for Windows를 먼저 설치합니다.

# https://git-scm.com/downloads/win 에서 다운로드 후 설치

네이티브 설치

PowerShell을 열고 아래 명령어를 실행합니다. 관리자 권한은 필요 없습니다. WinGet을 사용해도 됩니다.

# PowerShell (권장)
irm https://claude.ai/install.ps1 | iex

# 또는 WinGet
winget install Anthropic.ClaudeCode

인증

설치가 끝나면 터미널을 새로 열고 claude를 실행합니다. 브라우저가 열리면서 자동으로 인증 절차가 진행됩니다. API 과금 방식을 사용하려면 --console 플래그를 추가합니다.

# 터미널에서 claude 실행 → 브라우저 인증
claude

# API 키 인증 (콘솔에서 직접 입력)
claude auth login --console

설치 확인

버전과 인증 상태를 확인합니다.

claude --version
claude auth status

인증 명령어 요약

claude auth login	Claude 구독으로 로그인
claude auth login --console	API 키 입력 방식으로 로그인 (API 과금)
claude auth status	현재 인증 상태 확인
claude auth logout	로그아웃
claude update	최신 버전으로 업데이트

인증 관련 명령어

💡인증 방식 선택

개인 Claude 구독(Pro/Max 플랜)이 있다면 claude를 처음 실행할 때 브라우저에서 자동 인증됩니다. 팀·CI 환경처럼 API 키로 과금해야 하는 경우에는 claude auth login --console 명령어로 터미널에서 직접 키를 입력할 수 있습니다. 네이티브 설치는 백그라운드에서 자동 업데이트됩니다. WinGet으로 설치한 경우 winget upgrade Anthropic.ClaudeCode로 수동 업데이트가 필요합니다.

CLI 명령어

Claude Code의 CLI는 터미널에서 claude를 입력하면 인터랙티브 세션에 진입합니다. 세션 안에서 프롬프트를 입력하며 대화하는 것이 기본 사용 방식입니다. 아래 표에서 자주 쓰는 명령어와 그 역할을 확인할 수 있습니다.

claude	대화형 세션 시작
claude "query"	초기 프롬프트를 지정하여 세션 시작
claude -p "query"	비대화형 모드 — 응답 출력 후 즉시 종료 (SDK·스크립트·CI용)
cat file \| claude -p "query"	파이프로 전달된 내용을 프롬프트와 함께 처리
claude -c	가장 최근 대화 이어서 계속
claude -c -p "query"	가장 최근 대화를 SDK 방식으로 이어서 계속
claude -r "session" "query"	세션 ID 또는 이름으로 특정 대화 재개
claude update	최신 버전으로 업데이트
claude auth login	로그인
claude auth status	인증 상태 확인
claude agents	설정된 서브에이전트 목록 출력
claude mcp	MCP 서버 설정
claude plugin	플러그인 관리
claude remote-control	원격 제어 서버 시작
claude auto-mode defaults	자동 모드 분류 규칙 출력

Claude Code 핵심 명령어

Terminal

$ claude

╭──────────────────────────────────────╮
│ Claude Code                        │
│ /help for available commands        │
╰──────────────────────────────────────╯

> 이 프로젝트의 폴더 구조를 설명해줘

프로젝트 구조를 분석하겠습니다...

src/
├── components/   # React 컴포넌트
├── utils/        # 유틸리티 함수
└── index.ts      # 진입점

>

CLI 플래그

플래그는 명령어 실행 시 동작을 세밀하게 조정하는 데 사용됩니다. 세션 관리, 모델 선택, 출력 형식, 권한 제어 등 역할에 따라 아래 소절로 나누어 정리했습니다. 자주 쓰는 플래그는 ~/.claude/settings.json 에 기본값으로 저장해 두면 반복 입력을 줄일 수 있습니다.

세션 설정

--continue / -c	가장 최근 대화를 이어서 계속
--resume / -r <id>	세션 ID 또는 이름으로 특정 대화 재개
--fork-session	현재 세션을 포크하여 독립된 새 세션 생성
--from-pr <pr>	특정 GitHub PR에 연결된 세션을 재개. PR 번호 또는 URL 입력
--name / -n <name>	세션에 이름 지정
--session-id <id>	특정 세션 ID 사용
--worktree / -w <name>	격리된 git worktree에서 Claude Code 시작. 병렬 작업에 유용
--add-dir <path>	세션에 추가 디렉터리 포함

세션 관련 플래그

모델 & 성능

--model <name>	사용할 모델 지정. sonnet, opus 또는 전체 모델 ID 입력
--effort <level>	추론 노력 수준 설정: low / medium / high / max (Opus 전용)
--fallback-model <name>	주 모델 요청 실패 시 대체 모델 지정
--max-turns <n>	자동 모드에서 최대 턴 수 제한
--max-budget-usd <n>	세션당 최대 API 예산(USD) 설정

모델 및 성능 관련 플래그

ℹ️--effort 플래그

--effort 플래그는 Claude Opus 모델에서만 동작합니다. 복잡한 추론이 필요한 작업에는 high 또는 max를 설정하고, 빠른 응답이 중요한 경우에는 low를 사용합니다.

시스템 프롬프트

--system-prompt <text>	시스템 프롬프트를 직접 텍스트로 지정
--system-prompt-file <path>	시스템 프롬프트를 파일에서 읽어 지정
--append-system-prompt <text>	기존 시스템 프롬프트 끝에 텍스트 추가
--append-system-prompt-file <path>	기존 시스템 프롬프트 끝에 파일 내용 추가

시스템 프롬프트 관련 플래그

입출력

--print / -p	응답 출력 후 즉시 종료 (비대화형 프린트 모드)
--output-format <fmt>	출력 형식 지정: text / json / stream-json
--input-format <fmt>	입력 형식 지정
--json-schema <schema>	JSON 출력 스키마 지정
--verbose	상세 로그 출력
--debug	디버그 정보 출력
--no-session-persistence	세션 저장 비활성화
--include-partial-messages	스트리밍 중 부분 메시지도 포함하여 출력

입출력 관련 플래그

JSON 출력스트리밍 JSON

bash

claude -p "현재 디렉터리의 파일 목록" --output-format json

bash

claude -p "코드 리뷰" --output-format stream-json --include-partial-messages

권한 & 도구

--permission-mode <mode>	권한 모드 설정: default / acceptEdits / plan / auto / dontAsk / bypassPermissions
--allowedTools <tools>	허용할 도구 목록 지정
--disallowedTools <tools>	차단할 도구 목록 지정
--tools <tools>	사용 가능한 도구 집합 지정
--dangerously-skip-permissions	권한 확인 건너뜀 (위험, 신뢰된 자동화 환경 전용)
--allow-dangerously-skip-permissions	위 플래그 사용을 명시적으로 허용
--enable-auto-mode	자동 모드 활성화

권한 및 도구 관련 플래그

⚠️--dangerously-skip-permissions 주의

이 플래그는 모든 권한 확인을 건너뜁니다. 격리된 CI 환경이나 신뢰된 자동화 파이프라인에서만 사용합니다. 일반 개발 환경에서 사용하면 의도치 않은 파일 수정이나 명령 실행이 발생할 수 있습니다.

MCP & 플러그인

--mcp-config <path>	MCP 서버 설정 파일 경로 지정
--strict-mcp-config	설정 파일 외 MCP 서버 연결 차단
--plugin-dir <path>	플러그인 디렉터리 경로 지정
--channels <list>	연결할 채널 목록 지정
--chrome	Chrome 브라우저 도구 활성화
--no-chrome	Chrome 브라우저 도구 비활성화

MCP 및 플러그인 관련 플래그

기타

--bare	훅·플러그인을 건너뛰어 스크립트 호출 속도 향상
--init	초기화 훅을 실행하고 인터랙티브 모드 시작
--init-only	초기화만 수행하고 세션 시작하지 않음
--maintenance	유지보수 훅을 실행하고 인터랙티브 모드 시작
--remote "task"	claude.ai에 새 웹 세션을 만들어 작업 설명과 함께 시작
--remote-control / --rc	원격 제어 서버 모드로 시작
--teleport	웹 세션을 로컬 터미널로 가져와서 이어서 작업
--teammate-mode <mode>	에이전트 팀 표시 방식 설정: auto / in-process / tmux
--setting-sources	설정 소스 파일 목록 출력
--settings <path>	사용할 설정 파일 경로 지정
--ide <name>	연동할 IDE 지정
--disable-slash-commands	슬래시 명령어 비활성화
--agent <name>	실행할 에이전트 이름 지정
--agents <json>	에이전트 구성을 JSON으로 직접 전달

기타 플래그

슬래시 명령어

Claude Code 인터랙티브 세션에서 /로 시작하는 명령어를 입력하면 설정 변경, 세션 관리, 특수 기능을 빠르게 호출할 수 있습니다. /help를 입력하면 현재 설치된 커스텀 명령어를 포함한 전체 목록을 확인할 수 있습니다.

명령어	설명
/help	모든 명령어 + 커스텀 명령어 표시
/config	설정 인터랙티브 변경
/allowed-tools	도구 권한 설정
/model	모델 변경
/effort	모델 effort 레벨 설정 (low / medium / high / max)
/vim	Vim 편집 모드 활성화
/theme	테마 변경
/color	프롬프트 바 색상 설정
/clear	대화 초기화 (새 세션)
/copy	마지막 응답 복사. /copy N 으로 N번째 응답 복사
/copy w	선택 내용을 파일에 직접 쓰기
/resume	이전 세션 재개 (피커 표시)
/rename	세션 이름 변경
/plan	Plan 모드 진입. /plan [설명] 형태로도 사용 가능
/fast	Fast 모드 토글
/mcp	MCP 서버 관리
/agents	서브에이전트 생성 및 관리
/hooks	훅 설정
/context	컨텍스트 최적화 제안
/simplify	3-에이전트 코드 품질 리뷰
/batch	대규모 병렬 변경
/btw	사이드 질문 (대화 히스토리에 남지 않음)
/terminal-setup	터미널 단축키 설치 (Shift+Enter 등)
/doctor	설치 상태 점검
/compact	대화 내용을 요약하여 컨텍스트 윈도우 확보
/rewind	대화 또는 코드 변경을 이전 상태로 되돌리기
/diff	최근 코드 변경 사항 확인

키보드 단축키

Claude Code 인터랙티브 세션에서 사용할 수 있는 단축키 목록입니다. 터미널 종류와 운영체제 환경에 따라 일부 단축키의 동작이 다를 수 있습니다. 플랫폼별 차이가 있는 항목은 별도로 구분해 표시합니다.

일반 제어

단축키	동작
Ctrl+C	현재 입력 또는 생성 취소
Ctrl+D	세션 종료
Ctrl+L	터미널 화면 지우기 (대화 내용은 유지)
Ctrl+G	외부 에디터로 열기
Ctrl+X Ctrl+E	외부 에디터로 열기 (대체)
Ctrl+O	Verbose 출력 토글
Ctrl+R	명령어 히스토리 역방향 검색
Ctrl+B	실행 중인 작업을 백그라운드로 전환
Ctrl+T	태스크 리스트 토글
Ctrl+X Ctrl+K	백그라운드 에이전트 전부 종료
Esc+Esc	대화 되감기 및 요약
Shift+Tab	권한 모드 순환 (default → acceptEdits → plan → auto)

모드 전환

Windows / WSL

Alt+P: 모델 전환
Alt+T: 확장 사고 토글
Alt+O: Fast 모드 토글
Ctrl+V 또는 Alt+V: 클립보드 이미지 붙여넣기
Space (길게 누르기): 음성 입력 (Push-to-talk)

텍스트 편집

단축키	동작
Ctrl+K	커서 위치부터 줄 끝까지 삭제
Ctrl+U	전체 줄 삭제
Ctrl+Y	삭제한 텍스트 붙여넣기
Alt+Y	붙여넣기 히스토리 순환
Alt+B	한 단어 뒤로 이동
Alt+F	한 단어 앞으로 이동

멀티라인 입력

멀티라인 입력 단축키는 터미널 종류에 따라 지원 여부가 다릅니다. 아래는 터미널별 권장 방식입니다.

모든 터미널 공통Windows (PowerShell / Git Bash)WSL

\ + Enter: 백슬래시 뒤에 Enter를 입력하면 모든 터미널에서 줄바꿈이 가능합니다.
Ctrl+J: 라인 피드를 직접 삽입합니다.

Ctrl+J: 모든 Windows 터미널에서 바로 작동합니다 (라인 피드).
Shift+Enter: Windows Terminal에서는 기본 지원되지 않습니다. /terminal-setup으로 설정하거나, Ctrl+J 또는 \ + Enter를 사용합니다.

Ctrl+J: WSL 터미널에서도 바로 작동합니다.
Shift+Enter: /terminal-setup으로 설정이 필요합니다. 설정 없이 바로 쓰려면 Ctrl+J 또는 \ + Enter를 사용합니다.

입력 모드

Claude Code는 일반 텍스트 입력 외에 세 가지 특수 입력 모드를 제공합니다. 각 모드는 접두사 문자로 진입하며, 파일 참조, 쉘 명령어 실행, 히스토리에 남기지 않는 사이드 질문을 각각 담당합니다.

@ 파일 참조

@ 접두사 뒤에 파일 경로를 입력하면 해당 파일의 내용을 대화에 포함시킵니다. 글로브 패턴을 사용해 여러 파일을 한 번에 참조할 수 있습니다.

입력 예시	설명
@path/to/file	특정 파일을 대화에 포함
@src/*/.test.ts	글로브 패턴으로 여러 파일 동시 참조
@file1 @file2	여러 파일을 한 번에 참조

! Bash 모드

! 접두사를 붙이면 쉘 명령어를 Claude Code 안에서 직접 실행할 수 있습니다. 실행 결과는 대화 컨텍스트에 자동으로 추가됩니다.

동작	설명
! 접두사	쉘 명령어 직접 실행, 결과가 컨텍스트에 추가됨
Tab	이전 ! 명령어 자동완성
Escape / Backspace	Bash 모드에서 빠져나오기

/btw 사이드 질문

/btw는 대화 히스토리에 남지 않는 빠른 질문을 위한 모드입니다. Claude가 작업을 진행하는 중에도 사용할 수 있습니다.

특성	설명
히스토리	대화 히스토리에 남지 않음
사용 타이밍	Claude가 작업 중에도 사용 가능
도구 접근	불가 — 현재 컨텍스트로만 답변
닫기	Space / Enter / Escape

Vim 모드

/vim 명령어로 현재 세션에서 즉시 Vim 모드를 활성화할 수 있습니다. 영구적으로 사용하려면 /config 에서 설정을 변경합니다. 기본 Vim 키바인딩을 그대로 사용하므로 기존 Vim 사용자라면 별도 학습 없이 적용할 수 있습니다.

모드 전환

키	설명
Esc	NORMAL 모드로 전환
i	커서 앞에서 INSERT 모드 진입
I	줄 맨 앞에서 INSERT 모드 진입
a	커서 뒤에서 INSERT 모드 진입
A	줄 맨 끝에서 INSERT 모드 진입
o	아랫줄에 새 줄 추가 후 INSERT 모드 진입
O	윗줄에 새 줄 추가 후 INSERT 모드 진입

이동 (NORMAL 모드)

키	설명
h	왼쪽으로 이동
j	아래로 이동
k	위로 이동
l	오른쪽으로 이동
w	다음 단어 시작으로 이동
e	현재 단어 끝으로 이동
b	이전 단어 시작으로 이동
0	줄 맨 앞으로 이동
$	줄 맨 끝으로 이동
gg	문서 맨 처음으로 이동
G	문서 맨 끝으로 이동
f{char}	현재 줄에서 {char}가 나타나는 곳으로 앞으로 이동
F{char}	현재 줄에서 {char}가 나타나는 곳으로 뒤로 이동
t{char}	f와 동일하나 {char} 직전에 멈춤
T{char}	F와 동일하나 {char} 직후에 멈춤
;	f/F/t/T 이동 같은 방향으로 반복
,	f/F/t/T 이동 반대 방향으로 반복

편집 (NORMAL 모드)

키	설명
x	커서 위치 문자 삭제
dd	현재 줄 전체 삭제
D	커서부터 줄 끝까지 삭제
dw / de / db	단어 앞/끝/뒤로 삭제
cc	현재 줄 전체 변경 (삭제 후 INSERT 모드)
C	커서부터 줄 끝까지 변경
cw / ce / cb	단어 앞/끝/뒤로 변경
yy / Y	현재 줄 복사
yw / ye / yb	단어 앞/끝/뒤로 복사
p	커서 뒤에 붙여넣기
P	커서 앞에 붙여넣기
>>	들여쓰기 추가
<<	들여쓰기 제거
J	현재 줄과 다음 줄 합치기
.	직전 명령어 반복

텍스트 오브젝트

텍스트 오브젝트는 d(삭제), c(변경), y(복사) 등의 연산자와 함께 사용합니다. i는 내부(inner), a는 주변 공백이나 구분 문자를 포함한 범위(around)를 의미합니다.

텍스트 오브젝트	설명
iw / aw	단어 (공백 제외 / 공백 포함)
iW / aW	공백 기준 단어 (공백 제외 / 공백 포함)
i" / a"	큰따옴표 내부 / 큰따옴표 포함
i' / a'	작은따옴표 내부 / 작은따옴표 포함
i( / a(	소괄호 내부 / 소괄호 포함
i[ / a[	대괄호 내부 / 대괄호 포함
i{ / a{	중괄호 내부 / 중괄호 포함

💡

텍스트 오브젝트 예시: diw는 커서가 위치한 단어를 삭제하고, ci"는 큰따옴표 안의 내용을 변경합니다. 연산자와 오브젝트를 조합하면 정밀한 편집이 가능합니다.

Part 2: 심화편

기본 사용법에 익숙해졌다면 이 파트로 넘어갑니다. 설정, Skills, Hooks, MCP, 서브에이전트, 워크트리 등 Claude Code를 프로젝트에 맞게 커스터마이징하고 생산성을 극대화하는 방법을 다룹니다.

설정 파일

Claude Code의 설정은 계층 구조로 관리됩니다. 구체적인 설정이 일반적인 설정보다 우선하며, 프로젝트 수준 설정이 사용자 전역 설정을 덮어씁니다. 팀 공유 설정과 개인 설정을 분리하여 관리할 수 있습니다.

설정 계층

설정 파일 위치

📁~/.claude

📄settings.json (사용자 전역)

📁.claude

📄settings.json (프로젝트, git에 커밋)

📄settings.local.json (프로젝트 개인, git-ignore)

📄managed-settings.d/ (정책 조각, 알파벳 순 병합)

우선순위: settings.local.json > settings.json (프로젝트) > settings.json (사용자 전역)

주요 설정 항목

.claude/settings.json복사

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Read", "Write(src/**)", "Bash(git *)", "Bash(npm *)"],
    "deny": ["Read(.env*)", "Write(production.config.*)", "Bash(rm *)"]
  }
}

권한 설정

항목	설명
allow	자동 허용할 도구 패턴 목록
deny	차단할 도구 패턴 목록. allow보다 우선 적용됩니다.
패턴 예시	Bash(git ), Write(src/), Read(.env)

deny 패턴은 allow 패턴보다 항상 우선합니다. 같은 도구가 양쪽에 모두 일치하는 경우 차단됩니다.

CLAUDE.md

CLAUDE.md는 프로젝트별 지시사항을 담는 파일입니다. Claude Code가 세션 시작 시 자동으로 읽어 컨텍스트에 포함하며, 하위 디렉토리에도 별도로 배치할 수 있습니다.

CLAUDE.md 위치

📄~/.claude/CLAUDE.md (전역)

📄./CLAUDE.md (프로젝트 루트)

📄./src/CLAUDE.md (하위 디렉토리별)

활용 용도	예시
코딩 스타일 규칙	들여쓰기, 네이밍 컨벤션, 주석 기준
프로젝트 아키텍처	디렉토리 구조, 모듈 간 의존 관계
자주 사용하는 명령어	빌드, 테스트, 배포 스크립트
기술 스택 정보	프레임워크 버전, 주요 라이브러리

Skills (커스텀 명령어)

Skills는 마크다운 파일로 만드는 커스텀 슬래시 명령어입니다. 기존 .claude/commands/도 계속 동작하지만, Skills는 프론트매터 기반 자동 실행과 파일 관리 기능이 추가되었습니다. 프로젝트 단위로 버전 관리하며 팀 전체가 동일한 명령어를 공유할 수 있습니다.

파일 구조

Skills 디렉토리 구조

📁.claude/skills

📁my-skill

📄SKILL.md

.claude/skills/my-skill/SKILL.md복사

---
description: Brief description
argument-hint: [arg1] [arg2]
allowed-tools: Read, Bash(git:*)
model: sonnet
effort: high
---

Command prompt content here.
Arguments: $1, $2, or $ARGUMENTS
File references: @path/to/file
Bash execution: !`command here`

프론트매터 옵션

필드	설명
description	슬래시 명령어 목록에 표시되는 설명
argument-hint	명령어 입력 시 표시되는 인자 힌트
allowed-tools	이 스킬에서 허용할 도구 목록
model	사용할 모델 (sonnet, opus)
effort	effort 레벨 오버라이드

동적 인자

문법	설명
$1, $2, $3	위치 기반 인자
$ARGUMENTS	전체 인자를 하나의 문자열로 전달
@path/to/file	파일 내용을 프롬프트에 삽입
!`command`	쉘 명령어 실행 결과를 프롬프트에 삽입

.claude/skills/fix-issue/SKILL.md복사

---
description: Fix issue by number
argument-hint: [issue-number]
---

Fix issue #$ARGUMENTS following our coding standards.

Hooks

Hooks는 특정 이벤트에 자동으로 쉘 명령어를 실행하는 기능입니다. settings.json에서 설정하며, 도구 실행 전후, 세션 시작, 파일 변경 등 다양한 시점에 동작을 자동화할 수 있습니다.

이벤트 종류

이벤트	실행 시점
PreToolUse	도구 실행 전 (차단 가능)
PostToolUse	도구 실행 후
UserPromptSubmit	사용자 입력 처리 전
SessionStart	세션 시작 시
TaskCreated	태스크 생성 시
CwdChanged	작업 디렉토리 변경 시
FileChanged	파일 변경 감지 시
StopFailure	API 에러로 턴 종료 시
PostCompact	컨텍스트 압축 후
Elicitation	MCP 서버가 구조화된 입력 요청 시

설정 예시

.claude/settings.json복사

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write(*.py)",
      "hooks": [{
        "type": "command",
        "command": "python -m black \"$file\""
      }]
    }],
    "PreToolUse": [{
      "matcher": "Bash(rm *)",
      "hooks": [{
        "type": "command",
        "command": "echo 'BLOCK: rm 명령어는 허용되지 않습니다'"
      }]
    }]
  }
}

전체 보기

💡matcher 패턴 활용

matcher 패턴으로 특정 도구 또는 파일에만 훅을 적용할 수 있습니다. Write(*.py)는 Python 파일 저장 시에만, Bash(rm *)는 rm 명령어 실행 시에만 해당 훅이 동작합니다.

MCP 서버

MCP(Model Context Protocol)는 Claude Code에 외부 도구를 연결하는 표준 규격입니다. 데이터베이스, 검색 엔진, 클라우드 서비스 등 다양한 외부 시스템을 Claude가 직접 사용할 수 있게 해줍니다. 프로젝트 단위 또는 사용자 전역 범위로 등록하며, stdio·HTTP 두 가지 전송 방식을 지원합니다.

등록 & 관리

Terminal

$ claude mcp add my-server -e API_KEY=123 -- /path/to/server arg1
$ claude mcp add web-search --transport stdio -- npx open-websearch@latest
$ claude mcp add remote-server --transport http -- https://example.com/mcp
$ claude mcp list
$ claude mcp remove my-server

플래그	설명
--scope user	사용자 전역 등록 (기본값)
--scope project	프로젝트 전용 등록 (.claude/settings.json에 저장)
-e KEY=VALUE	서버 프로세스에 환경변수 전달

외부 설정 파일

--mcp-config 플래그로 JSON 파일에서 MCP 서버를 일괄 로드할 수 있습니다. 팀 단위로 서버 목록을 공유하거나, CI/CD 환경에서 동일한 설정을 재사용할 때 유용합니다.

mcp-servers.json복사

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    },
    "open-websearch": {
      "type": "stdio",
      "command": "npx",
      "args": ["open-websearch@latest"],
      "env": { "MODE": "stdio" }
    }
  }
}

서브에이전트

서브에이전트는 특정 작업에 특화된 별도의 Claude 인스턴스입니다. 메인 에이전트가 복잡한 작업을 분담시킬 때 사용하며, 각 에이전트는 독립된 컨텍스트와 도구 권한을 가집니다. 에이전트 정의 파일을 .claude/agents/ 디렉토리에 배치하면 메인 에이전트가 필요 시 자동으로 호출합니다.

설정

.claude/agents/reviewer.md복사

---
name: reviewer
description: 코드 리뷰 전문 에이전트
model: sonnet
effort: high
allowed-tools: Read, Grep, Glob
---

당신은 코드 리뷰 전문가입니다.
보안, 성능, 코드 품질에 집중해서 리뷰합니다.

프론트매터 옵션

필드	설명
name	에이전트 이름
description	설명 (메인 에이전트가 적합성 판단에 사용)
model	사용할 모델
effort	effort 레벨
allowed-tools	허용할 도구
disallowedTools	차단할 도구
maxTurns	최대 턴 수
initialPrompt	자동 실행할 첫 프롬프트

CLI에서 동적 생성

Terminal

$ claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer","model":"sonnet"}}'

워크트리

워크트리는 git worktree를 사용해서 저장소의 격리된 복사본에서 작업하는 기능입니다. 메인 브랜치를 건드리지 않고 병렬로 여러 작업을 동시에 진행할 수 있습니다. 각 워크트리는 독립된 작업 공간을 가지므로 실험적인 변경이나 긴급 수정을 안전하게 처리할 수 있습니다.

Terminal

$ claude -w feature-auth
$ claude --worktree my-feature

대규모 monorepo에서는 worktree.sparsePaths 설정으로 필요한 디렉토리만 체크아웃할 수 있습니다.

.claude/settings.json복사

{
  "worktree": {
    "sparsePaths": ["src/api", "src/shared", "package.json"]
  }
}

💡

서브에이전트가 자동으로 워크트리에서 작업하도록 설정할 수도 있습니다.

실전 활용: 기초편

설치와 명령어를 넘어서, 실제로 생산성을 높이는 패턴을 정리했습니다. 컨텍스트 관리, 모델 선택, 병렬 작업, 토큰 절약 등 장시간 세션에서 효율을 유지하는 방법입니다.

컨텍스트 관리

장시간 세션에서 가장 흔한 문제는 컨텍스트 윈도우가 채워지면서 Claude의 응답 품질이 떨어지는 현상(context rot)입니다. 자동 압축(auto compact)에 의존하면 작업 도중 임의의 시점에 압축이 일어나서 중요한 맥락이 사라질 수 있습니다. /compact를 탐색이 끝난 뒤, 실행 직전처럼 논리적 전환점에서 수동으로 실행하면 불필요한 탐색 맥락을 정리하고 실행에 필요한 맥락만 남길 수 있습니다.

전략	설명
전략적 /compact	자동 압축을 끄고 탐색 → 실행 전환점에서 수동 압축. 탐색 맥락을 정리한 뒤 계획만 남기고 실행
세션 파일 패턴	세션 종료 시 현재 상태를 .tmp 파일로 저장하고, 다음 세션에서 해당 파일을 불러와 이어서 작업. 날짜별로 파일을 분리하면 이전 맥락이 새 작업을 오염시키지 않음
Plan 모드 활용	계획을 세운 뒤 Plan 모드에서 컨텍스트를 정리하면, 탐색 맥락 없이 계획만으로 실행 가능
--system-prompt 주입	claude --system-prompt "$(cat context.md)"로 세션별 맥락을 시스템 프롬프트에 직접 주입. @파일 참조보다 우선순위가 높고 도구 호출 없이 즉시 로드

모델 선택 전략

모든 작업에 Opus를 쓸 필요는 없습니다. 코딩 작업의 90%는 Sonnet으로 충분하고, Opus는 첫 시도 실패, 5개 이상 파일에 걸친 작업, 아키텍처 결정, 보안 중요 코드에 사용합니다. Haiku는 반복적인 단순 작업이나 멀티에이전트의 워커 역할에 적합합니다. 서브에이전트 정의에서 모델을 지정하면 작업별로 자동 분배됩니다.

.claude/agents/quick-search.md (프론트매터)복사

---
name: quick-search
description: 빠른 파일 검색
tools: Glob, Grep
model: haiku  # 단순 검색은 Haiku로 비용 절약
---

서브에이전트 활용 팁

서브에이전트는 컨텍스트 절약의 핵심이지만, 메인 에이전트의 맥락을 모른 채 요약을 반환하기 때문에 중요한 디테일이 빠질 수 있습니다. 서브에이전트에 작업을 넘길 때는 **구체적인 쿼리와 함께 상위 목적까지 전달**하면 반환 품질이 올라갑니다. 반환된 요약이 부족하면 후속 질문을 보내서 보충하고, 최대 3회까지 반복한 뒤 수락합니다.

단순 위임

"src/api 폴더의 인증 관련 코드를 찾아줘"

목적 포함 위임

"src/api 폴더의 인증 관련 코드를 찾아줘. JWT 토큰 갱신 로직에 레이스 컨디션이 의심되는 상황이라 토큰 만료 처리 흐름에 집중해서 봐줘"

병렬 작업 패턴

여러 Claude 인스턴스를 동시에 띄울 때는 각 인스턴스의 작업 범위가 겹치지 않도록 설계해야 합니다. 코드를 수정하는 인스턴스는 git worktree로 격리하고, 나머지 인스턴스는 리서치나 질문 전용으로 쓰는 것이 안전합니다. /rename으로 각 세션에 이름을 붙여두면 나중에 재개할 때 혼동을 방지할 수 있습니다.

패턴	설명
Cascade 패턴	새 작업은 오른쪽 탭에서 열고, 왼쪽→오른쪽 순서로 확인. 동시에 3~4개 이상은 오히려 관리 오버헤드가 생산성보다 커짐
코딩 + 리서치 분리	메인 인스턴스는 코드 작업, 포크한 인스턴스는 문서 조사/질문 전용. 코드 충돌 없이 맥락 보강
Worktree 격리	코드 수정이 겹치는 작업은 반드시 git worktree로 분리. claude -w feature-auth 형태로 시작

토큰 절약

토큰 비용의 대부분은 입력에서 발생합니다. 파일이 수천 줄짜리라면 Claude가 여러 번 나눠 읽으면서 토큰을 소모하고, 중간에 정보를 놓칠 수도 있습니다. 코드베이스를 모듈화해서 파일당 수백 줄 수준으로 유지하면 토큰 비용과 정확도 모두 개선됩니다.

방법	효과
MCP → CLI + Skill 전환	GitHub MCP 대신 /gh-pr 커맨드로 gh pr create 래핑. 기능은 동일하지만 컨텍스트 윈도우를 차지하지 않음
코드베이스 모듈화	파일당 수백 줄로 유지. 긴 파일을 반복 읽는 비용을 줄이고 첫 시도 성공률도 올라감
백그라운드 프로세스 분리	Claude 안에서 빌드/테스트를 돌리면 출력 전체가 토큰으로 소모됨. 별도 터미널에서 실행하고 필요한 부분만 복사
llms.txt 활용	공식 문서 사이트에서 /llms.txt 경로를 확인하면 LLM에 최적화된 문서를 바로 피드할 수 있음
5분 안에 프롬프트 보내기	Anthropic API는 프롬프트 캐싱을 사용합니다. 마지막 요청 후 5분 이내에 다음 프롬프트를 보내면 이전 시스템 프롬프트와 컨텍스트가 캐시에 남아 있어서 입력 토큰 비용이 크게 줄어듭니다. 5분이 지나면 캐시가 만료되어 전체 컨텍스트를 다시 전송해야 합니다

메모리 지속 훅

세션 간 맥락을 자동으로 이어주는 훅 패턴입니다. PreCompact 훅으로 압축 전 상태를 저장하고, Stop 훅으로 세션 종료 시 학습 내용을 파일로 남기고, SessionStart 훅으로 다음 세션 시작 시 이전 맥락을 자동 로드합니다. 이 세 가지를 연결하면 수동 개입 없이 세션 간 연속성을 유지할 수 있습니다.

settings.json (메모리 지속 훅 예시)복사

{
  "hooks": {
    "PreCompact": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/pre-compact.sh"
      }]
    }],
    "SessionStart": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/session-start.sh"
      }]
    }],
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/session-end.sh"
      }]
    }]
  }
}

전체 보기

실전 활용: 심화편

기초편의 패턴에 익숙해졌다면, 장시간 세션 운영, 자동 학습, 검증 루프, 에이전트 오케스트레이션 같은 심화 패턴으로 넘어갈 차례입니다. 이 패턴들은 복잡한 프로젝트에서 일관성을 유지하고 재작업을 줄이는 데 핵심적입니다.

2-인스턴스 킥오프 패턴

새 프로젝트를 시작할 때 Claude 인스턴스 2개를 동시에 여는 패턴입니다. 왼쪽 터미널은 스캐폴딩 에이전트로 프로젝트 구조, CLAUDE.md, 에이전트 설정 등 기반을 잡습니다. 오른쪽 터미널은 리서치 에이전트로 외부 서비스 연결, PRD 작성, 아키텍처 다이어그램, 공식 문서 수집을 담당합니다. 두 인스턴스가 서로 다른 역할을 맡기 때문에 코드 충돌 없이 빠르게 프로젝트를 부트스트랩할 수 있습니다.

인스턴스	역할	산출물
인스턴스 1 (스캐폴딩)	프로젝트 구조 생성, CLAUDE.md·rules·agents 설정, 컨벤션 확립	코드 스켈레톤 + 설정 파일
인스턴스 2 (리서치)	외부 서비스 연결, 상세 PRD 작성, 공식 문서 클립 수집, 아키텍처 다이어그램	PRD + 레퍼런스 문서

동적 시스템 프롬프트 주입

CLAUDE.md나 .claude/rules/에 넣으면 매 세션마다 로드됩니다. 하지만 상황에 따라 다른 맥락이 필요할 때는 CLI 플래그로 시스템 프롬프트를 동적으로 주입할 수 있습니다. @파일 참조는 Read 도구를 호출해서 도구 결과로 들어오지만, --system-prompt는 시스템 프롬프트에 직접 주입되기 때문에 지시 우선순위가 더 높고 도구 호출 비용도 없습니다.

PowerShell 별칭 예시복사

# 일반 개발 모드
function claude-dev { claude --system-prompt (Get-Content ~/.claude/contexts/dev.md -Raw) }

# PR 리뷰 모드
function claude-review { claude --system-prompt (Get-Content ~/.claude/contexts/review.md -Raw) }

# 리서치 모드
function claude-research { claude --system-prompt (Get-Content ~/.claude/contexts/research.md -Raw) }

💡WSL에서는 bash 별칭

WSL 환경이라면 alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"' 형태로 .bashrc에 추가합니다.

연속 학습 패턴

같은 실수를 반복하거나, 매번 같은 교정 프롬프트를 보내야 하는 상황이 반복된다면 연속 학습 패턴이 필요합니다. Stop 훅을 사용해서 세션 종료 시 자동으로 세션을 분석하고, 디버깅 기법, 우회법, 프로젝트 고유 패턴 등 추출할 가치가 있는 지식을 스킬 파일로 저장합니다. 다음 세션에서 비슷한 문제가 발생하면 해당 스킬이 자동으로 로드됩니다.

방식	설명
Stop 훅 자동 추출	세션 종료 시 스크립트가 세션 로그를 분석하여 패턴을 ~/.claude/skills/learned/ 에 자동 저장. UserPromptSubmit 대신 Stop을 쓰는 이유는 매 메시지마다 실행되는 오버헤드가 없기 때문
/learn 수동 추출	비자명한 문제를 해결한 직후 /learn 명령어로 즉시 패턴 추출. 세션 종료까지 기다리지 않아도 됨
세션 반성 패턴	세션 로그를 반성 에이전트가 분석하여 성공/실패/교정 이력을 추출. 메모리 파일로 축적하면 세션이 쌓일수록 Claude가 사용자의 선호를 학습

검증 루프

코드 변경 후 자동으로 검증하는 루프를 설정하면 기술 부채가 쌓이는 것을 방지할 수 있습니다. 검증 방식은 크게 두 가지로 나뉩니다. 체크포인트 기반은 기능 구현처럼 마일스톤이 명확한 선형 작업에 적합하고, 연속 검증은 탐색적 리팩토링이나 유지보수처럼 마일스톤이 불명확한 장시간 세션에 적합합니다.

방식	작동	적합한 작업
체크포인트 기반	각 단계 완료 후 정의된 기준으로 검증. 실패하면 해당 단계에서 수정 후 다음 진행	기능 구현, 마이그레이션 등 명확한 단계가 있는 작업
연속 검증	N분마다 또는 주요 변경 후 테스트/린트/빌드 자동 실행. 회귀 발견 시 즉시 중단하고 수정	탐색적 리팩토링, 장시간 유지보수 세션

검증 지표: pass@k와 pass^k

에이전트 성능을 측정하는 두 가지 핵심 지표가 있습니다. pass@k는 k번 시도 중 최소 1번 성공하면 통과로, "일단 되기만 하면 되는" 상황에 적합합니다. pass^k는 k번 시도가 전부 성공해야 통과로, 일관성이 중요한 프로덕션 작업에 사용합니다. 예를 들어 단일 성공률이 70%일 때 pass@3은 91%이지만 pass^3은 34%입니다. 스킬이나 에이전트를 벤치마킹할 때 이 두 지표를 구분해서 보면 어디를 개선해야 하는지 명확해집니다.

벤치마킹 워크플로우

스킬이나 에이전트 설정이 실제로 효과가 있는지 확인하려면 git worktree를 활용한 A/B 비교가 유용합니다. 같은 작업을 Worktree A(스킬 적용)와 Worktree B(스킬 미적용)에서 동시에 실행한 뒤, git diff로 결과를 비교하고 토큰 사용량과 출력 품질을 대조합니다. 모델별 비교도 같은 방식으로 가능합니다.

Terminal

# Worktree A: 스킬 적용
$ git worktree add ../project-with-skill feature-a
$ cd ../project-with-skill && claude

# Worktree B: 스킬 미적용 (별도 터미널)
$ git worktree add ../project-without-skill feature-b
$ cd ../project-without-skill && claude

# 완료 후 비교
$ diff <(cd ../project-with-skill && git diff HEAD) <(cd ../project-without-skill && git diff HEAD)

에이전트 오케스트레이션

복잡한 작업은 하나의 에이전트에 모두 맡기기보다, 단계별로 전문 에이전트에 분배하는 순차 오케스트레이션 패턴이 효과적입니다. 각 에이전트는 하나의 명확한 입력을 받아 하나의 명확한 산출물을 만들고, 그 산출물이 다음 단계의 입력이 됩니다. 단계를 건너뛰지 않고, 중간 산출물을 파일로 저장해서 메모리가 아닌 파일 기반으로 맥락을 넘깁니다.

순차 오케스트레이션 패턴

리서치 (Explore 에이전트)

맥락 수집, 패턴 식별. 산출물: research-summary.md

계획 (Planner 에이전트)

research-summary.md를 읽고 구현 계획 수립. 산출물: plan.md

구현 (TDD 에이전트)

plan.md를 읽고 테스트 먼저 작성 → 코드 구현. 산출물: 코드 변경

리뷰 (Code Reviewer 에이전트)

모든 변경 사항 리뷰. 산출물: review-comments.md

검증

테스트 실행, 이슈 수정. 실패 시 구현 단계로 돌아감

에이전트 추상화 티어

모든 에이전트 패턴이 같은 난이도와 효용을 가진 것은 아닙니다. 아래는 쉬운 것부터 어려운 것 순서로 정리한 에이전트 활용 티어입니다. Tier 1을 충분히 활용한 뒤에 Tier 2로 넘어가는 것을 권장합니다.

티어	패턴	설명
Tier 1 (기본)	서브에이전트	컨텍스트 절약과 전문화에 직접적인 효과. 복잡도가 낮고 즉시 적용 가능
Tier 1 (기본)	메타프롬프팅	3분 투자해서 20분짜리 작업의 안정성을 높이는 패턴. 가정을 검증하고 프롬프트를 정교화
Tier 2 (고급)	장시간 에이전트	15분짜리 vs 1.5시간짜리 vs 4시간짜리 작업의 특성 차이를 이해해야 함. 시행착오 필요
Tier 2 (고급)	병렬 멀티에이전트	분산이 매우 크고 잘 분리된 작업에서만 효과적. 프롬프팅이나 머지에 시간이 더 들면 역효과
Tier 2 (고급)	역할 기반 멀티에이전트	모델이 빠르게 진화하므로 하드코딩된 휴리스틱은 금방 낡아짐. 비용 차이가 클 때만 유효

MCP를 CLI + Skill로 대체하기

GitHub, Supabase, Vercel 같은 플랫폼은 이미 강력한 CLI를 제공하고 있고, 해당 MCP는 사실상 CLI를 래핑한 것입니다. MCP를 항상 로드하면 컨텍스트 윈도우를 차지하고 토큰 비용이 추가됩니다. lazy loading이 도입되면서 초기 로드 문제는 완화되었지만, 토큰 사용량 자체는 CLI + Skill 조합이 여전히 효율적입니다. 예를 들어 GitHub MCP 대신 gh CLI를 래핑한 /gh-pr 커맨드를 만들면 동일한 기능을 컨텍스트 부담 없이 사용할 수 있습니다.

MCP 상시 로드

GitHub MCP가 세션 내내 도구 목록에 포함되어 컨텍스트와 토큰을 차지

CLI + Skill 조합

/gh-pr 커맨드로 gh pr create를 래핑. 필요할 때만 실행되고 컨텍스트를 차지하지 않음

재사용 가능한 패턴에 투자하기

초반에 재사용 가능한 워크플로우와 패턴을 구축하는 데 시간을 투자하면 복리 효과가 생깁니다. 서브에이전트, 스킬, 커맨드, MCP 설정, 계획 패턴은 한번 만들어두면 모델이 업그레이드되어도 그대로 작동합니다. 특정 모델의 트릭에 투자하는 것보다 패턴에 투자하는 것이 장기적으로 유리하고, 이 패턴들은 Claude Code 외에 다른 에이전트 도구로도 이식할 수 있습니다.

ℹ️참고 자료

이 섹션의 팁은 Affaan Mustafa의 Everything Claude Code 가이드(github.com/affaan-m/everything-claude-code)를 참고했습니다. 메모리 지속 훅, 연속 학습 스킬, 세션 파일 예시, 벤치마킹 설정 등 실전 코드를 해당 레포에서 확인할 수 있습니다.

FAQ

Claude Code 사용 시 자주 묻는 질문을 정리했습니다. 요금, 모델 선택, 타 도구와의 비교, 세션 관리 등 핵심 사항을 간결하게 답변합니다.

Claude Code는 무료인가요?

무료 Claude.ai 플랜으로는 사용할 수 없습니다. Claude Pro ($20/월), Max ($100/월 또는 $200/월), Team, Enterprise 구독이 필요합니다. API 키(Console 계정)로도 사용할 수 있으며, 이 경우 API 사용량 기준으로 과금됩니다.

어떤 모델을 쓸 수 있나요?

Claude Sonnet 4.6(기본), Claude Opus 4.6(Max/Team), Claude Haiku 4.5를 사용할 수 있습니다. /model 명령어나 --model 플래그로 전환합니다.

Cursor와 뭐가 다른가요?

Claude Code는 터미널 기반 CLI 도구이고, Cursor는 VS Code 기반 GUI IDE입니다. Claude Code는 터미널에서 직접 파일을 읽고 수정하며, 100만 토큰 컨텍스트를 지원합니다.

인터넷 연결이 필요한가요?

네, Anthropic API와 통신해야 하기 때문에 인터넷 연결이 필수입니다.

세션이 끊기면 작업이 사라지나요?

세션은 자동 저장됩니다. claude -c로 마지막 세션을 이어서 작업할 수 있고, claude -r "세션명"으로 특정 세션을 재개할 수 있습니다.

CLAUDE.md를 꼭 써야 하나요?

필수는 아니지만 강력히 권장합니다. 프로젝트의 코딩 스타일, 아키텍처, 기술 스택을 CLAUDE.md에 적어두면 Claude가 일관된 코드를 생성합니다.

MCP 서버는 어디서 찾나요?

GitHub에서 "MCP server"로 검색하면 수백 개의 커뮤니티 MCP 서버를 찾을 수 있습니다. Context7, Supabase MCP, Brave Search MCP 등이 인기 있습니다.

한 세션에서 최대 얼마나 사용할 수 있나요?

세션은 5시간 동안 유지됩니다. Pro 플랜은 중간 정도, Max5는 5배, Max20은 20배의 토큰 예산을 사용할 수 있습니다.

가이드바이브 코딩

CLAUDE.md 작성법 — AI 에이전트를 내 프로젝트에 맞추는 방법

Claude Code가 모든 세션에서 읽는 프로젝트 지침 파일 CLAUDE.md의 위치 계층, 작성 전략, 실전 예시, 팀 공유 패턴, AGENTS.md·GEMINI.md와의 차이를 한 문서에 정리했습니다.

2026. 4. 3.

가이드바이브 코딩

MCP(Model Context Protocol) 완전 가이드

MCP란 무엇인지부터 아키텍처, 전송 방식, Claude Code 설정법, 인기 서버 목록, 직접 서버 만들기, 보안 주의사항까지 한 곳에 정리했습니다.

2026. 4. 3.

튜토리얼바이브 코딩

Claude Code 플러그인·스킬 만들기 튜토리얼

Claude Code의 스킬(Skill)을 처음부터 만들어봅니다. SKILL.md 작성법, 프론트매터 옵션 전체, 동적 인자와 컨텍스트 주입, 서브에이전트 연동, 플러그인 패키징까지 단계별로 따라 할 수 있습니다.

2026. 4. 3.