Claude Code 시작하기

Claude Code 설치부터 첫 프로젝트 설정까지, 단계별로 안내해드립니다.

1
시스템 요구사항
2
설치
3
인증
4
첫 프로젝트

1시스템 요구사항 확인

운영체제

  • macOS 10.15 이상
  • Ubuntu 20.04+ / Debian 10+
  • Windows 10+ (네이티브 지원)

하드웨어 & 소프트웨어

  • 최소 4GB RAM
  • Node.js 18 이상
  • 인터넷 연결
  • Git 2.23+ (선택사항)

Windows 사용자 안내

네이티브 지원: Git for Windows 설치 시 Git Bash에서 직접 실행 가능합니다.
WSL 옵션: WSL 1 또는 WSL 2에서도 사용 가능합니다.

2Claude Code 설치

1. 터미널 열기

운영체제에 따라 터미널을 여는 방법이 다릅니다:

💡 추천 터미널: Ghostty

GPU 가속 렌더링으로 초고속 성능을 자랑하는 네이티브 터미널입니다. Claude Code와 함께 사용하면 더욱 빠르고 부드러운 개발 경험을 제공합니다.

10배 빠른 렌더링macOS, Linux 지원다운로드 →

macOS

Cmd + Space를 누르고 "터미널" 또는 "Terminal"을 입력하거나,
응용 프로그램 → 유틸리티 → 터미널을 실행하세요.

Windows

네이티브 지원: Git Bash (Git for Windows 필요)
WSL 옵션: Win 키를 누르고 "wsl"을 입력

Linux

Ctrl + Alt + T를 누르거나,
응용 프로그램 메뉴에서 "Terminal" 또는 "터미널"을 찾아 실행하세요.

2. Node.js 설치 확인

터미널에서 Node.js가 설치되어 있는지 확인합니다:

터미널
node --version

v18.0.0 이상이 표시되어야 합니다. 설치되지 않았다면 nodejs.org에서 다운로드하세요.

3. Claude Code 설치

운영체제에 따라 다양한 설치 방법을 선택할 수 있습니다:

npm (모든 플랫폼)

터미널
npm install -g @anthropic-ai/claude-code

Homebrew (macOS/Linux)

터미널
brew install claude-code

curl (직접 설치)

터미널
curl -fsSL https://claude.ai/install.sh | sh

Windows Git Bash 추가 설정

Portable Git 설치 시 bash 경로를 지정해야 할 수 있습니다:

$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

중요한 주의사항

sudo npm install -g를 사용하지 마세요. 권한 문제와 보안 위험을 초래할 수 있습니다.

4. 설치 확인

터미널
claude --version

Claude Code 버전이 표시되면 설치가 완료된 것입니다.

3인증 설정

Claude Code 시작

프로젝트 디렉토리로 이동한 후 Claude Code를 시작합니다:

터미널
cd my-project
claude

인증 방법 선택

1

Anthropic Console (권장)

기본 옵션으로, Anthropic Console을 통해 OAuth 인증을 진행합니다.

  • • console.anthropic.com에서 활성 결제 필요
  • • 가장 안정적인 인증 방법
2

Claude Pro/Max 플랜

Claude.ai Pro 또는 Max 구독을 통한 통합 인증

  • • 웹 인터페이스와 동일한 계정 사용
  • • 하나의 구독으로 모든 서비스 이용
3

기업용 플랫폼

Amazon Bedrock 또는 Google Vertex AI 연동

  • • 기업 클라우드 인프라와 통합
  • • 규정 준수 및 보안 요구사항 충족
  • • 온프레미스 배포 가능
4

API Key 인증

환경 변수를 통한 직접 API Key 설정

export ANTHROPIC_API_KEY="sk-ant-..."

4첫 프로젝트 초기화

1. 프로젝트 요약 생성

Claude Code가 프로젝트를 이해할 수 있도록 요약을 생성합니다:

Claude Code
claude> 이 프로젝트에 대해 요약해줘

2. CLAUDE.md 파일 생성

프로젝트 가이드 파일을 자동으로 생성합니다:

Claude Code
claude> /init

이 명령어는 프로젝트의 구조, 개발 명령어, 아키텍처 정보를 포함한 CLAUDE.md 파일을 생성합니다.

3. 변경사항 커밋

생성된 CLAUDE.md 파일을 저장소에 추가합니다:

Claude Code
claude> CLAUDE.md 파일을 커밋해줘

축하합니다!

Claude Code 설정이 완료되었습니다. 이제 자연어 명령으로 코딩을 시작할 수 있습니다.

다음 단계

기본 사용법 익히기

  • • 코드 질문하기: "인증이 어떻게 작동하는지 설명해줘"
  • • 파일 편집하기: "폼에 입력 검증을 추가해줘"
  • • 테스트 실행하기: "테스트를 실행하고 실패한 부분을 수정해줘"

고급 기능 탐험

  • • 확장된 사고: "이 기능의 아키텍처에 대해 깊이 생각해봐"
  • • Git 자동화: "이 기능에 대한 PR을 생성해줘"
  • • 웹 검색: Claude가 자동으로 문서를 찾아 참조
홈으로 돌아가기실전 튜토리얼

문제 해결

WSL에서 설치 오류가 발생해요

WSL에서 Windows npm을 사용하고 있을 수 있습니다. 다음을 시도해보세요:

터미널
npm config set os linux

또는 강제 설치:

터미널
npm install -g @anthropic-ai/claude-code --force --no-os-check
"node: not found" 오류가 나타나요

WSL이 Windows Node.js를 사용하고 있을 수 있습니다. 다음으로 확인:

터미널
which node && which npm

경로가 /mnt/c/로 시작한다면 Linux용 Node.js를 설치하세요:

터미널
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
권한 오류가 발생해요

npm 글로벌 설치 권한을 설정하세요:

터미널
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

그리고 ~/.bashrc 또는 ~/.zshrc에 추가:

설정 파일
export PATH=~/.npm-global/bin:$PATH

더 많은 문제 해결 방법은 문제 해결 가이드를 참고하세요.