Claude Code: 초보자를 위한 완벽 가이드 (국내 모델 활용)

완전히 처음부터 시작해서, 자연어를 이해하고 코드를 작성하며 자동으로 작업하는 Claude Code를 컴퓨터에 설치하고, 이를 사용하여 첫 번째 실제 작동하는 제품을 만들어 보세요.

시작하기

• 완전 초보자: 1장부터 5장까지 순서대로 따라 하세요. 첫 번째 웹 도구를 실행하는 순간, 공식적으로 시작한 것입니다.
• 오류 발생 시: 스크린샷을 찍어 Claude Code 또는 Doubao에 전달하세요. "현재 어떤 단계에 있고, 어떤 오류가 보인다"고 설명하는 것이 직접 검색하는 것보다 10배는 효율적입니다.

1장: 기본 개념 익히기

라이브스트리밍이나 매뉴얼을 이해하지 못하는 이유는 보통 머리가 나쁘기 때문이 아니라, 용어들이 서로 연결되지 않기 때문입니다. 이 장에서는 반복해서 등장할 용어들을 풀어 설명합니다.

1.1 세 가지 핵심 개념

1모델 = 뇌 (생각만 함, 손과 발이 없음)
2챗봇 = 뇌 + 입 (말은 할 수 있지만 행동은 못 함)
3에이전트 = 뇌 + 손/발 + 도구 상자 (말하고 행동할 수 있음)

• 모델: GPT, Claude, Gemini, DeepSeek, Doubao, Qwen, Kimi, GLM, MiniMax... 이들은 모델, 즉 '뇌'입니다.
• 챗봇: ChatGPT 웹, Doubao 앱, DeepSeek 대화창. 질문하면 답변은 하지만, 실제 작업은 사용자가 직접 해야 합니다.
• 에이전트: "웹사이트 하나 만들어줘"라고 말하면, 컴퓨터에서 폴더를 만들고, 코드를 작성하고, 실행하고, 디버깅까지 한 후 "다 됐습니다"라고 알려줍니다. Claude Code가 바로 에이전트입니다.

동일한 모델이라도 어떤 도구에서 사용하느냐에 따라 능력이 크게 달라집니다. 동일한 Claude 모델도 브라우저에서는 단순한 채팅에 불과하지만, Claude Code 안에서는 스스로 코드를 작성할 수 있습니다.

1.2 토큰, 컨텍스트, 하네스

• 토큰: AI가 텍스트를 이해하는 가장 작은 단위입니다. 한글 한 글자는 약 1-2 토큰, 영어 단어 하나는 약 1 토큰입니다. 토큰은 여러분의 '전기 요금'과 같습니다. 학습 단계에서는 토큰을 아끼지 마세요.
• 컨텍스트: 현재 대화 라운드의 모든 내용입니다. AI는 장기 기억이 없으며, 현재 '책상' 위에 있는 내용만 참고할 수 있습니다.
• 컨텍스트 윈도우: 각 모델의 '책상' 크기입니다. 2026년 기준, 주류 모델들은 100만 토큰(약 70만~80만 단어)에 도달했습니다.
• 컨텍스트 오염: 하나의 창에서 여러 가지 다른 주제를 이야기하면 AI가 혼란스러워집니다. 하나의 창에는 하나의 작업만, 새로운 주제는 새 창에서 시작하세요.
• 하네스 / 컨텍스트 엔지니어링: 소프트웨어가 아니라, AI를 능숙하게 다루기 위한 방법론의 집합입니다. 즉, 정보를 구성하고, 컨텍스트를 관리하고, AI를 안내하고, 결과를 검증하는 방법입니다. Claude Code가 뛰어난 이유는 이 하네스가 가장 성숙하기 때문입니다.

1.3 스킬이란 무엇인가?

스킬은 Claude를 위한 SOP 매뉴얼입니다.

맥도날드 빅맥이 전 세계 어디서나 같은 맛인 이유는 모든 매장에 셰프가 있기 때문이 아니라, 모든 매장에 SOP(표준 운영 절차)가 있기 때문입니다. 스킬은 Claude를 위한 이 SOP로, "무엇을 먼저 하고, 무엇을 다음에 하고, 어떤 도구를 사용하며, 무엇을 성공으로 간주할지"를 정의합니다.

• 한 번 작성하면 반복해서 호출할 수 있습니다.
• 자신만의 SOP를 작성하는 것은 Claude에게 '내 업무 경험을 가르치는' 것과 같아, Claude가 나의 '가상 직원'이 됩니다.

1.4 세 가지 결제 방식

가장 현실적인 해결책: 국내 모델 API + cc-switch를 사용하여 원클릭으로 전환하세요. 자세한 내용은 3장에서 설명합니다.

1.5 설치 전 알아두면 좋은 보조 도구

1.6 MCP — 에이전트를 위한 '소켓 표준'

MCP는 Model Context Protocol의 약자입니다.

이는 소켓 표준과 같아서, 에이전트가 다양한 외부 도구 및 데이터 소스(Feishu, 데이터베이스, 브라우저, Xiaohongshu, WeChat 등)에 연결될 수 있게 해줍니다.

비유하자면:

• USB 포트를 사용하면 컴퓨터에 주변 기기를 연결할 수 있고, 스피커를 연결하면 '음악을 재생'하는 능력이 생깁니다.
• MCP를 사용하면 Claude Code에 도구를 연결할 수 있고, Tavily를 연결하면 '실시간 트렌드를 검색'하는 능력이 생기며, xiaohongshu-mcp를 연결하면 'Xiaohongshu에 게시'할 수 있습니다.

기본적으로 Claude Code는 사용자가 제공한 정보만 처리하며, 인터넷을 능동적으로 검색하지 않습니다. 검색, 데이터베이스 읽기, 외부 API 호출 등이 필요하다면 MCP가 필요합니다.

1.7 멀티모달 — AI는 '텍스트 읽기' 이상을 할 수 있습니다

모달리티는 정보의 유형입니다. 텍스트는 하나의 모달리티이며, 이미지, 소리, 영상은 다른 모달리티입니다.

• 유니모달: 텍스트만 처리할 수 있습니다.
• 멀티모달: 텍스트, 이미지, 오디오, 비디오, 파일, 화면을 동시에 처리할 수 있습니다.

2026년 주류 모델 지원 현황:

입력 ≠ 출력

AI가 특정 모달리티를 '볼 수' 있다고 해서 그것을 '생성'할 수 있다는 뜻은 아닙니다.

• 이미지: 거의 모든 주류 모델이 이미지를 볼 수 있지만, 일부만 이미지를 그릴 수 있습니다 (GPT Image, Gemini, Doubao Seedance, Jimeng, Nano Banana 등).
• 비디오: Gemini, Doubao, Kimi는 비디오를 볼 수 있지만, LLM이 직접 비디오를 만들지는 않습니다. 대신 전문 도구(Wan, Seaweed Dance, Jimeng)를 사용합니다.

모델 강점:

초보자를 위한 실용적인 조언: 타이핑만 하지 말고, 스크린샷, 녹화 파일, 영상을 AI에 직접 던져서 효율을 높이는 법을 익히세요.

1.8 AI 도구 지형도 (누가 누군지)

하나의 지도로 다양한 도구들 간의 혼란을 정리합니다.

에이전트 도구 (작업을 도와줌)
``text
에이전트 도구
├── 명령줄 (터미널 기반, 가장 강력함)
│ ├── Claude Code —— Anthropic 제작, 현재 최고, 이 가이드의 주인공
│ └── Codex CLI —— OpenAI 제작, 오픈 소스
│
├── GUI (시각적 인터페이스, 사용자 친화적)
│ ├── Codex Desktop/Web —— OpenAI 제작
│ ├── Claude Cowork —— Anthropic 제작, 비기술자용
│ ├── Trae Solo —— ByteDance 제작, 국내산, Code 및 MTC 모드 지원
│ ├── WorkBuddy —— Tencent 제작, 국내산, 비개발자 사무 작업용
│ └── Kiro —— AWS 제작, 사양 기반 IDE (VS Code 포크)
│
├── 자율형 (백그라운드에서 실행)
│ ├── OpenClaw —— 전 Clawdbot, 오픈 소스, WeChat/TG를 통한 원격 제어
│ └── Hermes —— Nous Research 제작, 오픈 소스, 지속적 메모리
│
└── 워크플로 오케스트레이션 (블록 쌓기 자동화)
└── COZE —— ByteDance 제작, 드래그 앤 드롭 워크플로우
``

챗봇 도구 (대화 상대)
``text
챗봇
├── 해외
│ ├── ChatGPT (GPT 모델)
│ ├── Claude.ai (Claude 모델)
│ ├── Gemini (Google 모델)
│ └── Grok (xAI/Elon Musk, X 관련 작업용)
│
└── 국내
├── Doubao (ByteDance)
├── DeepSeek (가성비 우수)
├── Qwen (Alibaba)
├── Kimi (Moonshot AI)
├── WeChat Yuanbao (Tencent, 강력한 WeChat 생태계 데이터)
└── GLM / Zhipu Qingyan (Zhipu AI)
``

댓글에서 흔히 보이는 '은어':

1.9 관계를 한 문장으로 요약

1사용자 (인간)
2  ↕ 자연어
3Claude Code (에이전트) —— MCP를 통해 외부 도구에 연결
4  ↕ 호출
5모델 (Claude / GLM / MiniMax / Kimi…)
6  ↕ 소비
7토큰 (전기 요금)

2장: 환경 설정

4가지를 순서대로 설치합니다: Git → Node.js → VS Code → Claude Code.

2.1 칩 종류 확인

• Mac: Apple 아이콘 -> 이 Mac에 관하여. M1/M2/M3/M4는 ARM, Intel은 x86_64입니다.
• Windows: "내 PC" 우클릭 -> 속성. Intel/AMD는 x86_64입니다.

2.2 Git 설치

• Mac: 터미널을 열고 다음을 붙여넣습니다: /bin/zsh -c "$(curl -fsSL https://gitee.com/happyaicoder/HomebrewCN/raw/master/Homebrew.sh)". git --version으로 확인합니다.
• Windows: https://git-scm.com/https://git-scm.com/)에서 다운로드합니다. 기본 설정을 사용합니다.

2.3 Node.js 설치 (18+, 20 또는 22 권장)

• Mac: 다음을 붙여넣습니다: /bin/bash -c "$(curl -fsSL https://gitee.com/iamzhihuix/nvm-install-cn/raw/main/install.sh)". node -v로 확인합니다.
• Windows: https://nodejs.org/https://nodejs.org/)에서 LTS 버전을 다운로드합니다. PowerShell에서 npm -v가 실패하면 다음을 실행합니다: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser.

2.4 VS Code 설치

https://code.visualstudio.com/https://code.visualstudio.com/)에서 다운로드합니다. Windows에서는 "Add to PATH" 및 "Open with Code" 옵션을 선택합니다.

2.5 Claude Code 설치

• Mac: npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com. 권한 오류 시 sudo를 사용합니다.
• Windows: PowerShell을 관리자 권한으로 실행한 후: npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com.

2.6 일반적인 오류 해결

3장: Claude Code를 국내 모델로 설정하기

Claude Code는 껍데기이며, 내부에는 모델(뇌)이 필요합니다. 공식 Claude 모델을 사용하려면 해외 신용카드가 필요하고 계정 차단 위험이 있습니다. 국내 사용자에게 가장 현실적인 해결책은 cc-switch를 사용하여 국내 모델을 연결하는 것입니다.

3.1 모델 선택

초보자 추천: MiniMax 코딩 요금제 (월 29 RMB).

3.2 cc-switch 설치

GitHub 또는 Gitee Mirror에서 다운로드합니다.

3.3 API 키 발급받기 (예: MiniMax)

1. MiniMax 플랫폼에 가입합니다.
2. 코딩 요금제를 구매합니다.
3. 코딩 요금제 키(일반 API 키가 아님)를 복사합니다.

3.4 cc-switch에서 설정하기

1. cc-switch를 열고 Claude 아이콘을 클릭합니다.
2. +를 클릭하고, 제공자(예: MiniMax)를 선택하고, 키를 붙여넣은 후 추가를 클릭합니다.
3. 마우스를 모델 위로 가져가 "활성화"를 클릭합니다.

3.5 확인

터미널에 claude를 입력합니다. "당신은 어떤 모델인가요?"라고 질문합니다. MiniMax/GLM이라고 답하면 설정이 완료된 것입니다.

4장: Claude Code 기본 조작

4.1 두 가지 시작 방법

• 터미널: VS Code에서 폴더를 열고, 터미널을 열고 claude를 입력합니다.
• 플러그인: VS Code에서 Anthropic의 "Claude Code" 확장 프로그램을 설치합니다.

4.2 필수 단축키

4.3 세 가지 작업 모드

플랜 모드는 매우 중요합니다 — Claude가 행동하기 전에 단계를 먼저 생각합니다. 복잡한 기능을 구현할 때 사용하세요.

4.4 일반 모드 vs. 심층 사고 (ultrathink)

4.5 YOLO 모드 (무인 모드)

파일 변경 시마다 권한을 묻지 않습니다. 사용법: claude --dangerously-skip-permissions.

4.6 CLAUDE.md로 환경 설정하기

프로젝트 루트에 CLAUDE.md 파일을 만들어 선호도 설정을 작성합니다 (예: "주석은 한국어로 작성").

5장: '조기 읽기 도구' 만들기

5.1 디렉토리 및 PRD 생성

VS Code에서 마이크 볼륨이 임계값을 초과하면 이모지 동물을 생성하는 HTML/JS 앱에 대한 요구사항이 담긴 prd.md를 만듭니다.

5.2 구현

터미널에서 claude --dangerously-skip-permissions를 실행하고 다음을 입력합니다: @prd.md 이 기능을 구현해줘.

5.3 결과

브라우저에서 index.html을 열고, 마이크 액세스를 허용한 후 말을 하면 동물이 나타납니다.

6장: 워크플로 스킬 마스터하기

스킬은 재사용 가능한 SOP입니다. 스킬은 SKILL.md(설정), 스크립트, 템플릿을 포함합니다.

6.2 npx skills 사용하기

한 줄의 명령어로 스킬 설치: npx skills add jimliu/baoyu-skills. 스킬과 대상(Claude Code)을 선택합니다.

6.3 스킬 저장소

6.5 맞춤 스킬 만들기: 자동 일러스트레이션

APImart의 Nano Banana 2 API를 사용하여, 작성한 모든 아티클에 대해 손그림 스타일의 일러스트레이션 3개를 생성하는 스킬을 만듭니다.

6.6 스킬 vs MCP vs Hooks vs 플러그인

• 스킬: 레시피 (요리사를 위한 단계).
• MCP: 유틸리티 (주방의 수도/전기/가스).

7장: 하드웨어 및 네트워크

• Mac은 통합 메모리 덕분에 AI 작업에 더 좋지만, Windows도 문제없이 작동합니다.
• MCP 또는 이미지 생성 시 네트워크 오류가 발생하면 프록시(예: clash.verge)에서 TUN 모드를 사용하세요.

부록 A: 명령어 치트시트

claude, /skills list, /clear, /compact, /doctor, /model.

부록 B: 일반적인 오류

부록 C: 용어집

마지막으로

일단 길 위에 올라선 후에 운전 기술에 대해 이야기합시다. 2장부터 5장까지 먼저 시작하세요. AI는 생산성을 10배에서 100배까지 높여주는 도구입니다. 오늘 시작하세요.