Lab 02. 설치 & Bedrock 인증

• 터미널·에디터 준비: macOS / Windows 각각
• WSL2: Windows 사용자는 Ubuntu 환경에서 실습
• Claude Code 설치: 한 줄 설치
• AWS Bedrock 인증: 1·2일차와 동일한 백엔드(us-east-1) 연결

항목	macOS	Windows
터미널	cmux	Windows Terminal
에디터(선택)	Zed 또는 VS Code	Zed 또는 VS Code

에디터는 필수가 아니지만, Claude 가 파일을 어떻게 바꾸는지 눈으로 보며 진행하면 이해가 빠릅니다.

Claude Code 는 Linux · macOS 환경을 기준으로 동작합니다. Windows 사용자는 WSL2(Ubuntu) 안에서 실습하길 권장합니다. macOS · Linux 사용자는 이 단계를 건너뜁니다.

WSL2 가 무엇이고 왜 쓰나

항목	설명
WSL2 란	Windows 안에서 진짜 Linux 커널을 돌리는 공식 가상화 계층. Ubuntu 를 Windows 와 나란히 실행합니다
왜 쓰나	Claude Code · MCP 서버 · curl · uvx 등 대부분 도구가 Linux/macOS 를 1순위로 지원합니다. WSL2 면 설치 스크립트가 그대로 동작합니다

설치

사전 요구: Windows 10(2004 빌드 이상) 또는 Windows 11. PowerShell 을 관리자 권한으로 열고 한 줄이면 됩니다.

wsl --install

이 한 줄이 ① WSL 기능 켜기 → ② 가상 머신 플랫폼 켜기 → ③ Linux 커널 설치 → ④ Ubuntu 설치 까지 자동으로 처리합니다.

• 끝나면 재부팅합니다.
• Ubuntu 가 처음 열리면 사용자 이름·비밀번호를 만듭니다(Windows 계정과 별개).
• 버전을 확인합니다. VERSION 이 2 여야 합니다.

wsl --list --verbose

사용법

• Windows Terminal 에서 Ctrl+Shift+T 로 새 탭을 열고 Ubuntu 를 선택합니다. 설정에서 기본 프로필을 Ubuntu 로 지정해 두면 매번 고를 필요가 없습니다.
• 파일은 양쪽에서 보입니다. Windows 파일은 Ubuntu 에서 /mnt/c/Users/..., Ubuntu 파일은 Windows 탐색기에서 \\wsl$\Ubuntu\home\... 로 접근합니다.
• 이후 모든 명령(curl · claude · claude mcp add …)은 Ubuntu 터미널 안에서 실행합니다.

🚨 프로젝트 파일은 반드시 Linux 홈(~/) 아래에 두세요. /mnt/c(Windows 영역)에 두면 파일 입출력이 수십 배 느려집니다. 예: ~/projects/my-app.

macOS · Linux · WSL2(Ubuntu): 한 줄로 설치합니다.

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

설치가 끝나면 새 터미널을 열고 버전을 확인합니다.

claude --version

Windows 네이티브(WSL2 없이) 설치도 가능합니다. PowerShell 에서 irm https://claude.ai/install.ps1 | iex. 다만 이 과정은 WSL2 기준으로 진행합니다.

첫 실행(claude)은 다음 단계에서 Bedrock 인증을 설정한 뒤 합니다. 인증 없이 실행하면 다른 로그인 경로로 빠질 수 있습니다.

Claude Code 의 백엔드를 Amazon Bedrock 으로 지정합니다. 1·2일차에 쓰던 그 Bedrock(리전 us-east-1)을 그대로 사용합니다. 모델 접근 권한도 동일합니다.

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

자격증명은 1·2일차와 동일한 AWS 자격증명을 사용합니다(환경에 맞게 aws configure 또는 IAM 역할·환경변수). 별도 API 키는 필요 없습니다.

💡 매 세션 유지하려면 위 export 두 줄을 ~/.zshrc(macOS) 또는 ~/.bashrc(WSL2/Ubuntu) 에 추가하세요.

(선택) 모델 지정

지정하지 않으면 Bedrock 기본 모델로 동작합니다. 명시하려면 인퍼런스 프로파일 ID(us.anthropic.*. 1·2일차 환경점검에서 본 형식)를 씁니다.

# 메인 모델 (예: Sonnet 4.5)
export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-5-20250929-v1:0'
# 빠른 보조 모델 (Haiku 4.5) — 변수명 주의
export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

⚠️ 옛 변수 ANTHROPIC_SMALL_FAST_MODEL 은 폐기되었습니다 → ANTHROPIC_DEFAULT_HAIKU_MODEL 사용.

첫 실행

claude

첫 응답이 나오면 Bedrock 인증 성공입니다. 막히면 권한(bedrock:InvokeModel) · 리전 · 자격증명을 확인하세요.

💡 이 과정은 Bedrock 환경이라 일부 기능(예: /fast)은 사용할 수 없습니다. Bedrock 전용 제약이며 정상입니다.

배포된 점검 스크립트로 준비 상태를 한 번에 확인합니다.

bash 00_check_day3_env.sh

claude · Bedrock · node · uv · docker 가 모두 초록불이면 이후 MCP 실습까지 막힘이 없습니다.