Claude Code 사용법 3단계, 설치부터 실전까지
목차
Claude Code란 무엇인가
Claude Code는 Anthropic이 만든 CLI(명령줄 인터페이스, Command Line Interface) 기반 AI 코딩 에이전트입니다. 별도의 통합 개발 환경(IDE, Integrated Development Environment) 창을 열지 않고 터미널에서 claude 명령 하나로 실행하며, 프로젝트 폴더 전체를 스캔해 파일 간 연관관계를 파악한 뒤 코드를 읽고 수정하고 커밋까지 처리할 수 있습니다. 화면 안에서 실시간으로 결과를 보여주는 Cursor AI 같은 IDE형 도구와 달리, 터미널 명령과 자연어 요청을 오가며 작업하는 방식이라 적응에는 다소 시간이 걸리지만 대규모 코드베이스를 한 번에 다루는 데 강점이 있습니다.
설치 전 확인할 준비사항
계정 요구사항
Claude Code를 쓰려면 유료 구독이나 API 계정이 있어야 합니다. 무료로 웹에서 쓰는 Claude.ai 플랜은 Claude Code를 지원하지 않습니다.
Claude Code는 Pro·Max·Team·Enterprise·Console(API) 계정에서만 사용할 수 있으며, 무료 Claude.ai 플랜으로는 실행 자체가 되지 않습니다. 특히 Pro 요금제는 가벼운 작업에는 쓸 수 있지만, 코드베이스 분석처럼 토큰(AI가 응답을 생성할 때 소비하는 처리 단위) 소모가 큰 작업을 반복하면 한도에 빨리 도달할 수 있어 Max 이상을 권장하는 경우가 많습니다.
운영체제·터미널 환경
macOS·Linux·Windows(WSL 포함) 모두 지원합니다. 설치 방식에 따라 필요한 사전 준비가 달라지는데, 이 부분에서 흔히 오해가 생깁니다.
- 네이티브 설치(권장)를 선택하면 Node.js(자바스크립트 실행 환경)가 전혀 필요 없습니다.
- npm 설치(대안)를 선택할 때만 Node.js가 필요하며, 그것도 22 이상 버전이어야 경고 없이 설치됩니다.
- Node.js 22 미만에서 npm 설치를 하면 설치 자체는 완료되지만 EBADENGINE 경고 메시지가 표시됩니다.
즉 "Claude Code는 Node.js가 있어야 한다"는 단정은 정확하지 않습니다. 설치 방식을 어떤 걸 고르느냐에 따라 요구사항이 달라진다는 점을 먼저 구분해두면 설치 단계에서 헤매지 않습니다.
설치 및 첫 실행, 3단계로 끝내기
1단계: 설치하기
가장 먼저 할 일은 Claude Code 자체를 설치하는 것입니다. 2026년 8월 기준 Anthropic 공식 설치 문서는 네이티브 설치를 기본·권장 방법으로 안내합니다. macOS·Linux·WSL 사용자는 터미널에서 아래 명령 한 줄이면 됩니다.
curl -fsSL https://claude.ai/install.sh | bashWindows PowerShell 사용자는 아래 명령을 사용합니다.
irm https://claude.ai/install.ps1 | iex이 네이티브 설치는 Node.js 설치 여부와 무관하게 동작하고, 이후 버전이 올라갈 때도 백그라운드에서 자동으로 업데이트됩니다. 이미 Node.js 환경을 갖추고 개발 중이라면 아래처럼 npm으로 설치하는 대안도 여전히 작동합니다(단 Node.js 22 이상 권장).
npm install -g @anthropic-ai/claude-code2단계: 로그인 인증하기
설치가 끝나면 터미널에서 claude 명령을 한 번 실행합니다. 처음 실행하면 브라우저가 열리면서 Anthropic 계정 로그인 화면이 뜨는데, 여기서 Pro·Max·Team·Enterprise 중 자신이 구독 중인 계정으로 로그인하거나, Console(API) 방식이라면 API 키를 연결합니다. 인증이 완료되면 터미널로 자동 복귀하고, 이후 재실행 시에는 로그인 세션이 유지되어 매번 다시 로그인할 필요가 없습니다.
3단계: 프로젝트 폴더에서 실행하고 자연어로 요청하기
마지막 단계는 실제 작업 폴더로 이동해 Claude Code를 실행하는 것입니다.
cd my-project
claude명령을 실행하면 대화형 세션이 열립니다. 이 상태에서 코드를 한 줄씩 지정하지 않고 자연어로 요청하면 됩니다. 예를 들어 "로그인 API에 이메일 형식 검증 로직을 추가해줘"처럼 말하면, Claude Code가 관련 파일을 스스로 찾아 읽고 수정안을 제시합니다. 프로젝트 폴더 전체를 미리 인식하고 있으므로 파일 경로를 하나하나 알려주지 않아도 되는 것이 이 3단계 구조의 핵심입니다.
Claude Code 실전 활용법
자주 쓰는 슬래시 명령어
대화 중 슬래시(/)로 시작하는 명령을 쓰면 세션을 더 정교하게 제어할 수 있습니다.
- /init — 현재 프로젝트 구조를 분석해 작업 컨텍스트 파일을 생성
- /clear — 대화 맥락을 초기화해 새로운 작업을 시작
- /review — 최근 변경 코드에 대한 리뷰 요청
- /help — 사용 가능한 명령 목록 확인
대규모 코드베이스 다루는 팁
Claude Code의 강점은 여러 파일에 걸친 변경을 한 번에 처리하는 데 있습니다. 다만 프로젝트 규모가 크면 한 번의 요청 범위를 좁혀 지시하는 편이 결과 품질이 안정적입니다. "전체 리팩토링해줘"처럼 광범위한 요청보다는 "결제 모듈의 예외 처리만 정리해줘"처럼 범위를 지정하면 검토하기도, 되돌리기도 쉬워집니다. 또한 변경 사항은 항상 git 커밋 전에 diff(변경 내역)를 직접 확인하는 습관을 들이는 것이 안전합니다.
Cursor AI와 비교, 어떤 도구가 나에게 맞을까
화면을 보면서 바로바로 결과를 확인하고 싶다면 Cursor AI 같은 IDE형이 편할 수 있고, 터미널 작업에 익숙하며 대규모 코드베이스를 한 번에 다루고 싶다면 Claude Code가 더 맞을 수 있습니다. 두 도구 모두 별도의 AI 모델 구독료가 필요한 경우가 많으므로, 중복 구독 비용까지 고려해 선택하는 것이 좋습니다.
요금제별 지원 범위 한눈에 보기
| 요금제 | 특징 | Claude Code 지원 |
|---|---|---|
| 무료 Claude.ai | 웹 챗봇 기본 기능만 제공 | 미지원 |
| Pro | 개인용 기본 사용량, 가벼운 작업에 적합 | 지원(사용량 한도 낮음) |
| Max | 대용량 토큰, 반복적인 코드베이스 작업에 적합 | 지원(권장) |
| Team / Enterprise | 조직 단위 관리, 협업 기능 포함 | 지원 |
| Console(API) | 사용량 기반 종량제, API 키 방식 | 지원 |
자주 묻는 질문
Q. Claude Code는 무료로 쓸 수 있나요?
아니요. 무료 Claude.ai 플랜으로는 Claude Code를 실행할 수 없고, Pro 이상 유료 구독이나 Console API 계정이 있어야 합니다.
Q. npm으로 설치했는데 EBADENGINE 경고가 떠요. 문제가 되나요?
Node.js 버전이 22 미만일 때 뜨는 경고입니다. 설치 자체는 완료되지만, 경고 없이 안정적으로 쓰려면 Node.js를 22 이상으로 올리거나 curl·irm을 이용한 네이티브 설치로 바꾸는 것을 권장합니다.
Q. Windows에서도 설치할 수 있나요?
가능합니다. PowerShell에서 irm https://claude.ai/install.ps1 | iex 명령으로 네이티브 설치하면 되고, WSL 환경이라면 macOS·Linux와 동일한 curl 명령을 그대로 사용할 수 있습니다.
Q. 설치 후 업데이트는 어떻게 하나요?
네이티브 설치는 별도 조작 없이 백그라운드에서 자동 업데이트됩니다. npm으로 설치한 경우에는 npm update -g @anthropic-ai/claude-code 명령으로 수동 업데이트해야 합니다.
Q. Cursor AI와 Claude Code를 동시에 써도 되나요?
가능합니다. 다만 두 도구 모두 별도의 AI 모델 구독이 필요한 경우가 많아 동시에 쓰면 구독료가 중복될 수 있으므로, 작업 방식에 맞는 한쪽을 주력으로 정하고 나머지는 필요할 때만 보조로 쓰는 방식을 권장합니다.
