초기 설정
개발 환경 구성도
JetBrains
make / gradle
Code
PowerShell
diff / log
설치
요구사항
- 운영체제: macOS 13.0+, Windows 10 (1809+), Ubuntu 20.04+, Debian 10+, Alpine 3.19+
- 메모리: 4GB 이상 RAM 권장
- 인증: Anthropic API 키 또는 Claude Pro/Max/Team 구독
v2.1 이후 네이티브 설치가 권장 방법입니다. Node.js가 더 이상 필요하지 않습니다.
네이티브 설치 (권장)
macOS / Linux:
curl -fsSL https://claude.ai/install.sh | bash
Windows (PowerShell):
irm https://claude.ai/install.ps1 | iex
패키지 관리자로 설치
Homebrew (macOS):
brew install claude-code
WinGet (Windows):
winget install Anthropic.ClaudeCode
npm으로 설치 (지원 중단 예정)
npm을 통한 설치는 지원 중단(deprecated)되었습니다. 기존 npm 사용자는 네이티브 설치로 마이그레이션하세요.
# 기존 npm 설치 제거
npm uninstall -g @anthropic-ai/claude-code
# 네이티브 설치로 마이그레이션
curl -fsSL https://claude.ai/install.sh | bash
특정 버전 설치
특정 버전을 고정(pinning)해서 설치할 수 있습니다:
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89
설치 확인
claude --version
# 환경 진단 (설치, 인증, 네트워크 등 종합 확인)
claude doctor
claude doctor는 설치 상태, 인증, 네트워크 연결, 권한 등을 종합적으로 진단해줍니다.
릴리스 채널
Claude Code는 두 가지 릴리스 채널을 제공합니다:
| 채널 | 설명 | 적합한 사용자 |
|---|---|---|
latest (기본값) | 최신 기능이 바로 반영됨 | 최신 기능을 빠르게 사용하고 싶은 개인 개발자 |
stable | latest 대비 약 1주일 지연 반영 | 안정성이 중요한 팀/프로덕션 환경 |
채널 변경:
# settings.json에서 설정
# autoUpdatesChannel: "stable"
업데이트
Claude Code는 기본적으로 자동 업데이트됩니다.
# 수동 업데이트
claude update
# 자동 업데이트 비활성화
export DISABLE_AUTOUPDATER=1
바이너리 무결성 검증
v2.1.89 이후 버전은 GPG 서명된 매니페스트를 제공합니다. 설치 파일의 무결성을 검증할 수 있습니다:
# 매니페스트 다운로드 및 GPG 서명 확인
# 자세한 내용은 공식 문서의 Binary Integrity 섹션 참고
제거 (Uninstall)
# 네이티브 설치 제거 (macOS/Linux)
rm -rf ~/.claude/bin/claude
# Homebrew로 설치한 경우
brew uninstall claude-code
# npm으로 설치한 경우
npm uninstall -g @anthropic-ai/claude-code
# 설정 및 데이터 완전 삭제
rm -rf ~/.claude
인증
방법 1: Anthropic 계정 (Pro/Team 구독자)
claude
# 처음 실행 시 브라우저에서 로그인 페이지가 열립니다
방법 2: API 키
export ANTHROPIC_API_KEY="sk-ant-..."
claude
.bashrc 또는 .zshrc에 추가하면 매번 입력하지 않아도 됩니다:
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc
프로젝트 설정
CLAUDE.md 파일
프로젝트 루트에 CLAUDE.md 파일을 만들면 프로젝트별 지침을 설정할 수 있습니다:
# 프로젝트 가이드
## 기술 스택
- Next.js 14 (App Router)
- TypeScript
- Prisma + PostgreSQL
- Tailwind CSS
## 코딩 컨벤션
- 함수형 컴포넌트 사용
- 커밋 메시지는 Conventional Commits 형식
- 테스트는 Vitest로 작성
## 빌드 및 테스트
- 빌드: `npm run build`
- 테스트: `npm test`
- 린트: `npm run lint`
Claude Code는 작업 시작 시 이 파일을 자동으로 읽어 참고합니다.
.claude/ 디렉토리
프로젝트별 설정과 컨텍스트를 저장하는 디렉토리입니다:
.claude/
├── settings.json # 프로젝트별 설정
├── rules/ # 경로별 규칙 파일
└── skills/ # 커스텀 스킬 (재사용 가능한 워크플로우)
권한 설정
Claude Code가 파일을 수정하거나 명령어를 실행할 때의 권한을 설정합니다:
| 모드 | 설명 | 사용 시기 |
|---|---|---|
default | 모든 변경 시 확인 요청 (기본값) | 처음 사용할 때, 중요한 프로젝트 |
auto | 안전한 변경은 자동 승인 | 익숙해진 후, 빠른 작업 |
# auto 모드로 시작
claude --permission-mode auto
실전 예제: 첫 프로젝트에서 Claude Code 시작하기
새 프로젝트에서 Claude Code를 처음 설정하는 전체 과정입니다:
# 1. Claude Code 설치
curl -fsSL https://claude.ai/install.sh | bash
# 2. 설치 확인
claude --version
claude doctor
# 3. 프로젝트 디렉토리로 이동
cd ~/my-project
# 4. CLAUDE.md 자동 생성
claude /init
# 5. Claude Code 실행 (브라우저에서 인증 진행)
claude
# 6. 프로젝트 구조 파악 요청
# > 이 프로젝트의 구조와 기술 스택을 설명해줘
# 7. 작업 시작
# > src/utils/에 날짜 포맷팅 유틸리티 함수를 만들어줘
처음에는 default 모드(기본값)로 시작하여 Claude Code가 어떤 파일을 수정하는지 확인하면서 사용하세요. 익숙해지면 auto 모드로 전환하면 됩니다.
트러블슈팅
| 증상 | 원인 | 해결 방법 |
|---|---|---|
command not found: claude | 설치 경로가 PATH에 없음 | 터미널 재시작 또는 source ~/.zshrc 실행 |
| 인증 실패 | API 키가 잘못되었거나 만료됨 | claude doctor로 확인 후 키 재설정 |
| 브라우저가 열리지 않음 | 헤드리스 환경 (SSH 등) | ANTHROPIC_API_KEY 환경 변수로 인증 |
| npm 설치 시 권한 오류 | 글로벌 설치 권한 부족 | 네이티브 설치로 전환 권장 |
claude doctor 네트워크 오류 | 프록시/방화벽 차단 | HTTPS_PROXY 환경 변수 설정 |
| 업데이트 후 동작 이상 | 캐시 문제 | rm -rf ~/.claude/cache 후 재시작 |
연계 기능
개발 환경 구성 후 활용하면 더욱 강력해지는 연관 기능들입니다.
mcp.md — 개발 환경 구성도의 MCP 허브를 실제로 구축합니다. Slack, GitHub, DB 등 외부 서비스를 Claude와 연결하여 자동화 범위를 크게 넓힙니다.
rules.md — .claude/rules/ 디렉토리에 경로별·상황별 규칙을 정의하여 CLAUDE.md를 보완합니다. 특정 파일 타입이나 디렉토리에 다른 지침을 적용할 수 있습니다.
cli-reference.md — 초기 설정 후 자주 사용하는 모든 CLI 명령어와 플래그를 한눈에 확인합니다. /init, /doctor, /cost 등 슬래시 명령어도 포함됩니다.
장점, 단점과 한계점
장점
- 다양한 설치 방법: 네이티브 설치, Homebrew, WinGet, npm 등 환경에 맞는 여러 설치 옵션을 제공하여 선택의 폭이 넓습니다.
- 자동 업데이트: 기본적으로 자동 업데이트가 활성화되어 있어 항상 최신 기능과 보안 패치를 받을 수 있습니다.
- 릴리스 채널 선택:
latest와stable두 가지 채널을 제공하여, 개인 개발자는 최신 기능을, 팀은 안정성을 우선할 수 있습니다. - 바이너리 무결성 검증: GPG 서명된 매니페스트를 통해 설치 파일의 무결성을 검증할 수 있어 보안이 강화됩니다.
단점과 한계점
- Node.js 18+ 필요 (npm 설치 시): npm으로 설치하는 경우 Node.js 18 이상이 필요하며, 네이티브 설치로의 마이그레이션이 권장됩니다.
- macOS/Linux 우선 지원: Windows에서는 네이티브(Git Bash)의 샌드박싱 미지원 등 기능 제한이 있어 WSL 2 사용이 권장됩니다.
- 초기 인증 과정 복잡: 브라우저 기반 OAuth 인증과 API 키 설정 등 처음 사용자에게는 인증 방식 선택이 혼란스러울 수 있습니다.
- 방화벽/프록시 환경 제한: 기업 내부 네트워크에서 프록시나 방화벽으로 인해 설치 및 인증이 차단될 수 있습니다.
설치 후 claude doctor를 실행하면 설치 상태, 인증, 네트워크 등을 종합적으로 진단할 수 있습니다. 기업 프록시 환경에서는 HTTPS_PROXY 환경 변수를 먼저 설정한 후 설치를 진행하세요.