Claude Code 완전 가이드 (2026) — 설치부터 실전 자동화까지

Claude Code란?

IDE 자동완성만으로 한계를 느꼈다면, 터미널에서 프로젝트 전체를 이해하고 자율적으로 작업하는 AI 에이전트가 필요합니다.

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트입니다. GitHub Copilot처럼 한 줄씩 제안하는 게 아니라, 전체 작업을 자율적으로 수행합니다.

• 파일 읽기/쓰기/수정
• Git 작업 (커밋, 브랜치, PR)
• 빌드, 테스트, 배포
• 버그 디버깅 및 리팩토링
• 프로젝트 구조 탐색 및 이해

2025년 2월 Public Research Preview로 공개된 이후 빠르게 개발자 커뮤니티에서 채택되고 있습니다.

왜 Claude Code인가?

Step 1: 설치

요구 사항

• Node.js 18+ (npm으로 설치할 경우만 필요 — native installer 사용 시 불필요)
• Claude 구독(Pro, Max, Team, Enterprise) 또는 Anthropic Console API 키 — 둘 중 하나로 인증

설치

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

API 키 설정

# 환경 변수 설정
export ANTHROPIC_API_KEY="sk-ant-..."

# 또는 첫 실행 시 대화형 로그인
claude

Step 2: 기본 사용법

프로젝트 디렉토리에서 시작

cd my-project
claude

Claude Code가 프로젝트 구조를 자동으로 파악합니다.

주요 명령어

# 기본 대화
claude "이 프로젝트의 구조를 설명해줘"

# 파일 수정 요청
claude "login.tsx에서 비밀번호 유효성 검사를 추가해줘"

# 버그 수정
claude "테스트가 실패하는 원인을 찾아서 수정해줘"

# 새 기능 추가
claude "사용자 프로필 페이지를 만들어줘"

슬래시 커맨드

/help          — 도움말
/clear         — 대화 초기화
/commit        — 변경사항 커밋
/compact       — 컨텍스트 압축

Step 3: 실전 활용 팁

CLAUDE.md로 프로젝트 컨텍스트 제공

프로젝트 루트에 CLAUDE.md 파일을 만들면 Claude Code가 매번 참고합니다:

# CLAUDE.md

## 프로젝트 개요
Next.js 14 + TypeScript + Prisma + PostgreSQL

## 코드 컨벤션
- 함수형 컴포넌트만 사용
- 에러 핸들링은 try-catch로 통일
- 테스트: Vitest 사용

## 빌드/테스트
- `npm run build` — 빌드
- `npm run test` — 테스트
- `npm run lint` — 린트

멀티 턴 대화로 복잡한 작업

You: "새 API 엔드포인트 /api/users를 만들어줘"
Claude: (파일 생성 + 라우팅 설정)

You: "여기에 인증 미들웨어를 추가해줘"
Claude: (미들웨어 적용 + 기존 코드 수정)

You: "테스트도 작성해줘"
Claude: (테스트 파일 생성 + 실행)

서브에이전트로 병렬 작업

Claude Code는 복잡한 작업을 서브에이전트에 위임해서 병렬로 처리합니다:

• 코드 탐색: Explore 에이전트
• 계획 수립: Plan 에이전트
• 코드 리뷰: 별도 에이전트 실행

Step 4: 고급 설정

커스텀 슬래시 커맨드

.claude/commands/ 디렉토리에 커스텀 커맨드를 정의할 수 있습니다.

MCP 서버 연동

외부 도구(Linear, GitHub, Slack 등)를 MCP 프로토콜로 연동:

// 프로젝트 루트의 .mcp.json (프로젝트 범위)
// 또는 ~/.claude.json (사용자 전역 범위)
{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["@anthropic/linear-mcp-server"]
    }
  }
}

참고: .claude/settings.json은 hooks·permissions 등 동작 설정 전용입니다. MCP 서버 정의는 .mcp.json에 작성하세요.

Hook 시스템

.claude/settings.json에서 특정 이벤트에 스크립트를 실행할 수 있습니다:

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Command executed' >> /tmp/claude-log.txt"
          }
        ]
      }
    ]
  }
}

지원 이벤트: PreToolUse, PostToolUse, Stop, PreCompact, TaskCompleted 등

Claude Code vs Cursor: 어떤 걸 써야 할까?

결론: 둘 다 쓰는 게 베스트. 하지만 하나만 고르라면 터미널 중심 개발자에게는 Claude Code가 유리합니다.

다음 단계

• OpenClaw 설치부터 첫 자동화까지 — AI 에이전트로 일상 자동화
• Proxmox VE 8 설치 가이드 — Claude Code로 홈서버 관리 자동화

5분 안에 시작하기

1. curl -fsSL https://claude.ai/install.sh | bash
2. 프로젝트 폴더에서 claude 실행
3. “이 프로젝트 구조 설명해줘”로 첫 대화 시작

이것만으로 Claude Code의 핵심 가치를 체험할 수 있습니다.

이 글이 도움이 되었다면 즐겨찾기에 추가해주세요. AI 코딩 도구 관련 가이드를 계속 업데이트합니다.

이미지 출처

• (자체 제작) Claude Code 가이드 본문 예시 이미지 3종(워크플로우/설치 요약/핵심 명령어)

관련 글

• tmux에서 Claude Code 드래그 복사가 안 될 때 — OSC 52와 allow-passthrough
• GPT-5.5 vs Claude Opus 4.7 — 7일 간격으로 붙은 두 프론티어 모델 정면 비교
• Claude Opus 4.7과 Claude Design — Anthropic이 자기 모델로 자기 도구를 먹였다