Quick Flow

Claude Code는 터미널에서 프로젝트를 읽고 명령·파일 변경을 제안하는 도구입니다. 무료 Claude.ai 플랜만으로는 CLI를 쓸 수 없으며, Pro·Max·Team·Enterprise 구독, Claude Console 계정 또는 지원되는 클라우드 제공자 계정이 필요합니다. 새 설치는 네이티브 설치 관리자를 우선하고, 작업할 저장소 루트에서 세션을 시작합니다.

# macOS, Linux, WSL: 권장 설치 경로
curl -fsSL https://claude.ai/install.sh | bash

# 설치와 현재 버전을 확인한다.
claude --version

# 작업할 저장소에서 시작한다.
cd /path/to/project
claude

설치와 로그인

macOS·Linux·WSL에서는 네이티브 설치 관리자가 권장 경로이며 백그라운드 자동 업데이트를 사용합니다. Windows PowerShell은 irm https://claude.ai/install.ps1 | iex, Windows CMD는 별도 install.cmd 명령을 사용합니다. Homebrew와 WinGet도 설치할 수 있지만 자동 업데이트하지 않으므로 각각 brew upgrade 또는 winget upgrade로 관리해야 합니다.

예전에 npm install -g @anthropic-ai/claude-code로 설치한 환경도 동작할 수 있지만, 새 설치의 기본 선택은 아닙니다. claude 버전이 예상보다 오래되거나 바이너리가 여러 개면 설치 방식을 더 추가하지 말고, 먼저 which -a claude(Windows는 where.exe claude)로 실제 실행 파일을 확인합니다. 네이티브 설치와 오래된 npm 전역 설치가 섞이면 버전 차이와 PATH 혼동이 생길 수 있습니다.

첫 claude 실행은 브라우저 로그인으로 이어집니다. ANTHROPIC_API_KEY가 설정되어 있으면 로그인 화면 대신 해당 키를 사용할지 확인하며, 계정을 바꾸거나 다시 인증할 때는 실행 중인 세션에서 /login을 씁니다.

첫 세션의 순서

저장소 루트는 필수 제약은 아니지만, 작업 범위와 상대 경로를 분명하게 만드는 가장 안전한 시작점입니다. 먼저 코드 구조·진입점·실행 명령을 묻고, 그 다음 하나의 작은 수정과 검증으로 넘어갑니다. 이 순서는 Claude Code가 무엇을 읽었고 무엇을 바꾸려는지 확인하기 쉽습니다.

1. "이 프로젝트의 실행 명령, 진입점, 테스트 위치를 찾아 요약해 줘. 파일은 수정하지 마."
2. "로그인 테스트 실패를 재현해 줘. auth/ 밖은 수정하지 마."
3. "수정 전에 원인과 변경 파일 목록을 보여 주고, 수정 뒤에는 해당 테스트를 실행해 줘."

요청에는 목표만 쓰지 말고 변경 가능한 경로, 건드리면 안 되는 영역, 끝났다고 판단할 명령을 함께 넣습니다. 예를 들어 "로그인 버그를 고쳐 줘"보다 "auth/ 아래에서만 원인을 찾고 npm test -- auth가 통과할 때까지 수정해 줘"가 검토 가능한 요청입니다.

승인과 검증

기본 수동 승인에서는 Claude Code가 파일 수정과 대부분의 셸 명령 전에 권한을 묻습니다. 승인 창은 결과 검토를 대신하지 않습니다. 명령이 어디에서 실행되는지, 수정 대상이 요청 범위와 맞는지, 테스트 결과가 실제 성공 기준을 검증하는지를 따로 확인합니다.