Claude Code 설치보다 먼저
프로젝트 폴더를 정해야 하는 이유

터미널을 열기 전에 빈 연습 폴더부터 만듭니다

Claude Code는 현재 터미널이 가리키는 폴더를 작업 범위로 이해합니다. 다운로드 폴더나 문서 전체가 있는 위치에서 바로 실행하면 관련 없는 파일까지 탐색 대상이 될 수 있습니다. 처음에는 작은 테스트 프로젝트나 복사본을 출발점으로 삼는 것이 안전합니다.

macOS라면 터미널에서 프로젝트 폴더로 이동한 뒤 현재 위치를 한 번 확인합니다. Git을 쓰는 프로젝트라면 저장되지 않은 변경이 있는지도 먼저 봅니다. AI 도구가 만든 변경을 되돌릴 수 있는 기준점이 있어야 “뭔가 이상하다”는 느낌을 실제 파일 차이로 확인할 수 있습니다.

현재 공식 문서는 네이티브 설치를 권장합니다

2026년 8월에 Anthropic 공식 설치 문서를 확인하면 macOS·Linux·WSL의 권장 명령은 curl -fsSL https://claude.ai/install.sh | bash입니다. 예전 글에서 자주 보이던 npm 전역 설치만 따라갈 필요는 없습니다. 공식 문서는 네이티브 설치가 자동 업데이트를 지원하며 권장 방식이라고 표시합니다.

명령을 실행하기 전에 URL의 도메인이 claude.ai인지 직접 읽어보세요. 인터넷에서 받은 설치 스크립트를 바로 실행하는 방식이므로 출처 확인은 생략할 단계가 아닙니다. Homebrew나 WinGet 방식도 공식 문서에 있지만, 자동 업데이트 동작과 설치 위치가 다를 수 있으니 한 가지 방식만 골라 쓰면 관리가 덜 헷갈립니다.

내 맥에서 실행 가능한지 두 가지만 확인합니다

현재 공식 요구사항은 macOS 13 이상, 메모리 4GB 이상, 인터넷 연결입니다. Windows는 Windows 10 1809 이상, Linux는 Ubuntu 20.04·Debian 10·Alpine 3.19 이상을 안내합니다. 셸은 Bash·Zsh·PowerShell·CMD 등을 지원합니다. 사양을 만족해도 회사 보안 정책이나 프록시가 설치·로그인을 막을 수 있습니다.

설치가 끝나면 claude --version으로 명령이 인식되는지 확인합니다. ‘command not found’가 뜨면 재설치부터 하지 말고 터미널을 완전히 닫았다 열어 경로 설정이 반영됐는지 봅니다. claude doctor는 설치 상태와 업데이트 문제를 점검할 때 유용합니다.

첫 실행은 설명 요청 하나로 끝내는 게 좋습니다

준비한 프로젝트 폴더에서 claude를 실행하면 인증 절차가 이어집니다. 브라우저에서 로그인한 뒤 터미널로 돌아오면 먼저 “이 프로젝트의 구조와 실행 방법을 설명해줘. 파일은 수정하지 마”라고 요청해보세요. 이 답을 내가 아는 내용과 비교하면 도구가 프로젝트를 얼마나 정확히 읽었는지 판단할 수 있습니다.

처음부터 “전체를 리팩터링해줘”라고 하면 변경 파일이 많아지고, 결과가 실패했을 때 어느 판단이 잘못됐는지 찾기 어렵습니다. 작은 요청을 완료하고 직접 실행한 뒤 다음 범위를 넓히는 것이 결국 더 빠릅니다.

승인 창에서는 명령보다 영향 범위를 읽습니다

Claude Code는 파일 수정이나 명령 실행 전에 권한을 묻는 흐름을 제공합니다. 여기서 테스트 실행은 무조건 안전하고 설치 명령은 무조건 위험하다고 나누면 부족합니다. 테스트 스크립트가 외부 데이터베이스를 건드릴 수도 있고, 패키지 설치가 잠금 파일 수백 줄을 바꿀 수도 있습니다.

승인 전에는 대상 파일, 실행 디렉터리, 외부 네트워크 사용, 삭제·덮어쓰기 여부를 봅니다. 특히 환경변수 파일, 배포 설정, 데이터 마이그레이션은 작은 수정처럼 보여도 운영에 영향을 줄 수 있습니다. 비밀값을 대화에 붙여넣지 말고 필요한 변수 이름만 설명하세요.

수정 뒤에는 Claude의 요약만 읽고 끝내지 않습니다. 바뀐 파일 목록과 실제 차이를 확인하고, 프로젝트에서 평소 쓰던 빌드나 테스트를 직접 실행합니다. 화면 변경이면 브라우저에서 모바일 폭까지 확인해 두세요.

시작 전에 갖춰야 할 세 가지

공식 퀵스타트는 설치 명령보다 앞에 “Before you begin”을 둡니다. 여기서 막히는 경우가 의외로 많습니다.

설치 경로도 하나가 아닙니다. 문서는 Native Install을 권장으로 표시하고 Homebrew, WinGet을 대안 탭으로 둡니다. 어느 쪽으로 깔았는지에 따라 업데이트 방법과 바이너리 위치가 달라지므로, 나중에 문제가 생겼을 때 “어떻게 설치했는지”를 기억해 두면 해결이 빠릅니다.

그리고 이 퀵스타트가 다루는 건 터미널 CLI 하나입니다. 같은 Claude Code를 웹, 데스크톱 앱, VS Code, JetBrains IDE, Slack, 그리고 CI/CD의 GitHub Actions·GitLab에서도 쓸 수 있다고 안내 박스가 밝힙니다. 터미널이 불편하다면 처음부터 IDE 확장으로 시작해도 됩니다.

설치가 안 될 때는 오류 문장 하나를 그대로 남깁니다

로그인이 반복되면 기본 브라우저의 계정과 터미널 인증 세션이 같은지 확인합니다. 회사 네트워크에서만 실패한다면 프록시나 방화벽 정책을 의심할 수 있습니다. 명령이 갑자기 사라졌다면 여러 설치 방식을 섞어 쓰지 않았는지, 현재 셸이 설치 경로를 읽는지 확인합니다.

설치 방식이 헷갈릴 때는 which 결과 한 줄이면 됩니다

“내가 npm으로 깔았던가, 스크립트로 깔았던가”가 기억나지 않는 순간이 생각보다 자주 옵니다. 이때 재설치부터 하지 말고 실행 파일이 실제로 어디를 가리키는지 보면 됩니다. 아래는 네이티브 설치로 깔린 맥에서 직접 실행한 결과입니다.

읽는 순서는 이렇습니다. ls -l 결과의 맨 앞 l과 가운데의 -> 는 이 파일이 실행 파일 자체가 아니라 심볼릭 링크라는 표시입니다. 네이티브 설치는 ~/.local/bin/claude 라는 고정된 이름의 링크를 만들어 두고, 그 링크가 ~/.local/share/claude/versions/2.1.251 처럼 버전 번호가 붙은 실제 파일을 가리키게 합니다.

그래서 which claude 한 줄로 설치 방식을 구분할 수 있습니다. 링크가 .local/share/claude/versions/... 를 가리키면 공식 스크립트로 깐 네이티브 설치입니다. 반대로 경로가 node_modules 나 /usr/local/lib/node_modules 아래를 지나면 npm 전역 설치입니다. 앞서 “여러 설치 방식을 섞지 않았는지”를 확인하라고 한 대목을 이 명령 하나로 끝낼 수 있습니다.

구조를 알면 업데이트 동작도 짐작이 됩니다. 실제 실행 파일이 버전별 디렉터리에 따로 놓이므로, 새 버전이 설치되면 기존 파일을 덮어쓰는 대신 새 버전 디렉터리가 생기고 링크가 그쪽을 가리키도록 바뀌는 방식입니다. claude --version 이 보여주는 번호와 링크 끝의 디렉터리 이름이 같은지 비교하면 업데이트가 제대로 반영됐는지도 확인할 수 있습니다.

위 출력은 macOS에서 얻은 것입니다. Windows나 Linux는 설치 위치와 링크 표시 방식이 다를 수 있으니, 각자 환경에서 which claude(PowerShell이면 Get-Command claude) 결과를 직접 확인하고 공식 설치 문서의 해당 OS 항목과 맞춰 보세요.

문제를 검색할 때는 “Claude Code 안 됨”보다 운영체제 버전, 설치 방식, claude --version 결과, 오류 문장을 함께 적어야 정확한 답을 찾기 쉽습니다. 단, 로그를 그대로 공유하기 전에 사용자 경로와 토큰·저장소 주소가 포함됐는지 지웁니다.

설치 완료의 기준은 첫 변경을 되돌릴 수 있는 상태입니다

명령이 실행되는 것만으로 준비가 끝난 것은 아닙니다. 작은 파일 하나를 수정하고, 변경 내용을 읽고, 테스트하고, 필요하면 원래대로 돌릴 수 있어야 첫 설정이 완료됐다고 볼 수 있습니다. 이 흐름을 익힌 뒤에야 문서 작성, 반복 수정, 테스트 자동화처럼 더 큰 작업을 맡기는 것이 좋습니다.

며칠 사용한 뒤에는 어떤 승인에서 자주 멈췄는지 기록해보세요. 프로젝트 실행 명령이나 폴더 규칙을 문서로 남기면 매번 같은 설명을 반복하지 않아도 됩니다. 반대로 잘 모르는 명령까지 편의를 위해 상시 허용하는 것은 시간을 아끼는 설정이 아니라 검토 기회를 없애는 설정이 될 수 있습니다.