[Claude Code 실전 정복 #1] 설치부터 첫 실행까지 — 7년차 개발자가 겪은 진짜 과정 (2026)

시리즈: Claude Code 실전 정복 | 1편

작성자: 체리플랜 | 7년차 프론트엔드 개발자

---

하루 종일 구글링해도 안 풀리던 문제가 터미널 한 줄로 해결됐어요.

7년 동안 개발하면서 처음으로 "이건 진짜 혁명이다" 싶은 순간이었어요.

Claude Code 쓰기 전에는 이랬어요. 에러 메시지 복사 → 구글 검색 → Stack Overflow 찾기 → 버전 다르다고 적용 안 됨 → 다시 검색 → 유튜브 튜토리얼 → 따라해도 안 됨 → 또 검색. 이 사이클을 하루에 몇 번씩 반복했어요.

Claude Code 쓰면서 바뀐 건 단순해요. 지금 상황을 말로 설명하면 Claude가 프로젝트 파일을 직접 읽고, 원인을 찾고, 코드를 수정해요. 제가 구글링하던 시간이 그냥 없어졌어요.

이번 편에서는 Claude Code 설치 과정 — 특히 제가 직접 겪은 Node.js 버전 문제 해결 과정까지 포함해서 처음부터 정리해볼게요. 공식 문서 기반으로 2026년 최신 내용으로 작성했어요.

 

---

Claude Code가 뭔데요?

한 줄로 요약하면 터미널에서 실행하는 AI 코딩 어시스턴트예요.

일반 AI 채팅(Claude.ai, ChatGPT)과 결정적으로 다른 게 있어요. 채팅 기반 AI는 코드를 보여주면 "이렇게 고치세요"라고 알려줘요. 직접 수정은 못 해요. 제가 복사해서 붙여넣어야 해요.

Claude Code는 달라요. 프로젝트 파일을 직접 읽고, 직접 수정하고, 터미널 명령어도 실행해요. 그냥 "이 버그 고쳐줘"하면 파일 열어서 코드 바꾸고 저장까지 해요.

주요 기능:

• 프로젝트 전체 파일 구조 파악
• 파일 직접 읽기 / 수정 / 생성
• 터미널 명령어 실행 (npm install, git commit 등)
• Git 히스토리 분석
• 에러 디버깅 및 수정

바이브코딩으로 사이드 프로젝트 만드는 분들한테 특히 강력해요.

\아이디어 말로 설명하면 프로젝트 구조부터 컴포넌트까지 잡아줘요.

---

설치 전에 먼저 확인할 것

https://code.claude.com/docs/ko/overview

Claude Code 개요 - Claude Code Docs

https://claude.ai/

Claude

 

계정 요건

Claude Code는 유료 Anthropic 계정이 필요해요.

• Claude Pro ($20/월): 대부분의 개인 개발자에게 충분
• Claude Max ($100~200/월): 헤비 유저, 높은 rate limit 필요할 때
• Anthropic Console (API 종량제): 팀/기업 환경

무료 계정으로는 사용 불가예요. 이거 모르고 설치했다가 인증 단계에서 막히는 분들 많으니까 먼저 확인하세요.

 

운영 체제 지원

• macOS: 13.0 (Ventura) 이상
• Linux: Ubuntu 20.04+ 또는 Debian 10+
• Windows: WSL2 또는 Git Bash 필요 (네이티브 미지원)

윈도우 사용자분들 — 직접 실행이 안 되는 게 아니라, WSL2나 Git Bash 환경에서 실행해야 해요. 그냥 cmd나 PowerShell에서 바로 돌리려 하면 안 돼요.

---

설치 방법 — 2026년 기준 권장 방법

2026년 현재 Anthropic 공식 권장 설치 방법이 바뀌었어요.

예전엔 npm install -g @anthropic-ai/claude-code 가 기본이었는데, 지금은 네이티브 인스톨러가 공식 권장이에요.

방법 1: 네이티브 인스톨러 (권장)

macOS / Linux:

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

Windows (PowerShell):

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

이 방법의 장점:

• Node.js 설치 필요 없음
• 백그라운드 자동 업데이트
• 의존성 충돌 없음

설치 후 새 터미널 창 열고 버전 확인:

claude --version

버전 번호 뜨면 설치 성공이에요.

---

방법 2: npm 설치 (Node.js 환경에서)

npm install -g @anthropic-ai/claude-code

⚠️ 중요: sudo npm install -g 절대 금지예요. 권한 문제 + 보안 위험 생겨요. 권한 오류 뜨면 sudo 쓰지 말고 nvm으로 해결하세요 (아래 참고).

npm 방식은 Node.js 18 이상 필요해요.

---

제가 겪은 실제 에러 — Node.js 버전 문제

저는 현업 프로젝트가 레거시라서 Node.js 구버전을 쓰고 있었어요.

node --version 치면 v16.x 나오는 상황이었어요. Claude Code는 Node.js 18 이상이 필요해서, npm 방식으로 설치하려니까 바로 에러가 났어요.

이걸 해결한 게 nvm (Node Version Manager)이에요.

nvm으로 Node.js 버전 관리하는 법

nvm 설치 (macOS/Linux):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

설치 후 터미널 재시작하고:

# 현재 LTS 버전 설치
nvm install --lts

# LTS 버전으로 전환
nvm use --lts

# 버전 확인
node --version
# v22.x.x 나오면 정상

그리고 프로젝트마다 버전 다르게 쓰고 싶으면:

# 회사 프로젝트 폴더에서
nvm use 16

# 사이드 프로젝트 폴더에서
nvm use 22

7년 개발하면서 Node.js 버전 때문에 고생한 게 한두 번이 아니었는데, nvm 쓰고 나서 이 문제가 완전히 사라졌어요. Claude Code 설치 계기로 nvm까지 세팅하게 됐는데, 결과적으로 개발 환경이 훨씬 정리됐어요.

💡 팁: 네이티브 인스톨러 방식은 Node.js 버전과 무관하게 설치돼요. Node.js 버전 문제가 귀찮으면 네이티브 인스톨러 쓰세요.

---

설치 후 인증 — API 키 설정

설치 완료 후 처음 claude 명령어 실행하면 인증 과정이 시작돼요.

claude

브라우저가 자동으로 열리면서 Anthropic 계정 로그인 화면이 나와요. 로그인하고 권한 허용하면 터미널로 인증 토큰이 자동으로 돌아와요.

📸 [스크린샷: 브라우저 인증 화면 — 여기에 이미지 첨부]

CI/CD나 서버 환경처럼 브라우저가 없는 환경은 API 키 방식으로 인증해요:

export ANTHROPIC_API_KEY="your-api-key-here"

Anthropic Console (console.anthropic.com)에서 API 키 발급받을 수 있어요.

---

설치 확인 — 진단 명령어

인증까지 완료했으면 환경 진단 명령어 한 번 돌려보세요:

claude doctor

이 명령어가 Node.js 버전, 인증 상태, 파일 권한, MCP 서버 상태까지 자동으로 체크해줘요. 설치 직후 문제 있으면 여기서 바로 잡을 수 있어요.

주요 슬래시 명령어도 미리 알아두면 좋아요:

/help    — 전체 명령어 목록
/config  — 환경설정
/clear   — 현재 대화 초기화
/compact — 대화 요약 (토큰 절약)
/quit    — 종료

---

첫 실행 — 프로젝트 폴더에서 시작하기

설치 완료했으면 실제 프로젝트 폴더로 이동해서 실행해보세요.

cd my-project
claude

Claude Code가 프로젝트 구조를 자동으로 읽어요. 그 다음에 자연어로 요청하면 돼요.

처음 해볼 만한 것들:

> 이 프로젝트 구조 설명해줘
> package.json에 있는 의존성 중 오래된 것들 있으면 알려줘
> src/components 폴더에 어떤 컴포넌트들이 있어?

저는 처음 실행했을 때 cherryplan 허브 프로젝트 폴더에서 시작했어요.

"이 프로젝트 구조 파악하고 현재 문제점 있으면 알려줘"

라고 했더니 파일 구조를 전부 읽고, 의존성 버전 체크하고, CSS 관련 잠재 이슈까지 찾아줬어요. 이게 10초도 안 걸렸어요.

그 순간 "아, 이게 진짜 다른 도구구나" 싶었어요.

---

유료 요금 — 얼마나 나오냐면

Claude Pro ($20/월) 구독하면 Claude Code 포함이에요.

API 종량제 방식도 있는데, 일반적인 개발 작업 기준으로는 Claude Pro가 훨씬 효율적이에요. 헤비하게 쓰는 분들은 Claude Max ($100~200/월)로 올라가면 rate limit이 확 높아져요.

한 가지 주의할 게 있어요. 세션이 길어지고 컨텍스트가 쌓이면 토큰을 많이 써요. 실제로 쓰다 보면 /compact 명령어로 대화 요약해서 토큰 아끼는 습관이 생겨요. 이건 2편에서 자세히 다룰게요.

---

솔직한 한계

설치 과정 자체는 어렵지 않은데, 한 가지 걸리는 게 있어요.

유료 구독 필수라는 점이에요. 무료로 체험해볼 수가 없어요. "써보고 결정하고 싶다"는 분들한테는 이게 진입 장벽이에요.

그리고 Windows 사용자는 WSL2 세팅이라는 한 단계가 더 있어요. WSL2 자체가 어렵진 않지만, 처음 해보면 30분~1시간 추가로 잡아요.

저는 macOS 기준으로 쓰고 있어서 이 부분은 경험 밖이에요. Windows 분들은 공식 문서의 WSL2 섹션 참고하세요.

---

마무리: 설치는 시작일 뿐이에요

Claude Code 설치 자체는 5분이면 끝나요.

진짜 차이는 설치 후 어떻게 쓰느냐에서 나와요. 다음 편에서는 Claude Code를 실제로 어떻게 쓰는지 — VS Code 연동, 기본 워크플로우, 토큰 절약하는 프롬프트 패턴까지 정리할게요.

7년 개발하면서 쌓인 제 실무 방식이 Claude Code 만나면서 어떻게 바뀌었는지 구체적으로 보여드릴게요.

 

https://cherrycoding0.tistory.com/47

[Claude Code 실전 정복 #2] VS Code 연동 + 실전 워크플로우 — 7년차 개발자의 프롬프트 패턴 공개 (2026

 

---

https://cherrycoding0.tistory.com/48

[Claude Code 실전 정복 #3] CLAUDE.md 완전 정복 — 설정 한 번으로 매 세션이 달라지는 이유 (2026)