Claude Code 입문 가이드 2026 — 설치부터 첫 프로젝트까지 완전 정리

안녕하세요, 자바파커입니다.

"AI 코딩 도구가 너무 많은데, Claude Code는 뭐가 다른 건가요?"

솔직히 말하면 — 직접 써보기 전에는 저도 반신반의했습니다. 터미널에서 AI가 코드를 짠다고? 결국 ChatGPT에 코드 달라고 하는 거랑 뭐가 다르지?

결론부터 말씀드리면 — 완전히 다릅니다. Claude Code는 대화창에서 코드를 복붙하는 게 아니라, 내 프로젝트 폴더 안에서 직접 파일을 읽고, 수정하고, 테스트까지 실행하는 AI 에이전트입니다. 오늘은 설치부터 첫 프로젝트까지 한 번에 정리해보겠습니다.

Claude Code란? — 30초 정의

Claude Code는 Anthropic이 만든 AI 코딩 에이전트입니다. 터미널(또는 IDE)에서 자연어로 지시하면, AI가 프로젝트 전체를 이해하고 직접 코드를 작성·수정·실행합니다.

기존 AI 코딩 도구와의 차이를 정리하면:

한 줄 요약: "내 컴퓨터에서 일하는 AI 개발자"

설치 방법 — 3분이면 끝

시스템 요구사항

설치 (권장: 네이티브 설치)

macOS / Linux:

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

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

Homebrew (macOS):

brew install claude-code

설치 후 바로 실행:

claude

첫 실행 시 Anthropic 계정 로그인 화면이 나옵니다. 브라우저가 열리면 로그인하고 권한을 승인하면 끝입니다.

IDE 연동 (선택)

CLI 외에 IDE에서도 사용할 수 있습니다.

개인적으로는 터미널(CLI)에서 시작하는 걸 추천합니다. Claude Code의 핵심 경험이 터미널에 있고, IDE 확장은 결국 내부적으로 CLI를 호출하는 구조입니다.

요금제 — 얼마나 드나?

Claude Code는 무료 플랜이 없습니다. 아래 중 하나가 필요합니다.

실제 비용 감각:

• 일반적인 개발자 기준 하루 $6~12 정도 사용
• /cost 명령으로 현재 세션의 토큰 사용량과 비용을 실시간 확인 가능
• Sonnet 모델을 기본으로 쓰면 비용을 크게 줄일 수 있고, 복잡한 작업에만 Opus로 전환하는 전략이 효과적

처음 시작한다면 Pro($20)로 체험 → Max($100)로 전환하는 경로를 추천합니다.

핵심 기능 5가지 — 이것만 알면 시작 가능

1. 자연어로 코딩

> 로그인 API 엔드포인트를 만들어줘. Express.js 기반으로, 
  JWT 토큰 발급까지 포함해서.

Claude Code가 필요한 파일을 만들고, 패키지를 설치하고, 코드를 작성합니다. 사람은 결과를 확인하고 승인하면 됩니다.

2. 프로젝트 전체 이해

> 이 프로젝트의 인증 흐름을 설명해줘

프로젝트 전체 파일을 읽고 구조를 분석합니다. 최대 1M 토큰(약 300만 자)의 컨텍스트 윈도우 덕분에 대규모 프로젝트도 한 번에 이해합니다.

3. Git 통합

> 지금까지 변경사항을 커밋해줘

git add, commit, push, PR 생성까지 자연어로 처리합니다. 커밋 메시지도 변경 내용을 분석해서 자동 생성합니다.

4. CLAUDE.md — AI에게 주는 프로젝트 매뉴얼

프로젝트 루트에 CLAUDE.md 파일을 만들면, Claude Code가 매 세션마다 이 파일을 읽고 프로젝트의 규칙과 컨벤션을 따릅니다.

# CLAUDE.md

## 프로젝트 규칙
- TypeScript strict 모드 사용
- 함수명은 camelCase
- 테스트는 Vitest로 작성
- 커밋 메시지는 한국어로

비유하자면 신입 개발자에게 주는 온보딩 문서입니다. 한 번 작성하면 매번 같은 말을 반복할 필요가 없습니다.

5. MCP 서버 — 외부 도구 연결

MCP(Model Context Protocol)를 통해 Claude Code에 외부 도구를 연결할 수 있습니다.

• 데이터베이스: Supabase, PostgreSQL 직접 쿼리
• 브라우저: Playwright로 웹 자동화
• API: Slack, GitHub, Jira 등 연동

# 예: Playwright MCP 서버 연결
claude mcp add playwright npx @anthropic-ai/mcp-playwright

연결하면 Claude Code가 브라우저를 직접 조작하거나, DB를 조회하거나, Slack에 메시지를 보낼 수 있습니다.

첫 프로젝트 실습 — React Todo 앱 만들기

실제로 Claude Code를 사용해서 간단한 프로젝트를 만들어보겠습니다.

Step 1: 프로젝트 시작

mkdir my-todo-app
cd my-todo-app
claude

Step 2: 프로젝트 생성 요청

> React + TypeScript로 Todo 앱을 만들어줘. 
  Vite 기반으로 세팅하고, 할 일 추가/완료/삭제 기능을 포함해줘.

Claude Code가 하는 일:

1. npm create vite 실행
2. 필요한 패키지 설치
3. 컴포넌트 파일 생성
4. 기본 스타일 적용

Step 3: 기능 추가

> 할 일 목록을 localStorage에 저장해서 새로고침해도 유지되게 해줘

Step 4: 확인 및 실행

> dev 서버 실행해줘

이 과정이 5~10분 안에 끝납니다. 물론 프로덕션 품질의 코드는 아니지만, 프로토타이핑이나 학습 목적으로는 압도적으로 빠릅니다.

알아두면 좋은 명령어

실전 팁 5가지

1. CLAUDE.md를 먼저 만들어라

프로젝트 시작 전에 규칙을 정해두면 일관된 코드를 받을 수 있습니다. 없이 시작하면 매번 "TypeScript로 해줘", "테스트도 작성해줘"를 반복하게 됩니다.

2. 작은 단위로 요청하라

"전체 쇼핑몰 만들어줘" 보다 "상품 목록 API 만들어줘" → "장바구니 기능 추가해줘" 식으로 나눠서 요청하는 게 결과물 품질이 높습니다.

3. /compact를 적극 활용하라

긴 세션에서 컨텍스트가 쌓이면 속도가 느려지고 비용이 올라갑니다. 한 작업이 끝나면 /compact로 정리하세요.

4. Sonnet을 기본으로, Opus는 필요할 때만

일상적인 코딩은 Sonnet으로 충분합니다. 복잡한 아키텍처 설계나 대규모 리팩토링에만 Opus를 사용하면 비용을 절반 이하로 줄일 수 있습니다. Shift+Tab으로 전환합니다.

5. Git 커밋을 자주 하라

Claude Code가 코드를 수정하다가 잘못된 방향으로 갈 수 있습니다. 중간중간 커밋해두면 언제든 되돌릴 수 있습니다.

다음 단계

이 글에서 다룬 건 기본 중의 기본입니다. Claude Code를 더 깊이 활용하고 싶다면:

• MCP 서버 연결: 데이터베이스, 브라우저, 외부 API를 Claude Code에 연결하는 방법
• Hook 활용: 자동 린트, 테스트 실행, 커밋 메시지 검증 자동화
• 커스텀 스킬: 반복 작업을 슬래시 명령어로 자동화

이 주제들은 후속 포스팅에서 다루겠습니다.

FAQ

Q. Claude Code는 무료로 쓸 수 있나요?

아니요. 최소 Pro 플랜($20/월)이 필요합니다. 무료 체험은 제공되지 않지만, Pro 플랜으로 가볍게 시작한 뒤 필요하면 Max로 업그레이드하는 방식을 추천합니다.

Q. Windows에서도 쓸 수 있나요?

네. Windows 10 이상에서 네이티브로 지원됩니다. 단, Git for Windows가 사전 설치되어 있어야 합니다. PowerShell에서 irm https://claude.ai/install.ps1 | iex 명령으로 설치할 수 있습니다.

Q. 인터넷이 안 되면 사용할 수 없나요?

맞습니다. Claude Code는 Anthropic 서버와 통신해서 작동하므로 인터넷 연결이 필수입니다. 오프라인 모드는 지원하지 않습니다.

여러분은 AI 코딩 도구를 어떻게 활용하고 계신가요? Claude Code를 써보신 경험이 있다면 댓글로 공유해주세요!