Claude Code란?
Anthropic의 AI 기반 코딩 도구입니다. 터미널에서 자연어로 다음을 지시할 수 있습니다.
- 멀티 파일 코드 작성, 수정
- 셸 명령 실행과 결과 분석
- 테스트 작성, 실행
- Git 커밋과 PR 작성
- 디버깅, 리팩터링, 코드 리뷰
본 가이드는 터미널 CLI 기준이지만, Claude Code는 웹, 데스크톱 앱, VS Code와 JetBrains 확장, Slack, GitHub Actions와 GitLab CI/CD에서도 동일하게 사용할 수 있습니다.
시작하기 전에
다음이 필요합니다.
- 열려 있는 터미널 또는 명령 프롬프트
- 작업할 코드 프로젝트
- 다음 중 하나의 액세스:
- Claude 구독 (Pro, Max, Team 또는 Enterprise) — 권장
- Claude Console 계정 (선불 크레딧 기반 API 액세스)
- 지원되는 클라우드 제공자 (Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry)
무료 claude.ai 플랜에는 Claude Code 액세스가 포함되지 않습니다.
시스템 요구 사항
- 운영체제: macOS 13.0 이상, Windows 10 1809 이상 또는 Windows Server 2019 이상, Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상
- 하드웨어: RAM 4GB 이상, x64 또는 ARM64 프로세서
- 네트워크: 인터넷 연결 필요
- 셸: Bash, Zsh, PowerShell 또는 CMD
최신 요구 사항은 공식 설정 문서에서 확인할 수 있습니다.
단계 1 — 설치
공식 문서가 권장하는 방법은 Native Install입니다. 백그라운드에서 자동 업데이트가 적용됩니다.
공식 빠른 시작 문서: code.claude.com/docs/ko/quickstart — 설치 방법별 최신 명령과 OS별 차이는 항상 공식 문서를 우선 확인하세요.
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
네이티브 Windows에서는 Git for Windows 설치를 권장합니다. 설치되어 있으면 Claude Code가 Bash 도구를 사용하고, 없으면 PowerShell을 셸 도구로 사용합니다. WSL 환경에는 필요하지 않습니다.
Homebrew (macOS / Linux)
brew install --cask claude-code
claude-code는 안정 채널, claude-code@latest는 최신 채널입니다. Homebrew 설치는 기본적으로 자동 업데이트되지 않으므로 brew upgrade claude-code(또는 claude-code@latest)를 주기적으로 실행해야 합니다.
WinGet (Windows)
winget install Anthropic.ClaudeCode
WinGet도 기본적으로 자동 업데이트되지 않으므로 winget upgrade Anthropic.ClaudeCode로 주기적으로 업데이트해야 합니다. Homebrew나 WinGet에서 환경변수 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE를 1로 설정하면, 새 버전이 나왔을 때 Claude Code가 백그라운드에서 업그레이드 명령을 실행하고 재시작을 안내합니다.
npm
npm install -g @anthropic-ai/claude-code
npm 패키지는 Node.js 22 이상이 필요하며, 독립 설치 프로그램과 같은 네이티브 바이너리를 설치합니다. sudo로 설치하지 않습니다. 업그레이드는 npm install -g @anthropic-ai/claude-code@latest로 합니다.
Linux에서는 apt, dnf, apk 패키지 매니저로도 설치할 수 있습니다.
설치 확인
설치가 끝나면 새 터미널 창을 열고 다음을 실행합니다. 버전 번호가 출력되면 정상입니다.
claude --version
Native Install이 자동 업데이트되어 가장 간편합니다. Homebrew, WinGet은 명시적 업데이트가 필요하니 환경에 맞게 선택하세요.
단계 2 — 로그인
claude로 대화형 세션을 시작하면 처음에는 자동으로 로그인 프롬프트가 표시됩니다.
claude
세션 도중에는 /login 명령으로 다시 로그인하거나 계정을 바꿀 수 있습니다.
/login
지원되는 계정 유형:
- Claude Pro / Max / Team / Enterprise — 권장
- Claude Console — 선불 크레딧 기반 API 액세스. 첫 로그인 시 비용 추적용 “Claude Code” 워크스페이스가 자동 생성됨
- Amazon Bedrock / Google Cloud’s Agent Platform / Microsoft Foundry — 엔터프라이즈 클라우드 제공자
- Claude apps gateway — 조직이 자체 호스팅 게이트웨이를 운영하는 경우. 관리자가 게이트웨이 URL을 미리 설정해 두면
/login이 Cloud gateway 화면으로 바로 열리고 회사 SSO로 로그인합니다
자격 증명은 한 번 로그인하면 시스템에 저장되어 다시 로그인할 필요가 없습니다.
단계 3 — 첫 세션 시작
프로젝트 디렉토리로 이동해 claude를 실행합니다.
cd /path/to/your/project
claude
Claude Code 프롬프트 위에 버전, 현재 모델, 작업 디렉토리가 표시됩니다. /help로 사용 가능한 명령을, /resume으로 이전 대화 이어가기를 확인할 수 있습니다.
단계 4 — 첫 질문
코드베이스를 이해하는 것부터 시작합니다.
이 프로젝트는 무엇을 하나요?
이 프로젝트는 어떤 기술을 사용하나요?
주요 진입점은 어디인가요?
Claude는 필요한 파일을 자동으로 읽으므로 컨텍스트를 수동으로 추가할 필요가 없습니다.
단계 5 — 첫 코드 변경
주 파일에 hello world 함수 추가
Claude Code는 적절한 파일을 찾아 변경 사항을 보여줍니다. 변경 전에 확인을 요청하면 Yes를 선택해 승인합니다.
Claude가 묻지 않고 실행할 수 있는 작업의 범위는 세션의 권한 모드가 정합니다. Shift+Tab을 누르면 언제든 권한 모드를 전환할 수 있습니다.
단계 6 — Git 사용
어떤 파일을 변경했나요?
설명적인 메시지로 변경 사항 커밋
feature/quickstart라는 새 브랜치 생성
병합 충돌을 해결하는 데 도움을 주세요
단계 7 — 버그 수정과 기능 추가
자연어로 원하는 것을 설명하면, Claude가 관련 코드를 찾고 컨텍스트를 이해해 솔루션을 구현하고, 사용 가능한 경우 테스트를 실행합니다.
사용자 등록 양식에 입력 유효성 검사 추가
사용자가 빈 양식을 제출할 수 있는 버그가 있습니다 — 수정해주세요
단계 8 — 다른 워크플로
인증 모듈을 콜백 대신 async/await를 사용하도록 리팩터링
계산기 함수에 대한 단위 테스트 작성
설치 지침으로 README 업데이트
내 변경 사항을 검토하고 개선 사항을 제안해주세요
필수 명령
터미널에서 실행하는 명령:
| 명령 | 기능 |
|---|---|
claude | 대화형 모드 시작 |
claude "task" | 첫 프롬프트를 넣어 대화형 모드 시작 |
claude -p "query" | 일회성 쿼리 실행 후 종료 |
claude -c | 현재 디렉토리에서 가장 최근 대화 계속 |
claude -r | 이전 대화 재개 |
Claude Code 세션 안에서 실행하는 명령:
| 명령 | 기능 |
|---|---|
/help | 사용 가능한 명령 표시 |
/clear | 대화 기록 지우기 |
/resume | 이전 대화 이어가기 |
/exit 또는 Ctrl+D 두 번 | Claude Code 종료 |
Ctrl+C는 실행 중인 작업을 중단합니다. 실행 중인 작업이 없으면 첫 번째 누름은 입력을 지우고, 두 번째 누름에 종료합니다.
초보자 팁
- 구체적으로 요청하기 — “버그 수정”보다 “잘못된 자격 증명 입력 후 빈 화면이 나오는 로그인 버그 수정”
- 단계별 지침 — 복잡한 작업은 1, 2, 3단계로 나눠 전달
- Claude가 먼저 탐색하게 — 변경 전에 “데이터베이스 스키마 분석” 같은 이해 단계를 먼저 요청
- 단축키 활용 —
/로 사용 가능한 명령과 스킬 보기, Tab으로 명령 완성, ↑로 명령 기록,Shift+Tab으로 권한 모드 전환, 빈 입력에서?로 단축키 도움말
CLAUDE.md로 컨텍스트 제공
프로젝트 루트의 CLAUDE.md 파일은 모든 세션에서 자동으로 로드됩니다. 권장 내용:
- 프로젝트 개요와 기술 스택
- 디렉토리 구조 요약
- 주요 명령어 (build, dev, test 등)
- 코드 컨벤션과 금지 사항
자세한 작성법은 CLAUDE.md 잘 쓰는 법 가이드를 참고하세요.
Plan mode
복잡한 작업은 Plan mode에서 시작하면 Claude가 코드 변경 전에 계획을 먼저 제시합니다. Plan mode는 권한 모드 중 하나이므로 Shift+Tab으로 권한 모드를 순환해 진입하고 해제합니다. 검토 후 승인하면 실행이 시작됩니다. 자세한 사용법은 Plan mode 제대로 쓰기 가이드를 참고하세요.
다음 단계
- ccstatusline — 토큰, 모델, Git 브랜치를 상태바에 실시간 표시
- Superpowers — 브레인스토밍, TDD, 체계적 디버깅 워크플로 자동화
- 나의 첫 번째 Plugin 설치하기 — 마켓플레이스 설치 흐름 익히기
- Skill vs Plugin vs MCP 차이점 — 확장 타입 이해
- 공식 문서 — 빠른 시작 — 본 가이드의 출처