Claude Code 입문 - 설치부터 첫 실행까지! 터미널 AI 코딩 에이전트 완벽 가이드 🤖

안녕하세요! Mojangcam입니다 😎

지난 Claude Sonnet 5 출시 글에서 Claude Code의 기본 모델이 Sonnet 5로 교체됐다는 소식을 전해드렸는데요. 그 글을 보고 "그래서 Claude Code가 정확히 뭔가요? 어떻게 시작하나요?" 하고 궁금하셨던 분들이 계실 거예요. 그래서 오늘은 아예 처음부터, 설치부터 첫 실행까지 차근차근 다뤄볼게요!

이번 글에서 배울 것:

• Claude Code가 뭔지, 뭘 할 수 있는지
• 윈도우·맥·리눅스 설치 방법 (복붙 OK)
• 로그인부터 첫 코딩 지시까지
• 모델 바꾸는 법 — /model fable로 Fable 5 써보기!
• 자주 나는 에러와 해결법

ChatGPT나 Claude 웹에서 코드를 복사해다가 붙여넣고, 에러 나면 다시 복사해서 물어보고... 이 왕복 작업이 번거로우셨다면 오늘 글이 딱이에요. Claude Code는 터미널에서 내 프로젝트 폴더를 직접 읽고, 직접 고쳐주거든요!

🧠 Claude Code가 뭔가요?

Claude Code는 Anthropic이 만든 터미널에서 동작하는 AI 코딩 에이전트예요. 챗봇처럼 대답만 하는 게 아니라, 지시를 내리면 알아서 프로젝트 파일을 찾아 읽고 → 수정하고 → 명령어를 실행하고 → 깃(Git) 커밋까지 해주는 게 핵심이에요.

예를 들어 "로그인 폼에 입력 검증 추가해줘"라고 한 줄만 치면, 관련 파일을 스스로 찾아서 코드를 고치고 변경 내용을 보여줍니다. 요즘 유행하는 바이브 코딩(Vibe Coding)의 대표 주자 중 하나죠. 터미널 CLI가 기본이지만 VS Code·JetBrains 확장, 데스크톱 앱, 웹 버전도 있어요. 오늘은 가장 기본인 터미널 버전으로 진행할게요!

📌 준비물

• 운영체제: 윈도우 10(1809 이상) / macOS 13 이상 / Ubuntu 20.04 이상 (RAM 4GB 이상)
• Claude 유료 플랜: Pro·Max·Team·Enterprise 중 하나 — ⚠️ 무료 플랜으로는 Claude Code를 쓸 수 없어요! (Claude Console에서 API 크레딧을 충전해 쓰는 방법도 있습니다)
• 터미널: 윈도우는 PowerShell, 맥·리눅스는 기본 터미널
• (윈도우) Git for Windows 설치 권장 — Claude Code가 Bash 도구를 쓸 수 있게 돼요

Node.js는 필요 없어요! 예전에는 npm으로 설치하는 방식이 기본이었는데, 지금은 네이티브 설치가 공식 권장 방법이라 아무것도 미리 깔 필요가 없습니다. (이 글은 2026-07 기준, Claude Code v2.1.2xx 기준으로 작성했어요.)

📌 1단계 - 설치하기

운영체제에 맞는 명령어 한 줄이면 끝나요.

윈도우 (PowerShell):

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

윈도우 (CMD):

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

macOS / 리눅스 / WSL:

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

하나씩 뜯어볼게요 💡

• irm / iex : PowerShell의 Invoke-RestMethod(다운로드) + Invoke-Expression(실행) 줄임말이에요. 설치 스크립트를 받아서 바로 실행합니다.
• PowerShell vs CMD 구분법 : 프롬프트가 PS C:\로 시작하면 PowerShell, 그냥 C:\면 CMD예요. 서로 명령어가 달라서 바꿔 쓰면 에러가 나요! (아래 에러 섹션 참고)
• 네이티브 설치의 장점 : 백그라운드 자동 업데이트가 돼서 항상 최신 버전을 유지해줘요.
• 이 밖에 winget install Anthropic.ClaudeCode(윈도우), brew install --cask claude-code(맥)로도 설치할 수 있어요.

설치가 끝났으면 확인해볼까요?

claude --version

2.1.211 (Claude Code)처럼 버전 번호가 나오면 성공이에요! 🎉

📌 2단계 - 로그인하기

작업할 프로젝트 폴더로 이동해서 실행하면, 처음 한 번 로그인을 요청해요.

cd 내프로젝트폴더
claude

브라우저가 열리면서 Claude 계정 인증 화면이 나오는데, 로그인하면 끝! 인증 정보가 저장돼서 다음부터는 바로 시작됩니다. 계정을 바꾸고 싶으면 세션 안에서 /login을 입력하면 돼요.

📌 3단계 - 첫 지시 내려보기

이제 진짜 재미있는 부분이에요. 프롬프트에 평소 동료에게 말하듯 지시하면 됩니다.

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

Claude가 폴더 안 파일들을 스스로 읽고 요약해줘요. 파일을 일일이 붙여넣을 필요가 없다는 게 웹 챗봇과의 가장 큰 차이예요! 이어서 수정도 시켜볼까요?

main 파일에 hello world 함수 하나 추가해줘

Claude Code가 적절한 파일을 찾고 → 바꿀 내용을 미리 보여주고 → 내 승인을 받은 뒤에 수정해요. 기본 모드에서는 항상 물어보니 안심하셔도 됩니다.

하나씩 뜯어볼게요 💡

• 권한 모드 : Shift+Tab을 누르면 모드가 순환돼요. acceptEdits(파일 수정 자동 승인), plan(수정 없이 계획만 제안) 등 상황에 맞게 골라 쓰면 됩니다.
• 활용 예시 : 저처럼 디스코드 봇을 만들고 계시다면 "명령어에 쿨다운 추가해줘", "이 코드 리팩토링하고 설명해줘" 같은 지시가 잘 통해요. 깃도 대화로 처리됩니다 — "변경사항 커밋해줘, 메시지는 알아서".

🧩 모델 전환 - Fable 5도 써볼 수 있어요!

2026-07 현재 Claude Code의 기본 모델은 Sonnet 5예요 (자세한 내용은 지난 글 참고). 세션 안에서 /model 명령으로 언제든 바꿀 수 있습니다.

/model          ← 모델 선택 화면 열기
/model opus     ← Opus 4.8 (복잡한 추론)
/model fable    ← Fable 5 (최상위 모델!)

Fable 5는 Anthropic이 새로 낸 Claude 5 패밀리의 첫 모델로, Opus보다 윗급 티어예요. 2026-07-01부터 Claude Code에서 쓸 수 있게 됐고(v2.1.170 이상 필요), 길고 어려운 작업을 자율적으로 오래 수행하는 데 강합니다. 참고로 요청이 안전 분류기에 걸리면 Opus 4.8로 자동 전환될 수 있어요.

💡 요금 관련: Fable 5는 구독 플랜에 무료로 포함된 기간이 2026-07-19까지로 연장된 상태예요 (이미 두 차례 연장됐어요). 7/20부터는 사용량 크레딧 방식으로 바뀔 예정이라, 보시는 시점의 공식 공지를 꼭 확인해주세요!

💡 자주 쓰는 명령어 모음 (복붙 OK)

📌 자주 나는 에러

1. 'claude'은(는) 내부 또는 외부 명령... 이 아닙니다 (command not found) 원인: 설치 직후 PATH가 아직 반영되지 않았을 때 주로 발생해요. 해결: 터미널을 완전히 껐다가 다시 켜보세요. 그래도 안 되면 claude doctor로 진단하거나 설치 명령을 다시 실행하면 됩니다.
2. The token '&&' is not a valid statement separator 원인: CMD용 설치 명령을 PowerShell에 붙여넣은 경우예요. 해결: PowerShell에서는 irm https://claude.ai/install.ps1 | iex를 쓰세요. 반대로 'irm'은(는) ... 명령이 아닙니다가 나오면 CMD에서 PowerShell 명령을 쓴 거예요.
3. 로그인했는데 사용할 수 없다고 나와요 원인: 무료 플랜은 Claude Code가 포함되지 않아요. 해결: Pro 이상 구독 또는 Claude Console(API 크레딧) 계정이 필요합니다.
4. /model fable이 목록에 없어요 원인: Claude Code 버전이 낮은 경우예요 (v2.1.170 미만). 해결: claude update로 업데이트하면 나타나요.

📌 마무리

오늘은 Claude Code를 처음부터 끝까지 세팅해봤어요. 정리하면 — ① 명령어 한 줄로 설치하고 ② claude 실행 후 브라우저 로그인, ③ 프로젝트 폴더에서 자연어로 지시, ④ 필요하면 /model fable로 최상위 모델까지! 터미널이 낯설어도 오늘 글만 따라 하면 10분이면 충분합니다.

다음에는 AI 코딩 시리즈로 Cursor 사용법 입문과 무료 AI 코딩 도구 비교 (Claude Code·Cursor·Copilot) 글이 이어질 예정이에요. 기대해주세요 🙌

함께 보면 좋은 글:

• Claude Sonnet 5 출시! Claude Code 기본 모델 교체 - 달라진 점과 활용법 총정리