Skip to main content

사전 요구 사항

  • Node.js 20+ 또는 Bun (npm으로 설치할 경우)
  • macOS / Linux / WSL 권장 (Windows 네이티브도 지원되나 WSL 환경에서 더 안정적)
  • Anthropic Console 계정 (API 키 발급)
  • (선택) GitHub CLI (gh) — Git 작업 자동화에 유용

설치

npm으로 설치 (권장)

설치 후 버전 확인:

Homebrew (macOS)

첫 실행 및 인증

작업할 프로젝트 디렉토리로 이동한 뒤 실행합니다:
처음 실행 시 인증 옵션이 나타납니다:
  1. Anthropic Console 로그인 — 브라우저에서 OAuth로 로그인 (가장 일반적)
  2. API Key 직접 입력ANTHROPIC_API_KEY 환경 변수로도 가능
참고 회사 환경에서 SSO/SAML로 로그인된 Anthropic 계정을 사용한다면, 시스템 기본 브라우저(/usr/bin/open -a "Google Chrome" "...")로 OAuth가 열려야 합니다. tmux/cmux 환경에서 내장 브라우저로 열리면 SSO 세션이 없어 재인증이 필요할 수 있습니다.

프로젝트 초기화 (CLAUDE.md 생성)

프로젝트 단위로 Claude의 작업 방식을 알려주는 CLAUDE.md 파일을 두면 모든 세션에서 자동으로 컨텍스트로 사용됩니다.
/init 슬래시 커맨드를 실행하면 코드베이스를 분석해 초안을 만들어 줍니다. 이후 직접 편집해 다음과 같은 항목을 추가합니다:

사용자 글로벌 설정 (~/.claude/CLAUDE.md)

프로젝트가 아닌 사용자 본인의 작업 스타일을 정의하는 파일입니다. 모든 프로젝트에서 자동으로 로드됩니다.

settings.json — 권한과 환경 변수

자동 허용할 명령 화이트리스트

매번 권한을 묻지 않도록 안전한 명령을 등록합니다:
설정 위치 우선순위:
  1. Project: <project>/.claude/settings.json — 팀 공유
  2. Project local: <project>/.claude/settings.local.json — 개인 (gitignore)
  3. User: ~/.claude/settings.json — 모든 프로젝트 공통

환경 변수

Databricks 작업이라면 다음 환경 변수가 자동으로 사용됩니다:

.claudeignore — 컨텍스트에서 제외할 파일

.gitignore와 비슷한 형식으로, Claude가 읽지 않을 파일을 지정합니다. 시크릿 파일과 대용량 바이너리는 반드시 추가하세요.

설치 검증 체크리스트

  • claude --version 정상 출력
  • 프로젝트 디렉토리에서 claude 실행 → 인증 성공
  • > /help 입력 → 명령어 목록 표시
  • CLAUDE.md 파일 생성 후 첫 메시지에 자동 인식되는지 확인
  • .claudeignore.env 추가
  • (선택) gh auth status로 GitHub 인증 확인
다음 페이지에서 기본 워크플로우를 다룹니다.