Claude Code 첫걸음: 설치부터 첫 번째 명령어 실행까지 — 입문자 완전 가이드

터미널에 claude를 입력하는 순간, 단순한 텍스트 창이 AI 대화창으로 바뀐다. 처음 Claude Code를 접하는 개발자라면 설치 과정에서 막히거나 권한 요청에 당황하기 쉽다. 이 글은 아무것도 없는 상태에서 첫 번째 AI 명령어를 실행하기까지 전 과정을 직접 해보며 정리한 기록이다.

---

환경 준비 — 깨끗한 작업 공간 만들기

가장 먼저 할 일은 작업 폴더를 만드는 것이다. 기존 프로젝트 안에서 시작하면 Claude가 관계없는 파일까지 읽어들일 수 있기 때문에, 처음엔 빈 디렉터리에서 시작하는 게 낫다.

mkdir my-claude-project && cd my-claude-project

이 한 줄로 폴더를 만들고 바로 진입한다. ls를 쳐보면 아무것도 없는 텅 빈 상태다. 이 상태가 오히려 좋다. Claude가 프로젝트 구조를 처음부터 이해하며 컨텍스트를 쌓아가는 과정을 지켜볼 수 있기 때문이다.

---

설치 — AI 엔진 탑재하기

Node.js가 설치된 환경이라면 npm 한 줄로 끝난다.

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

-g 플래그가 핵심이다. 전역 설치를 하면 어느 폴더에서든 claude 명령어를 쓸 수 있다. 설치 중 아래처럼 버전 정보가 뜨면 성공이다.

added 1 package, and audited 1 package in 3s

설치 후 제대로 들어왔는지 확인하는 방법:

claude --version

버전 번호가 찍히면 엔진 탑재 완료다. 만약 command not found가 뜬다면 npm 글로벌 경로가 PATH에 없는 것이다. 아래 명령어로 경로를 확인하자.

npm config get prefix
# 출력 예: /usr/local
# → /usr/local/bin이 PATH에 있어야 함

Mac 기준으로 .zshrc나 .bash_profile에 아래 라인을 추가하면 해결된다.

export PATH="$(npm config get prefix)/bin:$PATH"

---

첫 실행 — AI에게 말 걸기

폴더 안에서 claude를 입력하고 엔터를 친다.

claude

Claude가 현재 디렉터리를 스캔하며 프로젝트 구조를 파악하기 시작한다. 빈 폴더라면 아무것도 없다는 걸 바로 인식한다. 여기서 자연어로 바로 요청을 던질 수 있다.

> 간단한 Python 스크립트로 현재 날짜와 시간을 출력하는 파일 만들어줘

Claude는 바로 실행하지 않고 먼저 무엇을 할지 보여준다. 파일을 만들기 전에 내용을 미리 보여주며 확인을 요청하는 구조다. 이 확인 단계가 처음엔 번거롭게 느껴지지만, 의도치 않은 파일 덮어쓰기를 막아주는 안전장치다.

---

권한 승인 — AI의 손에 도구 쥐어주기

파일 수정이나 명령어 실행 시 Claude는 권한 요청 프롬프트를 띄운다. 처음 보면 당황스럽다. 이게 뭔가 잘못된 건지 헷갈리기 쉽다.

권한 유형	의미	승인 여부
파일 읽기	코드 분석을 위한 파일 조회	항상 승인
파일 쓰기	새 파일 생성 또는 수정	내용 확인 후 승인
명령어 실행	터미널 명령 직접 실행	명령어 확인 후 승인

핵심은 승인 전에 반드시 내용을 읽는 것이다. Claude가 제안하는 명령어나 코드는 요청 의도에 맞게 생성됐지만, 가끔 환경 차이로 예상과 다른 동작을 할 수 있다.

첫 사용에서 권한 요청이 여러 번 반복된다면, 이후 --dangerously-skip-permissions 플래그로 자동 승인 모드로 전환할 수 있다. 단, 이 옵션은 스크립트 자동화 환경처럼 내용을 충분히 파악한 상태에서만 쓴다.

---

운영 팁 — 실제로 쓰다 보면 마주치는 것들

API 키 설정이 안 되어 있으면 Claude 실행 시 인증 오류가 뜬다. 처음 실행하면 Anthropic 계정 로그인을 안내하는데, 브라우저가 자동으로 열리며 인증이 진행된다. 헤드리스 서버 환경이라면 환경 변수로 직접 넣어야 한다.

export ANTHROPIC_API_KEY="sk-ant-..."

macOS vs Linux 차이: macOS에서는 npm 전역 설치 경로 문제가 더 자주 발생한다. Homebrew로 Node를 설치한 경우 /opt/homebrew/bin이 PATH에 있는지 먼저 확인한다. Linux에서는 sudo 없이 전역 설치가 안 되는 경우가 있어 nvm을 쓰는 쪽이 낫다.

Docker 환경: 컨테이너 안에서 Claude Code를 쓴다면 인터랙티브 모드(-it)로 실행해야 권한 프롬프트가 제대로 동작한다.

docker run -it --rm -v $(pwd):/workspace node:20 bash
# 컨테이너 안에서
npm install -g @anthropic-ai/claude-code && claude

---

마무리

설치가 끝이 아니다. claude를 처음 실행한 순간부터 터미널은 코드 생성기로 바뀐다. 권한 요청에 당황하지 말고, 내용을 읽고 승인하는 습관을 처음부터 들이면 이후 자동화 확장도 훨씬 안전하게 진행된다.

다음 글에서는 Claude Code로 실제 프로젝트에 기능을 추가하고, 변경 사항을 한 번에 커밋하는 과정을 다룬다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 입문
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독