Claude Code 설치 & 초기 설정 가이드: 5분 만에 시작하기

Claude Code 설치 & 초기 설정 가이드: 5분 만에 시작하기

Claude Code를 설치하고 첫 코드를 수정하기까지, 실제로 5분이면 충분합니다. 이 글에서는 Windows, macOS, Linux 환경별 설치 방법부터 로그인, 초기 설정, VS Code 확장, JetBrains 플러그인 설정, 그리고 흔한 에러 해결까지 단계별로 안내합니다.

Claude Code 설치

---

1. 설치 전 준비물

Claude Code를 사용하려면 아래 항목이 필요합니다.

항목	요구사항	비고
운영체제	macOS 13+, Windows 10+, Linux (Ubuntu 20.04+)	상세 버전은 아래 참조
RAM	4GB 이상 (8GB 권장)
인터넷	필수	오프라인 사용 불가
Anthropic 계정	Pro 플랜 이상 ($17/월~)	Free 플랜은 Claude Code 불가
Windows 전용	Git for Windows	git-scm.com에서 설치

지원 운영체제 상세

OS	최소 버전
macOS	13.0 (Ventura) 이상
Windows	10 (1809) 이상, Windows Server 2019+
Ubuntu	20.04 이상
Debian	10 이상
Alpine Linux	3.19 이상

구독 플랜 확인

플랜	Claude Code 사용	월 요금
Free	불가	무료
Pro	가능	$17~20
Max 5x	가능	$100
Max 20x	가능	$200

아직 구독하지 않았다면 claude.ai/pricing에서 Pro 이상 플랜을 구독하세요.

 

설치 전 준비물

---

2. 설치 방법 (OS별)

방법 1: 네이티브 설치 (추천)

가장 빠르고 안정적인 방법입니다. Node.js가 필요 없고, 자동 업데이트를 지원합니다.

macOS / Linux:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows 사용자 필수: 설치 전에 반드시 Git for Windows를 먼저 설치하세요. Claude Code는 Git Bash를 셸 환경으로 사용합니다.

방법 2: Homebrew (macOS 전용)

brew install --cask claude-code

Homebrew는 자동 업데이트가 안 됩니다. 주기적으로 brew upgrade claude-code를 실행하세요.

방법 3: WinGet (Windows 전용)

winget install Anthropic.ClaudeCode

WinGet도 자동 업데이트가 안 됩니다. 주기적으로 winget upgrade Anthropic.ClaudeCode를 실행하세요.

설치 방법 비교

방법	자동 업데이트	Node.js 필요	추천 환경
네이티브 설치	자동	불필요	모든 환경 (추천)
Homebrew	수동	불필요	macOS
WinGet	수동	불필요	Windows
npm (비권장)	수동	18+ 필요	레거시

설치 확인

설치 후 터미널에서 아래 명령어로 확인합니다.

claude --version

버전 번호가 출력되면 설치 성공입니다.

설치 방법 (OS별)

---

3. 첫 로그인

로그인 과정

터미널에서 claude를 실행하면 자동으로 로그인 과정이 시작됩니다.

claude

단계	내용
1	claude 입력 → 브라우저가 자동으로 열림
2	Anthropic 계정으로 로그인 (Google/이메일)
3	인증 완료 → 터미널로 자동 복귀
4	인증 정보가 로컬에 안전하게 저장됨

이후에는 다시 로그인할 필요 없이 바로 사용할 수 있습니다.

브라우저가 안 열릴 때

SSH나 원격 서버 환경에서는 브라우저가 자동으로 열리지 않을 수 있습니다.

1. 터미널에서 c키를 누르면 OAuth URL이 클립보드에 복사됩니다
2. 해당 URL을 수동으로 브라우저에 붙여넣기하면 됩니다

인증 정보 저장 위치

OS	저장 위치
macOS	암호화된 macOS 키체인
Windows	로컬 보안 저장소
Linux	로컬 보안 저장소

로그아웃하려면

/logout

 

첫 로그인

---

4. 초기 설정 5단계

로그인 후, 프로젝트를 효과적으로 사용하기 위한 초기 설정을 진행합니다.

Step 1: 프로젝트 폴더로 이동

cd /path/to/your/project
claude

Claude Code는 현재 디렉토리를 기준으로 프로젝트를 인식합니다. 반드시 작업하려는 프로젝트 폴더에서 실행하세요.

Step 2: /init으로 CLAUDE.md 생성

/init

/init 명령을 실행하면 Claude Code가 프로젝트를 분석하고 CLAUDE.md 파일을 자동 생성합니다.

CLAUDE.md란?

항목	설명
역할	프로젝트 전용 기억 파일
위치	프로젝트 루트에 생성
내용	기술 스택, 실행 방법, 코딩 규칙 등
효과	Claude Code가 매 세션마다 이 파일을 읽고 프로젝트를 즉시 이해

CLAUDE.md 예시:

# 프로젝트 개요
React + Node.js 기반 웹 애플리케이션

## 기술 스택
- React 18 + TypeScript
- Node.js 18 + Express
- PostgreSQL
- Jest (테스트)

## 실행 방법
npm install
npm start

## 코딩 규칙
- TypeScript strict 모드 사용
- 컴포넌트는 src/components에 배치
- 테스트는 __tests__ 폴더에 작성

Step 3: 권한 모드 설정

/config

모드	설명	추천 대상
Interactive (기본)	모든 작업 전에 승인 요청	처음 사용자, 민감한 프로젝트
Plan	계획을 보여주고 전체 승인 후 실행	복잡한 작업
Auto-Accept	승인 없이 자동 실행	숙련된 사용자

처음에는 Interactive 모드로 시작해서 Claude Code가 어떤 작업을 하는지 확인하면서 익히는 것을 추천합니다.

Step 4: 모델 설정

/model

모델	특징	추천 용도
claude-opus-4-6	가장 강력, 복잡한 작업	기본 추천
claude-sonnet-4-6	빠르고 균형잡힌 성능	일반 작업
claude-haiku-4-5	가장 빠르고 저렴	단순 작업, 비용 절약

Step 5: 진단 실행

claude doctor

이 명령은 설치 상태, 설정 파일, MCP 서버, 키바인딩 등을 종합 점검합니다. 문제가 있으면 해결 방법을 안내해줍니다.

초기 설정 5단계

---

5. VS Code 확장 설치

설치 방법

방법	절차
방법 1	VS Code → Ctrl+Shift+X → "Claude Code" 검색 → 설치
방법 2	커맨드 팔레트 (Ctrl+Shift+P) → "Install Extensions" → "Claude Code"

VS Code 1.98.0 이상이 필요합니다.

설치 후 확인

설치가 완료되면:

• 에디터 우측 상단에 Spark 아이콘(✱)이 나타남
• 하단 상태바에 "✱ Claude Code" 표시

주요 단축키

기능	macOS	Windows/Linux
Claude Code 포커스	Cmd+Esc	Ctrl+Esc
@멘션 삽입	Option+K	Alt+K
새 탭 열기	Cmd+Shift+Esc	Ctrl+Shift+Esc
새 대화	Cmd+N	Ctrl+N

VS Code에서 활용하기

코드 선택 후 질문: 코드를 드래그한 뒤 Claude Code 패널에서 질문하면, 선택한 코드가 자동으로 컨텍스트에 포함됩니다.

@멘션으로 파일 지정: @파일명을 입력하면 특정 파일을 컨텍스트로 직접 지정할 수 있습니다.

VS Code 확장 설치

---

6. JetBrains 플러그인 설치

지원 IDE

IDE	지원 여부
IntelliJ IDEA	지원
PyCharm	지원
WebStorm	지원
Android Studio	지원
PhpStorm	지원
GoLand	지원

설치 방법

1. Settings → Plugins 이동
2. "Claude Code" 검색
3. Install 클릭
4. IDE 재시작

사용 방법

JetBrains 내장 터미널에서:

claude

외부 터미널에서 IDE 연결:

/ide

ESC 키가 안 먹힐 때

JetBrains는 ESC 키를 에디터로 포커스 이동에 사용합니다.

해결: Settings → Tools → Terminal → "Move focus to the editor with Escape" 체크 해제

JetBrains 플러그인 설치

---

7. 설정 파일 구조

Claude Code의 설정 파일은 3가지 레벨로 구성됩니다.

설정 파일 위치

파일	위치	역할	Git 커밋
글로벌 설정	~/.claude/settings.json	모든 프로젝트 공통 설정	해당 없음
프로젝트 설정	.claude/settings.json	프로젝트별 설정 (팀 공유)	커밋 가능
로컬 설정	.claude/settings.local.json	개인 설정 (팀 비공유)	커밋 제외
CLAUDE.md	프로젝트 루트	프로젝트 컨텍스트	커밋 가능
MCP 설정	.mcp.json	MCP 서버 설정	프로젝트별

Windows에서 ~는 C:\Users\사용자이름입니다.

settings.json 예시

{
  "permissions": {
    "allow": [
      "Bash",
      "Read",
      "Edit",
      "Write",
      "Glob",
      "Grep"
    ]
  },
  "model": "claude-opus-4-6",
  "autoUpdatesChannel": "stable"
}

프로젝트 settings.json 예시

{
  "permissions": {
    "allow": [
      "Bash(npm install:*)",
      "Bash(npm start:*)",
      "Bash(npm test:*)"
    ]
  }
}

프로젝트 settings.json은 팀원과 공유할 수 있어, 팀 전체가 동일한 권한 설정을 사용할 수 있습니다.

설정 파일 구조

---

8. 흔한 에러 & 해결법

command not found: claude

원인: PATH에 설치 경로가 포함되지 않음

macOS / Linux:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Zsh 사용자:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows에서 irm 명령을 인식 못할 때

원인: CMD에서 PowerShell 명령어 실행

해결: PowerShell을 열고 다시 실행하거나, CMD용 명령어 사용:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Git for Windows 관련 에러

원인: Git for Windows 미설치

해결: git-scm.com에서 설치 후, settings.json에 경로 지정:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

SSL/TLS 연결 에러

Ubuntu/Debian:

sudo apt-get update && sudo apt-get install ca-certificates

macOS:

brew install ca-certificates

macOS dyld: cannot load 에러

원인: macOS 13 미만 버전

해결: macOS를 업데이트하거나, Homebrew로 설치:

brew install --cask claude-code

흔한 에러 & 해결법

---

9. 첫 사용: 이것부터 해보세요

설치와 설정이 끝났으면, 아래 순서로 Claude Code를 체험해보세요.

첫 대화

cd /path/to/your/project
claude

추천 첫 명령어 5가지

순서	명령	목적
1	"이 프로젝트가 뭘 하는 프로젝트야?"	코드베이스 이해 확인
2	"폴더 구조 설명해줘"	아키텍처 파악
3	"/init"	CLAUDE.md 생성
4	"README에 프로젝트 설명 추가해줘"	첫 파일 수정 체험
5	"변경사항 커밋해줘"	Git 자동화 체험

자주 쓰는 슬래시 커맨드

커맨드	기능
/help	도움말 보기
/init	CLAUDE.md 생성
/model	모델 변경
/config	설정 변경
/cost	현재 세션 비용 확인
/compact	대화 요약 (컨텍스트 절약)
/clear	대화 초기화

첫 사용

---

10. 업데이트 & 삭제

업데이트

설치 방법	업데이트 명령
네이티브	자동 (별도 조치 불필요)
Homebrew	brew upgrade claude-code
WinGet	winget upgrade Anthropic.ClaudeCode

수동 업데이트 확인:

claude update

업데이트 채널 설정

채널	특징
latest (기본)	새 기능 즉시 반영
stable	1주 지연, 주요 버그 회피

{
  "autoUpdatesChannel": "stable"
}

삭제 방법

네이티브 (macOS/Linux):

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

네이티브 (Windows PowerShell):

Remove-Item "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item "$env:USERPROFILE\.local\share\claude" -Recurse -Force

설정까지 완전 삭제:

rm -rf ~/.claude
rm ~/.claude.json

업데이트 & 삭제

---

마무리

Claude Code 설치는 간단합니다. 네이티브 설치 한 줄이면 끝이고, 로그인 후 /init으로 프로젝트 설정까지 5분이면 완료됩니다.

정리하면:

1. 네이티브 설치 (추천) → 자동 업데이트, Node.js 불필요
2. 로그인 → 브라우저에서 Anthropic 계정으로 인증
3. /init → CLAUDE.md 생성으로 프로젝트 맞춤 설정
4. VS Code / JetBrains → 선호하는 IDE에 확장 설치

다음 편에서는 Claude Code의 기본 사용법을 실전 예시와 함께 자세히 다룹니다.

---

이전 글: [1편] Claude Code란? AI 코딩 어시스턴트 완전정리
다음 글: [3편] Claude Code 기본 사용법: 첫 대화부터 코드 수정까지

---

면책 조항: 본 글은 교육 목적의 정보 제공용이며, Claude Code의 기능 및 요금제는 Anthropic의 정책에 따라 변경될 수 있습니다. 최신 정보는 공식 문서(docs.anthropic.com)를 참고하세요.