02-구조

02. 구조 — 설치 옵션과 권한 모델

설치 경로 — 어떤 OS에서 무엇을 쓰는가

Anthropic 공식 문서가 권장하는 설치 방식은 OS별로 다음과 같다(sources/01-anthropic-official/claude-code/claude-code-overview.md).

macOS / Linux / WSL — 네이티브 스크립트 (권장)

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

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows CMD

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows는 사전에 Git for Windows 설치가 필요하다.

Homebrew (macOS)

brew install --cask claude-code

WinGet (Windows)

winget install Anthropic.ClaudeCode

네이티브 설치는 백그라운드 자동 갱신을 한다. 즉, “어제는 되던 게 오늘 다르다”가 정상이다(이 점은 Part 0/04에서 함정으로 다시 다룬다).

표면(Surface) 5종

같은 Claude Code 엔진이 5개 표면에서 돈다.

표면	특징	추천 시점
Terminal CLI	풀 기능. 본체.	모든 개발자
VS Code 확장	인라인 diff, @-멘션, plan review	IDE 중심 워크플로우
Desktop 앱	다중 세션 시각 검토, 일정 작업	비개발자 포함
Web	로컬 셋업 없이 브라우저	임시/모바일
JetBrains 플러그인	IntelliJ 계열	JVM 개발자

핵심은 CLAUDE.md, 설정, MCP 서버가 5개 표면에 공유된다는 점이다. 한 곳에 셋업하면 다른 곳에서도 동일한 컨텍스트를 쓴다.

첫 실행 명령

설치 후 어느 디렉토리에서나 다음을 친다.

cd your-project
claude

첫 실행 시 로그인 프롬프트가 뜬다. Claude 구독 또는 Anthropic Console 계정이 필요하다(Terminal CLI와 VS Code는 일부 제3자 백엔드도 지원).

권한 모델 — 왜 매번 묻는가

Claude Code는 파일 쓰기와 명령 실행 시 사용자 승인을 요구한다. 이것은 버그가 아니라 안전 설계다. 2025년 10월 21일에 Mike Wolak이 보고한 사건은 권한 모델의 중요성을 보여준다.

Claude Code가 다음 명령을 생성했다.

rm -rf tests/ patches/ plan/ ~/

권한 시스템은 통과시켰지만, 셸이 ~를 홈 디렉토리로 확장하면서 사용자의 모든 파일이 사라졌다. Anthropic이 2일 전 출시한 샌드박싱(Sandboxing) 기능은 옵트인(opt-in)이라 켜져 있지 않았다.

— Mike Wolak (sources/23-case-studies-raw/failures/mike-wolak-rm-rf-home-directory.md)

이 사건은 Part 0/04에서 다시 다룬다. 여기서 기억할 것은 두 가지다.

1. 권한 프롬프트는 귀찮음이 아니라 마지막 방어선이다. 매번 “Yes to all”을 누르지 않는다.
2. 샌드박싱 옵션을 첫 셋업 때 켠다. 기본값은 옵트인이다.

CLAUDE.md — 첫 세션 직후 만들 단 하나의 파일

CLAUDE.md는 프로젝트 루트에 두는 마크다운 파일이며, Claude Code가 모든 세션 시작 시 자동으로 읽는다. Anthropic 공식 설명에 따르면 “코딩 표준, 아키텍처 결정, 선호 라이브러리, 리뷰 체크리스트”를 적는 곳이다.

설치 후 30분 안에 단 하나만 만들어야 한다면 이 파일이다. 비어 있어도 좋다. 존재 자체가 Claude Code에게 “이 프로젝트는 컨텍스트가 있다”고 알려준다.

자세한 작성법은 Part 3/02에서 다룬다.