Claude Code 설치 방법 완벽 가이드

Node.js 세팅부터 CLAUDE.md 설정까지 10분 완성

환경 구축에서 포기하는 사람이 생각보다 많다

"환경 구축"이라는 단어를 보자마자 브라우저 탭을 닫고 싶어진 적 있지 않나?

그 마음 안다. 나도 새 툴 세팅하다가 마음이 꺾인 게 한두 번이 아니다. Node.js 버전 안 맞아서 에러. API 키 설정했다고 생각했는데 환경변수가 안 잡혀서 Unauthorized가 나오고... 공식 문서 그대로 따라 했는데 안 된다. 주말 오후를 통째로 날리고 "나중에 하지 뭐"라며 조용히 터미널 닫기를 시전한다.

안심해도 된다. Claude Code 세팅은 진짜로 10분이면 끝난다. 내가 직접 빠졌던 함정까지 전부 짚어가며 하나씩 넘어가겠다.

시작 전 확인: 필요한 것

아래 네 가지만 있으면 준비 완료다.

설치

npm으로 글로벌 설치한다. 딱 한 줄이다.

# npm으로 글로벌 설치
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

여기서 command not found가 뜨면 Node.js가 없거나 버전이 낮은 것이다. 아래 명령어로 확인하자.

node --version
# v18.0.0 이상이어야 한다

가장 흔한 함정: Node.js 버전
나도 겪었다. 다른 프로젝트에서 쓰던 Node.js v16이 그대로 남아있어서,
npm install은 아무 문제없이 통과하는데 claude 명령어가 실행이 안 됐다. 30분 동안 이것저것 시도하다. node --version 쳐보고 바로 해결됐다. 설치 전에 Node.js 버전부터 확인하는 게 정답이다.

Windows 사용자 전용 설정
Claude Code는 네이티브 Windows 환경에서 동작하지 않는다. WSL2(Windows Subsystem for Linux) 를 통해 실행해야 한다. 이미 WSL2가 설치된 경우 아래 Node.js 설치 단계부터 진행하면 된다.

# WSL2 설치 (PowerShell을 관리자 권한으로 실행)
wsl --install

# WSL2 내에서 Node.js 설치 (Ubuntu 기준)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 또는 nvm 설치 진행도 가능
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

# Node.js 설치
nvm install 24

# 설치 확인
node -v # 현재 LTS기준 v24.14.0

# Claude Code 설치
npm install -g @anthropic-ai/claude-code

Windows Terminal에서 Ubuntu 탭을 열고 작업하면 가장 편하다. WSL2 파일시스템과 Windows 파일시스템 간 접근도 자유롭다.

인증 설정

설치 완료 후 다음은 인증이다. 사용 목적에 따라 두 가지 방법 중 선택한다.

방법 1: Anthropic 계정 직접 로그인 (개인 개발자에게 권장)

가장 간단하다. claude를 실행하면 첫 실행 시 자동으로 브라우저가 열리고 인증 플로우가 시작된다.

claude
# 브라우저가 열리며 Anthropic 계정 로그인 화면이 뜬다
# 로그인 완료 후 터미널로 돌아오면 인증 완료

Max 플랜(월 정액) 사용자와 API 종량제 사용자 모두 이 방법으로 인증할 수 있다.

방법 2: API 키 환경변수 설정 (CI/CD·자동화 스크립트용)

GitHub Actions, Jenkins 같은 자동화 파이프라인에 통합할 때는 이 방법을 사용한다.

# 현재 세션에서만 설정 (터미널 닫으면 사라짐)
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"

# 영구적으로 설정 (.zshrc 또는 .bashrc에 추가)
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

API 키는 Anthropic Console에서 발급받는다. 한국에서도 가입과 결제가 정상 지원된다.

실수하기 쉬운 포인트
.zshrc에 API 키를 추가한 뒤 source ~/.zshrc를 빠트리면 새 터미널에서도 적용이 안 된다. 수정 후 반드시 source ~/.zshrc를 실행하거나 터미널을 새로 열자.

보안 주의: 이건 진짜 중요하다
API 키는 절대 코드에 직접 써서 Git에 올리면 안 된다. .env 파일에 분리해서 관리하고, 반드시 .gitignore에 .env를 추가해야 한다. GitHub에 올라간 API 키는 수 분 내에 자동 크롤러에 의해 수집되고, 예상치 못한 과금으로 이어진 실제 사례가 많다. .env.example 파일로 키 형식만 공유하는 것이 표준 관행이다.

첫 번째 실행

이제 진짜 시작이다.

# 프로젝트 디렉토리로 이동한 뒤 실행
cd ~/my-project
claude

# 실행하면 아래와 같은 인터페이스가 나타난다
# ╭────────────────────────────────────────╮
# │ Claude Code │
# │ │
# │ Project: my-project │
# │ Model: claude-sonnet-4-6 │
# ╰────────────────────────────────────────╯
# >

이 프롬프트가 뜨는 순간이 꽤 특별하다. Claude Code는 첫 실행 시 프로젝트 구조를 자동으로 스캔해 코드베이스 전체를 파악한다. 아무것도 설명하지 않아도 이미 프로젝트를 이해하기 시작한 상태다.

모델 선택: 용도에 맞게 구분해서 써야 비용을 아낀다

Claude Code는 사용할 모델을 직접 선택할 수 있다. 모델 선택이 비용과 품질에 직결되기 때문에 이 부분은 제대로 이해해두는 게 좋다.

# Opus — 최고 성능, 고비용
claude --model claude-opus-4-6

# Sonnet — 균형형, 권장 (기본값)
claude --model claude-sonnet-4-6

# Haiku — 경량, 저비용
claude --model claude-haiku-4-5-20251001

실제 사용 구분 기준을 정리하면 이렇다.

처음엔 Sonnet으로 시작해서 감을 익히고, "이 문제는 좀 더 깊이 있는 답변이 필요하다" 싶을 때 Opus로 전환하는 방식이 가장 현실적이다.

CLAUDE.md — 이걸 쓰느냐 안 쓰느냐로 체감 품질이 완전히 달라진다

Claude Code 활용에서 가장 과소평가받는 설정이 바로 CLAUDE.md다.

프로젝트 루트에 CLAUDE.md 파일을 두면, Claude Code가 해당 프로젝트에 진입할 때마다 이 파일을 자동으로 읽어 맥락을 잡는다. 이게 실제로 엄청난 차이를 만든다.

CLAUDE.md가 없으면 매번 이렇게 시작해야 한다.

"이 프로젝트는 Next.js 16, TypeScript 기반이고, 테스트는 Vitest 써요. 커밋 메시지는 Conventional Commits 형식으로 작성해야 하고, 클래스 컴포넌트는 쓰지 말고……"

CLAUDE.md가 있으면 이런 전제 설명이 완전히 사라진다.

바로 본론부터 시작할 수 있다.

# CLAUDE.md

## 프로젝트 개요
Next.js 15 기반 이커머스 플랫폼. B2C 쇼핑몰이며 일 평균 방문자 1만 명 규모.

## 기술 스택
- 프레임워크: Next.js 16 (App Router)
- 언어: TypeScript 5.x (strict 모드)
- DB: PostgreSQL 17 + Prisma ORM
- 스타일링: Tailwind CSS v3
- 테스트: Vitest (유닛) + Playwright (E2E)
- 배포: Vercel (프론트) + AWS RDS (DB)

## 코딩 규칙
- 함수형 컴포넌트만 사용 (클래스 컴포넌트 금지)
- 상태 관리: useState, useReducer만 사용 (Zustand, Redux 등 금지)
- API 라우트 경로: `/api/v1/` 하위에 배치
- 커밋 메시지: Conventional Commits 형식 (`feat:`, `fix:`, `chore:` 등)
- 에러 처리: 모든 API 호출에 try-catch 필수

## 자주 쓰는 명령어
- `npm run dev`: 개발 서버 실행 (포트 3000)
- `npm run test`: 유닛 테스트 실행
- `npm run test:e2e`: E2E 테스트 실행
- `npm run lint`: ESLint + Prettier 실행
- `npm run build`: 프로덕션 빌드

## 디렉토리 구조
src/
app/ - 페이지 및 레이아웃 (App Router)
components/ - 재사용 UI 컴포넌트
lib/ - 유틸리티, 헬퍼 함수
types/ - TypeScript 타입 정의
prisma/ - DB 스키마 및 마이그레이션
tests/ - 테스트 파일 (유닛/E2E)

작성할 때 좋은 기준은 "신규 팀원이 온 첫날 꼭 알아야 할 것들" 이다. 기술 스택, 코딩 규칙, 자주 쓰는 명령어, 디렉토리 구조. 이것만 잘 써놔도 Claude Code의 응답 품질이 눈에 띄게 달라진다.

CLAUDE.md 활용 팁
- 프로젝트 루트에 두는 것이 기본. Claude Code가 자동으로 감지한다
- ~/.claude/CLAUDE.md 에 글로벌 설정을 두면 모든 프로젝트에 공통 적용된다 (선호하는 코딩 스타일, 언어 설정 등)
- 서브디렉토리에도 CLAUDE.md를 두면 해당 디렉토리에서만 적용되는 별도 지시를 넣을 수 있다 (예: src/api/CLAUDE.md에 API 관련 규칙만 별도 정의)
- 팀 프로젝트라면 Git에 커밋해서 팀원 전체가 공유하는 것이 좋다. 온보딩 문서 역할도 겸한다

권한 설정: 처음엔 기본값으로 시작하자

Claude Code가 파일을 쓰거나 명령어를 실행할 때, 기본값에서는 매 작업마다 확인을 요청한다. 처음엔 이게 조금 번거롭게 느껴질 수 있다. 그래도 처음부터 전체 권한을 열어줄 필요는 없다.

# 모든 작업을 자동 승인 (숙련자용)
claude --dangerously-skip-permissions

이 플래그 이름을 잘 보자. dangerously-skip-permissions. 이름에 "위험(dangerously)"이라고 대놓고 써있다. Anthropic이 일부러 이렇게 이름 붙인 건 그만한 이유가 있다.

권장 순서는 이렇다:

기본값(매번 확인)으로 시작한다

Claude Code가 어떤 파일을 건드리고, 어떤 명령어를 실행하는지 패턴을 파악한다

"이 정도는 자동으로 해도 되겠다" 싶어지면 그때 설정을 완화한다

신뢰가 쌓이기 전에 전권을 주는 건 협업이 아니라 방임이다. 특히 업무용 코드나 프로덕션 환경과 연결된 프로젝트에서는 더욱 신중하게 접근하자.

동작 확인: 첫 번째 대화

세팅이 다 됐으면 제대로 동작하는지 확인해보자.

# 빈 디렉토리 만들어서 테스트
mkdir ~/claude-test && cd ~/claude-test

# Claude Code 실행
claude

# 아래처럼 입력
> 안녕하세요! 간단한 Python Hello World 스크립트를 작성해주세요

Claude Code가 hello.py를 생성하고 실행까지 완료했다면 세팅은 끝이다.

이 순간 이상하게 감동적이다. 내가 입력한 말이 그대로 실행되고, 파일이 생기고, 코드가 작성되고, 실행 결과가 돌아온다. 지금까지 써온 AI 도구들과는 뭔가 다르다는 느낌이 분명히 있다. 그 감각이 맞다.

VS Code와 함께 쓰기

평소 VS Code를 메인 에디터로 쓴다면 통합 터미널에서 Claude Code를 실행하는 게 가장 자연스럽다.

# VS Code 통합 터미널에서 실행
claude

# VS Code 마켓플레이스에서 확장 기능도 설치 가능
# "Claude Code" 검색 후 설치

VS Code 확장 기능을 설치하면 사이드바에서 Claude Code를 조작할 수 있고, 파일 변경 diff가 에디터 내에서 바로 시각적으로 표시된다. "어떤 코드가 어떻게 바뀌었는지"를 에디터 안에서 확인하면서 작업하고 싶다면 확장 기능을 활성화해두는 게 편하다.

IntelliJ 계열(WebStorm, PyCharm 등)을 쓰는 개발자라면 내장 터미널에서 claude를 실행하면 된다. 별도 플러그인 없이 바로 사용 가능하다.

여기까지 왔다면 Claude Code가 실행되는 상태가 된 것이다. 설치, 인증, 첫 실행, CLAUDE.md 설정까지. 이것만으로 AI 에이전트와 함께 개발할 기반이 갖춰졌다.

다음 챕터에서는 Claude Code의 기본 조작법으로 들어간다. 지시를 어떻게 내리는지, 실제 워크플로는 어떻게 구성하는지. 직접 손을 움직이면서 바이브 코딩의 감각을 익혀보자.

✅ 정리

npm install -g @anthropic-ai/claude-code 로 설치 (Node.js v18 이상 필수)

Anthropic 계정 로그인 또는 API 키 환경변수 설정으로 인증

CLAUDE.md에 프로젝트 맥락을 담아두면 AI 응답 품질이 즉시 달라진다

모델은 Sonnet(일상) / Opus(복잡한 작업) / Haiku(경량 작업)로 나눠 쓴다

권한 설정은 기본값부터 시작해서 신뢰가 쌓이면 단계적으로 확장한다

---

©2024-2026 MDRules dev., Hand-crafted & made with Jaewoo Kim.

이메일문의: jaewoo@mdrules.dev

AI강의/개발/기술자문, Claude Code 전문강의, AI 업무 자동화 컨설팅 문의: https://talk.naver.com/ct/w5umt5

MDRules Dev - 네이버톡톡

AI 업무 자동화/에이전트/워크플로우설계 컨설팅/AI교육: https://mdrules.dev

MDRules Dev — AI 에이전트 경영과 AI 교육으로 차세대 경영 모델을 구축합니다