개발 도구 & OS

Claude Code 설치 가이드, 터미널 첫 세션까지 30분 완성

by Freedancer 2026. 4. 16.

Claude Code 설치 가이드를 따라 macOS·Windows·WSL 환경에서 30분 안에 터미널 첫 세션을 시작하고 실전 코드 수정까지 체험하는 완벽 로드맵입니다.

 

"Bolt.new로 첫 앱을 만들어봤는데, 이제 진짜 현업 개발자들이 쓰는 도구에 도전해보고 싶다." 바이브 코딩을 어느 정도 경험한 분이라면 자연스럽게 드는 생각입니다. 그리고 그 다음 목적지는 대부분 Claude Code로 귀결됩니다. 문제는 터미널이라는 장벽입니다. 검은 화면에 타이핑하는 모습이 생소하고, 설치 명령어만 봐도 머리가 아프죠.

이 글이 해결해드리는 3가지 핵심은 다음과 같습니다. 첫째, OS별 정확한 설치 명령어를 공식 문서 그대로 정리했습니다. 둘째, 설치 직후 첫 세션에서 무엇을 해야 하는지 공식 Quickstart 8단계 순서대로 안내합니다. 셋째, 초보자가 자주 실수하는 지점과 그걸 피하는 Pro Tips까지 담았습니다.

이 글에서는 Claude Code가 무엇인지부터 시작해, macOS·Linux·WSL·Windows PowerShell·CMD·Homebrew·WinGet 등 설치 방법을 모두 다루고, 첫 로그인과 첫 세션 시작, 코드베이스 탐색, 첫 코드 수정, Git 연동, 버그 픽스까지 실제 8단계를 단계별로 따라갑니다. 마지막으로 필수 명령어와 초보자 팁, 그리고 다음 단계로 넘어갈 때 알아야 할 CLAUDE.md, MCP, Skills 개념까지 정리했습니다.

📌 이 글에서 배울 수 있는 것

  1. macOS·Windows·WSL 환경별 Claude Code 설치 명령어
  2. 공식 Quickstart 8단계에 따른 첫 세션 실전 워크플로
  3. CLAUDE.md·MCP·Skills로 이어지는 생산성 향상 다음 단계

Claude Code란? 왜 터미널 기반 AI 코딩 도구인가

Claude Code는 Anthropic이 만든 에이전트형 AI 코딩 도구입니다. 공식 문서 표현대로 "코드베이스를 읽고, 파일을 편집하고, 명령을 실행하고, 개발 도구와 통합되는" 도구이며, 터미널, IDE, 데스크톱 앱, 브라우저 모두에서 사용할 수 있습니다. 이 글에서는 가장 기본이 되는 터미널(CLI) 환경을 중심으로 다룹니다.

왜 이렇게 많은 개발자가 Claude Code를 선택할까요? 2026년 2월 Pragmatic Engineer가 906명의 소프트웨어 엔지니어를 대상으로 실시한 설문조사에서 Claude Code는 46%의 "most loved" 비율로 가장 많이 사용되는 AI 코딩 도구로 꼽혔습니다. Cursor, GitHub Copilot, Codex 같은 경쟁 도구들을 제치고 현업 전문가들이 가장 사랑하는 도구로 자리 잡은 것입니다.

터미널 기반이라고 하면 "어렵지 않을까?"라는 우려가 들 수 있지만, 오히려 반대입니다. 한국어 자연어로 "이 프로젝트가 뭐 하는 거야?" 같은 질문을 던지면, Claude가 코드를 읽고 대답합니다. 파일을 수정할 때도 "이 폼에 입력 검증을 추가해줘"라고 말하면 해당 파일을 찾아 수정안을 제안합니다. 아직 Claude Code를 처음 들어보셨거나 바이브 코딩 개념 자체가 낯설다면 바이브 코딩 입문 5단계 가이드를 먼저 읽어보시는 것을 추천드립니다.

💡 필자의 설치 환경: 저는 macOS(Apple Silicon)와 WSL2(Ubuntu 24.04) 양쪽에서 Claude Code를 모두 사용하고 있습니다. 두 환경 모두 설치는 5분 이내로 끝났고, 첫 세션에서 "이 프로젝트 구조 설명해줘" 한 마디로 Claude가 폴더 트리를 스캔해 요약해주는 경험은 기존 Cursor 사용 경험과는 결이 분명히 달랐습니다.

시작 전 체크리스트 — 구독·OS·터미널 기초

설치에 들어가기 전에 아래 3가지를 준비해두시면 과정이 훨씬 매끄러워집니다.

🛠 준비물

  • Claude 구독 계정 — Pro, Max, Team, Enterprise 중 하나 (또는 Anthropic Console API 계정)
  • 터미널 실행 환경 — macOS 터미널, Linux bash, Windows PowerShell/CMD, WSL2
  • 코드 프로젝트 폴더 — 연습용으로 아무 프로젝트나 하나

⏱ 소요 시간: 약 30분 (설치 5분 + 로그인 5분 + 첫 세션 20분)

터미널(Terminal)이라는 단어가 낯설다면, "까만 화면에 글자만 쳐서 컴퓨터에 명령을 내리는 창"이라고 이해하시면 됩니다. macOS는 기본 설치되어 있고, Windows는 PowerShell이 기본 제공됩니다. WSL(Windows Subsystem for Linux)을 쓰시는 분은 WSL 전용 설치 명령어가 따로 있으니 해당 부분을 참고하시면 됩니다.

✅ 오늘 할 일 체크리스트

  • ☐ Claude 구독 계정을 준비한다
  • ☐ 내 OS에 맞는 설치 명령어를 실행한다
  • ☐ `/login` 으로 Claude 계정에 연결한다
  • ☐ 연습용 프로젝트 폴더에서 `claude` 를 실행한다
  • ☐ 첫 질문("이 프로젝트 뭐야?")을 던진다
  • ☐ "hello world 함수 추가해줘" 로 첫 코드 수정을 체험한다
  • ☐ `/help` 로 전체 명령어를 한 번 훑어본다

Step 1~3: 설치부터 로그인까지

Step 1. Claude Code 설치하기

공식 문서에서는 Native Install 방식을 가장 권장합니다. Native 설치는 백그라운드에서 자동 업데이트가 되어 항상 최신 버전을 유지해주기 때문입니다. OS별로 다음 명령어를 터미널에 붙여넣고 실행하세요.

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
⚠️ 자주 하는 실수: PowerShell에서 `The token '&&' is not a valid statement separator` 에러가 나면 사실은 PowerShell이 아니라 CMD용 명령어를 쓴 것입니다. 반대로 CMD에서 `'irm' is not recognized` 라고 나오면 PowerShell용 명령어를 CMD에 붙여넣은 것입니다. 프롬프트가 `PS C:\` 로 시작하면 PowerShell, 그냥 `C:\` 로 시작하면 CMD입니다. 또한 Windows Native 설치에는 Git for Windows가 먼저 설치되어 있어야 합니다. WSL 설치에는 필요하지 않습니다.

대안 설치 방법 — Homebrew / WinGet

이미 Homebrew나 WinGet을 쓰고 계신 분은 패키지 매니저로 설치하는 것도 편리합니다. 다만 이쪽은 자동 업데이트가 되지 않아 주기적으로 수동 업그레이드가 필요합니다.

macOS Homebrew:

brew install --cask claude-code

Homebrew에는 두 가지 cask가 있습니다. claude-code는 안정 채널(약 1주일 지연, 주요 리그레션이 있는 릴리즈는 스킵)이고, claude-code@latest는 최신 채널로 새 버전이 나오자마자 받습니다. 업그레이드는 brew upgrade claude-code 또는 brew upgrade claude-code@latest 로 수동 실행해야 합니다.

Windows WinGet:

winget install Anthropic.ClaudeCode

업그레이드는 winget upgrade Anthropic.ClaudeCode 로 주기적으로 실행하시면 됩니다.

Claude Code 설치 완료 후 터미널에 표시된 환영 메시지와 버전 정보 화면

Claude Code 설치 직후 터미널 환영 화면 스크린샷

Step 2. Claude 계정으로 로그인하기

설치가 끝나면 어떤 프로젝트 폴더에서든 claude 명령어로 실행할 수 있습니다. 첫 실행 시 로그인 프롬프트가 뜹니다.

claude
# 첫 사용 시 로그인 화면이 나타납니다

또는 세션 안에서 수동으로 로그인할 수도 있습니다.

/login
# 프롬프트를 따라 계정에 로그인

로그인 가능한 계정 종류는 다음 3가지입니다.

  • Claude Pro, Max, Team, Enterprise — 가장 권장. 월 구독이면 추가 결제 없이 Claude Code 사용 가능
  • Claude Console (API 계정) — 선불 크레딧 기반. 첫 로그인 시 Console에 "Claude Code" 워크스페이스가 자동 생성되어 비용을 추적
  • 클라우드 프로바이더 — Amazon Bedrock, Google Vertex AI, Microsoft Foundry 등 기업용 클라우드

로그인하면 자격 증명이 시스템에 저장되어 다시 로그인할 필요가 없습니다. 나중에 계정을 바꾸려면 /login 명령어를 다시 쓰면 됩니다.

Step 3. 첫 세션 시작하기

연습용 프로젝트 폴더로 이동해 claude 를 실행합니다.

cd /path/to/your/project
claude

Claude Code 환영 화면이 나타나며, 세션 정보·최근 대화·최신 업데이트가 표시됩니다. /help 를 치면 사용 가능한 명령어 목록이, /resume 을 치면 이전 대화를 이어갈 수 있습니다.

Step 4~5: 첫 세션 시작과 첫 질문 던지기

Step 4. 첫 질문 던지기 — 코드베이스 이해하기

이제 Claude에게 첫 질문을 던져봅니다. 한국어로 그대로 입력해도 잘 동작합니다.

이 프로젝트가 뭐 하는 거야?

Claude가 파일을 스캔해 요약해줍니다. 더 구체적으로 물어볼 수도 있습니다.

이 프로젝트가 어떤 기술 스택을 쓰고 있어?
메인 진입점이 어디야?
폴더 구조 설명해줘

Claude Code가 흥미로운 이유는 사용자가 파일을 수동으로 넣어줄 필요가 없다는 점입니다. 필요한 파일을 Claude가 스스로 찾아서 읽고 답합니다. 자기 자신의 기능에 대한 질문에도 답할 수 있습니다.

Claude Code로 뭘 할 수 있어?
커스텀 skill은 어떻게 만들어?
Docker랑 같이 쓸 수 있어?

Step 5. 첫 코드 수정 — "hello world 함수 추가해줘"

간단한 코드 수정을 시켜봅니다.

메인 파일에 hello world 함수를 추가해줘

Claude Code는 네 단계로 작업합니다. ① 적절한 파일을 찾고 ② 변경 내용을 미리 보여주고 ③ 승인을 요청하고 ④ 수정을 적용합니다. 항상 파일 수정 전에 허락을 구한다는 점이 핵심 안전 장치입니다. 세션 내에서 "Accept all" 모드를 켜면 개별 승인을 건너뛸 수도 있지만, 입문 단계에서는 한 건씩 확인하는 것이 안전합니다.

Step 6~8: 첫 코드 수정·Git 연동·버그 픽스

Step 6. Git과 Claude Code 함께 쓰기

Claude Code는 Git 작업을 대화형으로 처리해줍니다. 명령어를 외울 필요 없이 자연어로 말하면 됩니다.

내가 어떤 파일을 바꿨어?
변경사항을 설명적인 메시지와 함께 커밋해줘
feature/quickstart 라는 새 브랜치 만들어줘
최근 커밋 5개 보여줘
머지 충돌 해결 도와줘

Git 명령어를 외우려고 씨름하던 시간이 사라집니다. 특히 머지 충돌 해결은 Claude가 양쪽 변경의 맥락을 이해해 추천해주기 때문에 초보자에게 큰 도움이 됩니다.

Step 7. 버그 수정하거나 기능 추가하기

Claude는 디버깅과 기능 구현 모두에 능숙합니다. 자연어로 원하는 것을 묘사하면 됩니다.

사용자 회원가입 폼에 입력 검증을 추가해줘

기존 버그를 고치라고 지시할 수도 있습니다.

빈 폼을 제출할 수 있는 버그가 있는데, 고쳐줘

Claude는 ① 관련 코드를 찾고 ② 맥락을 이해하고 ③ 해결책을 구현하고 ④ 테스트가 있다면 실행까지 합니다.

Step 8. 다른 일반 워크플로 체험하기

Claude와 일하는 방법은 다양합니다. 아래 네 가지를 한 번씩 시도해보시면 감이 잡힙니다.

리팩터링:

인증 모듈을 콜백 대신 async/await 로 리팩터링해줘

테스트 작성:

calculator 함수들의 유닛 테스트를 작성해줘

문서 업데이트:

README에 설치 방법을 업데이트해줘

코드 리뷰:

내가 방금 바꾼 부분 리뷰해주고 개선점 제안해줘

핵심은 동료에게 말하듯 자연스럽게 요청하는 것입니다. 무엇을 달성하고 싶은지 묘사하면, Claude가 거기까지 도달하는 길을 함께 찾아줍니다.

필수 명령어와 초보자 Pro Tips

매일 쓰는 필수 명령어 8개

명령어 기능 예시
claude 대화형 모드 시작 claude
claude "task" 한 번만 실행하는 작업 claude "fix the build error"
claude -p "query" 한 번 질의 후 종료 claude -p "이 함수 설명해줘"
claude -c 현재 폴더의 최근 대화 이어가기 claude -c
claude -r 이전 대화 이력에서 재개 claude -r
/clear 대화 기록 초기화 /clear
/help 사용 가능한 명령어 표시 /help
exit 또는 Ctrl+D Claude Code 종료 exit

초보자가 꼭 기억할 4가지 Pro Tips

1. 요청을 최대한 구체적으로

❌ "버그 고쳐줘"
✅ "로그인 버그 고쳐줘 — 잘못된 자격 증명을 입력하면 빈 화면이 나오는 문제"
요청이 구체적일수록 결과 품질이 극적으로 좋아집니다.

2. 복잡한 작업은 단계로 쪼개기

한 번에 "쇼핑몰 전체 만들어줘" 말고, 아래처럼 단계를 직접 나열하는 편이 좋습니다.

1. 사용자 프로필을 위한 DB 테이블 생성
2. 프로필 조회·수정 API 엔드포인트 생성
3. 사용자가 프로필을 보고 편집할 수 있는 웹페이지 구축

3. Claude에게 먼저 탐색시키기

수정을 시키기 전에 맥락을 파악시키는 편이 안전합니다. "DB 스키마 분석해줘" → "이제 위 분석을 바탕으로 UK 고객이 가장 많이 반품한 상품 대시보드를 만들어줘" 같은 2단계 대화가 한 번에 요청하는 것보다 결과가 좋습니다.

4. 단축키로 시간 절약

  • ? — 사용 가능한 모든 키보드 단축키 표시
  • Tab — 명령어 자동 완성
  • — 이전 명령어 기록
  • / — 모든 명령어와 skill 목록 표시

다음 단계 — CLAUDE.md, MCP, Skills로 생산성 10배

첫 세션을 성공적으로 마치셨다면, 다음은 Claude Code를 나만의 도구로 길들이는 단계입니다. 공식적으로 권장하는 4가지 확장 기능을 소개드립니다.

1. CLAUDE.md — 프로젝트의 "영구 기억"

CLAUDE.md는 프로젝트 루트에 두는 마크다운 파일입니다. Claude Code는 매 세션 시작 시 이 파일을 자동으로 읽어 코딩 표준, 아키텍처 결정, 선호 라이브러리, 리뷰 체크리스트 같은 프로젝트 규칙을 기억합니다. "Bun을 쓰지 말고 Node를 써줘" 같은 규칙을 매번 반복할 필요가 없어집니다. 또한 Claude는 자동 메모리(auto memory)도 별도로 쌓아, 빌드 명령어나 디버깅 인사이트 같은 학습 내용을 세션 간에 보존합니다. CLAUDE.md 작성 방법이 궁금하시다면 CLAUDE.md 작성 가이드에서 자세히 다루고 있습니다.

2. MCP (Model Context Protocol) — 외부 도구 연결

MCP는 AI 도구를 외부 데이터 소스에 연결하는 오픈 표준입니다. MCP를 통해 Claude Code는 Google Drive의 디자인 문서를 읽고, Jira 티켓을 업데이트하고, Slack에서 데이터를 가져오고, 커스텀 툴링을 사용할 수 있습니다. 한 마디로 Claude Code에 "팔다리"를 달아주는 기능입니다.

3. Custom Commands & Skills — 반복 워크플로 패키지화

자주 쓰는 작업을 커스텀 명령어로 묶을 수 있습니다. 예를 들어 /review-pr 이나 /deploy-staging 같은 팀 공용 명령어를 만들어 공유할 수 있습니다. Skills는 이를 더 확장해 특정 작업의 절차를 폴더 단위로 체계화합니다.

4. Hooks — 자동 포맷팅, 린트 통합

Hooks는 Claude Code 동작 전후에 셸 명령어를 실행하는 기능입니다. 예를 들어 파일 수정 후 자동 포맷팅을 하거나, 커밋 전에 lint를 실행하는 것을 자동화할 수 있습니다.

📊 이 네 가지 기능(CLAUDE.md, MCP, Skills, Hooks)을 제대로 쓰는 것과 안 쓰는 것의 차이는 생산성에서 체감상 10배 이상이라고 느껴집니다. 설치와 첫 세션이 끝나셨다면, 가장 먼저 CLAUDE.md 하나를 작성해보시는 것을 강력히 권장합니다.

자주 묻는 질문 (FAQ)

Q. Claude Pro 구독이 없는데 API 계정만으로도 쓸 수 있나요?

네, 가능합니다. Anthropic Console에서 API 계정을 만들고 선불 크레딧을 충전하시면 사용할 수 있습니다. 첫 로그인 시 Console에 "Claude Code" 워크스페이스가 자동으로 생성되어 비용을 중앙에서 추적할 수 있습니다. 가격 정책은 변경될 수 있으므로 공식 사이트에서 최신 정보를 확인하시는 것이 정확합니다.

Q. macOS에서 `curl` 명령어가 작동하지 않습니다. 어떻게 하나요?

macOS는 기본적으로 `curl`이 설치되어 있지만, 드물게 보안 정책 때문에 실행이 차단되는 경우가 있습니다. 이 경우 Homebrew가 가장 간편한 대안입니다. brew install --cask claude-code 로 설치하실 수 있으며, Homebrew가 없다면 brew.sh에서 먼저 설치하시면 됩니다.

Q. WSL에서 Claude Code를 써도 네이티브 Windows 파일에 접근할 수 있나요?

네, WSL은 `/mnt/c` 경로를 통해 Windows 파일시스템에 접근할 수 있습니다. 다만 성능을 위해서는 WSL 내부 파일시스템(`~` 홈 디렉토리 아래)에 프로젝트를 두시는 것이 권장됩니다. WSL 크로스 파일시스템 접근은 I/O가 느릴 수 있습니다.

Q. Claude Code는 VS Code나 JetBrains IDE 안에서도 쓸 수 있나요?

네, 공식 확장(extension)이 있습니다. VS Code와 Cursor에서는 "Claude Code" 확장을 설치하면 IDE 안에서 인라인 diff, @-멘션, plan review, 대화 이력을 사용할 수 있습니다. JetBrains IDE(IntelliJ IDEA, PyCharm, WebStorm 등)는 JetBrains Marketplace에서 Claude Code 플러그인을 설치할 수 있습니다. 모든 환경이 같은 엔진을 공유하므로 CLAUDE.md와 MCP 설정이 그대로 호환됩니다.

Q. 세션을 껐다 켜도 이전 대화를 이어갈 수 있나요?

네, 두 가지 방법이 있습니다. claude -c 는 현재 폴더의 가장 최근 대화를 바로 이어가고, claude -r 은 이전 대화 이력 목록에서 특정 대화를 선택해 재개할 수 있습니다. 세션 안에서는 /resume 명령어로도 같은 기능을 사용할 수 있습니다.

Q. 토큰을 너무 많이 써서 비용이 걱정입니다. 줄이는 방법이 있나요?

작업 사이사이 /clear 로 대화 컨텍스트를 초기화하면 불필요한 토큰 소모를 줄일 수 있습니다. 또한 일상적인 작업에는 Sonnet 모델을, 복잡한 작업에는 Opus 모델을 선택적으로 사용하는 것도 비용 관리에 도움이 됩니다. API 사용자는 /cost 로 현재 세션의 토큰 사용량을 수시로 확인할 수 있습니다.

Q. 설치 중 문제가 생기면 어디서 도움을 받을 수 있나요?

세션 안에서는 /help 를 치거나 "설치 문제가 있어, 도와줘" 라고 직접 물어볼 수 있습니다. 공식 문서의 Troubleshooting 섹션이 가장 체계적이며, Anthropic Discord 커뮤니티에서도 실시간 도움을 받을 수 있습니다.

마무리 — 진짜 개발자처럼 일하는 첫날

Claude Code 설치와 첫 세션을 마치신 시점에서 이미 많은 분들이 "이게 이렇게 쉬웠나?"라는 반응을 보입니다. 터미널의 검은 화면이 더 이상 낯선 장벽이 아니라, 동료에게 말을 거는 대화창으로 바뀌는 순간입니다. 오늘의 핵심은 3가지입니다. ① OS에 맞는 설치 명령어 하나만 복사하면 설치는 끝난다, ② 첫 세션에서는 "이 프로젝트 뭐야?" 같은 탐색 질문부터 시작한다, ③ CLAUDE.md 한 파일만 만들어도 생산성이 체감 10배 달라진다.

💬 설치 중 막히는 부분이 있으셨나요? 어떤 OS 환경인지 댓글로 남겨주시면 함께 해결해보겠습니다.
🔖 이 글을 북마크해두시고 Claude Code를 켤 때마다 참고하시면 편리합니다.
📤 주변에 바이브 코딩 다음 단계로 고민하는 분이 있다면 이 글을 공유해 주세요.

ℹ️ 이 블로그는 Google 애드센스를 통해 광고 수익을 얻을 수 있습니다. 자세한 내용은 개인정보처리방침을 참고하세요.

※ 이 글은 2026-04-16 기준으로 작성되었습니다. 최신 정보는 공식 사이트에서 확인하세요.