"Claude Code 설치했는데 뭘 해야 할지 모르겠어요." — AI 개발 커뮤니티에서 가장 많이 보이는 말입니다. 인터넷에 설치 방법은 넘쳐나지만 설치 이후 30분에 대해 제대로 알려주는 곳은 거의 없습니다.
처음 Claude Code를 설치했을 때 가장 막혔던 부분은 "이제 뭘 하지?"였습니다. 터미널에 claude를 입력해서 실행은 됐는데, 그냥 쓰면 챗GPT와 다를 게 없었습니다. CLAUDE.md를 만들고 프로젝트 루트에서 실행하는 습관을 들이고 나서야 체감이 확 달라졌습니다. 이 글은 그 경험을 바탕으로 씁니다. Claude Code를 처음 시작하는 개발자가 설치부터 실전 투입까지 막힘 없이 진행할 수 있도록, 2026년 4월 현재 실제로 동작하는 설정과 자주 만나는 오류 해결법 중심으로 정리했습니다.
1. Claude Code란? — 설치 전에 알아야 할 핵심 개념
Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 어시스턴트입니다. 웹 채팅이나 IDE 플러그인이 아니라, 개발자가 이미 사용하는 터미널 환경에서 직접 동작합니다. 파일 시스템에 접근하고, Git과 연동하며, 실제 파일을 읽고 수정하는 일을 합니다.
가장 큰 강점은 긴 컨텍스트 처리 능력입니다. 2026년 4월 기준 Sonnet 4.6 모델은 표준 가격의 1M 컨텍스트 윈도우를 지원해, 대규모 코드베이스 전체를 한 세션에서 이해하고 분석할 수 있습니다. 여러 파일에 걸친 리팩토링, 버그 추적, 프로젝트 구조 분석이 특히 강합니다.
💡 Claude Code vs Cursor — 한 줄 요약
Claude Code = 깊은 분석 · 대형 프로젝트 이해 · CLI 중심 | Cursor = 빠른 인라인 편집 · GUI 중심 · 즉각적인 수정
사용 조건 (2026년 4월 기준): Claude Pro 이상 구독 또는 Anthropic Console API 계정이 필요합니다. Node.js 18 이상이 사전 설치되어 있어야 합니다.
2. OS별 설치 방법 (Mac · Windows · Linux)
설치 자체는 어렵지 않습니다. 단, 절대로 sudo npm install을 사용하지 마세요. 권한 충돌의 원인이 됩니다. nvm을 사용하면 모든 것이 홈 디렉토리에 설치되어 충돌이 없습니다.
| OS | 추천 방법 | 설치 명령 |
|---|---|---|
| Mac | Homebrew 또는 npm | brew install claude-code |
| Windows | 네이티브 설치 (Git Bash 필요) | npm install -g @anthropic-ai/claude-code |
| Linux | apt / dnf / apk 저장소 | npm install -g @anthropic-ai/claude-code |
설치 후 터미널에서 claude를 입력하면 CLI가 실행됩니다. 처음 실행 시 표시 스타일(라이트/다크 모드)을 선택하고, 브라우저를 통해 Claude 계정을 연결합니다. 연결이 완료되면 터미널에 성공 메시지가 뜹니다.
⚠️ Windows 사용자 주의: PowerShell 또는 CMD에서 설치 후 claude 실행 시 Git Bash가 설치되어 있으면 Claude Code는 내부적으로 Git Bash를 통해 명령을 처리합니다. Git for Windows를 먼저 설치하세요.
3. 설치 후 반드시 해야 할 5가지 초기 설정
대부분의 사람이 설치 후 바로 막히는 이유는 이 단계를 건너뛰기 때문입니다. 아래 5가지를 설정하면 Claude Code의 성능이 눈에 띄게 달라집니다.
① 모델 선택 — 용도에 맞게 고르세요
일반 코딩 작업에는 Sonnet 4.6이 최적입니다. 복잡한 아키텍처 설계나 까다로운 버그 추적에는 Opus 4.7(Max/Team 플랜 필요)을 씁니다. 단순 탐색·검색은 Haiku로 비용을 아낄 수 있습니다. /model 명령어로 언제든 전환 가능합니다.
② 업데이트 채널 설정 — latest vs stable
새 기능을 바로 받고 싶다면 latest 채널, 안정성이 중요하다면 stable 채널을 선택합니다. /config → 자동 업데이트 채널에서 설정하거나 settings.json에 직접 추가할 수 있습니다. 네이티브 설치 방식은 백그라운드 자동 업데이트를 지원해 별도 관리가 필요 없습니다.
③ 프로젝트 루트에서 실행하는 습관
Claude Code는 실행한 디렉토리를 프로젝트 루트로 인식합니다. 항상 프로젝트 최상위 폴더에서 claude를 실행하세요. 엉뚱한 폴더에서 실행하면 파일 참조가 꼬이거나 의도치 않은 파일이 수정될 수 있습니다.
④ Git 연동 확인
Claude Code는 Git과 직접 연동됩니다. 브랜치 생성, 커밋, PR 생성까지 터미널 한 곳에서 처리할 수 있습니다. Git이 초기화된 프로젝트에서 시작해야 이 기능을 제대로 활용할 수 있습니다. git init이 선행되었는지 반드시 확인하세요.
⑤ VS Code 확장 또는 JetBrains 플러그인 설치 (선택)
터미널 이외에 GUI 환경을 원한다면 VS Code 확장 프로그램을 설치하세요. 채팅 패널, 체크포인트 기반 실행 취소, @-멘션 파일 참조 등 추가 기능을 편집기 안에서 사용할 수 있습니다. JetBrains 플러그인도 현재 베타로 제공 중입니다.
4. CLAUDE.md — Claude를 내 프로젝트 전문가로 만드는 파일
CLAUDE.md는 프로젝트 루트에 두는 특수 파일입니다. Claude Code가 매 세션 시작 시 자동으로 읽어 프로젝트 컨텍스트를 이해합니다. 쉽게 말해 "이 프로젝트에서 Claude가 알아야 할 모든 것"을 적어두는 설정 파일입니다.
이 파일을 만들기 전에는 매번 "이 프로젝트는 Next.js고, TypeScript strict 쓰고, 이 폴더는 건드리면 안 돼"를 반복해서 설명해야 했습니다. CLAUDE.md 하나 만들고 나서 그 설명이 전부 사라졌습니다. 처음엔 번거롭게 느껴지지만, 두 번째 세션부터 효과가 바로 보입니다.
아래가 실전에서 바로 쓸 수 있는 기본 구조입니다.
# 프로젝트명
## 기술 스택
- Framework: Next.js 15 (App Router)
- DB: PostgreSQL + Prisma ORM
- 스타일: Tailwind CSS
## 코딩 규칙
- TypeScript strict 모드 사용
- 함수형 컴포넌트만 사용 (클래스 컴포넌트 금지)
- 커밋 메시지: Conventional Commits 형식
## 절대 건드리지 말 것
- /legacy 폴더 (레거시 코드, 추후 마이그레이션 예정)
- .env 파일 직접 수정 금지
프로젝트가 커질수록 CLAUDE.md의 가치는 올라갑니다. 팀으로 사용할 경우 이 파일을 Git에 커밋해 팀원 모두가 동일한 컨텍스트를 Claude에게 제공할 수 있습니다.
5. 초보자가 가장 많이 하는 실수 3가지
❌ 실수 1 — 프로젝트 전체를 무작정 던진다
"이 프로젝트 전체를 분석해줘"처럼 범위 없는 요청은 컨텍스트 소모가 크고 결과물이 흐릿해집니다. 대신 파일 또는 모듈 단위로 범위를 좁혀서 질문하세요.
❌ 실수 2 — 요청이 너무 추상적이다
"코드 좀 깔끔하게 해줘"가 아니라 "이 파일의 중복된 API 호출 로직을 커스텀 훅으로 분리해줘"처럼 구체적인 행동과 목적을 명시해야 정확한 결과가 나옵니다.
❌ 실수 3 — 한 번에 완성을 기대한다
Claude Code는 에이전트입니다. 복잡한 작업은 /plan 명령어로 계획을 먼저 확인하고 승인한 뒤 실행하는 습관을 들이세요. 큰 작업은 단계별로 나눠 진행하면 오류가 훨씬 줄어듭니다.
6. 바로 쓸 수 있는 실전 프롬프트 템플릿
아래 템플릿은 Claude Code에서 실제로 잘 작동하는 구조입니다. 복사해서 바로 사용하세요.
# 구조 분석
/plan 이 프로젝트의 디렉토리 구조를 분석하고 개선이 필요한 부분과 우선순위를 알려줘
# 범위 제한 리팩토링
src/utils/api.ts 파일만 리팩토링해줘. 다른 파일은 절대 건드리지 마.
# 버그 추적
로그인 후 대시보드로 리다이렉트가 안 되는 버그야. 관련 파일들을 추적하고 원인을 찾아줘.
# Git 자동화
feat/user-auth 브랜치를 만들고, 지금까지 수정한 내용을 커밋해줘. PR 설명도 작성해줘.
7. Cursor와 함께 써야 하는 이유
Claude Code를 세팅했다면 다음 단계는 Cursor와의 조합입니다. 두 도구는 경쟁 관계가 아니라 역할이 다른 파트너입니다.
| 상황 | Claude Code | Cursor |
|---|---|---|
| 대형 코드베이스 분석 | ✅ 최적 | △ 가능 |
| 빠른 인라인 코드 수정 | △ 가능 | ✅ 최적 |
| Git 자동화 | ✅ 최적 | △ 가능 |
| 새 기능 빠른 프로토타입 | △ 가능 | ✅ 최적 |
두 도구를 같이 쓰는 실전 워크플로우가 궁금하다면 → [[관련 정보: Cursor + Claude Code 실전 워크플로우 - 혼자 쓰면 반쪽, 같이 써야 터진다]]
8. 자주 발생하는 설치 오류와 해결 방법
설치 글을 몇 개 읽어도 막히는 이유는 대부분 이 파트가 빠져 있기 때문입니다. 커뮤니티에서 가장 자주 올라오는 오류 5가지를 원인과 해결책까지 정리했습니다.
🔴 오류 1 — command not found: claude
원인: npm 전역 설치 경로가 시스템 PATH에 등록되지 않은 상태.
해결: nvm을 사용해 재설치합니다. curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash → nvm install 22 → npm install -g @anthropic-ai/claude-code 순서로 진행합니다. 이후 터미널을 완전히 종료했다가 다시 열면 적용됩니다.
🔴 오류 2 — Node.js 버전 오류 (engine mismatch)
원인: Claude Code는 Node.js 18 이상을 요구합니다. 구버전이 설치된 환경에서 자주 발생합니다.
해결: node --version으로 버전을 확인합니다. 18 미만이면 nvm install 22 && nvm use 22로 업그레이드 후 Claude Code를 재설치합니다.
🔴 오류 3 — npm 권한 오류 (EACCES permission denied)
원인: sudo npm install을 사용했거나 npm 기본 디렉토리가 시스템 폴더에 설정된 경우.
해결: nvm으로 Node.js를 관리하면 모든 설치가 홈 디렉토리에 이루어져 권한 문제가 완전히 사라집니다. sudo는 절대 사용하지 마세요. 이미 문제가 생겼다면 기존 전역 패키지를 정리하고 nvm으로 새로 설치하는 것이 가장 빠릅니다.
🔴 오류 4 — 인증 실패 (Login failed / Authentication error)
원인: 브라우저 세션 만료, 잘못된 계정 연결, 또는 Claude Pro 이상 구독이 활성화되지 않은 상태.
해결: claude /login을 실행해 브라우저 인증을 다시 시도합니다. 로그인 방식(구독 연결 vs API 키)을 확인하고, claude.ai에서 구독 상태가 활성화되어 있는지 확인합니다. 인증 완료 후 /status로 연결 상태를 검증하세요.
🔴 오류 5 — Windows Git Bash 관련 오류
원인: Git for Windows가 설치되지 않았거나, PowerShell/CMD에서 실행 정책이 스크립트 실행을 막는 경우.
해결: Git for Windows를 먼저 설치합니다. PowerShell에서 실행 정책 오류가 발생하면 Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned를 실행하세요. WSL(Windows Subsystem for Linux) 환경을 사용하면 이런 문제를 한 번에 피할 수 있습니다.
9. 내 상황에 맞는 플랜 선택 가이드
"Pro 이상 필요"라는 말만 듣고 막막했던 분들을 위해 실제 사용 패턴별 추천 플랜을 정리했습니다. 처음엔 어느 플랜이 맞는지 몰라서 과한 플랜에 가입하는 경우가 많습니다.
| 사용자 유형 | 추천 플랜 | 월 비용 | 특징 |
|---|---|---|---|
| 처음 써보는 입문자 | Claude Pro | $20 | 일반 코딩 작업 충분 / 주간 사용량 제한 있음 |
| 매일 쓰는 개인 개발자 | Claude Pro | $20 | Sonnet 4.6 기준으로 대부분의 작업 커버 |
| 대형 프로젝트 / Opus 필요 | Claude Max | $100~ | Opus 4.7 기본 사용 / 높은 사용량 제공 |
| 팀 협업 환경 | Team | $25/인 | 팀 공유 설정 / 관리자 대시보드 |
| API 자동화 / CI/CD 통합 | Console API | 사용량 기반 | 토큰 단위 과금 / 헤드리스 자동화 가능 |
💡 처음이라면: Claude Pro $20부터 시작하는 것이 현실적입니다. 2026년 4월 기준으로 Pro 플랜에서 Claude Code 사용 가능 여부는 Anthropic 정책에 따라 변동이 있었던 만큼, 가입 전 공식 가격 페이지에서 최신 포함 항목을 반드시 확인하세요.
✅ Claude Code 첫 설정 실전 체크리스트
☐ Node.js 18 이상 설치 완료
☐ npm install -g @anthropic-ai/claude-code 실행 (sudo 없이)
☐ 브라우저 계정 연결 완료
☐ 업데이트 채널 설정 (latest 또는 stable)
☐ 프로젝트 루트에서 실행 확인
☐ Git 초기화 확인
☐ CLAUDE.md 파일 생성 (기술 스택 + 코딩 규칙 + 금지 사항)
☐ /plan 명령어로 첫 분석 테스트
☐ command not found 오류 시 nvm으로 재설치 확인
📌 이 글의 핵심 요약
• Claude Code는 터미널 기반 AI 에이전트로, 깊은 코드베이스 분석과 대형 프로젝트 이해에 강합니다.
• 설치는 5분이지만 진짜 실력은 초기 설정 30분에서 갈립니다.
• CLAUDE.md를 만들어두면 매 세션마다 프로젝트 컨텍스트를 다시 설명할 필요가 없습니다.
• /plan 명령어로 실행 전 계획을 확인하는 습관이 오류를 크게 줄여줍니다.
• Cursor와 조합하면 빠른 편집 + 깊은 분석을 동시에 커버할 수 있습니다.
❓ 자주 묻는 질문
Claude Code 무료로 쓸 수 있나요? 비용이 얼마나 드나요?
2026년 4월 기준으로 Claude Code를 사용하려면 Claude Pro 이상 구독(월 $20) 또는 Anthropic Console API 계정이 필요합니다. Pro 플랜은 사용량 제한이 있으며, Max·Team 플랜은 더 많은 사용량을 제공합니다. API 키 방식은 사용한 토큰만큼 비용이 발생합니다.
Claude Code가 제 코드를 학습 데이터로 사용하나요?
Anthropic은 API 사용자와 구독자의 코드를 모델 학습에 기본적으로 사용하지 않습니다. Enterprise 플랜은 별도의 데이터 격리 옵션을 제공합니다. 보안에 민감한 프로젝트라면 Anthropic의 데이터 처리 정책을 반드시 확인하세요.
Claude Code와 Cursor 중 하나만 써야 한다면 뭘 선택해야 하나요?
혼자 개발하며 GUI 환경을 선호한다면 Cursor가 진입 장벽이 낮습니다. 팀 단위 대형 프로젝트나 터미널 작업이 많다면 Claude Code가 더 강력합니다. 현실적으로 두 도구를 함께 쓰는 개발자가 가장 높은 생산성을 보고합니다.
Claude Code 설치 후 'claude' 명령어가 안 먹히는데 어떻게 해야 하나요?
가장 흔한 원인은 npm 전역 설치 경로가 PATH에 등록되지 않은 것입니다. nvm을 사용해 설치했다면 nvm use [버전]으로 활성화한 뒤 새 터미널 창을 열어보세요. 네이티브 설치 프로그램을 사용했다면 설치 스크립트를 다시 실행하면 자동으로 PATH가 설정됩니다.
Claude Code 설정 완료 후 다음 단계로
Cursor와 함께 써야 진짜 생산성이 올라갑니다.
실전 워크플로우 조합법을 바로 확인해보세요.
'AI' 카테고리의 다른 글
| AI 고블린 문제, OpenAI가 밝힌 진짜 원인은 '버그'가 아니었다 (1) | 2026.05.05 |
|---|---|
| Cursor AI 단축키만 외우지 마세요 - 생산성 2배 올리는 고급 기능 총정리 (2) | 2026.05.04 |
| PDF 넣으면 핵심만 뽑아주는 AI 사용법 (2026 최신 완전 정리) (0) | 2026.05.03 |
| Next.js App Router 심화 - Server Component vs Client Component언제 쓸까? (0) | 2026.05.02 |
| Vercel 무료 배포 완전 가이드 —Next.js 프로젝트 10분 만에 올리기 (0) | 2026.05.02 |