VS Code에서 Claude Code 시작하기 — 0부터 30분 안에 셋업 | 컴포넌트팀

‘Claude Code 한 번 써보고 싶은데 어디서부터 시작해야 할지 모르겠다’는 분들을 위한 글입니다. 컴포넌트팀이 5개 클라이언트 프로젝트에서 매일 사용하는 도구의 셋업 방법을, 처음 쓰는 분 기준으로 처음부터 끝까지 정리했습니다.

이 글을 따라 하면 30분 안에 Claude Code를 VS Code에 셋업하고, 첫 번째 실제 작업까지 마칠 수 있습니다.

1. Claude Code란 무엇인가

Claude Code는 Anthropic이 만든 AI 코딩 에이전트입니다. ChatGPT나 Copilot처럼 코드를 한 줄씩 제안하는 도구가 아니라, 목표를 받아 여러 파일을 동시에 수정하고 테스트까지 실행하는 자율 에이전트입니다.

기존 AI 코딩 도구와의 차이를 한 줄로 정리하면 이렇습니다.

Copilot — 다음 한 줄을 예측해주는 자동완성
Cursor — 채팅으로 여러 줄을 수정해주는 IDE
Claude Code — 목표를 주면 여러 파일을 자율로 수정하고 검증하는 에이전트

‘이 프로젝트에 다크 모드 추가해줘’라고 하면 Claude Code는 관련 파일을 스스로 찾고, CSS 변수를 정의하고, 토글 버튼을 만들고, 테스트까지 실행합니다. 사람은 결과를 검토하고 승인만 하면 됩니다.

VS Code에서 사용하면 이 모든 과정이 사이드바 패널 안에서 진행됩니다. 터미널을 따로 열 필요가 없습니다.

2. 시작하기 전 준비물

설치 전에 다음 4가지를 준비해야 합니다.

1) Node.js 18 이상

Claude Code는 npm 패키지로 배포됩니다. 터미널에서 확인:

node --version

v18.x.x 이상이 나오지 않으면 nodejs.org에서 최신 LTS 버전을 설치하거나 nvm으로 업그레이드해주세요.

2) VS Code 1.98.0 이상

VS Code 메뉴 → ‘VS Code 정보’ 또는 Ctrl+Shift+P → ‘About’에서 확인할 수 있습니다. 오래된 버전이면 자동 업데이트를 받거나 code.visualstudio.com에서 다운로드하세요.

3) Anthropic 계정과 Claude 구독

Claude Code 사용을 위해서는 Claude Pro, Max, Team, Enterprise 중 하나의 구독이 필요합니다. 구독은 claude.ai에서 가능합니다.

Pro ($20/월) — 개인 개발자에게 적합한 시작 단계
Max ($100/월) — 하루 종일 헤비하게 사용하는 경우

처음이라면 Pro로 충분합니다. 익숙해진 뒤 사용량을 보고 Max로 올리면 됩니다.

4) 기본 터미널 사용법

Claude Code는 VS Code 통합 터미널에서도 작동합니다. cd, ls 같은 기본 명령어 정도는 알고 있어야 첫 셋업이 매끄럽습니다.

3. 5분 만에 설치하기

준비물이 갖춰졌다면 설치는 매우 간단합니다.

1단계: VS Code 확장 설치

VS Code를 열고 단축키로 확장 패널을 엽니다.

macOS — Cmd + Shift + X
Windows/Linux — Ctrl + Shift + X

검색창에 ‘Claude Code’ 입력 후, 발행자가 Anthropic인 공식 확장을 찾아 Install 버튼을 누릅니다.

주의 — 비슷한 이름의 비공식 확장이 있을 수 있습니다. 반드시 발행자가 Anthropic인지 확인하세요. 정식 확장은 2백만 회 이상 설치되어 있어 쉽게 구별됩니다.

2단계: VS Code 재시작

확장이 설치된 뒤 사이드바에 Spark 아이콘이 나타나지 않으면 VS Code를 재시작합니다. Ctrl+Shift+P → ‘Developer: Reload Window’로도 가능합니다.

3단계: CLI 자동 설치 확인

VS Code 확장은 Claude Code CLI를 자동으로 설치합니다. 통합 터미널을 열고(단축키: Ctrl + `) 다음 명령어로 확인:

claude --version

버전 번호가 나오면 정상 설치된 것입니다. 만약 명령어를 찾을 수 없다면 수동 설치도 가능합니다:

npm install -g @anthropic-ai/claude-code

여기까지가 설치 과정의 전부입니다. 길면 5분, 빠르면 2분 안에 끝납니다.

4. 첫 로그인과 인증

설치가 끝났다면 이제 Claude 계정과 연결해야 합니다.

1단계: Spark 아이콘 클릭

VS Code 사이드바의 Spark 아이콘을 클릭하면 Claude Code 패널이 열립니다.

2단계: 로그인

처음 패널을 열면 ‘Sign in to Claude’ 버튼이 보입니다. 클릭하면 브라우저가 자동으로 열리며 Claude 로그인 페이지로 이동합니다.

3단계: 인증 완료

Claude 계정으로 로그인하면 ‘VS Code에서 Claude Code 사용 권한을 허용하시겠습니까?’ 같은 확인 화면이 나옵니다. Allow를 누르면 자동으로 VS Code로 돌아오고, 인증이 완료됩니다.

이제 Claude Code 패널에서 채팅창이 활성화됩니다.

5. 첫 작업 — 30분 안에 끝낼 수 있는 실습

설치만 하고 끝나면 절반밖에 안 한 겁니다. 진짜 익숙해지려면 첫 작업을 직접 해봐야 합니다. 다음은 Claude Code의 핵심 기능을 한 번에 경험할 수 있는 30분짜리 실습입니다.

준비: 새 프로젝트 폴더 만들기

VS Code에서 빈 폴더를 하나 열어주세요. 데스크톱에 claude-test라는 폴더를 만들고 VS Code로 여는 것을 추천합니다.

작업 1: 프로젝트 초기 셋업 시키기 (5분)

Claude Code 패널에 다음과 같이 입력해보세요:

이 폴더에 React + TypeScript + Tailwind CSS로 셋업한 Vite 프로젝트를 만들어줘.
기본 페이지에는 "Hello, Claude Code!"라는 텍스트만 표시해줘.

Claude Code는 다음과 같이 작동합니다.

작업 계획을 먼저 보여줌 (어떤 파일을 만들지)
Accept 버튼을 누르면 실제 파일 생성 시작
npm install 같은 명령어 실행 권한을 요청 → Allow
모든 파일이 생성되고 dev 서버 실행까지 자동 진행

5분이면 React 프로젝트 하나가 완성됩니다.

작업 2: 기능 추가 시키기 (10분)

이제 좀 더 복잡한 작업을 해봅니다:

다크 모드 토글 버튼을 우측 상단에 추가해줘.
시스템 설정도 자동 감지하고, 사용자 선택은 localStorage에 저장해줘.

Claude Code는 여러 파일을 동시에 수정합니다. 패널에 inline diff가 표시되어 어떤 코드가 추가/변경되는지 한눈에 보입니다. 마음에 들면 Accept, 수정이 필요하면 그대로 채팅창에 추가 요청을 입력합니다.

작업 3: 디버깅 시키기 (10분)

의도적으로 코드를 망가뜨려봅니다. App.tsx 파일에서 import 문 하나를 지우고 저장한 뒤:

지금 dev 서버에서 에러가 나는데, 원인 찾아서 고쳐줘.

Claude Code는 콘솔 로그를 읽고, 에러 메시지를 분석하고, 누락된 import를 찾아 복원합니다.

작업 4: 커밋과 푸시 (5분)

마지막으로:

지금까지 변경사항을 의미 단위로 깔끔하게 커밋 메시지 작성해서 git commit 해줘.

Claude Code는 변경 파일을 분석해 의미 단위로 묶고, 컨벤션에 맞는 커밋 메시지를 작성합니다.

여기까지 하면 Claude Code의 핵심 기능을 모두 한 번씩 경험한 것입니다.

6. 자주 쓰는 단축키와 명령어

매일 사용하면서 가장 자주 쓰게 되는 단축키와 명령어입니다.

기본 단축키

새 대화 시작 — Cmd + N (Mac) / Ctrl + N (Windows)
Spark 패널 열기 — 사이드바 Spark 아이콘 클릭
다중 라인 입력 — Shift + Enter

자주 쓰는 슬래시 명령어

채팅창에 /를 치면 사용 가능한 명령어가 뜹니다.

/init — 프로젝트에 CLAUDE.md 자동 생성
/plan — 코드 수정 전 계획만 먼저 받기
/review — 현재 변경사항 리뷰 받기
/clear — 대화 컨텍스트 초기화
/cost — 현재 세션의 토큰 사용량 확인

파일 멘션

@를 입력하면 파일 검색이 뜹니다.

@src/components/Button.tsx 이 파일의 props 타입을 정리해줘

여러 파일을 한 번에 멘션할 수도 있습니다.

@components/Header.tsx 와 @components/Footer.tsx의 스타일을 통일해줘

7. 다음 단계 — 무엇을 더 배워야 하는가

기본 셋업이 끝났다면 다음 단계로 학습할 내용은 다음과 같습니다.

1) CLAUDE.md 작성

프로젝트 루트에 CLAUDE.md 파일을 두면 Claude Code가 매 세션 시작 시 자동으로 읽습니다. 코딩 컨벤션, 도메인 용어, 금지 패턴을 적어두면 일관성 있는 결과를 얻을 수 있습니다.

자세한 작성법은 컴포넌트팀의 ‘Context Engineering 도입기’ 글에서 다룹니다.

2) MCP 서버 연결

Linear, Sanity, GitHub, Slack 같은 외부 도구를 Claude Code에 연결하면 ‘이번 주 마감인 Linear 이슈 모두 처리해줘’ 같은 요청이 가능해집니다. 표준 프로토콜인 MCP를 통해 1만 개 이상의 서버가 공개되어 있습니다.

3) Skills 작성

자주 쓰는 워크플로(예: PR 작성, 배포 체크리스트)를 Skill로 패키징할 수 있습니다. 한 번 만들어두면 모든 프로젝트에서 재사용 가능합니다.

4) Cursor와의 하이브리드 운영

빠른 인라인 편집은 Cursor, 자율적 다중 파일 작업은 Claude Code로 분배하는 하이브리드 운영이 효율적입니다. 자세한 분배 기준은 컴포넌트팀의 ‘하이브리드 워크플로 도입기’ 글에서 다룹니다.

8. 자주 막히는 5가지 문제와 해결책

1) 확장 설치 후 Spark 아이콘이 안 보임

VS Code를 완전히 종료한 뒤 재시작하세요. 그래도 안 보이면:

VS Code 버전 확인 (1.98.0 이상이어야 함)
확장이 비활성화되어 있지 않은지 확인
Cmd+Shift+P → ‘Developer: Reload Window’

2) claude 명령어를 찾을 수 없음

CLI가 자동 설치되지 않은 경우입니다. 수동 설치:

npm install -g @anthropic-ai/claude-code

권한 에러가 나면 sudo 대신 npm 글로벌 디렉터리를 변경하는 것을 권장합니다:

npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

3) 로그인 페이지가 열리지 않음

브라우저 팝업이 차단되어 있을 가능성이 높습니다. VS Code의 알림 영역에 표시된 URL을 직접 복사해 브라우저에 붙여넣으세요.

4) 패널이 사이드바에서 자꾸 사라짐

VS Code 재시작 후 패널이 다시 안 보이는 경우가 있습니다. 설정에서 다음 항목을 변경하세요:

"claudeCode.preferredLocation": "sidebar"

5) 토큰 사용량이 너무 빠르게 소진됨

다음 습관을 점검하세요.

새 작업 전 /clear로 컨텍스트 초기화
큰 파일을 통째로 멘션하기보다는 특정 함수만 지정
작업이 끝났는데 채팅창에 메시지를 계속 남기지 않기

/cost 명령어로 현재 세션의 사용량을 수시로 확인하면 비용 관리가 쉬워집니다.

마무리

Claude Code는 한 번 셋업하고 나면 매일 쓰는 도구가 됩니다. 처음 30분만 투자하면 그 다음부터는 코딩 방식 자체가 달라집니다.

컴포넌트팀은 1년간 Claude Code를 5개 클라이언트 프로젝트에 적용하면서, 단순 셋업을 넘어 운영·비용·보안까지 표준화한 워크플로를 만들어왔습니다. 이 운영 노하우는 ‘도입기’ 시리즈에서 차례대로 공개하고 있습니다.

다음에 읽으면 좋은 글

Claude Code + Cursor 하이브리드 워크플로 도입기 — 두 도구를 어떻게 분배할 것인가
Context Engineering — CLAUDE.md·AGENTS.md 설계기 — 일관된 결과를 만드는 컨텍스트 파일 작성법
5개 클라이언트 프로젝트를 Claude Code 1명이 동시에 굴린 한 달 — 실제 운영 데이터와 사고 사례

Claude Code 도입을 검토 중이거나 이미 사용 중인데 운영 표준이 필요한 회사라면, 컴포넌트팀이 정립한 노하우를 함께 적용해드릴 수 있습니다.