Claude Code 설치 방법: 전 플랫폼 완벽 설정 가이드 (2026)

Claude Code는 Anthropic에서 개발한 공식 커맨드라인 인터페이스로, AI 코딩 어시스턴트를 터미널에서 바로 사용할 수 있게 해줍니다. 브라우저 기반 도구와 달리, Claude Code는 전체 코드베이스를 읽고 명령을 실행하며 자연어를 통해 복잡한 멀티 파일 편집을 처리합니다. 커맨드라인을 벗어날 필요가 전혀 없습니다. 2026년 10월 현재, 권장 설치 방법은 네이티브 설치 프로그램으로, 별도의 의존성 없이 자동으로 업데이트됩니다. Claude Code에 로그인하는 방법은 두 가지입니다. 유료 Claude 플랜(Pro, Max, Team, Enterprise 중 하나, Pro는 $20/월부터)을 쓰거나, API 사용량만큼 과금되는 Claude Console 계정을 쓰면 됩니다. 무료 Claude 플랜에는 Claude Code가 포함되어 있지 않습니다.

핵심 요약

Claude Code 설치에 관해 알아야 할 모든 것을 핵심 사항으로 정리했습니다. macOS 또는 Linux에서는 터미널을 열고 curl -fsSL https://claude.ai/install.sh | bash를 실행하면 됩니다. 전체 과정은 2분도 채 걸리지 않습니다. Windows 사용자는 PowerShell에서 irm https://claude.ai/install.ps1 | iex를 실행하면 되며, 관리자 권한은 필요 없습니다. Git for Windows는 선택 사항으로, Bash 도구를 쓰고 싶을 때 설치합니다. 네이티브 설치 프로그램은 Node.js가 필요 없고 자동으로 업데이트되며 가장 안정적인 경험을 제공하기 때문에 공식 권장 방법입니다. Homebrew(brew install --cask claude-code)와 WinGet(winget install Anthropic.ClaudeCode)은 패키지 매니저를 선호하는 개발자를 위한 대안입니다. npm 방법(npm install -g @anthropic-ai/claude-code)은 공식 문서의 고급 설치 옵션으로 여전히 안내되며 지원 중단 상태가 아닙니다. Node.js 22 이상이 필요하고, 설치되는 것은 네이티브 설치 프로그램과 같은 바이너리입니다. Claude Code를 사용하려면 유료 Claude 플랜이나 Claude Console 계정이 필요합니다. 2026년 10월 20일 기준 claude.com/pricing에서 Pro는 월간 결제 $20/월, 연간 결제 시 월 $17이고, Max 5x는 $100/월, Max 20x는 $200/월(월간 결제만 가능)이며, Team 스탠다드 시트를 포함한 모든 유료 플랜에 Claude Code가 들어 있습니다. Console 계정은 토큰 사용량으로 과금되므로 Pro나 Max를 따로 구독하지 않아도 됩니다. 무료 플랜에는 Claude Code 접근이 포함되어 있지 않습니다. 설치 후, 프로젝트 디렉토리에서 claude를 실행하면 대화를 통해 코드를 읽고, 편집하고, 관리할 수 있는 대화형 코딩 세션이 시작됩니다.

Claude Code란 무엇이며, 정말 필요한 도구인가요?

Claude Code는 단순한 AI 코드 자동완성 도구가 아닙니다. 터미널에서 완전히 실행되는 에이전틱 코딩 환경입니다. Anthropic이 출시하여 2025년 5월에 정식 버전(GA)에 도달한 Claude Code는 전체 프로젝트 구조를 이해하고, 파일 간 탐색, 테스트 실행, 변경 사항 커밋, 여러 코드베이스에 걸친 복잡한 이슈 디버깅까지 동시에 수행할 수 있습니다. GitHub Copilot이나 Cursor 같은 도구와 근본적으로 다른 점은 Claude Code가 자율적인 에이전트로 작동한다는 것입니다. 자연어로 원하는 것을 설명하면 직접 계획을 세우고, 실행하고, 변경 사항을 검증합니다. 코드를 수동으로 선택하거나 파일 사이를 전환할 필요가 없습니다. 어떤 언어, 어떤 프레임워크, 어떤 에디터와도 호환됩니다. 실제로 에디터 자체가 필요하지 않으니까요.

Claude Code가 실제로 필요한지 여부는 여러분의 워크플로우와 터미널에서 보내는 시간에 달려 있습니다. 이미 커맨드라인 도구를 주로 사용하는 개발자라면, Claude Code는 기존 프로세스에 자연스럽게 통합됩니다. 한 번에 여러 파일을 수정해야 하는 작업에서 특히 뛰어납니다. 전체 코드베이스에 걸친 모듈 리팩토링, 프론트엔드와 백엔드를 아우르는 기능 구현, 애플리케이션의 여러 레이어를 추적해야 하는 이슈 디버깅 등이 그 예입니다. AI 코딩 도구를 평가 중인 개발자라면, Claude의 기반 모델이 경쟁사와 어떻게 비교되는지 이해하기 위해 ChatGPT와 Claude 종합 비교를 참고하시기 바랍니다. 주로 단일 파일 작업을 하는 경우 전통적인 인라인 코드 어시스턴트로 충분할 수 있지만, 복잡한 멀티 파일 엔지니어링 작업에서 Claude Code는 개발자 생산성을 크게 향상시키는 도구입니다. 이 도구는 특히 백엔드 개발자, 풀스택 엔지니어, 여러 서비스와 설정 파일을 정기적으로 다루는 DevOps 전문가들 사이에서 높은 채택률을 보이고 있습니다. Reddit과 개발자 포럼의 얼리 어답터들은 Claude Code가 프로젝트 컨텍스트를 이해하는 능력 — README 파일 읽기, 의존성 그래프 분석, 테스트 패턴 이해 — 이 개별 파일만 보는 AI 어시스턴트보다 훨씬 유용하다고 일관되게 강조합니다. 터미널에서 실행되기 때문에 git, docker, make 등 기존 커맨드라인 도구를 사용하는 개발자 워크플로우와 별도의 에디터 플러그인이나 설정 없이 완벽하게 통합됩니다.

Claude Code 설치 전에 준비할 사항

설치 명령을 실행하기 전에 두 가지를 확인해야 합니다. 시스템 요구 사항과 Claude 구독입니다. 이 두 가지를 미리 확인해두면 Claude Code를 설치한 후 인증이 안 되거나 운영 체제가 지원되지 않는다는 사실을 뒤늦게 발견하는 좌절감을 피할 수 있습니다. 대부분의 설치 가이드가 생략하는 단계이며, 많은 개발자가 설치 직후 막히는 원인이기도 합니다.

시스템 요구 사항은 간단하지만 플랫폼별로 다릅니다. macOS에서는 13.0(Ventura) 이상 버전이 필요하며, 이전 버전의 macOS는 네이티브 설치 프로그램에서 지원되지 않습니다(code.claude.com/docs/en/setup, 2026년 10월 기준). Windows 사용자는 Windows 10 버전 1809 이상 또는 Windows Server 2019+가 필요합니다. Git for Windows는 선택 사항입니다. 설치하지 않으면 Claude Code가 PowerShell 도구로 셸 명령을 실행하고, 설치하면 Bash 도구가 쓰는 Git Bash가 함께 생깁니다. Bash 기반 스크립트를 자주 다룬다면 git-scm.com에서 미리 설치해 두면 됩니다. Linux 사용자는 Ubuntu 20.04+, Debian 10+, 또는 Alpine 3.19+(Alpine은 추가 의존성 필요)가 필요합니다. 모든 플랫폼에서 최소 4GB RAM이 필요하며, 대규모 코드베이스 작업 시 8GB 이상을 권장합니다. 지원되는 셸은 Bash, Zsh, PowerShell, CMD입니다.

요금제는 많은 사람들이 미처 파악하지 못하는 부분입니다. Claude Code 자체는 무료로 설치할 수 있으며, 바이너리 다운로드에는 비용이 들지 않습니다. 실제로 사용하려면 두 가지 과금 방식 중 하나로 로그인해야 합니다. 첫 번째는 Claude 구독입니다. 2026년 10월 20일 기준 claude.com/pricing 웹 페이지에 표시된 가격(세금 별도)은 다음과 같으며, 같은 페이지의 FAQ는 Claude Code가 모든 유료 플랜에 포함된다고 밝힙니다. Pro는 월간 결제 시 $20/월, 1년치 $200를 한 번에 내는 연간 결제 시 월 $17입니다. Max 5x는 $100/월, Max 20x는 $200/월이며 둘 다 월간 결제만 가능합니다. Team 스탠다드 시트는 월간 결제 시 시트당 $25/월, 연간 결제 시 $20/월이고, 프리미엄 시트는 각각 $125/월과 $100/월이며 2~150명 팀이 대상입니다. 무료 Claude 플랜($0/월)에는 Claude Code가 포함되지 않습니다. Pro가 Claude Code를 쓸 수 있는 가장 저렴한 플랜이며, 대부분의 개인 개발자는 여기서 시작하면 됩니다. Max의 배수는 고정 토큰 양이 아니라 사용량 배수입니다. Anthropic의 Max 플랜 도움말은 Max 5x를 Pro 세션당 사용량의 5배, Max 20x를 20배로 설명하며, 세션 한도는 5시간마다 재설정되고 주간 한도가 따로 있습니다. Max에는 더 높은 출력 한도와 혼잡 시간대 우선 접근도 포함됩니다. 이 글을 처음 게시한 2026년 3월에는 Teams Premium을 $150/사용자/월로, 표준 Team 시트에는 Claude Code가 없다고 적었지만, 현재 요금 페이지는 두 시트 모두에 Claude Code를 표시합니다. 무료 Pro 체험이 있다고 가정하기 전에 현재 Claude Pro 체험 경계를 확인하거나, 전체 비교를 위한 상세 Claude 구독 요금 가이드를 확인해 보세요. 두 번째는 종량제 API 과금을 쓰는 Claude Console 계정입니다. Console 계정으로 로그인하거나 Anthropic API 키를 지정하면 실제 토큰 소비량만큼 요금이 부과되며, Pro나 Max 구독을 따로 살 필요는 없습니다. Amazon Bedrock, Google Cloud Agent Platform(Vertex AI), Microsoft Foundry로 Claude를 쓰는 조직이라면 Claude Code를 해당 플랫폼에 연결할 수도 있습니다.

Claude Code 설치 방법 (단계별)

이 가이드의 핵심 부분으로, 플랫폼별로 정리된 실제 실행 명령어입니다. 네이티브 설치 프로그램은 Claude Code에 필요한 모든 것을 번들로 포함하고 있어 Node.js를 설치하거나 npm 패키지를 관리할 필요가 없으므로, 모든 플랫폼에서 권장되는 접근 방식입니다. 아래 명령은 2026년 10월 기준 code.claude.com 공식 문서에 실린 명령과 같습니다.

macOS 및 Linux (WSL 포함)

macOS 또는 Linux에서 Claude Code를 설치하는 것은 시작부터 끝까지 약 2분이면 완료되는 진정한 한 줄 명령 프로세스입니다. 터미널을 여세요. macOS에서는 Cmd+Space를 누르고 "Terminal"을 입력한 후 Enter를 누르면 되며, Linux에서는 Ctrl+Alt+T를 사용하거나 선호하는 터미널 에뮬레이터를 사용할 수 있습니다. 그런 다음 다음 명령을 실행하세요:

curl -fsSL https://claude.ai/install.sh | bash

이 명령은 공식 설치 스크립트를 다운로드하고 실행하며, 운영 체제와 아키텍처를 자동으로 감지하고, 적절한 바이너리를 다운로드해 claude를 ~/.local/bin/claude에 둡니다. 다운로드하는 동안에는 진행 상황이 표시되지 않습니다. 설치 프로그램은 PATH를 직접 바꾸지 않습니다. ~/.local/bin이 아직 PATH에 없으면 출력의 Setup notes: 아래에 그 사실과 PATH를 추가하는 방법을 알려 줄 뿐입니다. 새 터미널 창을 열고 claude --version을 실행하여 설치를 확인하면 2.1.301 (Claude Code) 같은 형태의 버전 번호가 표시됩니다(번호는 업데이트마다 바뀝니다). WSL(Windows Subsystem for Linux)을 사용하는 경우 과정은 동일합니다. WSL 터미널을 열고 같은 curl 명령을 실행하면 됩니다. 설치 프로그램은 WSL을 Linux 환경으로 처리하므로 특별한 단계가 필요하지 않습니다. 확인 후, 프로젝트 디렉토리에서 claude를 입력하면 대화형 세션이 시작되어 AI 기반 코딩 어시스턴스를 사용할 수 있습니다.

Windows 설치

Windows에서도 설치 명령 하나면 되며, PowerShell이나 CMD를 관리자 권한으로 열 필요는 없습니다. Git for Windows는 2026년 10월 기준 공식 문서에서 선택 사항입니다. Git 없이 설치하면 Claude Code가 PowerShell 도구로 셸 명령을 실행하고, Git for Windows를 설치하면 Bash 도구가 쓰는 Git Bash를 사용할 수 있습니다. Bash 기반 스크립트와 도구를 많이 쓴다면 git-scm.com/downloads/win에서 Git for Windows를 내려받아 설치 중 "Add to PATH"를 선택하고, 설치 후 터미널을 재시작하세요.

Windows에서 Claude Code를 설치하는 방법은 두 가지입니다. 권장 방법은 PowerShell을 사용하는 것입니다. PowerShell을 여세요(시작 버튼을 마우스 오른쪽 버튼으로 클릭하고 "Windows PowerShell" 또는 "터미널"을 선택), 그런 다음 다음을 실행하세요:

irm https://claude.ai/install.ps1 | iex

기존 명령 프롬프트(CMD)를 선호하는 경우, 대신 다음 명령을 사용하세요:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

두 명령 모두 같은 결과를 달성합니다. 공식 설치 프로그램을 다운로드하고 Claude Code 바이너리를 %USERPROFILE%\.local\bin\claude.exe에 둡니다. 이 폴더가 아직 PATH에 없으면 설치 프로그램이 Setup notes: 아래에 알려 주고 해결 방법을 출력하지만, PATH를 직접 바꾸지는 않습니다. PowerShell 방법은 임시 파일을 남기지 않으므로 약간 더 깔끔합니다. 설치 후, 새 터미널 창에서 claude --version으로 확인하세요. 새 창에서도 명령이 인식되지 않으면 아래 "command not found" 항목대로 이 폴더를 사용자 PATH에 추가하세요. PATH에 한 번도 들어간 적 없는 폴더는 터미널을 다시 여는 것만으로는 추가되지 않습니다. Windows에서 흔한 실수 중 하나는 일부 개발자가 Git Bash(Git for Windows와 함께 제공되는 Bash 에뮬레이터)를 사용하여 curl 기반 macOS/Linux 설치 프로그램을 실행하려고 시도하는 것입니다. 이 방법이 가끔 작동하기는 하지만 권장 접근 방식이 아닙니다. 가장 안정적인 Windows 경험을 위해 PowerShell 또는 CMD 방법을 사용하세요. Windows에서 WSL을 사용하는 경우, WSL은 자체적인 별도의 파일 시스템과 PATH 설정을 유지하므로 Windows PowerShell 설치 프로그램 대신 WSL 환경 내에서 Linux curl 명령을 사용하여 설치해야 합니다.

패키지 매니저 대안 (Homebrew 및 WinGet)

모든 도구를 패키지 매니저를 통해 관리하는 것을 선호하는 개발자를 위해, Claude Code는 macOS의 Homebrew와 Windows의 WinGet을 통해 사용할 수 있습니다. macOS에서는 brew install --cask claude-code를 실행하면 됩니다. 이렇게 하면 Claude Code가 Homebrew cask로 설치되어 내장 자동 업데이트가 아닌 brew upgrade를 통해 업데이트가 관리됩니다. claude-code cask는 보통 일주일 정도 늦게 따라가는 stable 채널이고, 새 버전을 바로 받으려면 claude-code@latest cask를 설치합니다. Windows에서는 winget install Anthropic.ClaudeCode를 사용하여 Windows 패키지 관리자를 통해 설치할 수 있습니다. 두 패키지 매니저 방법 모두 네이티브 설치 프로그램과 동일한 Claude Code 바이너리를 제공하며, PATH 설정을 자동으로 처리합니다. 트레이드오프는 Claude Code의 내장 업데이트 메커니즘 대신 패키지 매니저를 통해 업데이트를 관리한다는 점인데, 일부 개발자는 도구 체인 전반의 일관성을 위해 이를 선호하고, 다른 개발자는 최신 버전을 유지하는 데 덜 편리하다고 느낍니다.

네이티브 설치 프로그램 vs Homebrew vs npm: 어떤 것을 선택해야 할까요?

세 가지 다른 설치 방법(Windows용 WinGet 포함)이 있어서 올바른 방법을 선택하는 것이 부담스러울 수 있습니다. 하지만 실제로는 보이는 것보다 간단합니다. 대다수의 사용자에게 네이티브 설치 프로그램이 올바른 선택이며, Anthropic의 공식 문서에서도 명시적으로 이를 권장합니다. 네이티브 설치 프로그램은 Node.js와 같은 런타임 의존성이 필요 없고, 항상 최신 버전을 유지하는 자동 업데이트를 포함하며, Anthropic이 주로 테스트하고 지원하는 방법이기 때문에 가장 안정적인 경험을 제공합니다. macOS, Windows, Linux, WSL 등 모든 플랫폼에서 OS별 단일 설치 명령으로 작동합니다.

Homebrew와 WinGet은 모든 개발 도구를 통합 패키지 매니저로 관리하는 것을 강하게 선호하는 경우 좋은 대안입니다. 많은 숙련된 개발자들이 전체 도구 체인을 brew 또는 winget 명령으로 유지하며, Claude Code에도 이를 사용하면 워크플로우의 일관성을 유지할 수 있습니다. 트레이드오프는 업데이트가 자동이 아니라는 점입니다. 새 버전을 받으려면 명시적으로 brew upgrade 또는 winget upgrade를 실행해야 하므로 최신 기능과 버그 수정에서 뒤처질 수 있습니다. 통제된 배포가 중요한 엔터프라이즈 환경에서는 자동으로 업데이트가 푸시되는 대신 업데이트 시점을 직접 선택할 수 있어 오히려 이점이 될 수 있습니다.

네이티브 설치 프로그램이 왜 그렇게 강력하게 권장되는지 이해하면 다른 옵션을 맥락적으로 파악하는 데 도움이 됩니다. Anthropic은 네이티브 설치 프로그램을 자체 완결형으로 설계했습니다. 시스템 수준의 패키지 매니저나 런타임 환경에 의존하지 않으므로 의존성 충돌, 버전 불일치, PATH 오염과 관련된 전체 카테고리의 설치 문제를 제거합니다. 설치되는 바이너리는 플랫폼과 아키텍처별로 빌드된 네이티브 실행 파일이라 Node.js 런타임 없이 실행됩니다. 2.1.113(2026년 4월 17일)부터는 npm 패키지도 플랫폼별 선택적 의존성으로 이 네이티브 바이너리를 설치하며, 설치된 claude는 실행 중에 Node.js를 호출하지 않습니다. 따라서 지금은 npm으로 설치했다고 해서 Node.js 위에서 더 느리게 돌아가는 것은 아닙니다. 자동 업데이트 메커니즘은 Claude Code를 실행할 때마다 새 버전을 확인하고 백그라운드에서 업데이트를 매끄럽게 적용하여, 수동 개입 없이 항상 최신 모델 개선 사항과 버그 수정에 접근할 수 있도록 합니다.

npm 방법(npm install -g @anthropic-ai/claude-code)은 2026년 10월 기준 공식 설치 문서의 고급 설치 옵션에 그대로 안내되어 있으며, 지원 중단으로 표시되어 있지 않습니다. 권장 방식이 네이티브 설치 프로그램이라는 점은 같습니다. 2026년 1월 21일 2.1.15에서 npm 설치 사용자에게 지원 중단 안내가 추가된 적은 있지만, 2.1.301 바이너리에는 그 안내 문구가 들어 있지 않습니다. npm 패키지는 Node.js 22 이상을 요구합니다(2.1.197까지는 18 이상). 더 오래된 Node.js에서는 설치 중 EBADENGINE 경고가 나오지만 설치는 끝나고 claude도 실행됩니다. 패키지가 내려받는 네이티브 바이너리가 실행 시 Node.js를 쓰지 않기 때문입니다. 다만 선택적 의존성이나 설치 후 스크립트를 건너뛰면(--omit=optional, --ignore-scripts) claude 실행 시 Error: claude native binary not installed.가 나오므로, 이 옵션 없이 다시 설치하세요. npm 전역 설치도 전역 폴더에 쓰기 권한이 있으면 자동으로 업데이트되며, 쓸 수 없을 때는 시작 시 한 번 안내가 뜨고 claude doctor가 해결 방법을 보여 줍니다. sudo npm install -g는 쓰지 마세요. npm 설치를 네이티브 버전으로 옮기고 싶다면 claude install을 실행하거나, npm uninstall -g @anthropic-ai/claude-code로 npm 패키지를 제거한 다음 해당 플랫폼의 curl 또는 PowerShell 명령으로 네이티브 버전을 설치하세요. 설정은 npm 패키지 위치가 아닌 홈 디렉토리에 저장되므로 구성과 설정이 보존됩니다.

Claude Code 첫 5분 활용법

설치 후 "설치 완료"에서 "생산적으로 사용"까지의 전환은 즉각적이어야 하며, Claude Code는 바로 그렇게 설계되었습니다. 터미널에서 처음 claude를 실행하면 CLI를 Claude 계정에 연결하는 인증 절차가 안내됩니다. 브라우저를 통해 로그인하라는 메시지가 표시되며, 여기서 Claude Code가 Pro, Max 또는 API 자격 증명을 사용하도록 승인합니다. 이것은 일회성 설정이며, 이후 실행 시에는 저장된 인증 정보가 사용됩니다.

인증이 완료되면, 가장 중요하게 이해해야 할 점은 Claude Code가 현재 작업 디렉토리를 기반으로 컨텍스트를 인식한다는 것입니다. Claude를 실행하기 전에 cd /path/to/your/project를 사용하여 프로젝트 폴더로 이동하면, Claude가 자동으로 코드베이스 구조를 스캔하고 이해합니다. 인수 없이 claude만 입력하면 대화형 세션이 시작됩니다. 여기서부터 자연어로 Claude에게 대화할 수 있습니다. 특정 함수가 어떻게 작동하는지 설명해달라고 요청하거나, 새 기능 구현을 요청하거나, 버그를 찾아 수정하라고 지시하거나, 모듈을 리팩토링하라고 명령할 수 있습니다. Claude Code는 파일을 읽고, 편집하고, 새 파일을 만들며, 심지어 여러분의 허가 하에 터미널 명령을 대신 실행할 수도 있습니다. 특히 유용한 첫 명령으로는 낯선 코드베이스에서 방향을 잡기 위한 claude "explain the architecture of this project"나, 즉각적인 실용적 가치를 위한 claude "run the tests and fix any failures" 등이 있습니다. 요청을 인수로 직접 전달하는 원샷 모드도 사용할 수 있습니다. 예를 들어 claude "add input validation to the user registration form"은 작업을 실행하고 대화형 세션을 시작하지 않고 종료되어 빠른 수정이나 스크립트 워크플로우에 완벽합니다.

Claude Code의 권한 관리 방식을 이해하는 것은 코드베이스를 신뢰하고 맡기는 데 필수적입니다. 기본적으로 Claude Code는 파일 변경이나 셸 명령을 실행하기 전에 승인을 요청하며, 의도하는 작업을 정확히 표시하고 확인을 기다립니다. 권한 모드를 통해 이 동작을 조정할 수 있습니다. 기본 모드는 모든 작업에 대해 승인을 요구하고, "acceptEdits" 모드는 파일 편집을 자동으로 승인하지만 셸 명령에 대해서는 여전히 확인을 요청하며, 더 빠른 실행을 원하는 숙련된 사용자를 위한 더 관대한 모드도 있습니다. 이 권한 시스템 덕분에 Claude Code가 예기치 않은 변경을 할 걱정이 없습니다. 모든 수정 사항이 실행 전에 표시되고 승인되므로, AI 지원 속도와 정확성의 혜택을 받으면서도 직접 변경하는 것과 동일한 수준의 제어를 유지합니다.

대화형 세션 외에도, Claude Code는 숙련된 사용자들이 매일 의존하는 여러 워크플로우 패턴을 지원합니다. git diff | claude "review this code change" 같은 명령으로 빠른 코드 리뷰를 위해 콘텐츠를 직접 Claude에 파이프하거나, cat error.log | claude "diagnose the root cause of these errors"로 빠른 디버깅을 수행할 수 있습니다. /init 명령은 프로젝트 루트에 CLAUDE.md 파일을 생성하여 프로젝트의 관례, 코딩 표준, 중요한 아키텍처 결정에 대한 지속적인 컨텍스트를 Claude에게 제공합니다. 이후의 모든 상호작용을 더 효과적으로 만드는 브리핑 문서라고 생각하면 됩니다. 숙련된 사용자들은 종종 이 파일에 기술 스택, 테스트 요구 사항, 코딩 스타일 선호도에 대한 정보를 채워넣어 세션 전반에 걸쳐 Claude의 제안 품질과 일관성을 크게 향상시킵니다.

또한 설정을 통해 Claude Code의 동작을 구성할 수 있습니다. 릴리스 채널 선택(stable vs latest), 확장 도구 접근을 위한 MCP(Model Context Protocol) 서버 설정, 선호하는 터미널 환경에 맞는 키보드 단축키 커스터마이징 등이 포함됩니다. MCP 통합은 특히 강력한데, Claude Code가 외부 도구 및 서비스 — 데이터베이스, 이슈 트래커, 문서 시스템 — 와 상호작용할 수 있게 해주어 단순한 코드 편집을 훨씬 넘어서는 기능을 제공합니다.

가장 흔한 5가지 설치 문제 해결법

설치 과정이 간단하더라도 문제가 발생할 수 있습니다. 설치 단계에서 문제가 생기면 도구를 사용해보지도 못하기 때문에 특히 답답합니다. 다음은 커뮤니티 토론과 지원 채널에서 가장 자주 등장하는 다섯 가지 문제와 해결 방법입니다.

설치 후 "command not found" 오류는 가장 흔한 문제이며, 거의 항상 설치 폴더가 셸의 PATH에 들어 있지 않은 것이 원인입니다. 바이너리가 놓인 위치와 셸이 명령을 찾는 경로는 별개라는 점부터 구분하세요. 네이티브 설치 프로그램은 macOS/Linux에서 ~/.local/bin/claude, Windows에서 %USERPROFILE%\.local\bin\claude.exe에 바이너리를 두지만 PATH는 바꾸지 않습니다. 폴더가 PATH에 없으면 Setup notes: 아래에 Native installation exists but ~/.local/bin is not in your PATH.와 해결 방법을 출력할 뿐입니다. macOS나 Linux에서는 먼저 ls -la ~/.local/bin/claude로 파일이 있는지 확인하고, echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"으로 그 폴더가 PATH에 들어 있는지 확인하세요. 아무것도 출력되지 않으면 직접 추가해야 합니다. Zsh라면 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc를 실행한 뒤 source ~/.zshrc를 실행합니다. Linux의 Bash는 같은 줄을 ~/.bashrc에, macOS의 Bash는 ~/.bash_profile에 추가합니다. Windows PowerShell에서는 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"로 파일을 확인한 다음, 공식 문제 해결 문서의 방법대로 사용자 PATH에 폴더를 추가합니다.

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

그다음 설치 프로그램을 실행한 창을 재사용하지 말고 새 PowerShell 창을 여세요. 터미널을 다시 여는 것은 PATH가 이미 설정 파일에 저장된 경우에만 효과가 있습니다. 열려 있던 창은 예전 PATH를 그대로 쓰고, 에디터 안의 터미널은 에디터가 시작될 때의 PATH를 쓰므로 에디터를 완전히 종료했다가 다시 열어야 합니다. PATH에 한 번도 추가하지 않은 폴더라면 터미널을 다시 열어도 해결되지 않습니다. 추가한 뒤 claude --version으로 확인하세요.

Windows에서 Git을 찾을 수 없음 오류는 현재 버전에서 Claude Code on Windows requires either Git for Windows (for bash) or PowerShell로 표시됩니다. Git for Windows는 선택 사항이고 Git Bash가 없으면 Claude Code가 PowerShell 도구를 쓰므로, 이 오류는 Git Bash와 PowerShell을 둘 다 찾지 못했다는 뜻입니다. 해결 방법은 세 가지입니다. PowerShell이 PATH에서 빠져 있다면 기본 위치인 C:\Windows\System32\WindowsPowerShell\v1.0 폴더를 PATH에 다시 추가하거나 PowerShell 7을 설치합니다. Git을 쓰고 싶다면 Git for Windows를 설치하면서 "Add to PATH"를 선택하고, 설치 후 터미널을 재시작하세요. Git을 이미 설치했는데도 찾지 못한다면 PowerShell에서 where.exe git으로 설치 위치를 확인하고, 그 설치의 bin\bash.exe 경로를 settings.json의 CLAUDE_CODE_GIT_BASH_PATH에 지정합니다. 새 터미널 창에서 git --version을 실행하여 Git이 제대로 설정되었는지 확인할 수 있습니다.

인증 실패는 일반적으로 로그인한 계정에 Claude Code 권한이 없을 때 발생합니다. 무료 플랜에는 Claude Code가 포함되어 있지 않으므로 유료 플랜(Pro $20/월부터, 또는 Team, Enterprise)이나 Claude Console 계정이 필요합니다. 계정에는 문제가 없는데도 인증할 수 없는 경우, claude auth logout 후 claude auth login을 실행하여 캐시된 자격 증명을 초기화하고 인증 절차를 다시 시작해 보세요(세션 안에서는 /logout도 쓸 수 있습니다). 네트워크 문제, 특히 Anthropic의 인증 엔드포인트를 차단하는 회사 방화벽이나 VPN도 인증 실패의 원인이 될 수 있습니다. 이 경우, 같은 네트워크에서 브라우저를 통해 claude.ai에 접근할 수 있는지 확인하세요.

설치 중 권한 오류는 설치 프로그램이 대상 디렉토리에 쓰거나 다운로드한 바이너리를 실행할 수 없을 때 발생합니다. macOS 및 Linux에서 설치 프로그램은 ~/.local/bin, ~/.local/share/claude, ~/.claude 아래에 파일을 씁니다. test -w ~/.local/bin && echo "writable"로 쓰기 권한을 확인하고, 쓸 수 없다면 sudo mkdir -p ~/.local/bin과 sudo chown -R $(whoami) ~/.local로 폴더 소유자를 본인 계정으로 바꾸세요. 꼭 필요한 경우가 아니면 sudo로 설치하지 않는 것이 중요합니다. root로 설치 프로그램을 실행하면 홈 디렉토리에 root 소유의 파일이 생성되어 나중에 일반 사용자로 Claude Code를 실행하려 할 때 다른 권한 문제가 발생합니다. 이전에 sudo로 설치 프로그램을 실행했다면, sudo chown -R $(whoami) ~/.claude로 소유권을 수정한 다음 sudo 없이 다시 시도하세요. Windows에서는 설치가 기본적으로 사용자에게 쓰기 권한이 있는 %USERPROFILE% 아래에 이루어지므로 PowerShell을 관리자 권한으로 실행할 필요가 없고, 권한 문제도 드뭅니다. 예전에 npm으로 설치했다가 npm 전용 권한 오류가 난다면 네이티브 설치 프로그램으로 바꾸는 것이 공식 문서의 안내입니다. 쓰기 권한이 제한된 기업 환경이나 엔드포인트 보호 소프트웨어, 애플리케이션 화이트리스트 정책이 적용된 환경에서는 IT 팀에 Claude Code 설치 디렉토리와 바이너리의 화이트리스트 등록을 요청해야 할 수 있습니다.

이전 npm 설치와의 버전 충돌은 이전에 npm을 통해 Claude Code를 설치한 후 네이티브 버전을 설치한 경우 혼란스러운 동작을 일으킬 수 있습니다. 두 버전이 모두 PATH에 존재하며, 셸이 잘못된 버전을 찾을 수 있습니다. which -a claude(macOS/Linux) 또는 where.exe claude(Windows)를 실행하면 PATH에 있는 claude가 모두 나열됩니다. 네이티브 설치는 ~/.local/bin/claude(Windows는 %USERPROFILE%\.local\bin\claude.exe), ~/.claude/local/은 예전 버전이 만든 로컬 npm 설치이고, npm -g ls @anthropic-ai/claude-code에 나오면 전역 npm 설치입니다. 여러 개가 나오면 하나만 남기고 나머지를 지우세요. 전역 npm은 npm uninstall -g @anthropic-ai/claude-code, 로컬 npm은 rm -rf ~/.claude/local, Homebrew는 brew uninstall --cask claude-code, WinGet은 winget uninstall Anthropic.ClaudeCode로 제거합니다. 오래된 npm 사본이 남아 있으면 Error: Cannot find module './yoga.wasm'가 날 수 있으며, 이 오류의 원인과 정리 순서는 Claude Code Cannot find module yoga.wasm 해결: 2.0.25 이하 복사본 정리에 정리되어 있습니다. 정리한 후 새 터미널을 열고 which -a claude를 다시 실행해 한 줄만 나오는지 확인한 다음, claude --version으로 최신 릴리스를 쓰고 있는지도 확인하세요.

위에서 다루지 않은 문제가 발생하면, code.claude.com의 공식 Claude Code 문제 해결 가이드에서 추가 해결 방법을 제공하며, claude doctor 명령은 일반적인 설정 문제를 자동으로 식별하는 진단 검사를 수행합니다. claude doctor를 실행하면 시스템 설정, 인증 상태, 감지된 문제에 대한 상세 보고서가 출력되어 설치에 문제가 생겼을 때 가장 좋은 출발점이 됩니다.

보안 유지 및 최신 상태 유지

보안은 개발자 도구를 설치할 때 가장 먼저 생각하는 것이 아닐 수 있지만, Claude Code는 주의가 필요한 독특한 사례를 제시합니다. 2026년에 보안 연구원들은 Google Ads를 통해 가짜 Claude Code 설치 페이지가 홍보되어 "InstallFix" 공격으로 알려진 악성 코드를 배포하는 캠페인을 발견했습니다(BleepingComputer 및 TechRepublic 보도). 이 악성 페이지는 공식 Anthropic 다운로드 페이지처럼 그럴듯하게 보였으며 유료 광고로 검색 결과 상단에 나타났습니다. 핵심 사항은 간단하지만 매우 중요합니다. 공식 출처에서만 Claude Code를 설치하세요. 정당한 설치 URL은 macOS/Linux용 claude.ai/install.sh, Windows PowerShell용 claude.ai/install.ps1, 공식 Homebrew cask, WinGet 패키지 Anthropic.ClaudeCode, 또는 공식 npm 레지스트리의 npm 패키지 @anthropic-ai/claude-code입니다. Google 광고나 익숙하지 않은 웹사이트를 통해 설치 페이지에 도달했다면, 명령을 실행하기 전에 URL을 신중하게 확인하세요.

설치 후 무결성을 확인하려면 claude --version으로 버전 출력을 확인하세요. 정상적인 설치는 2.1.301 (Claude Code)처럼 버전 번호 뒤에 (Claude Code)가 붙은 깔끔한 문자열을 표시합니다. 비정상적인 내용, 예기치 않은 브랜딩이 보이거나 바이너리가 예기치 않은 디렉토리에 위치해 있는 경우(macOS/Linux에서 which -a claude로 확인, 네이티브 설치라면 ~/.local/bin/claude), 즉시 삭제하고 공식 출처에서 다시 설치하세요. Claude Code는 AI 처리를 위해 Anthropic 서버와만 통신한다는 점도 주목할 만합니다. 코드를 제3자 서비스에 전송하지 않으며, 도구의 투명성 기능을 통해 어떤 데이터가 전송되는지 정확히 확인할 수 있습니다.

네이티브 설치 프로그램으로 Claude Code를 최신 상태로 유지하는 것은 간단합니다. 도구를 실행할 때 자동으로 업데이트를 확인하고 적용합니다. claude --version으로 현재 버전을 수동으로 확인하고 claude update로 업데이트 확인을 트리거할 수 있습니다. Homebrew를 통해 설치한 경우, 정기적으로 brew upgrade claude-code를 실행하여 최신 상태를 유지하세요. WinGet 설치의 경우 winget upgrade Anthropic.ClaudeCode를 사용하세요. npm으로 설치했다면 npm install -g @anthropic-ai/claude-code@latest로 업데이트합니다. npm update -g는 처음 설치할 때의 버전 범위를 따르기 때문에 최신 버전으로 올라가지 않을 수 있으니 피하고, sudo도 붙이지 마세요. 최신 버전을 유지하는 것은 새 기능뿐만 아니라 보안 패치와 안정성 개선에도 중요합니다. Claude Code 팀은 종종 일주일에 여러 번 업데이트를 제공하므로, 네이티브 설치 프로그램의 자동 업데이트 메커니즘은 수동 개입 없이 항상 최신 수정 사항과 기능을 확보하는 데 매우 유용합니다. Claude Code의 autoUpdatesChannel 설정으로 자동 업데이트와 claude update가 따르는 릴리스 채널도 고를 수 있습니다. 기본값인 latest 채널은 새 버전을 나오는 즉시 받고, stable 채널은 보통 일주일 정도 지난 버전을 쓰며 큰 회귀가 있었던 릴리스는 건너뜁니다. 프로덕션 작업에는 stable 채널을, 새로운 기능에 먼저 접근하려면 latest 채널을 사용하는 것이 좋습니다. Homebrew는 이 설정 대신 cask 이름으로 채널을 고릅니다(claude-code는 stable, claude-code@latest는 latest).

자주 묻는 질문

Claude Code는 무료로 사용할 수 있나요?

Claude Code 자체는 무료로 설치할 수 있으며, 바이너리 다운로드에는 비용이 들지 않습니다. 그러나 인증하고 실제로 사용하려면 유료 Claude 플랜이나 Claude Console 계정이 필요합니다. 구독으로 쓴다면 Claude Code가 포함된 가장 저렴한 플랜은 Claude Pro이며, 2026년 10월 20일 기준 월간 결제 $20/월, 연간 결제 시 월 $17입니다. 무료 Claude 플랜에는 Claude Code 접근이 포함되어 있지 않습니다. 또는 Claude Console 계정이나 Anthropic API 키로 종량제 과금을 쓸 수 있으며, 이 경우 구독 없이 월 정액이 아닌 코딩 세션 중 소비된 토큰에 따라 요금이 부과됩니다.

Claude Code는 오프라인에서 작동하나요?

아니요, Claude Code는 작동하려면 인터넷 연결이 필요합니다. 요청을 처리하기 위해 클라우드의 Anthropic Claude 모델과 통신하므로, 사용 중 안정적인 인터넷 연결이 필요합니다. 코드 자체는 컨텍스트를 위해 로컬에서 처리되지만, AI 추론은 Anthropic 서버에서 이루어집니다. 일부 설정은 로컬에 캐시되므로 실행과 기본 탐색은 연결 없이 작동하지만, 실제 AI 기반 어시스턴스는 온라인 상태가 필요합니다.

Claude Code를 VS Code나 JetBrains와 함께 사용할 수 있나요?

Claude Code는 독립형 터미널 도구이며 어떤 IDE도 필요하지 않습니다. 그러나 터미널에서 작동하므로 어떤 에디터나 IDE와 함께 사용할 수 있습니다. 많은 개발자들이 VS Code의 통합 터미널에서 분할 터미널 레이아웃으로 Claude Code를 실행하거나, JetBrains IDE 옆에 별도의 터미널 탭에서 실행합니다. 에디터 안에서 쓰고 싶다면 Anthropic이 공식으로 제공하는 VS Code 확장과 JetBrains 플러그인도 있습니다. 다만 VS Code 확장은 채팅 패널용 CLI 사본을 자체적으로 포함할 뿐 claude를 PATH에 추가하지 않으므로, 터미널에서 claude 명령을 쓰려면 위의 설치 명령으로 CLI를 따로 설치해야 합니다.

Claude Code를 어떻게 삭제하나요?

claude uninstall 같은 삭제 명령은 없으며, 설치한 방식에 맞는 명령으로 지웁니다. 네이티브 설치는 macOS/Linux/WSL에서 rm -f ~/.local/bin/claude와 rm -rf ~/.local/share/claude를 실행합니다. Windows PowerShell에서는 %USERPROFILE%\.local\bin\claude.exe 파일과 %USERPROFILE%\.local\share\claude 폴더를 Remove-Item으로 지웁니다. Homebrew를 통해 설치한 경우 brew uninstall --cask claude-code(latest cask라면 brew uninstall --cask claude-code@latest)를 사용하세요. WinGet의 경우 winget uninstall Anthropic.ClaudeCode를 사용하세요. npm을 통해 설치한 경우 npm uninstall -g @anthropic-ai/claude-code를 사용하세요. ~/.claude/에 있는 설정 파일은 직접 지우기 전까지 남아 있으므로, 나중에 다시 설치해도 설정을 잃지 않습니다. 설정까지 완전히 지우려면 rm -rf ~/.claude와 rm ~/.claude.json을 실행하되, VS Code 확장이나 데스크톱 앱이 남아 있으면 이 폴더가 다시 만들어지므로 그 앱들을 먼저 제거하세요. 삭제 후에도 claude가 실행된다면 다른 설치본이 남아 있는 것이니 which -a claude로 찾아 정리합니다.

Claude Code와 Claude 데스크톱 앱의 차이점은 무엇인가요?

Claude 데스크톱 앱은 claude.ai와 유사한 그래픽 채팅 인터페이스를 컴퓨터의 네이티브 애플리케이션으로 제공합니다. 반면 Claude Code는 소프트웨어 개발에 특화된 커맨드라인 도구입니다. Claude Code는 프로젝트의 파일을 읽고 수정하고, 터미널 명령을 실행하고, git과 상호작용하며, 멀티 파일 편집을 수행할 수 있습니다. 이러한 기능은 데스크톱 앱에는 없습니다. 데스크톱 앱은 범용 AI 어시스턴트이고, Claude Code는 터미널에 상주하는 전문 코딩 파트너라고 생각하면 됩니다.

Claude Code 사용량은 구독 한도에서 어떻게 차감되나요?

Claude Code 사용량은 구독의 사용 한도에서 차감되며, claude.com/pricing은 터미널 작업과 채팅이 같은 사용량 풀을 쓴다고 설명합니다. 한도는 5시간 단위의 롤링 세션으로 재설정되고 유료 플랜에는 주간 한도도 있어서, 대규모 코드베이스를 다루거나 연속적인 작업이 많은 무거운 Claude Code 세션은 Pro 사용량을 빠르게 소모할 수 있습니다. 2026년 10월 20일 기준 Max 5x($100/월)는 Pro 세션당 사용량의 5배, Max 20x($200/월)는 20배를 제공하며, Anthropic은 어느 플랜에도 고정된 토큰 수나 메시지 수를 공개하지 않습니다. 사용 한도에 도달하면 Claude Code가 알려주며, 한도가 재설정될 때까지 기다리거나 더 높은 등급으로 업그레이드하거나, 유료 플랜이라면 표준 API 요금으로 과금되는 사용 크레딧을 켜고 계속 작업할 수 있습니다. 구독 대신 Console 계정이나 API 키를 사용하면 구독 세션 한도 없이 종량제 가격을 받을 수 있지만, API 속도 제한은 여전히 적용되고 집중 사용 시 비용이 누적될 수 있습니다.

CI/CD 파이프라인이나 자동화 스크립트에서 Claude Code를 사용할 수 있나요?

네, Claude Code는 자동화 환경에서 잘 작동하는 비대화형 사용을 지원합니다. claude -p "generate unit tests for src/utils.ts"와 같이 명령을 인수로 직접 전달하면 대화형 프롬프트 없이 작업을 실행하고 결과를 출력합니다. CI/CD 통합의 경우, 대화형 브라우저 로그인 대신 환경 변수로 저장된 API 키를 사용하여 인증하는 것이 일반적입니다. 이를 통해 빌드 파이프라인의 일부로 자동화된 코드 리뷰, 테스트 생성 또는 문서 업데이트에 Claude Code를 사용할 수 있습니다. --output-format json 플래그는 스크립트 컨텍스트에서 특히 유용한데, 다른 도구가 프로그래밍 방식으로 파싱할 수 있는 구조화된 출력을 반환하기 때문입니다.

지금 바로 Claude Code로 코딩을 시작하세요

Claude Code 설치는 어떤 플랫폼에서든 5분도 걸리지 않으며, 네이티브 설치 프로그램은 단일 명령 실행만큼 프로세스를 간단하게 만듭니다. 시스템이 요구 사항(macOS 13+, Windows 10 1809+, 또는 Linux Ubuntu 20.04+)을 충족하는지 확인하고, 유료 Claude 플랜(Pro $20/월부터) 또는 Claude Console 계정이 있는지 확인한 다음, 해당 플랫폼에 맞는 설치 명령을 실행하세요. 네이티브 설치 프로그램은 대부분의 사용자에게 권장되는 선택입니다. 의존성을 자동으로 처리하고, 수동 개입 없이 최신 상태를 유지하며, Anthropic이 적극적으로 테스트하고 지원하는 가장 안정적인 경험을 제공합니다.

공식 출처(claude.ai, code.claude.com, 또는 GitHub anthropics/claude-code)에서만 다운로드하여 가짜 Google Ads를 통해 Claude Code 사용자를 표적으로 한 악성코드 캠페인으로부터 자신을 보호하세요. 설치 중 문제가 발생하면 위의 문제 해결 섹션에서 가장 흔한 다섯 가지 문제와 해결 방법을 다루고 있으며, claude doctor 명령은 진단 출발점으로 항상 사용할 수 있습니다. 설치가 완료되면 프로젝트 디렉토리로 이동하여 claude를 입력하고 빌드를 시작하세요. 새 기능 구현, 레거시 코드 리팩토링, 전체 코드베이스에 걸친 까다로운 이슈 디버깅 등 무엇이든 가능합니다. 여러분의 터미널이 가장 강력한 코딩 도구가 되었으며, 이제 모든 플랫폼에서 Claude Code를 안전하고 효과적으로 설치, 설정, 유지관리하는 지식을 갖추게 되었습니다.