환경 선택과 설치: CLI·VS Code·JetBrains·Desktop·Web

'어디서 실행하느냐'가 곧 워크플로다

Claude Code는 같은 엔진을 쓰더라도, 어떤 표면(surface)에서 실행하느냐에 따라 속도와 리듬이 달라집니다. 터미널(CLI)은 가장 가볍고 빠르게 자동화를 붙이기 좋고, IDE 확장은 "지금 보고 있는 코드"를 중심으로 수정·리뷰를 촘촘히 만들기 좋습니다. 데스크톱 앱은 병렬 세션과 미리보기, PR 모니터링처럼 '작업을 굴리는' 능력이 강하고, 웹은 아예 클라우드에서 작업을 돌려서 노트북을 닫아도 계속 진행시키는 데 유리합니다.¹⁵⁷

이 장의 목표는 간단합니다. 각 표면의 차이를 이해하고, 설치→로그인→첫 실행까지의 최소 경로를 한 번에 끝내는 것입니다.

표면 선택 가이드(결정 기준 3가지)

표면을 고를 때는 "기능 목록"보다 아래 3가지를 먼저 봐야 합니다.

첫째, 컨텍스트의 중심이 어디인지입니다. 지금 열어 둔 파일/선택 영역/진단 정보가 핵심이면 IDE가 편하고, 폴더 전체를 훑고 커맨드를 돌리는 흐름이면 CLI가 빠릅니다.²³

둘째, 병렬 작업을 얼마나 돌릴지입니다. 여러 작업을 동시에 굴리고 싶다면, 세션을 탭/윈도우로 나누기 쉬운 VS Code, 그리고 세션별 Git 작업트리(worktree) 격리까지 제공하는 Desktop이 강합니다.²⁵

셋째, 원격(클라우드/SSH)에서 돌릴 필요가 있는지입니다. 장시간 작업(대규모 리팩터, 긴 테스트, 마이그레이션)은 웹(또는 Desktop의 Remote 환경)이 특히 유리합니다.⁷⁵

공통 준비물(최소)

계정/인증

Claude Code는 첫 실행 시 로그인(또는 제공자 설정)이 필요합니다. CLI에서는 /login으로 로그인 흐름을 시작합니다.¹

Claude Code는 개인용 Claude Pro 또는 Max 요금제에서 사용할 수 있고, Team·Enterprise에서는 Claude Code가 포함된 좌석이나 관리 설정 형태로 제공됩니다.¹⁸ 또한 구독 없이도 Anthropic Console API 크레딧을 연결해 사용량 기반으로 쓸 수 있습니다. 다만 Pro·Max에서는 Claude와 Claude Code가 같은 사용 한도를 공유하며, 한도를 넘긴 뒤에는 API 크레딧 사용 여부를 선택할 수 있으므로, 실제로는 '구독 기반 사용'과 'API 종량 과금'이라는 두 경로가 함께 존재한다고 보는 것이 가장 정확합니다.⁸⁹

프로젝트 폴더

어떤 표면이든 "프로젝트 루트(레포 루트)"에서 시작하는 습관이 중요합니다. 특히 IDE 연동(JetBrains)은 프로젝트 루트에서 실행해야 IDE가 파일 접근/컨텍스트 공유를 자연스럽게 맞춥니다.³

1) CLI(터미널): 가장 빠르고, 자동화에 강한 기본기

CLI는 Claude Code의 '기본 표면'입니다. 나중에 IDE/데스크톱/웹을 쓰더라도, 설치·로그인·세션 제어(원격 작업 시작/텔레포트 등)는 결국 CLI가 기준이 되는 경우가 많습니다.¹⁷

최소 경로: 설치 → 로그인 → 첫 실행

1. 설치

   • 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

   • 대안: Homebrew / WinGet

     brew install --cask claude-code

     winget install Anthropic.ClaudeCode

   Windows는 Git for Windows가 필요합니다.¹

2. 로그인

   • 프로젝트 폴더에서 claude를 실행한 뒤, 필요하면 /login을 따라갑니다.¹

3. 첫 실행(프로젝트 루트에서)

   • cd /path/to/your/project → claude

   • 화면이 뜨면 바로 "이 프로젝트가 뭐 하는지 설명해줘" 같은 탐색 질문으로 시작할 수 있습니다.¹

CLI를 추천하는 상황

여러 레포를 오가며 동일한 작업을 반복하거나(예: 테스트/린트/코드모드), CI·훅·커스텀 커맨드 같은 자동화로 확장할 계획이라면 CLI부터 잡는 게 가장 빠릅니다.

2) VS Code: '보고 있는 코드' 중심으로 계획·수정·리뷰를 굴린다

VS Code 확장은 Claude Code를 IDE 안의 네이티브 UI로 씁니다. 계획(Plan) 문서를 IDE에서 바로 열어 코멘트로 피드백하고, 선택 영역을 파일/라인 범위로 참조(@-mention)하는 흐름이 강점입니다.²

최소 경로: 설치 → 로그인 → 첫 패널 열기

1. 사전 조건: VS Code 1.98+.²

2. 확장 설치

   • Extensions에서 "Claude Code"를 검색해 설치합니다.²

3. 첫 실행/로그인

   • 패널을 열면 첫 실행 시 로그인 안내가 나옵니다.²

4. 첫 작업 시작

   • 프로젝트 폴더를 열고, 작은 작업(설명/리팩터/테스트 추가)부터 요청합니다.

   • 코드 선택 후 단축키로 @파일#라인-라인 참조를 삽입해, "지금 보고 있는 부분"을 정확히 집어주면 시행착오가 줄어듭니다.²

VS Code를 추천하는 상황

코드 편집과 대화를 한 화면에서 빠르게 왕복하고, 변경 사항을 IDE 스타일로 검토(계획 문서/참조/히스토리)하며 진행하고 싶다면 VS Code가 가장 무난한 선택입니다.²

3) JetBrains: 강력한 IDE 기능 + 터미널 기반 에이전트의 결합

JetBrains 연동은 전용 플러그인을 통해 이루어지며, 기본적으로 IDE 터미널에서 claude를 실행할 때 연동 기능이 활성화됩니다. 변경 사항을 IDE diff 뷰어로 보거나, 선택 컨텍스트/진단 정보를 자동 공유하는 방식이 핵심입니다.³

최소 경로: CLI 설치 → 플러그인 설치 → IDE에서 실행

1. CLI가 먼저 필요

   • JetBrains 플러그인은 claude 커맨드를 호출합니다. 따라서 CLI를 먼저 설치해 두는 것이 안전합니다.³¹

2. 플러그인 설치

   • JetBrains Marketplace에서 Claude Code 플러그인을 설치하고 IDE를 재시작합니다.³

3. 첫 실행

   • IDE의 통합 터미널에서 프로젝트 루트 기준으로 claude를 실행합니다.³

4. (선택) 외부 터미널에서 IDE 연결

   • 외부 터미널에서 작업 중이라면 /ide로 JetBrains IDE에 연결할 수 있습니다.³

JetBrains에서 자주 생기는 '막힘' 두 가지

JetBrains에서는 ESC 키가 "터미널 → 에디터 포커스 이동"에 잡혀 Claude 중단이 안 될 수 있습니다. 이 경우 Terminal 설정에서 ESC 관련 단축키를 조정하라고 안내합니다.³

또한 Remote Development를 쓰는 경우 플러그인은 로컬이 아니라 원격 호스트에 설치되어야 합니다.³

4) Desktop(Claude 데스크톱 앱): 병렬 세션, 미리보기, PR 모니터링까지 한 곳에서

Desktop의 Code 탭은 터미널 없이도 Claude Code를 GUI로 쓰게 해줍니다. 중요한 차이는 "코딩 보조"를 넘어, 세션을 여러 개 돌리고(작업트리 격리), 앱 미리보기/PR 상태 추적/스케줄 작업 같은 운영 능력이 붙는다는 점입니다.⁵⁶

최소 경로: 설치 → Code 탭 → 4가지 선택 후 시작

1. 설치

   • 데스크톱 앱에는 Claude Code가 포함되어 있어, 별도로 Node.js나 CLI를 설치하지 않아도 Code 탭을 쓸 수 있습니다.⁶

2. Code 탭에서 첫 세션 시작(필수 4가지 설정)

   • Environment(로컬/Remote/SSH)

   • Project folder

   • Model

   • Permission mode

   이 4가지를 선택하고 작업을 입력하면 세션이 시작됩니다.⁵

Desktop을 추천하는 상황

여러 작업을 동시에 굴리면서(세션별 격리) 결과를 diff로 검토하고, 필요하면 미리보기로 실제 동작까지 확인하는 흐름을 원한다면 Desktop이 가장 편합니다.⁵⁶

5) Web(claude.ai/code): 로컬이 없어도, 클라우드에서 PR까지 만든다

웹 표면은 레포를 Anthropic 관리 VM에 클론해 작업을 수행하고, diff 뷰에서 검토한 뒤 PR 생성까지 이어지는 흐름이 기본입니다.⁷

최소 경로: 웹에서 바로 시작

1. claude.ai/code 접속

2. GitHub 계정 연결

3. Claude GitHub App을 레포에 설치

4. 기본 환경 선택

5. 작업 제출

6. diff 뷰에서 코멘트로 반복 수정 후 PR 생성⁷

최소 경로: CLI에서 웹으로 보내기 / 웹에서 CLI로 가져오기

• 터미널 → 웹(원격 실행):

  claude --remote "Fix the authentication bug in src/auth/login.ts"⁷

• 웹 → 터미널(텔레포트):

  • 터미널에서 claude --teleport 또는

  • CLI 내부에서 /teleport(/tp)로 세션 선택

  • 또는 /tasks에서 세션을 보고 텔레포트⁷

텔레포트는 "같은 레포 체크아웃", "클린한 git 상태" 같은 조건을 확인하고, 원격 세션의 브랜치를 fetch/checkout한 뒤 대화 히스토리까지 로컬로 가져옵니다.⁷

이 장을 끝내면 해야 할 것(3장 준비)

다음 장(첫 세션 15분 완주)로 넘어가기 전에, 아래만 확인하면 됩니다.

• CLI를 쓸 계획이면: claude가 프로젝트 루트에서 실행되고, /login까지 완료되어야 합니다.¹

• IDE를 쓸 계획이면: VS Code 확장 또는 JetBrains 플러그인이 설치되어 있고, "프로젝트 루트에서 실행합니다.²³

• 원격까지 염두에 두면: 웹(claude.ai/code)에서 GitHub 연결/앱 설치가 끝나 있어야 하고, CLI의 --remote와 --teleport로 왕복할 수 있어야 합니다.⁷

참고

¹Quickstart - Claude Code Docs

²Use Claude Code in VS Code - Claude Code Docs

³JetBrains IDEs - Claude Code Docs

⁴Run IntelliJ IDEA for the first time - JetBrains Documentation

⁵Use Claude Code Desktop - Claude Code Docs

⁶Get started with the desktop app - Claude Code Docs

⁷Claude Code on the web - Claude Code Docs

⁸Claude Code and new admin controls for business plans

⁹Claude, Claude API, and Claude Code: What's the Difference?