​
시스템 요구사항

  • 운영 체제: macOS 10.15+, Ubuntu 20.04+/Debian 10+, 또는 WSL을 통한 Windows
  • 하드웨어: 최소 4GB RAM
  • 소프트웨어:
    • Node.js 18+
    • git 2.23+ (선택사항)
    • PR 워크플로우를 위한 GitHub 또는 GitLab CLI (선택사항)
  • 네트워크: 인증 및 AI 처리를 위한 인터넷 연결 필요
  • 지역: 지원 국가에서만 사용 가능

​
설치 및 인증

1

Claude Code 설치

Install NodeJS 18+, then run:

npm install -g @anthropic-ai/claude-code

Do NOT use sudo npm install -g as this can lead to permission issues and security risks. If you encounter permission errors, see configure Claude Code for recommended solutions.

2

프로젝트로 이동

cd your-project-directory
3

Claude Code 시작

claude
4

인증 완료

Claude Code는 여러 인증 옵션을 제공합니다:

  1. Anthropic Console: 기본 옵션입니다. Anthropic Console을 통해 연결하고 OAuth 프로세스를 완료하세요. console.anthropic.com에서 활성 결제가 필요합니다.
  2. Claude App (Pro 또는 Max 플랜): Claude의 Pro 또는 Max 플랜에 구독하여 Claude Code와 웹 인터페이스를 모두 포함하는 통합 구독을 이용하세요. 동일한 가격대에서 더 많은 가치를 얻고 한 곳에서 계정을 관리할 수 있습니다. Claude.ai 계정으로 로그인하세요. 런칭 중에 구독 유형과 일치하는 옵션을 선택하세요.
  3. 엔터프라이즈 플랫폼: 기존 클라우드 인프라와 함께 엔터프라이즈 배포를 위해 Amazon Bedrock 또는 Google Vertex AI를 사용하도록 Claude Code를 구성하세요.

​
프로젝트 초기화

처음 사용하는 사용자에게는 다음을 권장합니다:

1

Claude Code 시작

claude
2

간단한 명령 실행

> summarize this project
3

CLAUDE.md 프로젝트 가이드 생성

/init
4

생성된 CLAUDE.md 파일 커밋

Claude에게 생성된 CLAUDE.md 파일을 저장소에 커밋하도록 요청하세요.

​
문제 해결

​
WSL 설치 문제 해결

현재 Claude Code는 Windows에서 직접 실행되지 않으며, 대신 WSL이 필요합니다.

WSL에서 다음과 같은 문제가 발생할 수 있습니다:

OS/플랫폼 감지 문제: 설치 중 오류가 발생하면 WSL이 Windows npm을 사용하고 있을 수 있습니다. 다음을 시도해보세요:

  • 설치 전에 npm config set os linux 실행
  • npm install -g @anthropic-ai/claude-code --force --no-os-check로 설치 (sudo 사용하지 마세요)

Node를 찾을 수 없음 오류: claude 실행 시 exec: node: not found가 표시되면 WSL 환경이 Windows의 Node.js 설치를 사용하고 있을 수 있습니다. which npm과 which node로 확인할 수 있으며, 이는 /mnt/c/가 아닌 /usr/로 시작하는 Linux 경로를 가리켜야 합니다. 이를 해결하려면 Linux 배포판의 패키지 매니저나 nvm을 통해 Node를 설치해보세요.

​
터미널 설정 최적화

Claude Code는 터미널이 적절히 구성되었을 때 가장 잘 작동합니다. 경험을 최적화하려면 다음 가이드라인을 따르세요.

지원되는 셸:

  • Bash
  • Zsh
  • Fish

​
테마 및 외관

Claude는 터미널의 테마를 제어할 수 없습니다. 이는 터미널 애플리케이션에서 처리됩니다. 온보딩 중이나 /config 명령을 통해 언제든지 Claude Code의 테마를 터미널에 맞출 수 있습니다.

​
줄 바꿈

Claude Code에 줄 바꿈을 입력하는 여러 옵션이 있습니다:

  • 빠른 이스케이프: \를 입력한 후 Enter를 눌러 새 줄을 만듭니다
  • 키보드 단축키: 적절한 구성으로 Option+Enter (Meta+Enter)를 누릅니다

터미널에서 Option+Enter를 설정하려면:

Mac Terminal.app의 경우:

  1. 설정 → 프로파일 → 키보드 열기
  2. “Option을 Meta 키로 사용” 체크

iTerm2 및 VSCode 터미널의 경우:

  1. 설정 → 프로파일 → 키 열기
  2. 일반에서 왼쪽/오른쪽 Option 키를 “Esc+“로 설정

iTerm2 및 VSCode 사용자를 위한 팁: Claude Code 내에서 /terminal-setup을 실행하여 더 직관적인 대안으로 Shift+Enter를 자동으로 구성하세요.

​
알림 설정

적절한 알림 구성으로 Claude가 작업을 완료했을 때를 놓치지 마세요:

​
터미널 벨 알림

작업 완료 시 소리 알림을 활성화하세요:

claude config set --global preferredNotifChannel terminal_bell

macOS 사용자의 경우: 시스템 설정 → 알림 → [터미널 앱]에서 알림 권한을 활성화하는 것을 잊지 마세요.

​
iTerm 2 시스템 알림

작업 완료 시 iTerm 2 알림의 경우:

  1. iTerm 2 환경설정 열기
  2. 프로파일 → 터미널로 이동
  3. “벨 음소거” 활성화 및 필터 알림 → “이스케이프 시퀀스 생성 알림 전송”
  4. 선호하는 알림 지연 설정

이러한 알림은 iTerm 2에 특화되어 있으며 기본 macOS 터미널에서는 사용할 수 없습니다.

​
대용량 입력 처리

광범위한 코드나 긴 지시사항으로 작업할 때:

  • 직접 붙여넣기 피하기: Claude Code는 매우 긴 붙여넣기 콘텐츠로 어려움을 겪을 수 있습니다
  • 파일 기반 워크플로우 사용: 콘텐츠를 파일에 작성하고 Claude에게 읽도록 요청하세요
  • VS Code 제한사항 인지: VS Code 터미널은 특히 긴 붙여넣기를 자르는 경향이 있습니다

​
Vim 모드

Claude Code는 /vim으로 활성화하거나 /config를 통해 구성할 수 있는 Vim 키바인딩의 하위 집합을 지원합니다.

지원되는 하위 집합에는 다음이 포함됩니다:

  • 모드 전환: Esc (NORMAL로), i/I, a/A, o/O (INSERT로)
  • 탐색: h/j/k/l, w/e/b, 0/$/^, gg/G
  • 편집: x, dw/de/db/dd/D, cw/ce/cb/cc/C, . (반복)