[이제와서 시작하는 Claude AI 마스터하기 #6] Claude Code 설치 및 첫 실행

게시 2026/01/20 업데이트 2026/02/08

By YonYonWare

18 분읽는 시간

[이제와서 시작하는 Claude AI 마스터하기 #6] Claude Code 설치 및 첫 실행

Claude Code는 터미널에서 동작하는 AI 코딩 에이전트입니다. 단순한 코드 자동완성이 아니라, 여러분의 프로젝트를 이해하고 파일을 읽고 수정하며, 명령어를 실행하고, Git 작업까지 수행할 수 있어요. 마치 옆에 시니어 개발자가 앉아있는 것처럼요! 이번 편에서는 설치부터 첫 번째 대화까지 완벽하게 안내해 드립니다.

완독 시간: 15분 ⭐⭐

📖 Claude Code란 무엇인가?

한 줄 설명

Claude Code = 터미널에서 동작하는 AI 페어 프로그래머

IDE 플러그인이나 웹 채팅과 달리, 터미널(CLI) 환경에서 직접 동작하면서 여러분의 프로젝트 전체를 파악합니다. 현재 Claude Opus 4.6, Claude Sonnet 4.5 등 최신 모델을 사용하며, Fast Mode로 빠른 응답도 지원합니다.

기존 AI 코딩 도구와의 차이점

┌─────────────────────────────────────────────────────────────────┐
│                    AI 코딩 도구 비교                             │
├─────────────────┬─────────────────┬─────────────────────────────┤
│   일반 AI 챗봇    │   IDE 플러그인   │      Claude Code           │
├─────────────────┼─────────────────┼─────────────────────────────┤
│ 코드 복붙 필요    │ 열린 파일만 인식  │ 프로젝트 전체 이해           │
│ 파일 수정 불가    │ 자동완성 중심     │ 직접 파일 수정              │
│ 명령어 실행 불가  │ 제한적 실행      │ 터미널 명령 실행            │
│ 컨텍스트 유실    │ 세션 한정        │ Git 히스토리까지 파악        │
└─────────────────┴─────────────────┴─────────────────────────────┘

일반 Claude와의 차이점

기능	일반 Claude	Claude Code	Claude Projects
코드 이해	단일 파일	전체 프로젝트	여러 파일
편집 능력	제안만	직접 수정	제안만
컨텍스트	200K 토큰	무제한*	200K 토큰
실행 환경	없음	터미널, 브라우저 등	없음
파일 시스템	제한적	전체 접근	프로젝트 파일
MCP 지원	불가	50+ 연동	불가
메모리	프로젝트 공유	CLAUDE.md	클라우드 저장

*로컬 파일 시스템에 의존

Claude Code가 할 수 있는 것들

기능	설명	예시
코드베이스 탐색	프로젝트 구조와 코드 이해	“이 프로젝트의 인증 로직을 설명해줘”
파일 수정	직접 코드 편집	“이 함수에 에러 핸들링 추가해줘”
명령어 실행	테스트, 빌드, 배포	“테스트 돌리고 실패하면 고쳐줘”
Git 작업	커밋, 브랜치, PR 생성	“변경사항 커밋하고 PR 만들어줘”
디버깅	에러 분석 및 수정	“이 에러 메시지 보고 원인 찾아줘”
리팩토링	코드 개선	“이 클래스를 SOLID 원칙에 맞게 분리해줘”
멀티 에이전트	병렬 작업 수행	“테스트와 린트를 동시에 돌려줘”

지원 플랫폼

Claude Code는 다양한 환경에서 사용할 수 있습니다:

터미널 (CLI): 핵심 경험. claude 명령어로 시작
VS Code: 네이티브 확장 프로그램
JetBrains IDE: IntelliJ, PyCharm, WebStorm 등
데스크톱 앱: 독립 실행형 애플리케이션
웹: claude.ai/code에서 브라우저로 사용
Slack: 슬랙에서 @claude 멘션으로 작업 요청
GitHub Actions: CI/CD 파이프라인 통합

이번 편에서는 터미널 CLI를 기준으로 설명합니다.

🔧 설치하기

사전 준비

설치 전에 다음이 필요합니다:

Claude 구독 (Pro, Max, Teams, Enterprise 중 하나)
- 또는 Claude Platform 계정 (API 크레딧 방식)
터미널 접근 가능한 환경

시스템 요구사항

운영체제: Windows 11+, macOS 12+, Ubuntu 22.04+
메모리: 8GB RAM
저장공간: 5GB 여유 공간
인터넷: 안정적인 연결 필요

설치 방법 선택

네 가지 설치 방법이 있습니다. 상황에 맞게 선택하세요:

방법 1: Native Install (권장 ⭐)

가장 권장하는 방법입니다. 자동 업데이트가 지원됩니다.

macOS / Linux / WSL:

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

Windows PowerShell:

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

Windows CMD:

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

방법 2: Homebrew (macOS)

brew install --cask claude-code

⚠️ Homebrew는 자동 업데이트가 안 됩니다. brew upgrade claude-code로 수동 업데이트하세요.

방법 3: WinGet (Windows)

  
winget install Anthropic.ClaudeCode

⚠️ WinGet도 자동 업데이트가 안 됩니다. winget upgrade Anthropic.ClaudeCode로 수동 업데이트하세요.

방법 4: npm (레거시)

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

⚠️ npm 설치는 deprecated 되었습니다. 위의 Native Install로 마이그레이션하세요. claude install 명령어로도 전환할 수 있습니다.

설치 확인

설치가 완료되면 터미널에서 확인해보세요:

claude --version

버전 정보가 출력되면 성공입니다! 🎉

🚀 첫 실행 및 로그인

Step 1: 프로젝트 디렉토리로 이동

Claude Code는 현재 디렉토리를 기준으로 동작합니다. 먼저 작업할 프로젝트로 이동하세요:

cd /path/to/your/project

Step 2: Claude Code 시작

claude

처음 실행하면 웰컴 화면이 나타납니다.

Step 3: 로그인

처음 사용할 때는 로그인이 필요합니다. 브라우저가 자동으로 열리고 인증 페이지로 이동합니다.

/login

로그인할 수 있는 계정 유형:

Claude Pro/Max/Teams/Enterprise: claude.com 구독 계정
Claude Console: API 크레딧 기반 계정
AWS Bedrock / Google Vertex AI: 엔터프라이즈 클라우드

💡 로그인 정보는 로컬에 저장되므로 매번 로그인할 필요 없습니다.

📋 기본 명령어 익히기

핵심 명령어 정리

명령어	설명	예시
`claude`	대화형 모드 시작	`claude`
`claude "작업"`	단일 작업 실행	`claude "테스트 실행해줘"`
`claude -p "질문"`	질문 후 종료	`claude -p "이 함수 설명해줘"`
`claude -c`	이전 대화 이어하기	`claude -c`
`claude commit`	Git 커밋 생성	`claude commit`

대화형 모드 내부 명령어

대화 중에 /로 시작하는 명령어를 사용할 수 있습니다:

명령어	설명
`/help`	도움말 보기
`/clear`	대화 기록 지우기
`/compact`	컨텍스트 압축
`/model`	모델 변경
`/fast`	Fast Mode 토글 (같은 모델, 빠른 출력)
`/resume`	이전 세션 복원
`/config`	설정 관리
`/tasks`	백그라운드 작업 관리
`/debug`	현재 세션 문제 진단
`/doctor`	환경 헬스 체크
`exit` 또는 `Ctrl+C`	종료

유용한 키보드 단축키

단축키	기능
`?`	모든 단축키 보기
`Tab`	명령어 자동완성
`↑`	이전 명령어
`/`	명령어 메뉴 열기
`Shift+Tab`	권한 모드 전환
`Ctrl+O`	Verbose 모드 토글
`Ctrl+G`	외부 에디터로 열기
`Ctrl+B`	현재 작업을 백그라운드로 전환
`Ctrl+S`	프롬프트 임시 저장(Stash)

💡 키보드 단축키는 커스터마이징할 수 있습니다! /keybindings로 설정하거나 ~/.claude/keybindings.json을 편집하세요.

🎯 첫 번째 코드 변경 해보기

실제로 Claude Code를 사용해봅시다!

실습 1: 프로젝트 이해하기

what does this project do?

Claude가 프로젝트 구조를 분석하고 요약해줍니다.

실습 2: 특정 질문하기

what technologies does this project use?

where is the main entry point?

explain the folder structure

실습 3: 간단한 코드 추가

add a hello world function to the main file

Claude가 다음 과정을 자동으로 수행합니다:

적절한 파일 찾기
변경사항 미리보기 표시
여러분의 승인 요청
승인 시 파일 수정

⚠️ Claude는 파일 수정 전에 항상 승인을 요청합니다. 안심하고 사용하세요!

실습 4: Git 작업

what files have I changed?

commit my changes with a descriptive message

Claude가 변경사항을 분석하고 적절한 커밋 메시지를 작성해줍니다.

🔗 MCP(Model Context Protocol) 통합

Claude Code의 가장 강력한 기능 중 하나는 MCP를 통한 확장성입니다.

MCP 서버 설치 예시

  
# 공식 MCP 서버 설치
claude mcp install postgres     # PostgreSQL 연동
claude mcp install github       # GitHub API 통합
claude mcp install kubernetes   # K8s 클러스터 관리
claude mcp install aws          # AWS 서비스 통합
claude mcp install slack        # Slack 알림/통합

MCP 설정 파일

  
{
  "mcpServers": {
    "github": {
      "provider": "@anthropic/mcp-server-github",
      "config": {
        "token": "${GITHUB_TOKEN}",
        "repos": ["owner/repo1", "owner/repo2"]
      }
    },
    "postgres": {
      "provider": "@anthropic/mcp-server-postgres",
      "config": {
        "connectionString": "${DATABASE_URL}",
        "ssl": true
      }
    }
  }
}

🔒 보안 및 프라이버시

데이터 처리 방식

graph LR
    A[Local Code] -->|Encrypted| B[Claude Code]
    B -->|Analysis Only| C[AI Model]
    C -->|Suggestions| B
    B -->|Results| D[Local Storage]

    E[No Code Storage] -.-> C
    F[No Training] -.-> C

    style E fill:#f99,stroke:#333,stroke-width:2px
    style F fill:#f99,stroke:#333,stroke-width:2px

보안 모범 사례

  
# .claudeignore 파일 사용
# 민감한 파일 제외
.env
.env.*
*.key
*.pem
*.p12
credentials/
secrets/

# 빌드 및 임시 파일
node_modules/
dist/
build/
*.log

📖 Claude Code 워크플로우 전체 아키텍처

graph TB
    subgraph "Claude Code CLI"
        A[User Input] --> B[Claude Code Agent]
        B --> C{Task Analysis}
    end

    subgraph "AI Processing"
        C --> D[Code Generation]
        C --> E[Code Analysis]
        C --> F[Debugging]
        C --> G[Refactoring]
    end

    subgraph "Tool Integration"
        D --> H[File Editor]
        E --> I[Static Analysis]
        F --> J[Debugger]
        G --> K[AST Parser]
    end

    subgraph "MCP Servers"
        H --> L[Filesystem MCP]
        I --> M[Git MCP]
        J --> N[Database MCP]
        K --> O[Custom MCP]
    end

    L --> P[Local Files]
    M --> Q[Git Repo]
    N --> R[Database]
    O --> S[External APIs]

💡 초보자를 위한 팁

1. 구체적으로 요청하세요

❌ "버그 고쳐줘"
✅ "로그인할 때 잘못된 비밀번호 입력하면 빈 화면이 나오는 버그 고쳐줘"

2. 단계별로 나눠서 요청하세요

유저 프로필을 저장할 데이터베이스 테이블 만들어줘
프로필 조회/수정 API 엔드포인트 만들어줘
프로필 편집 웹페이지 만들어줘

3. 먼저 이해시키세요

변경 전에 Claude가 코드를 충분히 이해하게 하세요:

먼저 데이터베이스 스키마를 분석해줘

그 다음에 변경 요청:

새로운 기능을 구현해줘

4. Claude Code에게 물어보세요

Claude Code 자체의 기능에 대해서도 물어볼 수 있습니다:

what can Claude Code do?

how do I create custom skills in Claude Code?

🔧 고급 기능 미리보기

CLAUDE.md를 통한 프로젝트 컨텍스트 설정

  
# CLAUDE.md

## 프로젝트 개요
이 프로젝트는 전자상거래 플랫폼으로...

## 아키텍처
- Frontend: Next.js 14 + TypeScript
- Backend: NestJS + PostgreSQL
- 인증: JWT + OAuth2

## 코딩 컨벤션
- 함수명: camelCase
- 컴포넌트: PascalCase
- 테스트 파일: *.test.ts

## 주의사항
- 모든 API는 버전 관리를 포함해야 함
- 보안 취약점 검사 필수

멀티 에이전트 협업

graph TD
    subgraph "Claude Code Agent Orchestra"
        A[Orchestrator] --> B[Code Generator]
        A --> C[Test Writer]
        A --> D[Documentation]
        A --> E[Security Checker]
        A --> F[Performance Optimizer]
    end

    subgraph "Quality Gates"
        B --> G[Code Review AI]
        C --> G
        D --> G
        E --> G
        F --> G
    end

    G --> H[Final Output]
    G --> I[Feedback Loop]
    I --> A

🛠️ 트러블슈팅

자주 발생하는 문제와 해결법

문제	원인	해결방법
“command not found”	PATH 설정 문제	`export PATH=”$PATH:/usr/local/bin”`
느린 응답	큰 프로젝트	`.claudeignore`로 불필요 파일 제외
MCP 연결 실패	서버 미실행	`claude mcp status`로 확인

디버깅 모드

  
# 상세 로그 활성화
claude --debug

# 환경 헬스 체크
/doctor

📝 오늘 배운 것 정리

✅ Claude Code는 터미널에서 동작하는 AI 코딩 에이전트

✅ 네 가지 설치 방법: Native Install(권장), Homebrew, WinGet, npm(레거시)

✅ 핵심 명령어: claude, claude "작업", claude -c

✅ 파일 수정 전 항상 승인 요청 → 안전하게 사용 가능

✅ MCP를 통해 GitHub, DB, K8s 등 다양한 서비스와 통합 가능

✅ 구체적이고 단계별로 요청하면 더 좋은 결과

🔗 다음 편 미리보기

[이제와서 시작하는 Claude AI 마스터하기 #7] Agentic Loop 이해하기

Claude Code가 어떻게 동작하는지 깊이 있게 알아봅니다:

Agentic Loop의 3단계 (Context → Action → Verify)
내장 도구(Tools)의 종류와 역할
컨텍스트 윈도우와 세션 관리
체크포인트로 안전하게 되돌리기

🔗 참고 자료

🚀 “이제와서”가 아닙니다. 지금이 가장 빠른 시작점이에요!

AI, Claude

🎯 이번에 배울 것

📖 Claude Code란 무엇인가?

한 줄 설명

기존 AI 코딩 도구와의 차이점

일반 Claude와의 차이점

Claude Code가 할 수 있는 것들

지원 플랫폼

🔧 설치하기

사전 준비

시스템 요구사항

설치 방법 선택

방법 1: Native Install (권장 ⭐)

방법 2: Homebrew (macOS)

방법 3: WinGet (Windows)

방법 4: npm (레거시)

설치 확인

🚀 첫 실행 및 로그인

Step 1: 프로젝트 디렉토리로 이동

Step 2: Claude Code 시작

Step 3: 로그인

📋 기본 명령어 익히기

핵심 명령어 정리

대화형 모드 내부 명령어

유용한 키보드 단축키

🎯 첫 번째 코드 변경 해보기

실습 1: 프로젝트 이해하기

실습 2: 특정 질문하기

실습 3: 간단한 코드 추가

실습 4: Git 작업

🔗 MCP(Model Context Protocol) 통합

MCP 서버 설치 예시

MCP 설정 파일

🔒 보안 및 프라이버시

데이터 처리 방식

보안 모범 사례

📖 Claude Code 워크플로우 전체 아키텍처

💡 초보자를 위한 팁

1. 구체적으로 요청하세요

2. 단계별로 나눠서 요청하세요

3. 먼저 이해시키세요

4. Claude Code에게 물어보세요

🔧 고급 기능 미리보기

CLAUDE.md를 통한 프로젝트 컨텍스트 설정

멀티 에이전트 협업

🛠️ 트러블슈팅

자주 발생하는 문제와 해결법

디버깅 모드

📝 오늘 배운 것 정리

🔗 다음 편 미리보기

🔗 참고 자료

인기 태그