Claude Code 설치 방법 Windows macOS 첫 프로젝트 안전 설정

Claude Code 설치는 운영체제에 맞는 공식 명령 한 줄을 실행하고, claude --version으로 확인한 뒤 프로젝트 폴더에서 claude를 시작하면 됩니다. macOS·Linux·WSL은 셸 설치 스크립트, Windows는 PowerShell 설치 명령이 공식 네이티브 경로입니다. 처음부터 홈 폴더 전체를 열지 말고 복사하거나 새로 만든 연습 프로젝트에서 시작하는 것이 안전합니다.

첫 세션에서는 바로 “전부 고쳐줘”라고 요청하지 마세요. 먼저 읽기 질문으로 구조를 파악하고, Plan 모드로 수정 파일과 명령을 확인한 다음 작은 변경만 승인해야 합니다. Manual 모드에서는 읽기 중심이며 수정과 대부분의 셸·네트워크 작업 전에 승인을 요구합니다. 다만 현재 Pro·Max·Team 터미널 세션은 Auto 모드로 시작할 수 있어 일부 편집과 명령이 사용자 확인 없이 실행될 수 있습니다. 첫 실습은 상태 표시줄에서 Manual 또는 Plan 모드를 확인하고 시작하세요.

30초 설치 순서

Claude Pro·Max·Team·Enterprise, Console 계정 또는 지원 클라우드 접근을 준비합니다.
운영체제별 공식 네이티브 설치 명령을 실행합니다.
claude --version으로 설치를 확인합니다.
연습 프로젝트 폴더로 이동해 claude를 실행하고 브라우저 로그인을 완료합니다.
첫 질문은 “이 프로젝트의 구조와 진입점을 설명하고 파일은 수정하지 마”로 시작합니다.
Shift+Tab으로 Plan 모드를 선택하고 계획을 승인한 뒤 작은 변경과 테스트만 진행합니다.

Claude Code를 쓰기 전에 준비할 것

클로드 코드 설치 후 Claude Code는 터미널이나 지원 IDE에서 코드베이스를 읽고, 파일을 수정하고, 테스트와 Git 명령을 실행할 수 있습니다. 현재 공식 최소 조건은 macOS 13 이상, Windows 10 1809 이상 또는 Windows Server 2019 이상, 4GB 이상 RAM, x64·ARM64 프로세서, 인터넷 연결과 Anthropic 지원 국가입니다.

준비 항목	권장 상태	이유
계정	Pro·Max·Team·Enterprise 구독, Console 또는 지원 클라우드	공식 빠른 시작 문서의 접근 조건
터미널	macOS Terminal, Windows PowerShell, Linux 셸	설치와 첫 실행에 필요
프로젝트	Git으로 관리되는 복사본 또는 새 연습 폴더	변경점을 diff로 확인하고 되돌리기 쉬움
비밀정보	`.env`, 키 파일, 운영 DB 자격증명을 분리	에이전트가 불필요한 민감 파일을 읽는 위험 축소
검증 명령	테스트, 빌드, 린트 명령을 미리 파악	변경 완료 조건을 객관적으로 확인

가격과 모델 선택이 먼저 궁금하다면 기존 Claude Sonnet 5 가격과 모델 선택 기준을 함께 보세요. 이 글은 모델 비교가 아니라 설치부터 첫 로컬 작업까지의 실행 절차에 초점을 둡니다.

운영체제별 Claude Code 설치 방법

Claude Code Windows macOS Linux 설치 명령과 실행 순서 썸네일

아래 명령은 2026년 8월 13일 Anthropic 공식 빠른 시작 문서 기준입니다. 터미널에 붙여넣기 전에 도메인이 claude.ai인지 확인하고, 블로그나 댓글에서 변형된 설치 명령을 그대로 실행하지 마세요.

macOS Linux WSL 네이티브 설치

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

네이티브 설치는 공식 문서에서 권장하는 경로이며 백그라운드 자동 업데이트를 지원합니다. 설치 후 새 터미널을 열고 버전을 확인합니다.

claude --version

Windows PowerShell과 CMD 설치

시작 메뉴에서 PowerShell을 열었다면 다음 명령을 실행합니다.

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

명령 프롬프트 CMD에서는 다음 공식 명령을 사용합니다.

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

PowerShell과 CMD 명령은 서로 호환되지 않습니다. 프롬프트 앞에 PS C:가 보이면 PowerShell입니다. 네이티브 Windows에서는 Git for Windows가 설치되어 있으면 Bash 도구를 사용할 수 있고, 없으면 PowerShell이 셸 도구로 사용됩니다. WSL 환경은 별도로 Git for Windows가 필요하지 않습니다.

Homebrew와 WinGet을 고를 때

패키지 관리 도구로 버전을 통일해야 하는 환경이라면 Homebrew나 WinGet도 공식 지원됩니다.

# macOS Homebrew 안정 채널
brew install --cask claude-code

# Windows WinGet
winget install Anthropic.ClaudeCode

다만 Homebrew와 WinGet 설치는 자동 업데이트가 아닙니다. 보안 수정과 새 기능을 받으려면 각각 brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode를 주기적으로 실행해야 합니다. npm 전역 설치도 현재 공식 지원됩니다. 다만 새 설치에는 자동 업데이트되는 네이티브 설치를 우선하고, npm 설치를 선택하면 Node.js 22 이상과 수동 업그레이드 조건을 확인하세요.

로그인과 과금 방식을 먼저 구분하기

설치 후 claude를 실행하면 첫 사용 시 브라우저 인증이 열립니다. Claude Pro·Max·Team·Enterprise 구독, Claude Console 선불 크레딧 또는 지원 클라우드 공급자로 로그인할 수 있습니다. 같은 화면처럼 보여도 구독 포함 사용량과 API 종량제는 과금 체계가 다릅니다.

예상 밖 API 요금 방지
컴퓨터에 ANTHROPIC_API_KEY 환경 변수가 설정돼 있으면 구독 로그인을 건너뛰고 API 키 사용을 제안할 수 있습니다. 그러면 Pro나 Max 포함 사용량이 아니라 API 사용료가 발생할 수 있습니다. 구독 한도 안에서만 쓰려면 /login에서 구독 계정으로 인증하고, 한도 초과 시 API 크레딧 전환 제안을 거절하세요.

로그인 후에는 /status 또는 /usage로 계정과 사용량을 확인할 수 있습니다. Claude 채팅과 Claude Code 사용량은 구독 한도를 공유합니다. 따라서 웹 채팅을 많이 쓴 날에는 코드 세션 한도가 예상보다 빨리 줄어들 수 있습니다. 기능과 가격은 바뀔 수 있으므로 실제 구독 화면과 공식 가격 페이지를 확인하세요.

첫 프로젝트 폴더에서 안전하게 시작하기

가장 흔한 초보 실수는 홈 디렉터리나 여러 저장소가 섞인 상위 폴더에서 Claude Code를 실행하는 것입니다. 공식 보안 문서도 프로젝트 하위 폴더에서 시작할 것을 권합니다. Manual 모드에서는 시작 폴더와 하위 폴더가 기본 쓰기 경계입니다. Auto 모드는 범위 밖 읽기에 별도 승인을 요구하지 않을 수 있으므로 민감한 저장소에서는 Manual, 권한 규칙과 샌드박스를 함께 확인하고 첫 실행의 workspace trust 경로를 읽은 뒤 승인하세요.

cd /path/to/your/project
claude

프로젝트가 아직 없다면 작은 연습 폴더를 만들어 README나 간단한 예제 파일로 시작하세요. 실제 서비스 저장소를 사용한다면 새 Git 브랜치를 만들고 작업 전 상태가 깨끗한지 확인합니다.

git status
git switch -c test/claude-code-first-run

Git을 쓰지 않는 폴더라면 원본을 복사해 별도 작업 폴더를 만드는 것이 최소 안전장치입니다. 운영 서버, 동기화된 중요 문서 폴더, 비밀키가 있는 홈 폴더에서 첫 실습을 시작하지 마세요.

읽기 계획 변경 테스트 4단계 루프

Claude Code 첫 프로젝트 읽기 계획 변경 테스트 안전 루프 썸네일

1 읽기 질문으로 구조를 파악합니다

첫 프롬프트에서 수정 금지를 명시합니다.

이 프로젝트의 목적, 주요 폴더, 실행 진입점, 테스트 명령을 설명해줘.
아직 파일을 수정하거나 명령을 실행하지 마.

설명이 실제 README와 파일 구조에 맞는지 확인하세요. 잘못 이해한 부분이 있다면 구현 전에 바로잡아야 불필요한 수정과 토큰 사용을 줄일 수 있습니다.

2 Plan 모드에서 변경 범위를 고정합니다

Shift+Tab을 눌러 Plan 모드로 전환한 뒤 수정할 파일, 실행할 명령, 테스트 기준을 먼저 요청합니다. Plan 모드는 소스 파일 편집을 막고 탐색과 계획 수립에 사용됩니다. 다만 읽기 전용 셸 명령은 실행될 수 있고, Auto가 제공되는 환경에서는 분류기가 승인한 탐색 명령이 실행될 수 있으므로 표시되는 명령도 확인하세요.

로그인 폼의 빈 입력만 막으려 해.
수정할 파일과 테스트 방법을 계획으로만 제시해줘.

계획에 요청하지 않은 데이터베이스 변경, 패키지 교체, 광범위한 리팩터링이 포함되면 범위를 줄여 다시 요청합니다.

3 작은 변경만 승인하고 diff를 읽습니다

Manual 모드에서는 파일 수정과 대부분의 셸·네트워크 작업 전에 승인을 요구합니다. Auto 모드에서는 분류기가 작업을 검토하고 일부 편집과 명령을 별도 프롬프트 없이 실행할 수 있으므로 현재 모드를 먼저 확인하세요. 명령이 이해되지 않으면 승인 창에서 설명 기능을 사용하거나 /permissions로 현재 허용·질문·차단 규칙을 확인하세요.

acceptEdits는 파일 편집을 자동 승인하므로 첫 프로젝트에서는 기본 또는 Plan 모드가 더 안전합니다. 특히 모든 권한 확인을 우회하는 설정은 신뢰할 수 있는 격리 환경 외에는 사용하지 마세요. 에이전트 권한의 피해 범위를 더 넓게 설계하려면 AI 에이전트 권한과 피해 범위 점검법을 참고할 수 있습니다.

4 테스트와 Git diff를 확인한 뒤 커밋합니다

git diff
# 프로젝트에 맞는 테스트 명령 실행
npm test

테스트가 통과했다는 문장만 믿지 말고 실제 출력과 변경 파일을 확인하세요. 테스트가 없는 프로젝트라면 재현 절차, 예상 입력과 출력, 되돌리기 방법을 먼저 만들게 하세요. 중요한 변경은 코드 리뷰와 보안 검사를 별도로 거쳐야 합니다.

승인 창에서 멈춰야 하는 신호

현재 프로젝트의 상위 폴더나 홈 폴더 전체를 읽겠다고 합니다.
.env, SSH 키, 클라우드 자격증명, 브라우저 프로필을 읽으려 합니다.
curl, wget 또는 새 MCP를 통해 외부 서비스로 데이터를 보내려 합니다.
요청 범위보다 많은 파일을 삭제하거나 패키지를 전면 교체합니다.
테스트 없이 Git 커밋이나 원격 push를 실행하려 합니다.
명령 설명과 실제 셸 명령의 대상 경로가 다릅니다.

웹페이지, 이슈, README 같은 외부 콘텐츠 안에는 에이전트를 속이는 프롬프트 인젝션 문구가 있을 수 있습니다. Anthropic은 네트워크 요청, 새 MCP, 첫 코드베이스에 별도 확인 절차를 두지만 완전한 방어는 아닙니다. 외부에서 받은 스크립트나 설치 문장을 파이프로 바로 실행하지 말고, 민감한 저장소는 dev container나 가상머신에서 작업하세요.

처음 써볼 만한 프롬프트 5개

이 저장소의 목적과 폴더 구조를 설명하고 수정하지 마.
실행과 테스트 명령을 README와 설정 파일 근거로 찾아줘.
현재 브랜치 변경 사항을 읽고 위험도가 큰 순서로 리뷰해줘.
이 버그를 재현하는 최소 테스트 계획만 작성해줘.
한 파일만 수정하는 가장 작은 해결책을 제안하고 승인 전 멈춰줘.

구체적인 파일, 완료 기준, 테스트 대상을 포함하면 전체 저장소를 불필요하게 훑는 일을 줄일 수 있습니다. 복잡한 작업은 Plan 모드에서 먼저 합의하고, 서로 무관한 작업으로 넘어갈 때는 /clear로 긴 컨텍스트를 비우세요.

사용량과 비용을 줄이는 기본 습관

습관	효과	명령 또는 방법
무관한 작업 분리	오래된 대화가 매 요청에 포함되는 비용 축소	`/clear`
사용량 확인	구독 한도와 긴 컨텍스트 원인 점검	`/usage`
계획 먼저 작성	잘못된 방향의 재작업 방지	Shift+Tab Plan 모드
구체적인 범위 지정	불필요한 파일 읽기와 수정 감소	파일명·함수·테스트 명시
세션 진단	설정, MCP, 컨텍스트 문제 확인	`/doctor` 또는 `claude doctor`

Pro·Max 사용자는 구독에 Claude Code가 포함되지만 무제한은 아닙니다. 더 많은 사용이 필요할 때 API 크레딧을 켜면 표준 API 요금이 별도로 적용됩니다. 개인의 손익분기점은 저장소 크기와 세션 길이에 따라 달라지므로 가격표만 보고 자동 전환을 켜지 말고 일주일 사용 기록으로 판단하세요. 고성능 모델 선택과 비용 차이는 Claude Opus 5 비용과 effort 도입 가이드에서 이어서 확인할 수 있습니다.

설치 문제 빠르게 해결하기

claude 명령을 찾지 못함: 새 터미널을 열고 다시 확인합니다. PATH 문제라면 공식 설치 문제 해결 문서를 따릅니다.
PowerShell에서 && 오류: CMD용 명령을 PowerShell에 입력한 경우입니다. 사용 중인 셸에 맞는 명령을 사용합니다.
로그인 반복 또는 구독이 안 보임: /logout, claude update, 터미널 재시작 후 claude에서 올바른 계정을 고릅니다.
예상 밖 API 키 인증: ANTHROPIC_API_KEY 환경 변수를 확인하고 구독 계정으로 다시 로그인합니다.
설정이나 MCP가 동작하지 않음: 실행 중이면 /doctor, 시작되지 않으면 셸에서 claude doctor를 실행합니다.

공식 자료

자주 묻는 질문

Claude Code는 무료 계정으로 설치해 쓸 수 있나요?

설치 파일 자체와 서비스 접근 조건은 구분해야 합니다. 공식 빠른 시작 문서는 Claude Pro·Max·Team·Enterprise 구독, Claude Console 계정 또는 지원 클라우드 접근을 준비 조건으로 안내합니다. 구독과 API 요금은 별도 체계이므로 로그인 화면과 실제 계정 조건을 확인하세요.

Windows에서 Git for Windows가 꼭 필요한가요?

필수는 아닙니다. 공식 문서는 네이티브 Windows에서 Git for Windows를 권장하며, 설치되어 있으면 Claude Code가 Bash 도구를 사용할 수 있습니다. 없으면 PowerShell이 셸 도구로 사용되고, WSL 환경에는 Git for Windows가 필요하지 않습니다.

Claude Code가 내 컴퓨터 파일을 마음대로 바꾸나요?

Manual 모드에서는 읽기 중심이며 수정과 대부분의 셸·네트워크 작업 전에 승인을 요구합니다. Auto 모드에서는 분류기가 일부 작업을 사용자 확인 없이 실행할 수 있습니다. 첫 프로젝트에서는 Manual 또는 Plan 모드를 직접 선택하고 프로젝트 하위 폴더에서 모든 변경을 Git diff로 검수하세요.

Pro 요금제를 쓰는데 API 요금이 따로 청구될 수 있나요?

가능합니다. ANTHROPIC_API_KEY 환경 변수가 설정되어 있거나 한도 초과 후 API 크레딧 사용에 동의하면 구독 포함 사용량과 별도로 표준 API 요금이 적용될 수 있습니다. 구독 한도만 쓰려면 올바른 계정으로 로그인하고 API 크레딧 전환을 거절하며 /usage를 확인하세요.

결론

공식 설치 경로를 사용한 뒤 연습용 프로젝트에서 Manual 또는 Plan 모드로 시작하고, 실제 변경은 Git diff와 테스트 결과로 확인하세요.