macOS에서 Claude Code 설치 시작하기

Claude code install은 Node.js가 설치되어 있다면 macOS와 Linux에서 간단합니다. Claude code install의 가장 빠른 방법은 npm을 사용하는 것이며, 비공식 스크립트보다 공식 패키지와 업데이트가 연결되어 있기 때문에 더 좋습니다.

결과

설정 후, 터미널에서 Claude Code를 실행하고 Anthropic에 인증한 후 프로젝트 디렉터리에 연결할 수 있습니다. 이를 통해 코드베이스 인식 프롬프트, 타겟 수정 및 셸 지원 워크플로를 추가 에디터 플러그인 없이 시작할 수 있습니다.

이 빠른 시작 가이드는 가장 신뢰할 수 있는 짧은 경로에 중점을 두고 있습니다. 고정된 버전이나 관리된 워크스테이션 이미지를 필요로 하는 팀은 나중에 추가할 수 있지만, 설치는 공식 패키지에 가깝게 유지하는 것이 좋습니다. 작동 부품이 적을수록 온보딩 실패가 줄어듭니다.

전제 조건

macOS나 Linux에서 지원되는 셸을 사용하고, npm이 사용 가능한 현재 Node.js 버전을 설치해야 합니다. Anthropic 계정이 필요하며, 현재 Claude 요금제에 대한 자세한 내용은 공식 가격 페이지를 확인하세요.

대부분의 설치 실패는 Claude Code가 아닌 셸 구성에서 발생합니다. node, npm, 또는 전역 npm 바이너리가 PATH에서 누락되면 패키지가 올바르게 설치되더라도 터미널에서 작동하지 않을 수 있습니다.

요구 사항	중요한 이유	검증 방법
Node.js + npm	공식 설치 경로는 npm을 사용합니다.	node -v 및 npm -v
macOS 또는 Linux 셸	Claude Code는 터미널 사용을 위해 설계되었습니다.	echo $SHELL
Anthropic 계정	CLI가 Claude에 접근하기 전에 인증이 필요합니다.	공식 Anthropic 사이트에서 로그인
프로젝트 디렉터리	레포 내에서 실행하면 도구에 유용한 맥락을 제공합니다.	pwd를 목표 폴더 내에서 실행

1단계: Node.js가 없으면 설치하기

node -v와 npm -v가 이미 작동한다면 이 단계를 건너뛰세요. 공식 설치 관리자 또는 버전 관리자를 통한 Node 설치가 더 안전합니다. 손상된 npm 경로는 Claude Code보다 더 많은 설치 실패를 초래할 수 있습니다.

macOS에서는 많은 팀이 Homebrew나 nvm을 사용합니다. Linux에서는 버전 관리자가 배포 패키지보다 깨끗한 경우가 많습니다. 배포 저장소는 종종 현재 Node 릴리스를 따라가지 못하고, npm 동작을 분리하여 전역 CLI 설치를 혼란스럽게 만들 수 있습니다.

검증이 설치 방법보다 더 중요합니다. node -v가 버전을 반환하지만 npm -v가 실패하면 Claude Code에 손을 대기 전에 Node를 수정해야 합니다. 공식 Claude code install 경로는 npm에 의존하며, 두 개의 손상된 레이어를 동시에 디버깅하는 것은 이득이 없습니다.

2단계: claude code install 명령 실행하기

공식 패키지는 npm으로 설치됩니다:

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

글로벌 설치는 CLI의 올바른 기본값입니다. 로컬 프로젝트 설치는 경로 마찰을 추가하고, 팀이 도구 버전을 매우 적극적으로 고정하지 않는 한 아무것도 해결하지 않습니다.

여기서 많은 내부 문서가 지나치게 복잡해집니다. 래퍼 스크립트, 복사된 바이너리 및 셸 별칭은 추가 실패 지점을 생성하며, 직접적인 npm 명령은 진리의 출처를 명확하게 유지하고 업데이트를 예측 가능하게 만듭니다.

글로벌 설치 중에 셸에서 권한 오류가 발생하면 npm의 글로벌 접두사를 수정하거나 sudo를 강제로 사용하지 않고 Node 버전 관리자를 사용하는 것이 좋습니다. 업데이트를 위해 상승된 권한이 필요한 CLI는 개발자 기계에서 좋지 않은 기본값입니다.

3단계: 바이너리가 PATH에 있는지 확인하기

다음 명령을 실행하세요:

claude --version

셸에서 claude를 찾을 수 없는 경우, npm이 바이너리를 PATH에 내보내지 않는 디렉터리에 설치했을 가능성이 높습니다. 이는 셸 문제이며, 재설치 전에 npm의 글로벌 바이너리 경로를 수정해야 합니다.

바이너리 디렉터리가 셸에 보이지 않으면 재설치가 거의 도움이 되지 않습니다. npm 접두사와 글로벌 바이너리 구성을 확인한 후, 일치하는 디렉터리가 현재 셸 시작 파일인 .zshrc, .bashrc 또는 워크스테이션 이미지에서 사용되는 셸 구성에 로드되어 있는지 확인하세요.

새로운 터미널에서 테스트하는 것이 가장 간단한 확인 방법입니다. claude --version가 한 세션에서만 작동한다면, 경로 변경이 수동으로 적용된 것입니다.

4단계: 인증 및 프로젝트 열기

Claude Code가 검사할 레포지토리로 이동한 후 CLI를 시작하세요:

cd /path/to/project
claude

기계가 아직 로그인되지 않았다면 CLI가 인증을 요청합니다. 파일 인식은 현재 작업 디렉터리에 따라 달라지기 때문에, 다른 위치에서 열기보다는 목표 레포에서 실행하는 것이 좋습니다.

이곳에서 설치 품질이 실제 유용성과 만나는 첫 번째 지점입니다. 잘못된 디렉터리에서 성공적으로 실행되는 것은 바이너리가 작동한다는 것만 증명하며, 레포 내에서 실행하는 것은 도구가 중요한 파일을 볼 수 있다는 것을 증명합니다.

인증은 설치와는 별개의 체크포인트로 취급해야 합니다. claude가 시작되지만 로그인 실패 시 패키지는 올바르게 설치되며, 다음 수정은 계정 접근, 네트워크 정책 또는 브라우저 기반 인증 흐름에서 이루어져야 합니다.

5단계: 하나의 제한된 작업 수행하기

모듈 검토, 실패한 테스트 설명, 또는 하나의 파일에 대한 리팩터링 제안과 같은 좁은 프롬프트로 시작하세요. 작은 작업은 권한 문제, 레포 접근 문제 및 프롬프트 품질을 더 빠르게 드러냅니다.

좋은 첫 번째 프롬프트는: “이 레포의 아키텍처를 요약하고 새로운 API 엔드포인트를 추가하기에 가장 안전한 위치를 식별하라.” 이는 레포 읽기, 코드 이해 및 실용적인 출력을 한 번에 테스트합니다.

제한된 프롬프트는 명확한 성공 조건을 생성하기 때문에 더 좋습니다. 답변이 진입점을 잘못 식별하거나, 테스트를 무시하거나, 파일을 발명하면 팀은 편집을 신뢰하기 전에 맥락이나 권한을 수정해야 한다는 것을 즉시 배웁니다.

광범위한 프롬프트는 모호한 출력 뒤에 나쁜 설정을 숨깁니다. 정확한 작업은 CLI가 Claude code install이 단순히 완료된 것이 아니라, 개발자가 사용하려는 레포에서 실제로 유용하다는 것을 증명하게 합니다.

첫 시도해볼 것

Claude Code에게 현재 레포를 검사하고 디렉터리, 진입점 및 테스트 명령의 짧은 맵을 생성하도록 요청하세요. 처음 수정 요청보다 좋습니다. 팀은 도구가 어떤 것도 쓰기 전에 맥락 품질을 검증할 수 있습니다.

예시 프롬프트: “이 레포를 읽고 주요 서비스, 로컬 개발 명령 및 변경할 때 가장 위험한 영역을 나열하라.”

읽기 전용 지향 작업은 CLI가 구조, 명명 및 개발자 워크플로를 얼마나 잘 이해하는지 드러내기 때문에 가장 안전한 첫 실행입니다. 요약이 레포와 일치하면 환경이 패치 제안, 테스트 수정 또는 리팩터링과 같은 더 높은 신뢰의 작업에 준비됩니다.

이 또한 팀에게 온보딩을 위한 기준 프롬프트를 제공합니다. 모든 기계에서 동일한 첫 작업을 재사용하면 문제가 레포, 계정 또는 한 개발자의 셸 설정에서 오는지 쉽게 파악할 수 있습니다.

일반적인 실수

• Node를 설치했지만 npm의 글로벌 바이너리 디렉터리를 노출하지 않음. claude --version가 npm 설치 후 실패하면 패키지를 반복해서 재설치하기보다는 npm 접두사와 글로벌 바이너리 설정을 확인하세요.
• sudo npm install -g를 첫 번째 수정으로 사용. 이는 글로벌 패키지 경로에 root 소유 파일을 남기고, 이후 업데이트를 더 어렵게 만들 수 있습니다.
• 레포 외부에서 Claude 실행. CLI는 현재 디렉터리로 프로젝트와 함께 사용할 때 최적의 성능을 발휘합니다. 그렇지 않으면 파일 참조가 모호해지거나 쓸모없어집니다.
• 거대한 작업으로 시작. “이 전체 모놀리스를 감사하라”는 첫 번째 프롬프트로 좋지 않습니다. 이는 일반적인 출력 뒤에 설정 문제를 숨깁니다.
• 내부 문서에 계획 세부정보를 하드코딩. 공식 Anthropic 가격 페이지를 대신 확인하세요: https://www.anthropic.com/pricing.

공식 패키지 이름, 명령 및 문서는 변경될 수 있으니, 팀 온보딩에 적용하기 전에 Anthropic의 문서에서 현재 Claude code install 명령을 확인하세요. 대부분의 개발 팀에게 npm은 간단하고 스크립팅 가능하며 사용자 정의 래퍼나 복사된 바이너리보다 감사하기 쉬운 올바른 기본값입니다.