📖 2026 완전 정복 가이드

Claude Code
A to Z 마스터 가이드

설치부터 고급 활용까지 — 이 글 하나로 Claude Code 완전 정복. 초보자도 바로 시작할 수 있도록 용어 정의, 요금, 명령어, 팁까지 모두 담았습니다.

📦 설치 가이드 💰 요금 완벽 비교 ⌨️ 핵심 명령어 📘 용어 사전 🔌 MCP 연동 💡 실전 팁

📋 목차

01 Claude Code란? 02 왜 써야 하나? 03 핵심 용어 사전 04 요금 완벽 비교 05 설치 & 시작하기 06 핵심 명령어 모음 07 CLAUDE.md 활용 08 작동 모드 3가지 09 MCP 서버 연결 10 IDE 통합 11 실전 팁 & 베스트 프랙티스 12 자주 묻는 질문

Section 01

Claude Code란?

Anthropic이 만든 AI 기반 코딩 에이전트 — 터미널에서 자연어로 코드를 다룬다

Claude Code는 Anthropic이 개발한 AI 코딩 에이전트(Agent)입니다. 단순히 "코드를 써주는 챗봇"이 아니라, 여러분의 컴퓨터 터미널에 직접 설치해서 사용하는 도구입니다. 자연어로 지시하면 Claude가 파일을 읽고, 수정하고, 명령어를 실행하고, Git까지 관리합니다.

💡

쉽게 이해하기: 기존 Claude.ai (웹 채팅)는 "대화 상대"라면, Claude Code는 "실제로 내 컴퓨터에서 일해주는 직원"입니다. 직접 파일을 열어보고, 코드를 고치고, 커밋까지 해줍니다.

🤖

에이전트 방식

단순 답변이 아니라 실제로 작업을 수행. 파일 수정·명령 실행·Git 커밋까지

💬

자연어 인터페이스

"이 버그 고쳐줘", "테스트 코드 만들어줘" 처럼 말하듯 지시 가능

🗂️

코드베이스 이해

프로젝트 전체 구조를 파악하여 맥락에 맞는 코드를 작성

🔌

MCP 확장

GitHub, Slack, DB 등 외부 서비스와 연결해 작업 범위를 무한 확장

🖥️

다양한 실행 환경

터미널, VS Code, JetBrains, 데스크톱 앱, 웹 브라우저 모두 지원

⚡

엄청난 성장

2026년 2월 기준, 공개 GitHub 커밋의 4%가 Claude Code로 작성됨

Section 02

왜 써야 하나?

다른 AI 코딩 도구들과 무엇이 다른가

Cursor, GitHub Copilot 등 다양한 AI 코딩 도구가 있습니다. Claude Code만의 강점을 정리했습니다.

기능/특징	Claude Code	Cursor	GitHub Copilot
터미널 기반 자율 작업	✓ 강력	△ 제한적	✗
전체 파일 동시 수정	✓	✓	△
Git 자동 커밋/PR	✓	△	✗
MCP 외부 연동	✓ 강력	△	✗
CI/CD 자동화	✓ 헤드리스 모드	✗	△
인라인 코드 완성	△	✓ 강력	✓ 강력
멀티 모델 전환	△ (Haiku/Sonnet/Opus)	✓	✗

🎯

언제 Claude Code가 유리한가? 대규모 리팩토링, 터미널 중심 워크플로우, 원격 서버 작업, CI/CD 자동화, MCP 생태계 활용 시. 반면 인라인 자동완성이 주 목적이라면 Cursor가 더 편리할 수 있습니다.

Section 03

핵심 용어 사전

처음엔 낯설었던 그 단어들 — 여기서 한 번에 정리

CLI
Command Line Interface

터미널(검은 화면)에서 명령어를 입력해 사용하는 방식. Claude Code를 설치하면 터미널에서 claude 명령어로 사용합니다.

npm
Node Package Manager

Node.js의 패키지 설치 도구. Claude Code는 npm으로 설치합니다. Node.js가 먼저 설치되어 있어야 합니다.

Node.js

JavaScript를 컴퓨터에서 실행할 수 있게 해주는 런타임. Claude Code 설치 시 필요한 사전 조건입니다.

Agent
에이전트

AI가 단순 답변이 아니라 계획을 세우고, 도구를 사용하고, 여러 단계를 거쳐 작업을 완수하는 방식. Claude Code의 핵심 동작 방식입니다.

Context Window
컨텍스트 윈도우

AI가 한 번에 기억할 수 있는 텍스트의 양(토큰 수). 긴 대화나 많은 파일을 다루면 컨텍스트가 꽉 차 정보를 잊을 수 있습니다.

Token
토큰

AI가 텍스트를 처리하는 단위. 영어 단어 하나 ≈ 1토큰, 한국어는 글자당 2~4토큰 정도 소모. 요금 계산의 기준입니다.

MCP
Model Context Protocol

Claude Code를 외부 서비스(GitHub, Slack, DB 등)와 연결하는 표준 프로토콜. 마치 플러그인처럼 기능을 확장합니다.

CLAUDE.md

프로젝트에 대한 지속적인 지침을 담은 파일. 빌드 명령어, 코딩 규칙, 아키텍처 설명 등을 적어두면 Claude가 매번 참고합니다.

Slash Command
슬래시 명령어

대화 중 /로 시작하는 명령어. /clear, /compact, /model 등 세션 관리 기능을 제공합니다.

Headless Mode
헤드리스 모드

대화 없이 한 번의 명령으로 Claude Code를 실행하는 방식. CI/CD 파이프라인이나 자동화 스크립트에 활용합니다.

Diff View

코드 변경 내용을 "수정 전 vs 수정 후"로 나란히 보여주는 화면. Claude가 파일을 수정하면 diff로 확인하고 승인/거부할 수 있습니다.

Subagent
서브에이전트

메인 Claude가 복잡한 작업을 여러 개의 하위 AI 에이전트에게 분산하여 병렬로 처리하는 방식. 대규모 작업 속도를 높입니다.

Git Worktree

하나의 Git 저장소에서 여러 작업 디렉토리를 만드는 기능. 여러 Claude Code 세션을 동시에 다른 브랜치에서 실행할 때 활용합니다.

Hooks
훅

도구 실행 전/후에 자동으로 실행되는 커스텀 명령어. 예: Python 파일 저장 시 자동 포매터 실행.

Plan Mode
계획 모드

Claude가 실제 작업 전에 계획을 먼저 설명하고, 사용자 승인 후 실행하는 모드. 신중한 작업 시 활용합니다.

Pro / Max / Team
요금제

Claude Code 사용 가능한 유료 구독 플랜들. Free 플랜에서는 Claude Code를 사용할 수 없습니다.

Section 04

요금 완벽 비교

무료로는 사용 불가 — 나에게 맞는 플랜 고르기

⚠️

중요! Claude Code는 무료(Free) 플랜에서는 사용할 수 없습니다. 최소 Pro 플랜($20/월)이 필요합니다. 단, Claude.ai 웹 채팅은 무료로 이용 가능합니다.

Free

영원히 무료

Claude.ai 웹 채팅
기본 모델 (Sonnet)
5시간마다 사용량 리셋
Claude Code 사용 불가
Opus 모델 불가

어떤 플랜을 선택해야 할까?

🌱

Pro ($20)

가벼운 사용자

주 2~3회 사용, 간단한 버그 수정이나 코드 생성. 처음 시작한다면 Pro부터. 부족하면 그때 업그레이드하면 됩니다.

💪

Max 5x ($100)

일반 개발자

매일 Claude Code를 사용하며 중간 규모 프로젝트를 다룬다면. Pro 한도에 자주 막힌다면 Max 5x가 적합합니다.

🚀

Max 20x ($200)

헤비 유저

복수 인스턴스 동시 실행, 대규모 프로젝트, 팀 단위 업무 자동화. 하루 종일 Claude Code를 돌리는 사람에게 적합합니다.

Extra Usage (초과 사용)

Pro/Max 유저는 포함 한도를 넘어도 Extra Usage를 켜면 API 요금으로 계속 사용할 수 있습니다. 가끔 무거운 작업이 있다면 Max로 업그레이드하기 보다 Extra Usage + 지출 한도 설정이 더 경제적입니다.

API 직접 사용

구독 없이 API 키로 Claude Code를 사용할 수도 있습니다. 자동화 스크립트, CI/CD 파이프라인 등 사람이 아닌 코드가 Claude를 호출하는 경우에 적합합니다. 모델별 요금은 아래와 같습니다:

API 요금 (100만 토큰 기준)
# 입력 / 출력 가격
Opus 4.7   : $5 / $25  per 1M tokens
Sonnet 4.6 : $3 / $15  per 1M tokens
Haiku 4.5  : $1 / $5   per 1M tokens

Section 05

설치 & 시작하기

3분 안에 첫 번째 세션 시작하기

⚠️

사전 조건: 유료 Claude 계정(Pro 이상) + Node.js 설치. Node.js는 nodejs.org에서 LTS 버전을 설치하면 됩니다.

방법 1 — 터미널(CLI) 설치 (공식 권장)

Node.js 설치 확인

터미널을 열고 Node.js가 설치됐는지 확인합니다. 없다면 nodejs.org에서 설치.

Terminal
node --version   # v18 이상이어야 함

Claude Code 설치

npm으로 전역 설치합니다. 인터넷이 연결된 상태에서 아래 명령어 한 줄이면 끝!

Terminal
npm install -g @anthropic-ai/claude-code
claude --version  # 설치 확인

프로젝트에서 시작

작업할 프로젝트 폴더로 이동한 뒤 claude를 실행합니다. 이제 자연어로 지시하면 됩니다!

Terminal
cd my-project
claude

# 이런 식으로 말하면 됩니다:
> 이 프로젝트의 구조를 설명해줘
> src/api.js의 버그를 찾아서 고쳐줘
> UserService 클래스에 단위 테스트 추가해줘
> 변경 내용을 커밋하고 PR 만들어줘

방법 2 — VS Code 확장 프로그램

VS Code에서 확장 프로그램을 통해 GUI로 사용할 수 있습니다.

VS Code
# 확장 프로그램 검색 단축키
Mac:     Cmd + Shift + X
Windows: Ctrl + Shift + X

# 검색창에 "Claude Code" 입력 → 설치
# 설치 후 명령 팔레트에서 "Claude Code" 입력
Mac:     Cmd + Shift + P
Windows: Ctrl + Shift + P

방법 3 — 데스크톱 앱

code.claude.com에서 데스크톱 앱을 다운로드하면 diff 시각화, 여러 세션 동시 실행, 클라우드 세션 등 추가 기능을 GUI로 사용할 수 있습니다. 유료 구독 필요.

방법 4 — 웹 브라우저

code.claude.com에서 로컬 설치 없이 브라우저에서 바로 Claude Code를 실행할 수 있습니다. 환경 설정이 어려운 초보자에게 추천합니다.

Section 06

핵심 명령어 모음

터미널 명령어 + 대화 중 슬래시 명령어 총정리

터미널에서 사용하는 명령어

명령어	설명
claude	현재 폴더에서 대화형 세션 시작
claude "질문이나 지시"	한 줄 명령 바로 실행 (헤드리스)
claude -p "프롬프트"	헤드리스 모드로 실행 (자동화용)
claude --version	설치된 버전 확인
claude update	최신 버전으로 업데이트
claude mcp add <이름> <경로>	MCP 서버 추가
claude mcp list	등록된 MCP 서버 목록 확인
claude mcp remove <이름>	MCP 서버 제거
claude --mcp-debug	MCP 디버그 모드로 실행

대화 중 슬래시 명령어 (/)

명령어	설명
/init	프로젝트 분석 후 CLAUDE.md 자동 생성. 새 프로젝트에서 가장 먼저 실행!
/clear	대화 기록 초기화 (새 작업 시작 시 토큰 절약)
/compact	대화 기록 압축 (긴 세션에서 컨텍스트 공간 확보, 40~60% 절약)
/cost	현재 세션의 토큰 사용량과 비용 확인
/status	현재 로그인 상태, 플랜, 설정 확인
/model	사용 모델 변경 (Haiku / Sonnet / Opus)
/memory	자동 저장된 메모리 확인 및 편집
/allowed-tools	허용된 도구 목록 확인 및 관리
/mcp	현재 연결된 MCP 서버 상태 확인
/vim	Vim 편집 모드 활성화
/help	도움말 및 명령어 목록 표시

키보드 단축키

단축키	설명
Shift + Tab	작동 모드 전환 (일반 → 계획 → 자동 수락)
Ctrl + C	현재 작업 중단
↑ / ↓	이전/다음 명령어 기록 탐색

Section 07

CLAUDE.md 활용법

프로젝트 지침을 저장해 매번 설명하지 않아도 되게 하는 마법 파일

CLAUDE.md는 프로젝트 루트에 만드는 마크다운 파일입니다. Claude Code가 세션을 시작할 때 자동으로 읽어들여, 빌드 명령어, 코딩 규칙, 프로젝트 구조 등을 매번 설명하지 않아도 됩니다.

✨

빠른 시작: 프로젝트 폴더에서 /init을 실행하면 Claude가 프로젝트를 분석해 CLAUDE.md를 자동으로 만들어줍니다!

CLAUDE.md 예시

CLAUDE.md
# 프로젝트 개요
쇼핑몰 백엔드 API 서버 (Node.js + Express)

## 기술 스택
- Node.js v20 + TypeScript
- Express 백엔드
- PostgreSQL 데이터베이스

## 주요 명령어
- `npm run dev`   : 개발 서버 실행 (포트 3000)
- `npm run test`  : Jest 테스트 실행
- `npm run build` : 프로덕션 빌드

## 코딩 규칙
- ES 모듈(import/export) 사용, CommonJS(require) 금지
- 모든 async 함수에 에러 처리 필수
- 파일명은 camelCase 사용

## 주의사항
- .env 파일 절대 커밋 금지
- production 브랜치 직접 푸시 금지

무엇을 적어야 할까?

✅

포함할 것

Claude가 추측할 수 없는 빌드/테스트 명령어, 팀 코딩 규칙, 브랜치 전략, 프로젝트 고유 아키텍처

❌

제외할 것

코드를 읽으면 알 수 있는 것, 표준 언어 문법 규칙, 자주 바뀌는 정보, 긴 API 문서 (링크로 대체)

Section 08

작동 모드 3가지

Shift+Tab으로 전환 — 상황에 따라 골라 쓰기

🎯

일반 모드 (Normal)

기본 모드. 각 작업(파일 수정, 명령어 실행)마다 사용자 승인을 요청합니다. 처음 사용자에게 권장.

📋

계획 모드 (Plan)

작업을 실행하기 전에 Claude가 계획을 먼저 설명합니다. 승인하면 실행. 중요한 작업 전 체크용으로 유용.

⚡

자동 수락 모드 (Auto Accept)

Claude가 제안하는 모든 작업을 자동 승인. 빠른 작업에 유리하지만 되돌리기 어려운 작업엔 주의.

⚠️

자동 수락 모드 주의: 파일 삭제나 시스템 명령어가 자동으로 실행될 수 있습니다. 중요한 프로젝트에서는 일반 모드나 계획 모드를 사용하세요. Git으로 버전 관리를 하고 있다면 안전합니다.

Section 09

MCP 서버 연결

GitHub, Slack, DB 등 외부 서비스와 연결해 Claude의 능력을 무한 확장

MCP(Model Context Protocol)는 Claude Code를 외부 서비스와 연결하는 표준 방식입니다. MCP 서버를 추가하면 Claude가 직접 GitHub 이슈를 읽고, Slack에 메시지를 보내고, 데이터베이스를 쿼리할 수 있습니다.

MCP 서버 추가 방법

Terminal
# 기본 구문
claude mcp add <이름> <서버 경로나 명령어>

# 예: PostgreSQL 데이터베이스 연결
claude mcp add postgres /path/to/postgres-mcp \
  --connection-string "postgresql://user:pass@localhost/mydb"

# 예: SSE 방식 서버 연결
claude mcp add --transport sse my-server \
  https://example.com/sse-endpoint

# 서버 목록 확인
claude mcp list

# 서버 제거
claude mcp remove postgres

MCP로 할 수 있는 일 (예시)

🐙

GitHub MCP

"JIRA 이슈 ENG-123의 기능을 구현하고 GitHub에 PR 생성해줘"

🗄️

Database MCP

"users 테이블 스키마 설명해줘", "최근 주문 10건 보여줘"

💬

Slack MCP

"Slack에서 새 디자인 확인하고, 이걸 기반으로 컴포넌트 업데이트해줘"

📊

Sentry MCP

"Sentry에서 최근 에러 확인하고 원인 분석해줘"

💡

MCP 범위 설정: MCP 서버는 전역(모든 프로젝트) 또는 프로젝트별로 등록할 수 있습니다. 팀 공유가 필요하다면 .mcp.json 파일로 코드베이스에 체크인할 수 있습니다.

Section 10

IDE 통합

내가 쓰는 개발 도구에서 바로 Claude Code 사용하기

💙

VS Code

Extensions에서 "Claude Code" 검색 → 설치. 명령 팔레트(Cmd/Ctrl+Shift+P)에서 Claude Code 실행.

🟠

JetBrains (IntelliJ, WebStorm, PyCharm 등)

JetBrains Marketplace에서 "Claude Code [Beta]" 검색 → 설치 → IDE 재시작.

🌊

Cursor / Windsurf

Extensions에서 "Claude Code" 검색 → 설치 후 동일하게 사용 가능.

🖥️

데스크톱 앱

code.claude.com에서 다운로드. Diff 시각화, 멀티 세션, 작업 예약 등 추가 기능 제공.

🎯

IDE 내 터미널 팁: VS Code / JetBrains의 내장 터미널에서 claude를 실행하면 자동으로 해당 IDE 확장이 활성화됩니다. Diff를 IDE 내에서 시각적으로 검토할 수 있습니다.

Section 11

실전 팁 & 베스트 프랙티스

비용 절약부터 생산성 극대화까지

💰 비용 절약 팁

🔄 모델을 상황에 맞게 선택

간단한 파일 검색·탐색은 Haiku(가장 저렴), 일반 코딩·디버깅은 Sonnet(기본), 복잡한 아키텍처 설계는 Opus(최고 품질). /model로 전환하세요.

🗜️ /compact와 /clear 활용

긴 세션에서 /compact로 대화 압축(토큰 40~60% 절약). 새 작업을 시작할 때는 /clear로 컨텍스트 초기화.

💡 /cost로 사용량 모니터링

세션 중간중간 /cost를 실행하면 현재 세션에서 얼마나 토큰을 썼는지 확인할 수 있습니다.

🚀 생산성 팁

📄 항상 /init으로 시작

새 프로젝트를 시작할 때 가장 먼저 /init을 실행하세요. Claude가 프로젝트를 분석해 CLAUDE.md를 자동 생성합니다. 이후 세션에서 컨텍스트 제공 시간을 크게 줄일 수 있습니다.

🔀 멀티 세션으로 병렬 작업

Git Worktree로 여러 브랜치를 만들고 각각 다른 터미널에서 Claude Code를 실행하면 동시에 여러 작업을 진행할 수 있습니다. 예: 한 세션에서 버그 수정, 다른 세션에서 새 기능 개발.

📝 커스텀 슬래시 명령어 만들기

.claude/commands/ 폴더에 마크다운 파일을 만들면 반복 작업을 슬래시 명령어로 저장할 수 있습니다. 팀원과 Git으로 공유도 가능.

🎯 구체적으로 지시하기

"이거 고쳐줘"보다 "src/auth/login.ts의 중복 검사 로직을 리팩토링하고 단위 테스트 추가해줘"처럼 구체적으로 지시할수록 좋은 결과가 나옵니다.

🔒 권한 설정으로 안전하게

.claude/settings.json에서 허용/거부할 명령어를 지정할 수 있습니다. 예: curl 명령어 금지, npm test만 허용 등.

모델 선택 가이드

사용 시나리오별 권장 모델
Haiku 4.5  : 파일 탐색, 간단한 검색, 서브에이전트 작업
            → 비용 Opus 대비 약 5배 저렴

Sonnet 4.6 : 일반 코딩, 버그 수정, 테스트 작성, 코드 리뷰
            → 기본값. 대부분의 상황에서 최적

Opus 4.7   : 복잡한 아키텍처 설계, 대규모 리팩토링, 난해한 버그
            → Max/Team Premium 플랜에서 기본 사용

Section 12

자주 묻는 질문 (FAQ)

초보자들이 가장 헷갈려하는 것들

Q. Claude.ai와 Claude Code는 다른 건가요?

네, 완전히 다릅니다. Claude.ai는 웹 브라우저에서 쓰는 채팅 서비스이고, Claude Code는 여러분의 컴퓨터 터미널에 설치해서 실제 파일을 읽고 수정하는 에이전트 도구입니다. 둘 다 같은 Claude AI를 사용하지만 용도와 사용 방법이 다릅니다.

Q. 코딩을 전혀 모르는데 쓸 수 있나요?

네! 자연어로 "이 프로그램을 만들어줘"라고 하면 Claude가 코드를 작성합니다. 다만 터미널(검은 화면)에 익숙하지 않다면 처음엔 어색할 수 있습니다. 웹 브라우저에서 실행되는 code.claude.com으로 시작하면 터미널 없이도 사용할 수 있습니다.

Q. 한국어로도 사용 가능한가요?

물론입니다. "이 버그 고쳐줘", "테스트 코드 만들어줘" 등 한국어로 자유롭게 지시할 수 있습니다. 단, 한국어 입력은 영어 대비 토큰을 2~4배 더 소모하므로 사용량 소진이 빠를 수 있습니다.

Q. 내 코드가 Anthropic에 전송되나요?

Claude Code 작동 시 코드가 Anthropic 서버로 전송됩니다. 민감한 기업 정보나 개인정보가 포함된 코드는 주의하세요. 기업 환경에서는 Enterprise 플랜의 데이터 보안 정책을 확인하세요.

Q. 실수로 파일이 삭제되면 어떻게 하나요?

Git으로 버전 관리를 하고 있다면 안전합니다. Claude Code를 사용하기 전에 git init으로 Git을 설정하고 주기적으로 커밋하세요. 혹시 모르니 처음엔 일반 모드(Normal)로 사용해 각 작업을 확인하세요.

Q. 5시간 한도가 뭔가요?

Pro 플랜은 5시간마다 사용량이 리셋되는 구조입니다. 5시간 내에 사용량이 초과되면 그 5시간이 지날 때까지 사용이 제한됩니다. Opus 모델이나 Claude Code는 일반 채팅보다 토큰을 더 많이 사용해 한도가 빨리 소진됩니다.

Q. Windows에서도 사용 가능한가요?

네. Windows에서 PowerShell이나 WSL(Windows Subsystem for Linux)로 사용할 수 있습니다. 데스크톱 앱의 경우 Windows ARM64는 원격 세션만 지원합니다.

Q. Pro → Max로 언제 업그레이드해야 할까요?

"Pro 한도 초과로 작업이 반복해서 끊기고, 그로 인한 시간 손실이 월 $80보다 크다고 느낄 때" 업그레이드를 고려하세요. 처음엔 Pro로 시작하고, 가끔 무거운 주간에는 Extra Usage(지출 한도 설정)를 활용하는 것이 경제적입니다.

🎉

시작 전 체크리스트

✅ Claude 유료 계정(Pro 이상) 준비
✅ Node.js 설치 (nodejs.org에서 LTS 버전)
✅ npm install -g @anthropic-ai/claude-code 실행
✅ 프로젝트 폴더에서 claude 실행 + 로그인
✅ /init으로 CLAUDE.md 자동 생성
✅ 자연어로 첫 번째 작업 지시!

저작자표시 비영리 동일조건 (새창열림)

'AI 활용노트' 카테고리의 다른 글

초보 유튜브 채널 꾸미기 완벽 가이드 (0)	2026.05.01
Codex의 장점과 Claude Code 비교: 초보자도 쉽게 이해하는 AI 코딩 에이전트 선택법 (0)	2026.04.30
Claude Opus 4.7 설정 최적화: 달라진 점, 주의할 점 (0)	2026.04.28
코덱스를 시작하기 전에 먼저 알아두면 좋은 것 (0)	2026.04.21
2026년 대화형 AI를 바라보는 가장 현실적인 시선 (0)	2026.03.20