Anthropic Claude Code 완벽 가이드: AI 코딩 어시스턴트의 모든 것

Complete Guide to Anthropic Claude Code: Everything About AI Coding Assistant

2025-12-25 인공지능

Claude Code는 Anthropic에서 개발한 공식 AI 코딩 어시스턴트 CLI(Command Line Interface) 도구입니다. 터미널에서 작동하며 개발자들이 아이디어를 빠르게 코드로 변환하고, 버그를 수정하고, 코드베이스를 탐색하는 데 혁신적인 도움을 제공합니다. 이 가이드에서는 Claude Code의 설치부터 고급 기능까지 모든 것을 상세히 다룹니다.

English: Claude Code is the official AI coding assistant CLI tool developed by Anthropic. It operates in the terminal and provides revolutionary assistance to developers in quickly converting ideas into code, fixing bugs, and navigating codebases. This guide covers everything from installation to advanced features of Claude Code in detail.

1. Claude Code란 무엇인가?

1.1 핵심 개념

Claude Code는 에이전트 기반 아키텍처를 사용하는 터미널 네이티브 AI 도구입니다. 기존의 IDE 플러그인과 달리, Claude Code는 터미널에서 직접 작동하며 파일 편집, 명령 실행, Git 커밋 생성 등을 자율적으로 수행할 수 있습니다.

┌─────────────────────────────────────────────────────────┐
│                  Claude Code 아키텍처                      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   [사용자] ─────────────────────────────── [터미널]      │
│       │                                       │         │
│       ▼                                       ▼         │
│   자연어 명령  ────────────► Claude Code Engine        │
│                                      │                  │
│                    ┌─────────────────┼─────────────────┐│
│                    ▼                 ▼                 ▼│
│               [파일 읽기]      [코드 수정]      [명령 실행]│
│               [검색/분석]      [테스트 작성]    [Git 작업]│
│                                                         │
└─────────────────────────────────────────────────────────┘

1.2 주요 특징

터미널 네이티브: IDE가 아닌 터미널에서 직접 작동
에이전트 모드: 자율적으로 작업을 계획하고 실행
파이핑 지원: Unix 철학에 따라 다른 도구와 연결 가능
직접 실행: 파일 편집, 명령 실행, Git 커밋 생성 가능
맥락 인식: 전체 코드베이스를 이해하고 작업

1.3 주요 사용 사례

사용 사례	설명	예시 명령
코드 생성	자연어 설명에서 코드 작성	"사용자 인증 API 엔드포인트 생성해줘"
버그 수정	오류 분석 및 자동 수정	"TypeError 오류 수정해줘"
리팩토링	코드 품질 개선	"이 함수를 TypeScript로 변환해줘"
테스트 작성	단위 테스트 자동 생성	"이 모듈에 대한 테스트 코드 작성해줘"
문서화	코드 주석 및 README 작성	"이 프로젝트의 README 작성해줘"

2. 설치 및 시작하기

2.1 설치 방법

Claude Code는 여러 가지 방법으로 설치할 수 있습니다:

macOS/Linux/WSL (권장)

# 공식 설치 스크립트
curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

# PowerShell에서 실행
irm https://claude.ai/install.ps1 | iex

Homebrew (macOS)

# Homebrew를 통한 설치
brew install --cask claude-code

NPM

# NPM을 통한 설치
npm install -g @anthropic-ai/claude-code

2.2 첫 번째 실행

# 프로젝트 디렉토리로 이동
cd your-project

# Claude Code 시작
claude

# 첫 실행 시 로그인 필요
/login

2.3 시스템 요구사항

운영체제: macOS 10.15+, Windows 10+, Linux (Ubuntu 20.04+)
Node.js: 18.0 이상 (NPM 설치 시)
메모리: 최소 4GB RAM 권장
인터넷: 안정적인 인터넷 연결 필요

3. 슬래시 명령어 완벽 가이드

3.1 기본 명령어

Claude Code는 다양한 슬래시 명령어를 제공합니다:

명령어	설명
`/help`	도움말 표시
`/config`	설정 인터페이스 열기
`/model`	AI 모델 선택 (Sonnet, Opus, Haiku)
`/clear`	대화 히스토리 초기화
`/compact`	대화 압축 (토큰 절약)
`/cost`	토큰 사용량 및 비용 통계
`/exit`	Claude Code 종료

3.2 고급 명령어

명령어	설명
`/agents`	서브에이전트 관리
`/mcp`	MCP 서버 연동 관리
`/memory`	CLAUDE.md 메모리 편집
`/permissions`	권한 관리
`/resume`	이전 대화 재개
`/hooks`	Hooks 설정
`/sandbox`	샌드박스 모드 활성화
`/doctor`	설치 상태 확인
`/bug`	버그 리포트 제출

3.3 사용자 정의 슬래시 명령어

자신만의 명령어를 만들 수 있습니다:

# 위치: .claude/commands/commit.md

---
argument-hint: [message]
description: 깃 커밋 메시지 생성
---

`git diff HEAD`를 보고 적절한 깃 커밋 메시지를 만들어주세요: $ARGUMENTS

이후 /commit "버그 수정" 형태로 사용할 수 있습니다.

4. 에이전트 모드와 서브에이전트

4.1 에이전트 모드란?

Claude Code의 에이전트 모드는 자율적으로 작업을 계획하고 실행하는 기능입니다:

┌─────────────────────────────────────────────────────────┐
│                   에이전트 모드 워크플로우                   │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   [작업 요청] → [분석/계획] → [실행] → [검증] → [완료]    │
│                     │         │         │              │
│                     ▼         ▼         ▼              │
│              코드베이스   파일 수정   테스트 실행         │
│               탐색      명령 실행   결과 확인           │
│                                                         │
└─────────────────────────────────────────────────────────┘

4.2 서브에이전트 (Sub-agents)

특화된 AI 어시스턴트를 정의하여 사용할 수 있습니다:

# 위치: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: 코드 리뷰 전문가. 코드 변경 후 사용
tools: Read, Grep, Glob, Bash
model: sonnet
---

당신은 시니어 코드 리뷰어입니다. 다음 원칙을 따라 코드를 리뷰해주세요:
1. 가독성과 유지보수성 확인
2. 보안 취약점 검토
3. 성능 최적화 제안
4. 테스트 커버리지 확인

4.3 내장 서브에이전트

Plan Agent: 계획 모드에서 코드베이스 연구
Explore Agent: 빠른 코드 탐색 (읽기 전용)
General Purpose Agent: 복잡한 다단계 작업 처리

5. MCP (Model Context Protocol) 서버 연동

5.1 MCP란?

MCP는 외부 도구와 데이터 소스를 Claude Code에 연결하는 개방형 프로토콜입니다. GitHub, Jira, Slack 등 다양한 서비스와 통합할 수 있습니다.

5.2 MCP 서버 설치

# HTTP 서버 추가
claude mcp add --transport http notion https://mcp.notion.com/mcp

# SSE 서버 추가
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Local Stdio 서버 추가
claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

5.3 MCP 관리 명령어

# 모든 서버 나열
claude mcp list

# 특정 서버 정보 확인
claude mcp get github

# 서버 제거
claude mcp remove github

# 세션 내에서 관리
/mcp

5.4 인기 있는 MCP 서버

서버	용도
GitHub	저장소, 이슈, PR 관리
Sentry	오류 모니터링 및 분석
Notion	문서 및 데이터베이스 접근
Jira	프로젝트 관리 및 이슈 추적
PostgreSQL	데이터베이스 쿼리 및 관리
Slack	팀 커뮤니케이션 통합
Google Drive	파일 저장 및 공유
Figma	디자인 자산 접근

6. Skills 기능

6.1 Skills란?

Skills는 Claude가 자동으로 발견하고 사용하는 재사용 가능한 역량입니다. 특정 작업을 수행하기 위한 지침, 템플릿, 스크립트를 포함할 수 있습니다.

6.2 Skill 구조

my-skill/
├── SKILL.md          # 필수: 스킬 정의
├── reference.md      # 선택: 참조 문서
├── examples.md       # 선택: 사용 예제
├── scripts/
│   └── helper.py     # 선택: 헬퍼 스크립트
└── templates/
    └── template.txt  # 선택: 템플릿 파일

6.3 SKILL.md 작성

---
name: pdf-processing
description: PDF 파일에서 텍스트 추출, 양식 채우기, PDF 병합. PDF 파일 작업 시 사용
allowed-tools: Read, Grep, Glob
---

# PDF 처리

## 지시사항

1. PyPDF 또는 pdfplumber 라이브러리 사용
2. 텍스트 추출 시 레이아웃 유지
3. 오류 처리 포함
4. 처리 결과 보고

6.4 Skills 저장 위치

프로젝트: .claude/skills/skill-name/
개인: ~/.claude/skills/skill-name/

7. Hooks 기능

7.1 Hooks란?

Hooks는 특정 이벤트에서 자동으로 실행되는 커스텀 셸 명령어입니다. 워크플로우 자동화에 매우 유용합니다.

7.2 Hook 이벤트 종류

이벤트	설명	사용 사례
`PreToolUse`	도구 실행 전	특정 작업 차단
`PostToolUse`	도구 실행 후	코드 포매팅 자동화
`PermissionRequest`	권한 요청 시	권한 로깅
`UserPromptSubmit`	프롬프트 제출 시	입력 검증
`Notification`	알림 전송 시	외부 알림 연동
`Stop`	응답 완료 시	완료 알림
`SessionStart`	세션 시작 시	환경 초기화
`SessionEnd`	세션 종료 시	정리 작업

7.3 Hooks 설정 예제

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$file_path\""
          }
        ]
      }
    ]
  }
}

7.4 실제 사용 사례

코드 포매팅: TypeScript/JavaScript 파일 저장 시 자동 포매팅
파일 보호: 프로덕션 파일 수정 차단
로깅: 모든 bash 명령 기록
린팅: 파일 수정 후 자동 린트 실행

8. IDE 통합

8.1 VS Code 확장 프로그램

Claude Code는 VS Code와 완벽하게 통합됩니다:

설치 방법

# VS Code 마켓플레이스에서 설치
1. Cmd+Shift+X (Mac) / Ctrl+Shift+X (Windows/Linux)
2. "Claude Code" 검색
3. Install 클릭

주요 단축키

단축키	기능
`Cmd/Ctrl+Esc`	에디터와 Claude 사이 포커스 전환
`Cmd/Ctrl+Shift+Esc`	새 탭에서 대화 열기
`Alt+K`	@-멘션 파일 참조 삽입

주요 기능

인라인 차이점 검토
@-멘션으로 파일 참조
계획 리뷰 인터페이스
여러 탭/창에서 대화

8.2 JetBrains IDE 통합

IntelliJ IDEA, PyCharm, WebStorm 등 JetBrains IDE를 지원합니다:

지원 IDE

IntelliJ IDEA
PyCharm
WebStorm
GoLand
PhpStorm
Android Studio

설치 방법

Settings → Plugins → Marketplace → "Claude Code" 검색 → Install

주요 기능

IDE 내 차이점 보기
선택 컨텍스트 자동 공유
IDE 진단 정보 공유
파일 참조 단축키: Cmd/Ctrl+Option/Alt+K

9. 설정 및 구성

9.1 설정 파일 위치

사용자 설정: ~/.claude/settings.json
프로젝트 설정: .claude/settings.json
로컬 설정: .claude/settings.local.json (Git 무시)

9.2 주요 설정 옵션

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)"
    ],
    "additionalDirectories": ["../docs/"],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "production",
    "CUSTOM_VAR": "value"
  },
  "model": "claude-sonnet-4-5-20250929",
  "outputStyle": "Explanatory",
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true
  },
  "attribution": {
    "commit": "Generated with Claude Code",
    "pr": "Generated with Claude Code"
  }
}

9.3 설정 우선순위

Enterprise (최고) - 조직 정책
Command Line - 세션 임시 설정
Local Project - 개인 프로젝트 설정
Project - 팀 공유 설정
User (최저) - 개인 기본 설정

10. 보안 및 권한 관리

10.1 3계층 권한 시스템

도구 유형	예시	승인 필요
읽기 전용	파일 읽기, Grep, Glob	아니오
Bash 명령	셸 명령 실행	예
파일 수정	파일 쓰기, 편집	예

10.2 권한 규칙 설정

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run test:*)",
      "Read(./src/**)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Bash(rm -rf:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

10.3 권한 모드

default: 각 도구 사용 시 권한 요청
acceptEdits: 파일 편집 자동 승인
plan: 분석만 가능 (수정 불가)
bypassPermissions: 모든 권한 자동 승인 (주의 필요!)

# 권한 모드 변경
claude --permission-mode plan
claude --permission-mode acceptEdits

10.4 보안 모범 사례

민감한 파일(.env, credentials.json 등)은 deny 목록에 추가
읽기 전용 Skills에는 allowed-tools: Read, Grep, Glob 제한
정기적으로 /permissions로 권한 검토
프로덕션 환경에서는 샌드박스 모드 활성화

11. CLI 플래그 및 옵션

11.1 기본 사용

# 대화형 모드
claude

# 한 번의 작업 실행
claude "사용자 인증 기능 구현해줘"

# 쿼리 후 종료
claude -p "이 프로젝트의 구조 설명해줘"

11.2 세션 관리

# 가장 최근 대화 계속
claude -c

# 특정 세션 재개
claude -r "session-name"

11.3 모델 및 권한

# 특정 모델 사용
claude --model opus
claude --model sonnet
claude --model haiku

# 권한 모드 설정
claude --permission-mode plan
claude --dangerously-skip-permissions

11.4 추가 설정

# 추가 디렉토리 접근
claude --add-dir ../docs

# 시스템 프롬프트 추가
claude --append-system-prompt "Always use TypeScript"

# 에이전트 설정
claude --agents '{"reviewer":{"description":"...","prompt":"..."}}'

12. 키보드 단축키

단축키	기능
`Ctrl+C`	입력/생성 취소
`Ctrl+D`	세션 종료
`Ctrl+L`	화면 지우기
`Ctrl+O`	상세 출력 토글
`Ctrl+R`	역순 히스토리 검색
`Esc` + `Esc`	변경 사항 되돌리기
`?`	단축키 도움말
`Up/Down`	명령 히스토리 이동

13. 실전 워크플로우 예시

13.1 새 기능 개발

claude
> 사용자 프로필 API 엔드포인트 생성해줘
> 데이터베이스 마이그레이션 작성해줘
> 테스트 코드 추가해줘
> 커밋 생성해줘

13.2 버그 수정

claude
> 오류: TypeError: Cannot read property 'name' of undefined at line 45
> 버그 분석하고 수정해줘
> 테스트 실행해서 확인해줘

13.3 코드 리팩토링

claude
/agents
> 코드 리뷰어 에이전트로 src/utils 폴더 검토해줘
> 권장 사항 적용해줘

14. 결론 및 권장사항

Claude Code는 개발자의 생산성을 혁신적으로 향상시키는 AI 코딩 어시스턴트입니다. 터미널 네이티브 환경에서 자율적으로 작업을 수행하고, MCP를 통해 다양한 외부 서비스와 통합할 수 있습니다.

핵심 활용 팁

Skills 활용: 반복적인 작업은 Skills로 자동화하세요
Hooks 설정: 코드 포매팅, 린팅 등을 자동화하세요
MCP 연동: GitHub, Jira 등 필요한 서비스를 연결하세요
보안 설정: 민감한 파일은 반드시 deny 목록에 추가하세요
IDE 통합: VS Code나 JetBrains IDE와 함께 사용하면 더욱 강력합니다

Claude Code를 통해 더 빠르고 효율적인 개발 경험을 시작해보세요!

English: Claude Code is an AI coding assistant that revolutionizes developer productivity. It operates autonomously in terminal-native environments and can integrate with various external services through MCP. Leverage Skills for automation, set up Hooks for code formatting, connect necessary services via MCP, and always add sensitive files to the deny list for security. Start your faster, more efficient development experience with Claude Code!

목록으로 돌아가기

Anthropic Claude Code 완벽 가이드: AI 코딩 어시스턴트의 모든 것

Complete Guide to Anthropic Claude Code: Everything About AI Coding Assistant

1. Claude Code란 무엇인가?

1.1 핵심 개념

1.2 주요 특징

1.3 주요 사용 사례

2. 설치 및 시작하기

2.1 설치 방법

macOS/Linux/WSL (권장)

Windows PowerShell

Homebrew (macOS)

NPM

2.2 첫 번째 실행

2.3 시스템 요구사항

3. 슬래시 명령어 완벽 가이드

3.1 기본 명령어

3.2 고급 명령어

3.3 사용자 정의 슬래시 명령어

4. 에이전트 모드와 서브에이전트

4.1 에이전트 모드란?

4.2 서브에이전트 (Sub-agents)

4.3 내장 서브에이전트

5. MCP (Model Context Protocol) 서버 연동

5.1 MCP란?

5.2 MCP 서버 설치

5.3 MCP 관리 명령어

5.4 인기 있는 MCP 서버

6. Skills 기능

6.1 Skills란?

6.2 Skill 구조

6.3 SKILL.md 작성

6.4 Skills 저장 위치

7. Hooks 기능

7.1 Hooks란?

7.2 Hook 이벤트 종류

7.3 Hooks 설정 예제

7.4 실제 사용 사례

8. IDE 통합

8.1 VS Code 확장 프로그램

설치 방법

주요 단축키

주요 기능

8.2 JetBrains IDE 통합

지원 IDE

설치 방법

주요 기능

9. 설정 및 구성

9.1 설정 파일 위치

9.2 주요 설정 옵션

9.3 설정 우선순위

10. 보안 및 권한 관리

10.1 3계층 권한 시스템

10.2 권한 규칙 설정

10.3 권한 모드

10.4 보안 모범 사례

11. CLI 플래그 및 옵션

11.1 기본 사용

11.2 세션 관리

11.3 모델 및 권한

11.4 추가 설정

12. 키보드 단축키

13. 실전 워크플로우 예시

13.1 새 기능 개발

13.2 버그 수정

13.3 코드 리팩토링

14. 결론 및 권장사항

핵심 활용 팁

이 글 공유하기