Initial commit to new repository

docs/claude-code-docs-main/03_설치.md

@@ -0,0 +1,253 @@
+# 설치
+
+> macOS, Linux, Windows(WSL 경유)에 Claude Code를 설치합니다. Node.js 18 이상이 필요합니다.
+
+## 요구사항
+
+- **Node.js 18 이상** — Claude Code는 시작 시 Node.js 버전을 확인하고, 18 미만이면 오류와 함께 종료합니다.
+- **npm** — Node.js에 포함되어 있습니다.
+
+현재 버전 확인:
+
+```bash
+node --version
+npm --version
+```
+
+---
+
+## Claude Code 설치
+
+npm으로 전역 설치:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+설치 후 동작 확인:
+
+```bash
+claude --version
+```
+
+---
+
+## 플랫폼별 안내
+
+### macOS
+
+macOS에서는 npm 전역 설치가 기본적으로 작동합니다. `npm install -g` 실행 시 권한 오류가 발생하면 두 가지 옵션이 있습니다:
+
+**옵션 A: npm 권한 수정 (권장)**
+
+홈 폴더의 디렉토리를 사용하도록 npm을 설정:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+```
+
+셸 프로파일(`~/.zshrc` 또는 `~/.bash_profile`)에 다음 추가:
+
+```bash
+export PATH=~/.npm-global/bin:$PATH
+```
+
+프로파일 다시 로드 후 설치:
+
+```bash
+source ~/.zshrc
+npm install -g @anthropic-ai/claude-code
+```
+
+**옵션 B: Node 버전 관리자 사용**
+
+[nvm](https://github.com/nvm-sh/nvm) 또는 [fnm](https://github.com/Schniz/fnm) 같은 도구는 홈 디렉토리에 Node.js를 설치해서 전역 권한 문제를 완전히 피할 수 있습니다:
+
+```bash
+# nvm 사용
+nvm install --lts
+nvm use --lts
+npm install -g @anthropic-ai/claude-code
+```
+
+### Linux
+
+대부분의 Linux 배포판에서 `npm install -g`는 `sudo` 또는 npm prefix 수정이 필요합니다. `sudo` 사용은 나중에 권한 문제를 일으킬 수 있으므로 권장하지 않습니다.
+
+**권장: Node 버전 관리자 사용**
+
+```bash
+# nvm 설치
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
+
+# 셸 다시 로드 후 Node.js 설치
+nvm install --lts
+nvm use --lts
+
+# Claude Code 설치
+npm install -g @anthropic-ai/claude-code
+```
+
+**대안: npm 전역 prefix 수정**
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+npm install -g @anthropic-ai/claude-code
+```
+
+### Windows (WSL)
+
+Claude Code는 Windows Subsystem for Linux(WSL)를 통해 Windows에서 실행됩니다. 커맨드 프롬프트나 PowerShell에서 직접 실행하는 것은 지원되지 않습니다.
+
+**1단계: WSL 설치**
+
+관리자 권한으로 PowerShell 열고 실행:
+
+```powershell
+wsl --install
+```
+
+메시지가 나타나면 재시작. 기본적으로 Ubuntu와 함께 WSL 2가 설치됩니다.
+
+**2단계: WSL 터미널 열기**
+
+시작 메뉴에서 Ubuntu를 실행하거나, PowerShell에서 `wsl`을 실행합니다.
+
+**3단계: WSL 안에 Node.js 설치**
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
+source ~/.bashrc
+nvm install --lts
+nvm use --lts
+```
+
+**4단계: Claude Code 설치**
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+> 📝 항상 WSL 터미널 안에서 `claude`를 실행하세요 — Windows CMD나 PowerShell에서 실행하지 마세요. 프로젝트 파일은 WSL 파일시스템(`~/projects/` 등) 안에 있어야 최상의 성능을 발휘합니다. `/mnt/c/...`를 통한 Windows 파일 접근은 가능하지만 느립니다.
+
+---
+
+## 업데이트
+
+최신 버전으로 업데이트:
+
+```bash
+npm update -g @anthropic-ai/claude-code
+```
+
+또는 Claude Code 내장 업데이트 커맨드 사용:
+
+```bash
+claude update
+```
+
+현재 버전 확인:
+
+```bash
+claude --version
+```
+
+---
+
+## 제거
+
+Claude Code 제거:
+
+```bash
+npm uninstall -g @anthropic-ai/claude-code
+```
+
+`claude` 바이너리가 제거됩니다. `~/.claude/`의 설정 파일은 자동으로 제거되지 않습니다. 삭제하려면:
+
+```bash
+rm -rf ~/.claude
+```
+
+---
+
+## 문제 해결
+
+### 설치 후 `claude` 커맨드를 찾을 수 없음
+
+npm 전역 bin 디렉토리가 `PATH`에 없는 경우입니다.
+
+npm이 전역 바이너리를 설치하는 위치 확인:
+
+```bash
+npm config get prefix
+```
+
+해당 경로의 `bin` 서브디렉토리를 `PATH`에 추가해야 합니다. 예를 들어 출력이 `/home/you/.npm-global`이면:
+
+```bash
+export PATH=/home/you/.npm-global/bin:$PATH
+```
+
+셸을 다시 로드(`source ~/.zshrc` 또는 새 터미널 열기) 후 다시 시도하세요.
+
+### Node.js 버전이 18 미만
+
+Claude Code는 Node.js 18 이상이 필요합니다. 시작 시 이 오류가 보이면:
+
+```
+Error: Claude Code requires Node.js version 18 or higher.
+```
+
+버전 관리자를 사용해 Node.js를 업그레이드하세요:
+
+```bash
+# nvm
+nvm install --lts
+nvm use --lts
+
+# fnm
+fnm install --lts
+fnm use --lts
+```
+
+### npm install -g 시 권한 거부
+
+`sudo npm install -g`를 사용하지 마세요 — root 소유 파일이 남아 추가 문제를 일으킬 수 있습니다. 대신 npm prefix를 사용자 쓰기 가능 디렉토리로 수정하세요:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+export PATH=~/.npm-global/bin:$PATH
+npm install -g @anthropic-ai/claude-code
+```
+
+### 첫 실행 시 인증 실패
+
+브라우저 기반 OAuth 흐름이 실패하거나 브라우저를 사용할 수 없는 경우, 환경 변수로 API 키를 직접 설정하세요:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+claude
+```
+
+셸 프로파일에 추가하면 영구적으로 설정됩니다. API 키는 [Anthropic Console](https://console.anthropic.com)에서 발급받을 수 있습니다.
+
+### Docker 또는 CI 환경에서 실행
+
+비대화형 환경에서는 환경 변수로 인증하세요:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+비대화형으로 실행하려면 `-p` 플래그 사용:
+
+```bash
+claude -p "테스트 스위트를 실행하고 실패를 보고해줘"
+```
+
+샌드박스 컨테이너에서 권한 프롬프트 없이 Claude Code를 작동시켜야 한다면 `--dangerously-skip-permissions` 플래그를 사용하세요. 이 플래그는 Claude Code의 샌드박스 안전 검사를 통과한 환경(인터넷 접근 없음, 컨테이너 외부에서 root로 실행하지 않음)에서만 작동합니다.