Claude Code 완전 가이드 — 설치부터 첫 프로젝트까지 (Windows/Mac)

 

🤖 AI 테크 마스터 | 02/24편

1편에서 2026년 AI 프로그래밍 트렌드를 살펴봤습니다. 개발자의 65%가 AI 코딩 도구를 쓰고 있고, 코드 작성 속도가 55% 빨라진다는 숫자도 확인했죠. 이제 직접 써볼 차례입니다.

오늘 설치할 도구는 Claude Code입니다. Anthropic이 만든 터미널 기반 AI 코딩 어시스턴트인데, 1편에서 소개했던 "에이전트형" 도구의 대표 주자예요. 자연어로 명령하면 코드를 만들고, 수정하고, 실행까지 해주는 녀석입니다.

이 글에서는 Windows와 Mac 양쪽 모두 Claude Code 설치 방법을 다룹니다. 설치 → 인증 → VS Code 연동 → 첫 프로젝트 실행까지, 비개발자도 따라할 수 있게 한 단계씩 진행할게요.

📌 이 글에서 다루는 내용

✅ Claude Code가 뭔지, 다른 AI 도구와 뭐가 다른지

✅ Windows / Mac 설치 방법 (2026년 최신 네이티브 설치)

✅ 인증 설정과 요금제 선택 가이드

✅ VS Code 연동 방법

✅ 첫 프로젝트: 파이썬 계산기 만들기

✅ 자주 발생하는 오류 5가지와 해결법

 

Claude Code, 정확히 뭐가 다른가?

1편에서 AI 코딩 도구를 세 가지 유형으로 나눴습니다. IDE 통합형(Copilot, Cursor), 대화형(ChatGPT, Claude.ai), 에이전트형(Claude Code, GitHub Copilot Workspace). Claude Code는 세 번째 유형인 에이전트형입니다.

에이전트형이 뭐가 다르냐면, 단순히 "코드를 제안"하는 게 아니라 직접 파일을 만들고, 수정하고, 터미널 명령어를 실행합니다. ChatGPT에 "파이썬 스크립트 만들어줘"라고 하면 코드를 보여주기만 하잖아요? Claude Code는 "만들어줘"라고 하면 진짜 파일을 만들어서 저장합니다. 실행까지 해줍니다.

 

구체적으로 Claude Code가 할 수 있는 것들을 정리하면 이렇습니다.

🔧 Claude Code 핵심 기능

• 코드 생성: "로그인 페이지 만들어줘" → 파일 생성 + 코드 작성

• 코드 수정: "이 함수에서 버그 찾아서 고쳐줘" → 자동 수정

• 프로젝트 이해: "이 프로젝트 구조 설명해줘" → 코드베이스 분석

• Git 관리: "변경사항 커밋해줘" → git add, commit, push 실행

• 테스트 실행: "테스트 코드 만들고 실행해줘" → 작성 + 실행 + 결과 보고

• 터미널 명령: "패키지 설치해줘" → pip install, npm install 실행

요약하면, Claude Code는 "내 컴퓨터에서 실제로 작업하는 AI 개발자"입니다. 채팅창에서 답변만 주는 게 아니라, 터미널에서 직접 행동합니다.

 

설치 전 준비물 — 이것만 체크하세요

Claude Code를 설치하기 전에 확인해야 할 게 몇 가지 있습니다. 2026년 현재 Anthropic은 네이티브 설치(Native Install)를 공식 권장하고 있어요. 예전에 많이 쓰던 npm 설치 방식은 공식적으로 deprecated(지원 종료 예정)됐습니다.

⚠️ 2026년 변경사항 — 이전 가이드 주의

• 인터넷에 있는 npm install -g @anthropic-ai/claude-code 방식은 deprecated입니다

• 네이티브 설치는 Node.js가 필요 없습니다 (이전과 큰 차이!)

• Windows에서도 네이티브 설치가 가능해졌습니다 (Git Bash 필요)

• sudo npm install -g는 절대 쓰지 마세요 (권한 문제 발생)

설치에 필요한 준비물은 간단합니다.

📋 설치 전 체크리스트

✅ 운영체제: Windows 10 이상 / macOS 10.15 이상 / Ubuntu 20.04 이상

✅ 인터넷 연결: 설치 파일 다운로드 + 인증에 필요

✅ Claude 계정: Pro($20/월) 이상 구독 또는 API 키 필요

✅ Windows만: Git for Windows 설치 (Git Bash 포함) 또는 WSL

 

STEP 1: Claude Code 설치 — Windows편

Windows에서 Claude Code를 설치하는 방법은 크게 두 가지입니다. 방법 A: PowerShell 네이티브 설치(간편, 추천)와 방법 B: WSL(Windows Subsystem for Linux)(리눅스 환경, 완전한 호환)이에요.

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

가장 간단한 방법입니다. PowerShell을 열고 한 줄만 입력하면 됩니다.

📎 PowerShell (관리자 권한 불필요)

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

이 한 줄이면 Claude Code가 자동으로 다운로드되고 설치됩니다. Node.js도 필요 없어요. 설치가 끝나면 반드시 터미널을 닫았다가 새로 열어주세요. PATH가 갱신되어야 claude 명령어가 인식됩니다.

단, 하나 주의할 점이 있습니다. Claude Code는 내부적으로 Git Bash를 사용합니다. Git이 설치되어 있지 않으면 설치 과정에서 Git 설치를 안내할 거예요. Git for Windows 공식 사이트에서 미리 설치해두면 좋습니다.

📎 설치 확인

claude --version

버전 번호가 나오면 설치 성공입니다. 만약 'claude' is not recognized 에러가 나오면, 터미널을 닫았다 다시 열어보세요. 그래도 안 되면 뒤쪽 트러블슈팅 섹션을 확인하세요.

방법 B: WSL 설치 (리눅스 환경 선호 시)

리눅스 환경이 더 안정적이고 기능도 완전합니다. 특히 Bash 샌드박싱(보안 기능)을 쓰려면 WSL 2가 필요해요. 장기적으로 개발 환경을 제대로 세팅하고 싶은 분은 이 방법을 추천합니다.

📎 PowerShell (관리자 권한 필요) → WSL 설치

wsl --install -d Ubuntu

설치 후 컴퓨터 재시작 필요. Ubuntu 첫 실행 시 사용자 이름/비밀번호 설정.

WSL Ubuntu가 준비되면, Ubuntu 터미널에서 Claude Code를 설치합니다.

📎 Ubuntu (WSL) 터미널

curl -fsSL https://claude.ai/install.sh | bash
source ~/.bashrc
claude --version

 

STEP 1: Claude Code 설치 — Mac편

Mac은 훨씬 간단합니다. 터미널(Terminal.app)을 열고 아래 명령어를 입력하세요.

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

📎 Mac 터미널

curl -fsSL https://claude.ai/install.sh | bash
source ~/.zshrc
claude --version

방법 B: Homebrew 설치

Homebrew를 이미 쓰고 있다면 이 방법도 편합니다. 단, Homebrew 설치는 자동 업데이트가 안 되기 때문에 brew upgrade claude-code를 수동으로 해줘야 합니다.

📎 Homebrew

brew install --cask claude-code
claude --version

 

STEP 2: 인증 설정 — Claude 계정 연결하기

설치가 끝났으면 Claude Code를 실행해봅시다. 터미널에서 claude를 입력하면 처음 한 번은 인증(로그인) 과정을 거칩니다.

📎 첫 실행

claude

브라우저가 열리면서 OAuth 인증 페이지로 이동합니다.

인증 방법은 두 가지입니다.

① Claude Pro/Max 구독으로 로그인 (추천) — claude.ai 계정으로 바로 로그인합니다. Pro($20/월) 이상 구독이면 Claude Code가 구독에 포함되어 있어요. 별도 결제 없이 바로 사용 가능합니다.

② API 키로 인증 — Anthropic Console에서 API 키를 발급받아 사용하는 방식입니다. 사용한 만큼 토큰 비용이 청구돼요. 개발자이거나 팀 프로젝트에서 비용을 세밀하게 관리하고 싶을 때 적합합니다.

💰 요금제 비교 (2026년 2월 기준)

• Pro $20/월 ($17/월 연간): Claude Code 포함, 일반적인 개발에 충분

• Max 5x $100/월: Pro 대비 5배 사용량, Opus 4.6 접근, Agent Teams

• Max 20x $200/월: Pro 대비 20배 사용량, 제한 거의 없음

• API 종량제: Sonnet 4.5 — 입력 $3 / 출력 $15 (100만 토큰당)

→ 처음 시작하신다면 Pro $20/월이면 충분합니다.

인증이 완료되면 터미널에 Claude Code의 프롬프트가 나타납니다. 이렇게 생겼어요:

╭────────────────────────────────────╮
│ ✻ Welcome to Claude Code!         │
│                                    │
│   /help for available commands     │
╰────────────────────────────────────╯

> _

이 프롬프트가 보이면 성공입니다! 이제 여기에 자연어로 명령을 입력하면 됩니다.

 

STEP 3: VS Code와 연동하기

Claude Code는 터미널에서 직접 쓸 수도 있지만, VS Code 안에서 쓰면 훨씬 편합니다. 코드를 보면서 바로 옆에서 Claude Code한테 명령을 내릴 수 있으니까요.

방법은 간단합니다. VS Code를 열고, 내장 터미널(Ctrl+` 또는 ⌘+`)에서 claude를 실행하면 끝이에요. 별도 확장 프로그램 설치 없이 바로 사용할 수 있습니다.

📎 VS Code 터미널에서 실행

# 프로젝트 폴더로 이동
cd ~/my-project

# Claude Code 실행
claude

Windows 사용자 팁: VS Code의 기본 터미널을 Git Bash로 바꾸면 Claude Code가 훨씬 안정적으로 동작합니다. VS Code 설정(Ctrl+Shift+P → "Terminal: Select Default Profile")에서 Git Bash를 선택하세요. WSL을 쓴다면 "WSL Bash"를 선택하면 됩니다.

 

STEP 4: 첫 프로젝트 — "환율 계산기" 만들기

이론은 여기까지. 바로 만들어봅시다. Claude Code한테 간단한 파이썬 프로그램을 만들어달라고 해볼게요.

📎 1단계: 프로젝트 폴더 만들기

# Windows (PowerShell)
mkdir C:\Users\$env:USERNAME\my-first-project
cd C:\Users\$env:USERNAME\my-first-project

# Mac
mkdir ~/my-first-project
cd ~/my-first-project

📎 2단계: Claude Code 실행 후 명령하기

claude

> 원화를 달러로 환전하는 간단한 파이썬 계산기를 만들어줘. 
  환율은 사용자가 입력하게 하고, 수수료 1%를 자동으로 계산해줘.
  결과를 보기 좋게 출력해줘.

이렇게 입력하면 Claude Code가 exchange_calculator.py 파일을 직접 만들고 코드를 작성합니다. 화면에 뭘 하고 있는지 실시간으로 보여주기 때문에, 어떤 파일을 만들고 어떤 코드를 쓰는지 확인할 수 있어요.

파일이 만들어지면 바로 실행해봅시다.

📎 3단계: 실행 요청

> 방금 만든 파일 실행해줘

Claude Code가 python exchange_calculator.py를 실행하고, 환율 입력 → 원화 입력 → 수수료 계산 → 결과 출력까지의 과정을 보여줍니다. 여기서 한 발 더 나가볼까요?

📎 4단계: 기능 추가 요청

> 여기에 엔화, 유로 환전도 추가해줘.
  메뉴 선택 방식으로 만들고, 
  잘못된 입력 시 에러 처리도 넣어줘.

Claude Code가 기존 파일을 직접 수정합니다. 새로 만드는 게 아니라, 이미 있는 코드에 기능을 추가하는 거예요. 이게 에이전트형의 핵심이죠. 대화를 이어가면서 프로그램을 점점 발전시킬 수 있습니다.

 

CLAUDE.md — 프로젝트의 "설명서" 만들기

Claude Code에는 CLAUDE.md라는 특별한 파일이 있습니다. 프로젝트 폴더에 이 파일을 만들어두면, Claude Code가 작업을 시작할 때 자동으로 읽습니다. 일종의 "프로젝트 매뉴얼"이에요.

📎 CLAUDE.md 예시

# 환율 계산기 프로젝트

## 프로젝트 설명
원화를 외화로 환전하는 계산기 프로그램

## 기술 스택
- 언어: Python 3.11+
- 스타일: PEP 8 준수

## 규칙
- 함수명은 한글 주석 필수
- print 출력은 f-string 사용
- 에러 메시지는 한국어로 작성

이렇게 해두면 Claude Code가 "아, 이 프로젝트는 파이썬이고, 한국어 주석을 쓰고, PEP 8을 지켜야 하는구나"라고 이해합니다. 매번 같은 설명을 반복하지 않아도 되니까 작업 효율이 크게 올라가요.

 

자주 쓰는 슬래시 명령어 5가지

Claude Code 안에서 /로 시작하는 슬래시 명령어를 사용할 수 있습니다. 자주 쓰는 것만 정리하면:

• /help — 사용 가능한 명령어 전체 목록 확인

• /compact — 현재 대화를 요약해서 토큰 절약 (긴 작업 시 필수)

• /clear — 대화 초기화, 새로운 작업 시작할 때

• /model — AI 모델 전환 (Sonnet ↔ Opus 등)

• /cost — 현재까지 사용한 토큰 비용 확인

특히 /compact는 꼭 기억해두세요. Claude Code를 오래 사용하다 보면 대화 내용이 길어지면서 토큰 비용이 늘어나고 응답도 느려집니다. /compact를 실행하면 지금까지의 대화를 요약해서 압축하기 때문에 비용과 속도 모두 개선됩니다.

 

트러블슈팅 — 자주 발생하는 오류 5가지

설치 과정에서 문제가 생길 수 있습니다. 가장 흔한 오류와 해결법을 정리했어요.

❌ 오류 1: 'claude' is not recognized / command not found

가장 많이 발생하는 오류입니다. 설치는 됐는데 터미널이 claude 명령어를 찾지 못하는 거예요. 해결: 터미널을 완전히 닫고 새로 열어주세요. 그래도 안 되면 PATH를 수동으로 추가합니다.

📎 Mac/Linux PATH 수동 추가

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

❌ 오류 2: Node.js version 18 or higher required

이 메시지가 나오면 npm(구버전) 방식으로 설치된 경우입니다. 네이티브 설치로 전환하세요.

📎 네이티브로 마이그레이션

# 기존 npm 버전 제거
npm uninstall -g @anthropic-ai/claude-code

# 네이티브 설치
curl -fsSL https://claude.ai/install.sh | bash

❌ 오류 3: 인증 실패 / OAuth 에러

브라우저에서 로그인했는데 터미널에 반영이 안 되는 경우입니다. 해결: 브라우저 쿠키를 지우고 다시 시도하거나, claude doctor를 실행하세요.

❌ 오류 4: WSL에서 "Windows path" 관련 에러

WSL에서 Windows 쪽 Node.js가 잡히는 경우입니다. which node를 입력해서 경로가 /mnt/c/로 시작하면 문제예요. 해결: WSL 안에서 Node.js를 따로 설치하세요.

❌ 오류 5: 느린 응답 / 토큰 제한

Pro 요금제에서 오래 작업하면 속도 제한에 걸릴 수 있습니다. 해결: /compact로 대화를 압축하거나, /model로 Sonnet(더 빠름)으로 전환하세요.

💡 만능 진단 도구: claude doctor

어떤 문제든 먼저 claude doctor를 실행해보세요. 설치 상태, 인증 상태, PATH 설정 등을 자동으로 진단하고 해결법을 알려줍니다. 웬만한 문제는 이걸로 해결됩니다.

 

오늘 배운 핵심 정리

✅ Claude Code는 터미널에서 직접 파일을 만들고 실행하는 "에이전트형" AI 도구
✅ 2026년 최신: 네이티브 설치 추천 (npm은 deprecated)
✅ Windows: PowerShell 한 줄 또는 WSL / Mac: curl 한 줄로 설치
✅ Pro $20/월 구독이면 Claude Code 포함, 입문용으로 충분
✅ CLAUDE.md로 프로젝트별 규칙을 설정하면 효율 극대화
✅ 문제 발생 시 claude doctor가 만능 진단 도구

 

자주 묻는 질문 (FAQ)

Q. Claude Code는 무료로 쓸 수 있나요?

설치 자체는 무료입니다. 하지만 사용하려면 Claude Pro($20/월) 이상 구독이 필요합니다. 무료 플랜에서도 Claude Code를 실행할 수는 있지만, 사용량 제한이 매우 낮아서 실용적이지 않아요.

Q. Python이 설치되어 있지 않은데 파이썬 코드를 실행할 수 있나요?

아니요, Claude Code가 코드를 "만들어"주지만 "실행"하려면 해당 언어의 런타임이 필요합니다. 파이썬 코드를 실행하려면 Python이 설치되어 있어야 해요. 다만 Claude Code에게 "파이썬 설치해줘"라고 말하면 설치 방법을 안내하거나, 패키지 매니저로 직접 설치해주기도 합니다.

Q. ChatGPT를 이미 쓰고 있는데 Claude Code도 필요한가요?

목적이 다릅니다. ChatGPT는 "코드를 보여주는" 도구이고, Claude Code는 "코드를 직접 만들고 실행하는" 도구입니다. ChatGPT로 코드를 받아서 복사-붙여넣기하는 과정이 번거롭다면, Claude Code가 그 과정을 없애줍니다. 특히 여러 파일에 걸친 수정이나 프로젝트 단위 작업에서 차이가 크게 납니다.

Q. Claude Code와 Cursor, 뭘 쓰는 게 좋나요?

Cursor는 VS Code 안에서 코드를 제안하고 편집하는 "IDE 통합형"이고, Claude Code는 터미널에서 프로젝트 전체를 관리하는 "에이전트형"입니다. 둘 다 써도 됩니다. Cursor로 코드를 편집하면서, 큰 규모의 리팩토링이나 프로젝트 설정은 Claude Code로 하는 식으로 조합하면 효과적이에요.

 

다음 편 예고

3편: VS Code 완벽 세팅 — 개발 생산성을 10배 올리는 확장 프로그램

Claude Code를 설치했으니, 이제 개발 환경을 제대로 세팅할 차례입니다. 다음 편에서는 VS Code의 필수 확장 프로그램, 테마, 단축키, Git 연동, 터미널 설정까지 — 생산성을 극대화하는 세팅법을 다룹니다.

 

💰 이 기술을 투자 분석에 적용하면?

Claude Code로 환율 계산기를 만들어봤죠? 이런 AI 도구가 실제 금융 시장에서는 어떻게 활용되고 있는지
MoneyTrendLab — AI가 주식시장을 지배하고 있다에서 확인해보세요.

 

📚 AI 테크 마스터 시리즈 전체 목록

01편: 2026년 AI 프로그래밍 트렌드 — 코딩 못해도 AI로 개발하는 시대
▶ 02편: Claude Code 완전 가이드 — 설치부터 첫 프로젝트까지 (현재 글)
03편: VS Code 완벽 세팅 — 생산성을 10배 올리는 확장 프로그램
04편: 파이썬 기초 속성 — AI 프로그래밍에 필요한 것만 2시간에
05편: 파이썬 데이터 분석 기초 — pandas와 matplotlib
06~24편: 순차 공개 예정

 

이 글은 2026년 2월 기준으로 작성되었습니다. Claude Code의 설치 방법, 요금제, 기능은 Anthropic의 업데이트에 따라 변경될 수 있습니다. 최신 정보는 공식 문서를 참고하세요.