본문으로 건너뛰기
콰이어트 노트QUIET NOTES

터미널 몰라도 되는 Claude Code VSCode 설정 가이드 (macOS/Linux)

콰이어트·약 12분 읽기
QUIET NOTES / AI

터미널 명령어 하나 모르는 상태에서도 15분 안에 자신만의 웹페이지를 만들 수 있습니다. 이 글을 끝까지 따라하면 Claude Code 설치부터 HTML 파일 생성, 브라우저에서 결과 확인까지 완료됩니다.

Claude Code가 뭔가요?

Claude Code는 Anthropic에서 만든 AI 코딩 도구입니다. “간단한 웹페이지 만들어줘”라고 말하면 파일을 만들고, 코드를 작성하고, 심지어 Git 커밋까지 자동으로 해주죠.

일반적인 AI 챗봇과 다른 점은 직접 파일을 수정하고 명령어를 실행한다는 겁니다. 여러분은 그냥 자연어로 원하는 걸 말하기만 하면 됩니다.

시작 전 준비물

다음 항목들을 미리 확인해주세요.

1. 운영체제

  • macOS 10.15 이상 또는 Linux (Ubuntu 20.04+, Debian 10+)
  • 이 글은 macOS 기준으로 설명합니다

💡 Windows 사용자 안내: Windows에서는 WSL(Windows Subsystem for Linux) 또는 Git Bash가 필요합니다.

2. Claude 요금제

  • Claude Pro ($20/월) 이상 필요
  • ⚠️ 중요: 무료 플랜에서는 Claude Code를 사용할 수 없습니다
  • claude.ai에서 구독 상태를 확인하세요

3. VSCode

  • 공식 사이트에서 다운로드 후 설치
  • 버전 1.98.0 이상 필요
  • 이미 설치되어 있다면 Help → Check for Updates로 업데이트 확인

1단계: 터미널 열기

터미널이 처음이라면 겁먹지 마세요. 그냥 명령어를 입력하는 검은 화면일 뿐입니다.

macOS에서 터미널 여는 방법

방법 1: Spotlight 검색 (가장 쉬움)

  1. Command(⌘) + Space 누르기
  2. “터미널” 또는 “Terminal” 입력
  3. Enter 키 누르기

Spotlight에서 Terminal 검색

방법 2: Finder 사용

  1. 응용 프로그램 폴더 열기
  2. 유틸리티 폴더 클릭
  3. 터미널 더블클릭

터미널이 열리면 검은색(또는 흰색) 화면에 커서가 깜빡이는 게 보일 겁니다. 준비 완료!

터미널 첫 화면

2단계: Claude Code 설치하기

가장 간단하고 빠른 방법입니다. 터미널에 아래 명령어를 복사해서 붙여넣고 Enter를 누르세요.

macOS / Linux 설치 명령어

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

💡 팁: 복사는 Command(⌘) + C, 터미널에 붙여넣기는 Command(⌘) + V입니다!

무슨 일이 일어나나요?

  • curl: 인터넷에서 설치 스크립트를 다운로드합니다
  • bash: 다운로드한 스크립트를 실행합니다
  • 자동으로 Claude Code가 컴퓨터에 설치됩니다

설치 진행 화면

설치가 완료되면 다음과 같은 메시지가 보입니다:

✓ Claude Code installed successfully!
✓ Added to PATH

설치 확인하기

제대로 설치되었는지 확인해볼까요? 터미널을 완전히 종료했다가 다시 열고, 이렇게 입력하세요:

claude --version

버전 번호가 나오면 성공입니다! 🎉

버전 확인 화면

🔧 고급: npm으로 설치하기 (Node.js 사용자용) Node.js가 이미 설치되어 있고 npm이 익숙하다면 이 방법도 가능합니다: “`bash npm install -g @anthropic-ai/claude-code “` **요구사항:** – Node.js 18 이상 필요 – npm 권한 오류 발생 시 [npm 공식 가이드](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) 참고 > ⚠️ **초보자에게는 위의 curl 방식을 추천합니다.** npm 방식은 Node.js 설정에 따라 권한 오류가 발생할 수 있습니다.

3단계: VSCode 확장 설치하기

이제 VSCode에서 Claude Code를 사용할 수 있게 만들어봅시다.

확장 설치 과정

1. VSCode 실행

2. 확장 마켓플레이스 열기

  • 왼쪽 사이드바에서 네모 4개 모양 아이콘 클릭 (Extensions)
  • 또는 단축키: Command(⌘) + Shift + X

VSCode Extensions 아이콘

3. 검색창에 “Claude Code” 입력

Claude Code 검색

4. “Claude Code for VS Code” 확장 찾기

  • 정확한 확장명: Claude Code for VS Code
  • 제작자: Anthropic (꼭 확인하세요!)
  • 파란색 “Install” 버튼 클릭

Install 버튼

💡 참고: 이 확장은 250만 회 이상 설치된 공식 확장입니다. 제작자가 “Anthropic”인지 반드시 확인하세요.

5. 설치 완료 대기

몇 초 후 “Install” 버튼이 톱니바퀴 아이콘으로 바뀌면 완료입니다.

💡 팁: VSCode를 다시 시작할 필요는 없습니다. 바로 사용할 수 있어요!

4단계: 첫 실행 및 인증

Claude Code 실행하기

1. 명령 팔레트 열기

  • Command(⌘) + Shift + P (macOS)
  • 또는 상단 메뉴: View → Command Palette

명령 팔레트

2. “Claude Code: Start” 입력 후 선택

Claude Code Start

3. 인증 진행

  • 브라우저가 자동으로 열립니다
  • Claude.ai 로그인 (Claude Pro 계정으로)
  • “Authorize” 버튼 클릭

인증 화면

⚠️ 브라우저가 자동으로 안 열리면? 터미널에 표시된 URL을 복사해서 브라우저 주소창에 직접 붙여넣으세요. URL은 보통 https://claude.ai/oauth/... 형식입니다.

4. VSCode로 돌아가기

  • “Authentication successful!” 메시지 확인
  • 화면 하단에 Claude Code 채팅창이 나타납니다

Claude Code 채팅 인터페이스

⚠️ 인증 안 될 때: claude.ai에서 Claude Pro 구독 상태를 다시 한번 확인하세요!

5단계: 첫 작업 해보기

이제 진짜로 사용해볼 시간입니다. 간단한 웹페이지를 만들어봅시다.

실습: 자기소개 페이지 만들기

1. 작업할 폴더 열기

  • VSCode에서 File → Open Folder
  • 새 폴더를 만들거나 기존 폴더 선택 (예: “my-first-page”)

폴더 열기

2. Claude에게 요청하기

Claude Code 채팅창에 이렇게 입력하세요:

index.html 파일을 만들어줘.
내 이름은 홍길동이고,
"안녕하세요! 저는 AI와 함께 코딩을 배우고 있습니다"라는
간단한 자기소개 페이지를 만들어줘.

3. Claude가 작업하는 걸 지켜보기

Claude Code는 이렇게 동작합니다:

  1. “index.html 파일을 생성하겠습니다” 라고 알려줌
  2. 자동으로 파일 생성
  3. HTML 코드 작성
  4. 완료 메시지 표시

코드 생성 과정

4. 결과 확인하기

왼쪽 탐색기에 index.html 파일이 생성되었습니다. 클릭해서 내용을 확인해보세요!

5. 브라우저에서 열어보기

가장 쉬운 방법:

  1. Finder에서 작업 폴더로 이동
  2. index.html 파일을 더블클릭 (기본 브라우저에서 열립니다)

Live Server 확장이 있다면:

  • 파일을 우클릭 → “Open with Live Server”
  • 코드 수정 시 자동으로 새로고침됩니다

완성된 웹페이지

💡 팁: “배경색을 파란색으로 바꿔줘”, “글씨 크기를 키워줘” 같은 추가 요청도 바로 할 수 있습니다!

자주 발생하는 문제 해결법

문제 1: “Permission denied” 오류

증상: 설치 시 권한 오류가 발생합니다.

원인: 홈 디렉토리나 설치 경로에 쓰기 권한이 없는 경우

해결법:

# ❌ 이렇게 하지 마세요! (보안 문제 발생 가능)
sudo curl -fsSL https://claude.ai/install.sh | bash

대신 다음을 확인하세요:

# 1. 홈 디렉토리 권한 확인
ls -la ~/

# 2. .local 폴더가 있는지 확인 (없으면 생성)
mkdir -p ~/.local/bin

# 3. 다시 설치 시도
curl -fsSL https://claude.ai/install.sh | bash

그래도 안 되면 Homebrew로 설치해보세요 (macOS):

brew install --cask claude-code

문제 2: “claude: command not found”

증상: 설치 후 claude --version을 입력하면 명령어를 찾을 수 없다고 나옵니다.

해결법:

Step 1: 터미널 새로고침

터미널을 완전히 종료했다가 다시 열어보세요.

또는 이 명령어 실행:

source ~/.zshrc

(bash 사용자는 source ~/.bashrc)

Step 2: 그래도 안 되면 PATH 수동 추가

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

문제 3: VSCode에서 확장을 찾을 수 없음

증상: Extensions에서 “Claude Code”를 검색해도 안 나옵니다.

해결법:

  1. VSCode 버전 확인 – 1.98.0 이상 필요 (Help → About)
  2. VSCode 업데이트 (Help → Check for Updates)
  3. VSCode 완전히 종료 후 재시작
  4. 인터넷 연결 확인
  5. VSCode Marketplace 웹사이트에서 직접 “Install” 클릭

문제 4: 인증이 계속 실패함

증상: “Authentication failed” 메시지가 반복됩니다.

체크리스트:

  • claude.ai에 로그인되어 있는가?
  • Claude Pro 구독이 활성화되어 있는가?
  • 브라우저에서 쿠키/캐시를 차단하고 있지 않은가?
  • VPN 사용 중이라면 잠시 꺼보기

해결 시도:

  1. 브라우저에서 claude.ai 로그아웃 후 다시 로그인
  2. VSCode 명령 팔레트에서 “Claude Code: Sign Out” 실행 후 재인증
  3. 다른 브라우저에서 시도

문제 5: “Rate limit exceeded” 오류

증상: 여러 요청을 빠르게 보내면 오류가 발생합니다.

해결법:

  • 이전 작업이 완료될 때까지 기다렸다가 다음 요청 보내기
  • 너무 큰 작업은 여러 단계로 나눠서 요청하기
  • Claude에게 “천천히 단계별로 진행해줘”라고 요청

마무리

축하합니다! 🎉 이제 여러분도 Claude Code를 사용할 수 있습니다.

핵심 정리

항목 내용
Claude Code란 자연어로 코딩하는 AI 도구
필수 요금제 Claude Pro ($20/월)
설치 명령어 curl -fsSL https://claude.ai/install.sh \| bash
VSCode 확장 “Claude Code for VS Code” (제작자: Anthropic)
VSCode 버전 1.98.0 이상 필요

다음 단계

이제 기본 설정은 끝났습니다. 다음 글에서는 Claude Code로 실전 프로젝트를 만들어보겠습니다:

  • 다음 글: Claude Code로 Todo 앱 10분 만에 완성하기 (예정)

참고 링크

이해가 쌓이는 곳, 콰이어트 노트

궁금한 점이나 더 나은 설명이 있다면 알려주세요.

의견 보내기

KEEP EXPLORING