Claude Code 처음 설치하고 실행해보기

AI 코딩 도구를 한번 써보고 싶은데, 첫 화면이 “터미널에 무언가를 입력하라”는 것이라면 거기서부터 막히기 쉽습니다. Claude Code 같은 도구는 그래픽 화면 대신 터미널에서 동작하기 때문에, 설치와 첫 실행의 흐름을 미리 알아두면 훨씬 덜 당황하게 됩니다.

이 글에서는 특정 버전이나 명령을 단정하기보다, 처음 설치할 때 거치는 일반적인 단계와 확인할 점을 순서대로 정리합니다.

Claude Code가 어떤 도구인가

Claude Code는 터미널에서 실행하는 AI 코딩 보조 도구입니다. 그래픽 앱처럼 창을 띄우는 대신, 작업하려는 폴더 안에서 명령을 입력해 대화하듯 코드를 다루는 방식입니다. 그래서 설치도 일반 프로그램보다는 개발 도구를 설치하는 흐름에 가깝습니다.

도구의 정확한 기능·요금·지원 범위는 환경과 시점에 따라 달라질 수 있으니, 세부 사양은 공식 안내를 기준으로 보는 것이 좋습니다. 이 글의 목적은 “정확한 명령을 외우게 하는 것”이 아니라, 설치라는 과정 전체가 어떤 단계로 이루어지는지 그림을 그려 두는 데 있습니다. 흐름을 알고 있으면, 공식 문서의 명령이 조금 달라져도 어디에 해당하는 단계인지 바로 알아볼 수 있습니다.

설치 전에 갖춰야 할 것

대부분의 터미널 기반 도구처럼, Claude Code도 실행 환경이 먼저 준비되어 있어야 합니다. 환경이 갖춰지지 않은 상태에서 설치 명령부터 입력하면 “명령을 찾을 수 없다”거나 “이런 프로그램이 없다”는 오류가 나기 쉬운데, 이는 도구의 문제가 아니라 토대가 빠진 경우가 대부분입니다.

• 터미널 접근 — 리눅스, macOS의 터미널, 또는 윈도우라면 WSL을 통한 리눅스 터미널이면 됩니다. 윈도우만 써왔다면 먼저 WSL로 리눅스 터미널을 마련해 두는 편이 흐름이 깔끔합니다.
• Node.js와 npm — 많은 터미널 도구가 Node.js 환경 위에서 설치·실행됩니다. npm은 Node.js를 설치하면 보통 함께 들어오는 패키지 매니저로, 다른 도구를 내려받아 설치하는 통로 역할을 합니다.

Node.js가 준비됐는지 확인하기

설치를 시작하기 전에, Node.js와 npm이 이미 동작하는지 한 번 확인해 두면 좋습니다. 버전을 출력해 보는 명령으로 간단히 점검할 수 있습니다.

node -v
npm -v

두 명령이 버전 숫자를 출력하면 준비가 된 것이고, “명령을 찾을 수 없다”는 메시지가 나오면 아직 Node.js가 없는 상태입니다. 이때는 무작정 설치 명령을 찾기보다, 버전을 깔끔하게 관리할 수 있는 버전 매니저로 Node.js를 들이는 방법을 함께 살펴보는 편이 이후가 편합니다. 시스템 전체에 한 버전만 박아 두기보다, 프로젝트마다 다른 버전을 오갈 수 있게 해 두면 나중에 충돌이 줄어듭니다.

설치와 첫 실행의 흐름

1. 공식 안내에서 설치 방법 확인

가장 먼저 할 일은 임의의 명령을 따라 치는 것이 아니라, 공식 문서에서 설치 방법을 확인하는 것입니다. 도구는 자주 갱신되어 패키지명이나 권장 설치 방식이 바뀔 수 있기 때문입니다.

2. 패키지 매니저로 설치

보통은 npm 같은 패키지 매니저로 설치합니다. 일반적인 흐름은 “패키지 매니저에게 특정 패키지를 설치하라고 한 줄로 지시”하는 형태인데, 정확한 패키지명과 옵션은 시점에 따라 바뀔 수 있으므로 이 글에서 단정하지 않습니다. 공식 안내에 나온 명령을 그대로 복사해 쓰는 것이 가장 안전합니다. 설치 도중 권한 오류가 난다면, 관리자 권한으로 무리하게 강제하기보다 설치 위치나 권한 설정을 점검하는 편이 안전합니다.

3. 작업 폴더로 이동해서 실행

설치가 끝났다면, 아무 곳에서나 실행하지 말고 작업하려는 프로젝트 폴더 안으로 먼저 이동한 뒤 도구를 실행합니다. 이 도구는 “지금 위치한 폴더”를 작업 대상으로 삼는 경우가 많기 때문에, 어디서 실행하느냐가 곧 어떤 파일을 다루게 되느냐로 이어집니다. 폴더 이동은 cd 명령으로 합니다.

cd ~/projects/my-app

4. 첫 인증(로그인)

처음 실행할 때는 대개 한 번 인증(로그인) 절차를 거칩니다. 보통 화면에 안내 링크나 절차가 표시되고, 그것을 따라가면 계정과 도구가 연결됩니다. 한 번 인증해 두면 이후에는 매번 로그인하지 않아도 되는 경우가 많지만, 구체적인 방식과 유효 기간은 환경·버전에 따라 다를 수 있으니 화면 안내를 그대로 따르는 것이 정확합니다.

도구가 파일을 다룰 때 거치는 확인 절차

AI 코딩 도구가 단순한 챗봇과 다른 점은, 대화에 그치지 않고 실제로 파일을 만들거나 고치고, 명령을 실행할 수 있다는 데 있습니다. 그만큼 통제가 중요합니다. 그래서 이런 도구들은 보통, 파일을 바꾸거나 명령을 실행하기 전에 사용자에게 “이대로 진행해도 되는지” 확인을 거치는 장치를 둡니다.

처음 쓸 때는 이 확인이 번거롭게 느껴질 수 있지만, 무엇을 바꾸려는지 미리 보고 승인하는 과정이라 안전망 역할을 합니다. 도구에 따라 확인을 건너뛰고 더 자동으로 동작하게 하는 옵션을 제공하기도 하는데, 구체적인 플래그 이름이나 동작은 도구·버전마다 다르므로 여기서 단정하지 않겠습니다. 입문 단계에서는 자동화 옵션을 켜기보다, 무엇을 바꾸는지 한 번씩 확인하며 쓰는 기본 동작에 익숙해지길 권합니다.

초보자가 자주 막히는 부분

• 사전 준비를 건너뜀 — Node.js/npm이 없으면 설치 자체가 진행되지 않습니다. 먼저 환경을 갖춰야 합니다.
• 명령을 검색으로 베껴 옴 — 오래된 글의 명령은 지금과 다를 수 있습니다. 공식 문서의 최신 안내를 우선하세요.
• 권한 오류 — 설치 중 권한 문제가 나오면 무리하게 강제하기보다 권한·설치 경로 설정을 점검하는 편이 안전합니다.
• 엉뚱한 폴더에서 실행 — 작업하려는 프로젝트 폴더 안에서 실행해야 의도한 파일을 다룰 수 있습니다.
• 확인 절차를 귀찮아서 꺼버림 — 파일을 바꾸기 전 확인하는 단계는 안전망입니다. 처음에는 켜둔 채로 쓰며 익히세요.

정리

Claude Code 같은 터미널 도구의 설치는 “명령 한 줄”보다, 환경을 먼저 갖추고 공식 안내를 따르는 흐름이 핵심입니다. 버전과 환경에 따라 세부 절차는 달라질 수 있으니 단정하지 말고 공식 문서를 기준으로 삼으세요. 설치를 마쳤다면, 도구를 더 잘 활용하기 위한 기본기를 함께 점검해 두면 도움이 됩니다.