[Claude] Claude Code 설치 및 시작하기 (Mac/Windows/Linux)

Claude API의 강력한 기능을 터미널에서 직접 사용할 수 있는 Claude Code.

코드 작성, 디버깅, 리팩토링을 자연어 대화로 해결하는 혁신적인 개발 도구입니다.

이번 가이드에서는 Claude Code 설치부터 첫 사용까지, 운영체제별 완벽 설치 가이드를 제공합니다.

 

 

Claude Code란?

Claude Code는 Anthropic이 개발한 AI 코딩 어시스턴트로, 터미널, IDE, 브라우저에서 작동합니다.

 

핵심 기능

1. 자연어로 코드 작성

claude "React로 To-Do 앱 만들어줘"

설명만 하면 Claude가 코드를 작성하고 테스트합니다.

2. 버그 자동 수정

claude "npm test 실패 원인 찾아서 고쳐줘"

에러 메시지를 분석하고 자동으로 수정합니다.

3. 코드베이스 이해

claude "이 프로젝트 구조 설명해줘"

전체 프로젝트를 분석하여 명확한 설명을 제공합니다.

4. Git 통합

claude commit
claude "PR 만들어줘"

Git 작업을 자연어로 처리합니다.

 

사용 가능한 플랫폼

• Terminal (CLI) - 메인 사용 방식
• Web - claude.ai/code (설치 불필요)
• Desktop App - 독립 실행형 앱
• VS Code - 확장 프로그램
• JetBrains - IntelliJ, PyCharm 등 플러그인
• GitHub Actions - CI/CD 자동화
• GitLab CI/CD - 파이프라인 통합

 

설치 전 확인사항

시스템 요구사항

항목	요구사항
OS	macOS 13.0+ / Windows 10 1809+ / Ubuntu 20.04+
RAM	4GB 이상 (8GB 권장)
네트워크	인터넷 연결 필수
계정	Claude Pro/Max/Teams/Enterprise 또는 Console

필요한 것들

•  Claude 구독 (Pro, Max, Teams, Enterprise) 또는 API 크레딧
•  안정적인 인터넷 연결
•  Git (버전 관리 기능 사용 시)
• Anthropic 지원 국가에 위치

설치 방법

macOS & Linux (권장)

가장 간단한 방법은 curl 설치:

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

Homebrew 사용:

brew install --cask claude-code

⚠️ 주의: Homebrew 설치는 자동 업데이트가 되지 않습니다.
주기적으로 brew upgrade claude-code 실행이 필요합니다.

 

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

WinGet:

winget install Anthropic.ClaudeCode

⚠️ 주의: WinGet 설치는 자동 업데이트가 되지 않습니다.
winget upgrade Anthropic.ClaudeCode로 수동 업데이트하세요.

 

Windows WSL (Windows Subsystem for Linux)

WSL 1 또는 WSL 2 모두 지원:

1. WSL 터미널 열기
2. Linux 설치 명령어 실행:

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

WSL 2 사용 장점:

• 샌드박스 모드 지원 (보안 강화)
• 더 빠른 파일 시스템 성능

설치 확인

설치 후 다음 명령어로 확인:

claude doctor

출력 예시:

✓ Claude Code v1.x.x installed
✓ Installation type: Native
✓ Auto-updates enabled
✓ All systems operational

 

첫 실행 및 로그인

1단계: Claude Code 실행

터미널에서:

claude

처음 실행하면 로그인 프롬프트가 나타납니다.

2단계: 로그인

브라우저가 자동으로 열리며 다음 중 하나로 로그인:

• Claude Pro/Max/Teams/Enterprise (권장)
• Claude Console (API 크레딧 사용)
• Amazon Bedrock / Google Vertex AI / Microsoft Foundry

로그인 후 자격 증명이 저장되어 다시 로그인할 필요 없습니다.

계정 전환:

/login

초기 설정

기본 설정 확인

/config

설정 메뉴에서 다음을 조정할 수 있습니다:

• ✅ 기본 모델 선택 (Opus/Sonnet/Haiku)
• ✅ Thinking 모드 활성화
• ✅ 자동 업데이트 채널 (latest/stable)
• ✅ 권한 모드 설정

 

CLAUDE.md 생성 (중요!)

프로젝트 루트에 .claude/CLAUDE.md 파일 생성:

mkdir -p .claude
touch .claude/CLAUDE.md

CLAUDE.md 예시:

# 프로젝트 개요
이 프로젝트는 React와 Node.js를 사용한 웹 애플리케이션입니다.

## 기술 스택
- Frontend: React 18, TypeScript
- Backend: Node.js, Express
- Database: PostgreSQL
- Testing: Jest, React Testing Library

## 아키텍처
- MVC 패턴 사용
- RESTful API 구조
- JWT 기반 인증

## 개발 환경 설정
\`\`\`bash
npm install
npm run dev
\`\`\`

## 코딩 컨벤션
- ESLint + Prettier 사용
- 함수명은 camelCase
- 컴포넌트명은 PascalCase

이 파일은 Claude가 프로젝트를 이해하는 데 사용되며, 모든 대화에서 자동으로 로드됩니다.

 

권한 설정

.claude/settings.json 파일을 생성하여 권한 모드 설정:

{
  "permissions": {
    "defaultMode": "normal"
  }
}

권한 모드:

• Normal - Claude가 파일 변경 전 승인 요청 (기본값)
• Auto-Accept - 파일 수정 자동 적용 (빠름, 위험)
• Plan - 계획만 수립, 실행하지 않음 (안전)

 

첫 번째 명령어

기본 명령어

명령어	설명	예시
claude	대화형 세션 시작	claude
claude "작업"	일회성 작업 실행	claude "hello world 함수 추가"
claude -p "질문"	질문 후 종료	claude -p "이 함수 설명"
claude -c	최근 대화 계속	claude -c
claude commit	Git 커밋 생성	claude commit
/help	도움말 보기	/help
/config	설정 메뉴	/config
/resume	이전 세션 재개	/resume
/clear	대화 기록 삭제	/clear

 

처음 물어볼 질문

Claude Code를 시작한 후 다음 질문들을 시도해보세요:

프로젝트 이해:

이 프로젝트는 뭐하는 거야?

어떤 기술 스택을 사용하고 있어?

폴더 구조를 설명해줘

첫 코드 작성:

main.js에 hello world 함수를 추가해줘

Git 작업:

변경된 파일 목록 보여줘

적절한 커밋 메시지로 커밋해줘

 

키보드 단축키

Claude Code 대화 중 유용한 단축키:

단축키	기능
?	단축키 목록 보기
Ctrl+C 또는 exit	종료
Ctrl+O	Verbose 모드 (Thinking 과정 보기)
Tab	명령어 자동완성
↑ / ↓	명령어 히스토리
Ctrl+R	명령어 역방향 검색
Shift+Tab	권한 모드 전환
Option+T (Mac) / Alt+T (Windows)	Thinking 모드 토글

 

실전 사용 예제

예제 1: 버그 수정

claude

npm test를 실행했는데 에러가 나와.
에러 메시지: "TypeError: Cannot read property 'name' of undefined"
auth.js 파일에서 발생했어.

Claude가 코드를 분석하고 수정 방법을 제안합니다:

auth.js를 검토했습니다. user 객체가 null일 때 발생하는 문제입니다.
다음과 같이 수정하겠습니다:

- user.name → user?.name
또는 null 체크 추가

수정을 진행할까요?

예제 2: 리팩토링

utils.js의 콜백 함수들을 async/await로 바꿔줘

Claude가 파일을 분석하고 현대적인 코드로 리팩토링합니다.

예제 3: PR 생성

feature/auth 브랜치 만들고 변경사항 커밋한 다음 PR 만들어줘

한 번의 명령으로 브랜치 생성, 커밋, Push, PR 생성을 모두 수행합니다!

예제 4: 파이프라인 활용

cat build-error.txt | claude -p "이 빌드 에러의 근본 원인을 찾아줘"

유닉스 철학에 따라 다른 명령어와 연계하여 사용 가능합니다.

 

 

업데이트 관리

자동 업데이트

Native 설치 (curl/PowerShell):

• 백그라운드에서 자동 업데이트 ✅

Homebrew/WinGet 설치:

• 수동 업데이트 필요 ⚠️

수동 업데이트

claude update

Homebrew:

brew upgrade claude-code

WinGet:

winget upgrade Anthropic.ClaudeCode

업데이트 채널 변경

~/.claude/settings.json 편집:

{
  "autoUpdatesChannel": "stable"  # 또는 "latest"
}

• stable - 안정적인 릴리스만 (권장)
• latest - 최신 기능 빠르게 체험

 

자주 묻는 질문 (FAQ)

Q1. Claude Code는 무료인가요?

A: Claude Code 자체는 무료이지만, 사용하려면 다음 중 하나가 필요합니다:

• Claude Pro ($20/월)
• Claude Max ($60/월)
• Claude Teams (조직 요금제)
• Claude Console API 크레딧

 

Q2. 설치 없이 사용할 수 있나요?

A: 네! claude.ai/code에서 웹 브라우저로 바로 사용할 수 있습니다. 설치가 필요 없습니다.

 

Q3. VS Code 또는 JetBrains에서도 사용 가능한가요?

A: 네! 다음 확장 프로그램/플러그인을 설치하세요:

• VS Code: VS Code 마켓플레이스에서 "Claude Code" 검색
• JetBrains: Plugin 마켓플레이스에서 "Claude Code" 검색

 

Q4. 프라이빗 코드베이스도 안전한가요?

A: 네. Anthropic은 엄격한 프라이버시 정책을 따릅니다:

• 코드는 모델 학습에 사용되지 않음
• Enterprise 요금제는 추가 보안 기능 제공
• 데이터는 전송 중 암호화

 

Q5. 오프라인에서도 작동하나요?

A: 아니요. Claude Code는 인터넷 연결이 필요합니다. Claude 모델이 Anthropic 서버에서 실행되기 때문입니다.

 

Q6. Git 없이도 사용할 수 있나요?

A: 네! Git 기능 없이도 코드 작성, 리팩토링, 디버깅 등 대부분의 기능을 사용할 수 있습니다. Git은 선택 사항입니다.

 

다음 단계

더 알아보기

Claude Code를 설치했다면 다음 글들을 확인하세요:

• 7편: Claude Code 핵심 명령어 & 슬래시 커맨드 총정리 (예정)
• 8편: Claude Code VS Code 연동 - 개발환경 세팅 가이드 (예정)
• 9편: Claude Code MCP 서버 설정법 - GitHub, 파일시스템 연동 (예정)

추천 리소스

• 공식 문서
• Claude Code Cookbook
• Discord 커뮤니티

 

결론 - Claude Code로 개발 생산성 극대화

Claude Code는 자연어로 코드를 작성하는 새로운 시대를 엽니다.

핵심 요약:

1.  설치는 단 한 줄의 명령어로 완료
2.  웹에서 즉시 사용 가능 (claude.ai/code)
3.  터미널, IDE, 브라우저 모두 지원
4.  CLAUDE.md로 프로젝트 컨텍스트 유지
5.  Git 통합으로 버전 관리 간편화

다음 편에서는 Claude Code 핵심 명령어 & 슬래시 커맨드를 총정리합니다!

---

📌 관련 글:

• 5편: Claude API Tool Use (Function Calling) 구현하기
• 7편: Claude Code 핵심 명령어 & 슬래시 커맨드 총정리

🔗 참고 자료:

• Claude Code 공식 사이트
• Claude Code 설치 가이드
• CLAUDE.md 작성 가이드

---

Sources:

• Claude Code Official Documentation
• Claude Code Installation Guide
• Claude Code Getting Started