AI 배우기

Claude Code 완벽 입문 가이드: 설치부터 기초 명령어까지

bigempty 2026. 2. 9. 10:30

Claude Code 완벽 입문 가이드: 설치부터 기초 명령어까지

AI 코딩 어시스턴트 Claude Code를 터미널에서 바로 사용하는 방법을 처음부터 끝까지 안내합니다.

Claude Code란?

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 어시스턴트입니다. 단순한 코드 자동완성 도구가 아니라, 프로젝트의 코드베이스 전체를 이해하고 파일 편집, 버그 수정, 테스트 실행, Git 워크플로우 관리까지 자연어 명령으로 처리하는 에이전트형 도구입니다.

할 수 있는 일들:

코드 작성, 리팩터링, 버그 수정
코드베이스 구조 분석 및 설명
테스트 코드 생성 및 실행
Git 커밋, PR 생성, 머지 충돌 해결
셸 명령어 실행 및 프로젝트 빌드

1. 시스템 요구사항

항목 요구사항

운영체제	macOS 10.15+, Ubuntu 20.04+/Debian 10+, Windows 10+ (WSL 또는 Git Bash)
하드웨어	RAM 4GB 이상
네트워크	인터넷 연결 필수 (인증 및 AI 처리)
셸	Bash, Zsh, Fish 권장
Node.js	NPM 설치 시에만 18+ 필요 (네이티브 설치는 불필요)

2. 설치 방법

방법 1: 네이티브 설치 (권장 ⭐)

Node.js 없이도 설치 가능한 공식 권장 방법입니다.

macOS / Linux / WSL:

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

macOS (Homebrew):

brew install --cask claude-code

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: NPM 설치 (레거시)

NPM 설치는 현재 deprecated 상태입니다. 가능하면 네이티브 설치를 사용하세요.

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

⚠️ sudo npm install -g는 절대 사용하지 마세요. 권한 문제와 보안 위험이 발생합니다.

설치 확인

claude --version

버전 번호가 정상 출력되면 설치 완료입니다. 문제가 발생하면 다음 명령어로 진단해보세요:

claude doctor

3. 인증 설정

설치 후 프로젝트 디렉터리에서 claude를 실행하면 인증 과정이 시작됩니다.

cd your-project
claude

세 가지 인증 방식 중 선택할 수 있습니다:

방식 설명

Claude Console (API)	console.anthropic.com에서 결제 설정 후 OAuth로 연결. 사용량 기반 과금.
Claude Pro/Max 구독	claude.ai의 Pro 또는 Max 구독으로 통합 인증. 고정 월 요금.
기업용 플랫폼	Amazon Bedrock, Google Vertex AI, Microsoft Foundry 연동

환경 변수로 API 키를 직접 설정할 수도 있습니다:

export ANTHROPIC_API_KEY="sk-ant-..."

이 줄을 ~/.bashrc 또는 ~/.zshrc에 추가하면 영구 적용됩니다.

4. 기초 환경 셋팅

4.1 CLAUDE.md 생성 — 프로젝트 컨텍스트 설정

/init 명령으로 프로젝트 루트에 CLAUDE.md 파일을 생성합니다. 이 파일은 Claude Code가 프로젝트를 이해하는 데 사용하는 "프로젝트 메모리"입니다.

/init

CLAUDE.md에는 다음과 같은 내용을 포함하면 좋습니다:

# 프로젝트 컨텍스트

## 기술 스택
- Frontend: React + TypeScript
- Backend: Node.js + Express
- DB: PostgreSQL

## 코딩 컨벤션
- 새 코드는 TypeScript로 작성
- 함수형 컴포넌트 + Hooks 사용
- 테스트는 Jest로 작성

## 디렉터리 구조
- src/components/ — UI 컴포넌트
- src/utils/ — 유틸리티
- src/api/ — API 라우트

4.2 설정 파일 (settings.json)

Claude Code의 전역 설정은 ~/.claude/settings.json에서 관리합니다:

{
  "permissions": {
    "allowedTools": ["Read", "Write", "Bash(git *)", "Bash(npm *)"],
    "deny": ["Read(.env*)", "Bash(rm -rf *)", "Bash(sudo *)"]
  }
}

이렇게 설정하면 Git과 npm 명령은 자동 허용하되, 환경 변수 파일 읽기나 위험한 명령은 차단됩니다.

4.3 모델 선택

Claude Code에서 사용할 모델을 변경할 수 있습니다:

/model

모델 특징

Sonnet 4.5	성능과 속도의 균형. 일반 작업에 추천
Opus 4.5	최고 성능. 복잡한 멀티스텝 작업에 적합
Haiku 4.5	빠른 응답. 간단한 작업에 적합, 토큰 절약

4.4 알림 설정

긴 작업 완료 시 터미널 벨로 알림 받기:

claude config set --global preferredNotifChannel terminal_bell

5. 기본 사용법

5.1 세션 시작과 관리

# 새 세션 시작
claude

# 특정 질문으로 바로 시작
claude "이 프로젝트의 구조를 설명해줘"

# 마지막 세션 이어하기
claude -c

# 이전 세션 목록에서 선택하여 재개
claude --resume

5.2 헤드리스 모드 (스크립트용)

대화형 인터페이스 없이 결과만 출력하는 -p 플래그:

claude -p "src/utils.ts 파일의 함수 목록을 알려줘"

파이프와 조합하면 강력합니다:

cat error.log | claude -p "이 에러 로그를 분석해줘"
git diff | claude -p "이 변경사항을 요약해줘"

5.3 파일 참조 (@)

@ 기호로 특정 파일이나 디렉터리를 지정할 수 있습니다:

@src/components/Button.tsx 이 컴포넌트의 접근성 문제를 검토해줘

5.4 셸 명령 직접 실행 (!)

!를 앞에 붙이면 셸 명령을 바로 실행합니다:

!npm test
!git status

6. 핵심 슬래시 명령어 정리

세션 관리

명령어 설명

/help	사용 가능한 모든 명령어 표시
/clear	대화 기록 초기화 (새 컨텍스트로 시작)
/compact	대화를 요약하여 컨텍스트 창 확보
/status	버전 정보 및 연결 상태 확인
/exit	세션 종료 (Ctrl+D도 가능)

프로젝트 설정

명령어 설명

/init	CLAUDE.md 파일 생성 (프로젝트 메모리)
/add-dir	추가 작업 디렉터리 등록 (모노레포 등)
/model	사용 모델 변경

개발 도구

명령어 설명

/review	현재 변경사항 코드 리뷰 요청
/doctor	설치 상태 및 설정 진단
/todos	Claude가 추적 중인 TODO 항목 목록
/rewind	이전 체크포인트로 코드 상태 되돌리기
/context	현재 컨텍스트 사용량 시각화
/bug	Anthropic에 버그 리포트 전송

7. 실전 활용 예시

코드 이해하기

이 프로젝트의 전체 아키텍처를 설명해줘

@src/auth/middleware.ts 이 미들웨어가 어떻게 동작하는지 분석해줘

코드 작성하기

JWT 토큰을 사용하는 사용자 인증 시스템을 만들어줘. 로그인, 로그아웃, 보호된 라우트 미들웨어 포함.

버그 수정

npm test를 실행하고, 실패하는 테스트를 분석해서 수정해줘

Git 워크플로우

현재 변경사항을 리뷰하고 적절한 커밋 메시지로 커밋해줘

feature-login 브랜치를 새로 만들어서 체크아웃해줘

리팩터링

이 콜백 기반 코드를 async/await로 변환해줘

8. 커스텀 슬래시 명령어 만들기

자주 쓰는 워크플로우를 슬래시 명령으로 저장할 수 있습니다.

프로젝트 전용 명령어

.claude/commands/ 디렉터리에 마크다운 파일을 만듭니다:

mkdir -p .claude/commands

예시 — .claude/commands/commit.md:

현재 변경사항을 분석하고 다음 단계를 수행해줘:
1. git diff로 변경사항 확인
2. Conventional Commits 형식에 맞는 커밋 메시지 작성
3. 커밋 실행

이제 Claude Code 세션에서 /project:commit으로 실행할 수 있습니다.

전역 명령어 (모든 프로젝트 공용)

~/.claude/commands/ 디렉터리에 저장하면 모든 프로젝트에서 사용 가능합니다.

인자 전달

명령어 파일에서 $ARGUMENTS를 사용하면 동적 입력을 받을 수 있습니다:

<!-- .claude/commands/review-file.md -->
다음 파일을 보안 관점에서 리뷰해줘: $ARGUMENTS
SQL 인젝션, XSS, 인증 취약점을 중점적으로 확인.

사용: /project:review-file src/api/users.ts

9. 유용한 팁

컨텍스트 관리가 핵심입니다. 대화가 길어지면 /compact로 요약하거나 /clear로 초기화하세요. 컨텍스트 창이 가득 차면 응답 품질이 떨어집니다.

Git을 적극 활용하세요. Claude가 변경을 가할 때마다 커밋하도록 요청하면, 잘못된 변경을 쉽게 되돌릴 수 있습니다.

이미지를 활용하세요. macOS에서는 Shift+Command+Control+4로 스크린샷을 찍고 Control+V로 붙여넣을 수 있습니다. UI 목업이나 에러 화면을 보여주면 더 정확한 도움을 받습니다.

Plan 모드를 활용하세요. Shift+Tab으로 Plan 모드에 진입하면 Claude가 바로 코드를 작성하지 않고, 먼저 해결 방법을 계획합니다.

10. 자동 업데이트

네이티브 설치 시 Claude Code는 자동으로 최신 버전을 유지합니다. 수동 업데이트가 필요하면:

claude update

Homebrew 설치의 경우:

brew upgrade claude-code

Windows(winget) 설치의 경우:

winget upgrade Anthropic.ClaudeCode

자동 업데이트를 비활성화하려면:

export DISABLE_AUTOUPDATER=1

마무리

Claude Code는 단순한 코드 생성기가 아니라, 터미널에서 함께 일하는 AI 페어 프로그래머입니다. 설치 후 프로젝트 디렉터리에서 claude를 실행하고, /init으로 프로젝트 컨텍스트를 설정하는 것부터 시작해보세요. 기본 명령어에 익숙해지면 커스텀 슬래시 명령어로 자신만의 워크플로우를 만들어 생산성을 크게 높일 수 있습니다.

공식 문서: code.claude.com/docs