Claude Code: 실용적인 입문 가이드

가장 흥미로운 부분으로 들어가 봅시다: AI를 사용해 코드를 작성하는 것입니다.

여러분은 이렇게 생각할 수도 있습니다: “나는 코드에 대해 아무것도 몰라, 이게 나와 무슨 상관이지?”

반대로, 코드를 모르기 때문에 이 도구가 더 적합합니다.

웹페이지 하나 만드는 데 5만 원을 썼던 친구를 기억하시나요? Claude Code를 사용하면 그런 일은 다시는 없을 겁니다. 여러분이 원하는 것을 평범한 언어로 AI에게 말하기만 하면, AI가 완전한 프로그램을 작성해 줍니다.

오늘 소개할 Claude Code는 터미널에서 실행되는 AI 프로그래밍 어시스턴트입니다. 여러분이 원하는 것을 평범한 언어로 말하면, AI가 전체 프로그램을 작성해 줍니다.

왜 IDE 대신 터미널 도구를 사용할까?

IDE란 무엇인가?

IDE = 통합 개발 환경 (Integrated Development Environment)

간단히 말해, IDE는 프로그래머가 코드를 작성할 때 사용하는 소프트웨어입니다. 예를 들어:

VS Code
Cursor
PyCharm
WebStorm

이러한 도구들은 복잡한 인터페이스와 강력한 기능을 가지고 있지만, 코드에 대해 전혀 모르는 사람에게는 오히려 부담이 됩니다.

터미널을 추천하는 이유

이유 1: 간단한 인터페이스

IDE: 버튼, 메뉴, 사이드바, 상태 표시줄이 가득… 처음 보면 압도됩니다.
터미널: 그냥 검은 화면 하나 – 명령어를 입력하고 결과를 받으며, 깔끔하고 직관적입니다.

이유 2: 코드를 직접 수정할 필요가 없음

코드를 전혀 이해하지 못한다면, IDE에 표시된 코드는 외계어처럼 보일 것입니다. 읽을 수도 없고 어떻게 바꿔야 할지도 모릅니다.

모든 것이 AI에 의해 작성된다면, 굳이 코드를 볼 필요가 있을까요?

터미널의 Claude Code는 다음을 수행합니다:

자동으로 파일 생성
자동으로 코드 작성
자동으로 코드 수정
자동으로 테스트 실행

여러분은 원하는 것을 말하기만 하면, 나머지는 Claude Code가 처리합니다.

이유 3: 더 가벼운 소프트웨어

Cursor/VS Code: 수백 MB, 게다가 다양한 플러그인을 설치해야 함
터미널: 시스템에 내장되어 있어 추가 설치가 필요 없음

요약: 코딩 경험이 전혀 없고 AI가 도움을 주어 무언가를 만들고 싶은 사람에게는 터미널 + Claude Code가 가장 간단하고 직접적인 조합입니다.

터미널 기초: 프로젝트 폴더 여는 방법

Claude Code를 사용하기 전에 한 가지 기본 작업을 배워야 합니다: 터미널에서 프로젝트 폴더를 여는 방법.

Mac 사용자

방법 1: 마우스 오른쪽 버튼으로 열기 (권장)

Finder에서 프로젝트 폴더를 찾습니다.
폴더를 마우스 오른쪽 버튼으로 클릭합니다 (또는 트랙패드에서 두 손가락으로 탭).
“폴더에서 새 터미널 열기” 를 선택합니다.

방법 2: Option + 마우스 오른쪽 버튼으로 경로 복사

Finder에서 프로젝트 폴더를 찾습니다.
Option 키를 누른 상태에서 폴더를 마우스 오른쪽 버튼으로 클릭합니다.
"‘폴더명’을(를) 경로 이름으로 복사" 를 선택합니다.
터미널을 엽니다 (Launchpad에서 “터미널” 검색).
cd 를 입력합니다 (cd 뒤에 공백 주의).
Command + V를 눌러 경로를 붙여넣습니다.
Enter 키를 누릅니다.

예시:

cd /Users/yourname/Desktop/my-project

방법 3: 드래그 앤 드롭

터미널을 엽니다.
cd 를 입력합니다 (공백 주의).
Finder에서 폴더를 터미널 창으로 드래그합니다.
경로가 자동으로 입력되면 Enter 키를 누릅니다.

Windows 사용자

파일 탐색기에서 프로젝트 폴더를 찾습니다.
주소 표시줄에 cmd 또는 powershell을 입력하고 Enter 키를 누릅니다.
해당 폴더에서 명령줄이 바로 열립니다.

또는:

폴더를 마우스 오른쪽 버튼으로 클릭합니다.
“터미널에서 열기” 를 선택합니다 (Windows 11).

Claude Code란 무엇인가?

한 문장으로 요약

Claude Code = 터미널에서 실행되는 AI 프로그래밍 어시스턴트

Anthropic(Claude를 만든 회사)의 공식 명령줄 도구입니다. 터미널에서 대화하면 다음과 같은 일을 할 수 있습니다:

새 프로젝트 생성
코드 작성
코드 수정
버그 수정
코드 설명
명령어 실행

웹 버전 Claude와 어떻게 다른가?

기능	Claude 웹	Claude Code
사용 방법	브라우저에서 채팅	터미널에서 명령어 입력
파일 조작 가능?	아니요, 대화만 가능	예, 파일을 직접 생성하고 수정 가능
코드 실행 가능?	아니요	예, 컴퓨터에서 코드 실행 가능
가장 적합한 용도	질문하기, 글쓰기	프로젝트 구축, 프로그램 작성

핵심 차이: 웹 버전은 “말"만 할 수 있지만, Claude Code는 “행동"할 수 있습니다.

Claude Code 설치 방법

사전 요구 사항

Node.js: Claude Code는 Node.js가 필요합니다.
- 다운로드: https://nodejs.org
- LTS(장기 지원) 버전을 선택하세요.
- 설치 후 터미널에서 node -v로 확인합니다.

2. 네트워크 환경: Claude의 API에 접근할 수 있어야 합니다 (VPN이 필요할 수 있음).

설치 단계

터미널을 열고 다음을 실행합니다:

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

설치가 완료될 때까지 기다립니다. 다음과 같은 출력이 보이면 성공입니다:

added 1 package in 2s

설치 확인:

claude --version

버전 번호가 표시되면 설치가 성공한 것입니다.

사용 방법 여러 가지

Claude Code는 AI 기능에 접근하는 여러 가지 방법을 지원합니다. 자신에게 맞는 방법을 선택하세요.

방법 1: Claude 멤버십 구매

이것이 가장 간단하고 직접적인 방법입니다.

Claude 멤버십 등급:

요금제	가격	Claude Code 할당량
Claude Pro	월 $20	제한된 할당량, 가벼운 사용에 적합
Claude Max	월 $100	더 높은 할당량, 많은 사용에 적합
Claude Max	월 $200	최고 할당량, 전문 개발에 적합

설정:

Claude 멤버십을 구매한 후 터미널을 엽니다.
claude를 실행하여 시작합니다.
안내에 따라 Claude 계정에 로그인합니다.
로그인하면 사용할 수 있습니다.

방법 2: 다른 모델의 API 사용

Claude 멤버십을 구매하고 싶지 않다면, 다른 모델의 API를 사용하여 Claude Code를 구동할 수 있습니다.

지원되는 모델:

DeepSeek
OpenAI GPT 시리즈
OpenAI 형식과 호환되는 기타 API

2.1 환경 변수로 설정 (DeepSeek 예시)

DeepSeek의 API는 Anthropic 형식과 호환되므로 직접 대체하여 사용할 수 있습니다.

Mac/Linux 설정:

터미널에서 다음 명령어를 실행합니다 (임시 설정 – 터미널을 닫으면 사라집니다):

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=${DEEPSEEK_API_KEY}
export API_TIMEOUT_MS=600000
export ANTHROPIC_MODEL=deepseek-chat
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

그런 다음 claude를 실행하면 됩니다.

Windows 설정 (PowerShell):

$env:ANTHROPIC_BASE_URL="https://api.deepseek.com"
$env:ANTHROPIC_AUTH_TOKEN="Your DeepSeek API Key"

그런 다음 claude를 실행하면 됩니다.

참고: 이 방법은 임시 설정이며, 터미널을 닫으면 사라집니다. 영구 설정을 원하면 아래 settings.json 방법을 사용하세요.

참고 자료: https://api-docs.deepseek.com/guides/anthropic_api

2.2 settings.json으로 설정 (권장)

이 방법이 더 편리합니다. 한 번 설정하면 Claude Code를 시작할 때마다 자동으로 이 설정을 사용합니다.

설정 단계:

Claude Code 설정 폴더를 찾습니다:
- Mac/Linux: ~/.claude/
- Windows: %USERPROFILE%\.claude\
settings.json 파일을 생성하거나 편집합니다 (예시):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com",
    "ANTHROPIC_AUTH_TOKEN": "Your DeepSeek API Key"
  }
}

파일을 저장하고 Claude Code를 다시 시작합니다.

팁: .claude 폴더가 없다면 claude 명령어를 한 번 실행하면 자동으로 생성됩니다.

터미널에서 Claude Code 시작하는 방법

기본 시작

터미널을 엽니다.
cd 명령어로 프로젝트 폴더로 이동합니다.
claude를 입력하고 Enter 키를 누릅니다.

cd /path/to/your/project
claude

Claude Code가 시작되고, 요청을 입력할 수 있는 대화형 인터페이스가 나타납니다.

자주 사용하는 명령어와 개념

Claude Code의 자주 사용하는 명령어

명령어	동작
`/help`	도움말 보기
`/clear`	현재 대화 지우기
`/exit` 또는 `Ctrl+C`	Claude Code 종료
`/compact`	대화 기록 압축하여 토큰 절약
`/init`	프로젝트 초기화, CLAUDE.md 파일 생성

계획 모드 (Plan Mode)

계획 모드 = Claude가 먼저 계획을 세우고 실행하도록 함

기본적으로 Claude는 즉시 코드 작성을 시작합니다. 하지만 때로는 실행 전에 생각할 시간을 주고 싶을 때가 있습니다. 그럴 때 계획 모드를 활성화합니다.

전환 방법?

Shift + Tab을 눌러 세 가지 모드를 순환합니다:

모드	설명
Normal	일반 모드, Claude가 직접 실행
Plan	계획 모드, Claude는 계획만 세우고 실행하지 않음; 사용자 확인 대기
Auto	자동 모드, Claude가 모든 작업을 자동으로 실행, 확인 요청 없음

계획 모드는 언제 사용하나요?

프로젝트가 복잡해서 Claude가 먼저 접근 방식을 명확히 하길 원할 때
Claude가 어떻게 변경할지 확신이 서지 않아 계획을 보고 싶을 때
Claude의 행동을 더 정밀하게 제어하고 싶을 때

편집 수락 (Accept Edits)

편집 수락 = Claude의 수정을 자동으로 승인할지 여부

Claude가 파일을 생성하거나 수정하려고 할 때, 기본적으로 사용자의 확인을 요청합니다.

전환 방법?

Shift + Tab을 눌러 모드를 변경하면 다음이 표시됩니다:

Accept edits: off – 모든 수정에 대해 수동 확인 필요
Accept edits: on – 모든 수정을 자동으로 수락, 확인 없음

권장 사항:

초보자는 off 상태를 유지하여 Claude가 각 단계에서 무엇을 하는지 확인하는 것이 좋습니다.
익숙해지면 on으로 전환하여 더 원활한 작업 흐름을 경험하세요.

`resume`이란?

resume = 이전 대화 재개

터미널을 닫거나 Claude Code를 종료한 후, 다음에 --resume 플래그를 사용하여 이전 대화를 계속할 수 있습니다:

claude --resume

Claude가 이전에 논의한 내용을 기억하므로 처음부터 다시 시작할 필요가 없습니다.

resume은 언제 사용하나요?

어제 작업한 프로젝트를 오늘 이어서 하고 싶을 때
컴퓨터가 예기치 않게 종료되어 작업을 복구하고 싶을 때
Claude가 중단된 지점부터 계속 작업하길 원할 때

CLAUDE.md란?

CLAUDE.md = 프로젝트 설명 파일

프로젝트 루트 디렉토리에 있는 Markdown 파일입니다. Claude에게 프로젝트의 배경을 알려줍니다.

생성 방법?

먼저 claude를 실행하여 Claude Code를 시작한 후, /init을 입력합니다.

claude

Claude Code 내에서 다음을 입력합니다:

/init

Claude가 자동으로 프로젝트를 분석하고 CLAUDE.md 파일을 생성합니다.

무엇에 사용되나요?

Claude Code가 시작될 때 이 파일을 읽어 다음을 이해합니다:

프로젝트가 무엇을 하는지
어떤 기술 스택을 사용하는지
특별한 요구 사항이 있는지
코드 스타일 선호도

CLAUDE.md 예시:

# Project Description

This is a personal translation tool webpage.

## Tech Stack
- Pure HTML/CSS/JavaScript
- No frameworks

## Requirements
- Code comments in English
- Clean and modern interface
- Support dark mode

이 파일이 있으면 Claude Code를 시작할 때마다 프로젝트 배경을 설명할 필요가 없습니다.

Skill

Skill = Claude Code 단축 명령어

Skill은 미리 설정된 명령어로, Claude가 특정 작업을 빠르게 수행하도록 합니다.

자주 사용하는 내장 Skill:

명령어	동작
`/commit`	자동으로 git 커밋 메시지 생성 및 코드 커밋
`/review`	코드 리뷰 및 문제 찾기
`/fix`	코드 오류 수정

사용 방법?

Claude Code에서 슬래시 명령어를 입력하기만 하면 됩니다. 예:

/commit

Claude가 자동으로 코드 변경 사항을 분석하고 적절한 커밋 메시지를 생성합니다.

사용자 정의 Skill은 이후 장에서 자세히 다루겠습니다.

MCP (Model Context Protocol)

MCP = Claude를 외부 도구 및 데이터 소스에 연결

MCP는 Claude Code가 다양한 외부 서비스에 연결할 수 있게 해주는 프로토콜입니다. 예를 들어:

데이터베이스
파일 시스템
웹 서비스
기타 AI 도구

이렇게 생각하세요: MCP는 Claude에 “플러그인"을 추가하여 더 많은 일을 할 수 있게 합니다.

예시:

Obsidian에 연결하여 Claude가 노트를 직접 읽고 쓰게 함
브라우저에 연결하여 Claude가 웹 페이지를 자동화하게 함
데이터베이스에 연결하여 Claude가 데이터를 쿼리하고 분석하게 함

MCP 설정 및 사용법은 이후 장에서 자세히 다루겠습니다.

실습: Claude로 번역 웹페이지 만들기

이제 많은 것을 배웠으니, 직접 실습해 봅시다!

로컬 번역 웹페이지를 만들어서 Gemini API를 사용한 번역을 구현할 것입니다.

1단계: 프로젝트 폴더 생성

바탕화면(또는 원하는 곳)에 새 폴더를 만듭니다. 예를 들어 demo라는 이름으로 만듭니다.
앞서 배운 방법을 사용하여 이 폴더를 터미널에서 엽니다.

2단계: Claude Code 시작

claude

3단계: 요청 입력

Claude Code에 다음을 입력합니다 (복사해도 됩니다):

Create a translation webpage tool with the following requirements:

1. Features:
   - Left input box for the source text, right side shows the translation result
   - Support Chinese-English translation
   - A "Translate" button
   - A "Clear" button
   - A "Copy Result" button

2. Interface:
   - Clean and modern design
   - Support dark/light mode toggle
   - Responsive design, works on mobile

3. Technical requirements:
   - Use only HTML, CSS, JavaScript, no frameworks
   - All code in a single HTML file
   - Call the Gemini API for translation

4. Settings (important):
   - A "Settings" button on the page
   - Clicking it opens a settings panel where you can configure:
     - API Key
     - API URL
     - Model Name
   - Save settings to the browser's localStorage, auto-load next time
   - The settings panel should have "Save" and "Cancel" buttons

5. Translation logic:
   - Auto-detect the input language
   - If Chinese, translate to English
   - If English, translate to Chinese

Please create this HTML file directly.

4단계: Claude가 완료할 때까지 기다리기

Claude가 자동으로:

HTML 파일을 생성합니다.
모든 코드를 작성합니다.
파일 위치를 알려줍니다.
실행 후 파일 생성을 동의할지 묻습니다 – 1 또는 2를 선택하세요.

5단계: 실행 및 API 설정

생성된 HTML 파일을 더블 클릭하여 브라우저에서 엽니다.
페이지의 “설정” 버튼(보통 톱니바퀴 아이콘)을 클릭합니다.
나타난 설정 패널에 다음을 입력합니다:
- API Key: AI Studio에서 받은 API 키
- API URL: https://generativelanguage.googleapis.com/v1beta
- Model Name: gemini-3-flash-preview
“저장"을 클릭합니다.

설정은 브라우저에 자동 저장되므로 다음에 다시 입력할 필요가 없습니다.

6단계: 사용 시작

이제 다음을 할 수 있습니다:

왼쪽 입력 상자에 중국어 또는 영어를 입력합니다.
“번역” 버튼을 클릭합니다.
번역 결과가 오른쪽에 나타납니다.
“결과 복사"를 클릭하여 번역된 텍스트를 복사합니다.

요약

오늘 배운 내용:

IDE 대신 터미널을 사용하는 이유: 코드를 모르는 사람에게 터미널이 더 간단하고 직접적입니다.
터미널에서 프로젝트 여는 방법: 마우스 오른쪽 버튼, 드래그 앤 드롭, 또는 cd 명령어 사용.
Claude Code란 무엇인가: 터미널에서 파일을 직접 조작할 수 있는 AI 프로그래밍 어시스턴트.
설치 및 설정 방법: npm으로 설치, 공식 멤버십 또는 타사 API 지원.
자주 사용하는 명령어: resume으로 대화 재개, CLAUDE.md로 프로젝트 설명.
실습: Claude로 번역 웹페이지 만들기.

핵심 아이디어: 코드 작성 방법을 알 필요 없이, 원하는 것을 설명하는 방법만 알면 됩니다.