Claude Code 퀵스타트

Claude Code 퀵스타트

몇 분이면 AI 기반 코딩 어시스턴트를 쓸 수 있습니다. 설치, 로그인, 첫 세션 시작부터 첫 코드 변경과 git 연동까지, 일상적인 개발 태스크에서 Claude Code를 어떻게 쓰는지 익힐 수 있습니다.

출처: 공식문서

본문

시작 전 준비

이 가이드는 터미널 CLI를 다룹니다. Claude Code는 웹, 데스크톱 앱, VS Code, JetBrains IDE, Slack, CI/CD(GitHub Actions, GitLab)에서도 사용할 수 있습니다.

1단계: Claude Code 설치

다음 방법 중 하나로 설치합니다.

네이티브 설치(권장)

  • 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
    The token '&&' is not a valid statement separator가 보이면 PowerShell이 아니라 CMD입니다. 'irm' is not recognized as an internal or external command가 보이면 CMD가 아니라 PowerShell입니다. 프롬프트가 PS C:\로 시작하면 PowerShell, C:\로 시작하면 CMD입니다. 설치가 syntax error near unexpected token '<', 403, 또는 다른 curl 오류로 실패하면 Troubleshoot installation을 참고하세요. 네이티브 Windows에서는 Claude Code가 Bash 도구를 쓰도록 Git for Windows를 권장합니다. 없으면 PowerShell을 셸 도구로 사용합니다. WSL은 Git for Windows가 필요 없습니다. 네이티브 설치는 백그라운드 자동 업데이트됩니다.

Homebrew

brew install --cask claude-code

claude-code는 안정 채널(보통 일주일가량 뒤처짐), claude-code@latest는 최신 채널을 따릅니다. Homebrew는 자동 업데이트되지 않으니 brew upgrade claude-code 또는 brew upgrade claude-code@latest로 업데이트하세요.

WinGet

winget install Anthropic.ClaudeCode

자동 업데이트되지 않으니 주기적으로 winget upgrade Anthropic.ClaudeCode를 실행하세요.

Debian/Fedora/RHEL/Alpine에서는 apt, dnf, apk로도 설치할 수 있습니다. 설치가 잘 됐는지 확인하려면:

claude --version

이 명령은 버전 번호 뒤에 (Claude Code)를 출력합니다.

2단계: 계정 로그인

Claude Code는 계정이 필요합니다. claude 명령으로 인터랙티브 세션을 시작하면 첫 사용 시 로그인을 요청합니다:

claude

Claude 구독 또는 Console 계정은 브라우저에서 인증을 완료하라는 안내를 따릅니다. ANTHROPIC_API_KEY 환경변수를 설정했다면 로그인 프롬프트를 건너뛰고 키 승인을 요청합니다. 나중에 계정을 바꾸거나 재인증하려면 세션 안에서 /login을 입력합니다:

/login

다음 계정 유형으로 로그인할 수 있습니다: Claude Pro, Max, Team, Enterprise (권장), Claude Console (선불 크레딧 API — 첫 로그인 시 중앙 비용 추적용 "Claude Code" 워크스페이스가 자동 생성됨), Amazon Bedrock·Google Cloud Agent Platform·Microsoft Foundry (엔터프라이즈 클라우드), 조직이 운영한다면 셀프호스팅 Claude apps gateway.

로그인하면 자격 증명이 저장되어 다시 로그인할 필요가 없습니다. 자세한 내용은 Credential Management 참고.

3단계: 첫 세션 시작

프로젝트 디렉터리에서 터미널을 열고:

cd /path/to/your/project
claude

/path/to/your/project를 작업할 프로젝트 경로로 바꾸세요. Claude Code 프롬프트 위에 버전·현재 모델·작업 디렉터리가 표시됩니다. /help로 명령을, /resume로 이전 대화를 이어갑니다.

4단계: 첫 질문

코드베이스 이해부터 시작해 보세요:

what does this project do?

더 구체적으로도 물을 수 있습니다:

what technologies does this project use?

where is the main entry point?

explain the folder structure

Claude 자신의 기능에 대해서도 물어볼 수 있습니다: what can Claude Code do?, how do I create custom skills in Claude Code?, can Claude Code work with Docker?

Claude Code는 필요에 따라 프로젝트 파일을 읽으므로 수동으로 컨텍스트를 추가할 필요가 없습니다.

5단계: 첫 코드 변경

간단한 태스크를 시도합니다:

add a hello world function to the main file

Claude Code가 알맞은 파일을 찾아 변경 사항을 보여줍니다. 변경 전에 물어보면 Yes를 선택해 승인합니다. Auto mode는 Pro·Max·Team 요금제 인터랙티브 터미널 세션의 기본 시작 권한 모드로, 분류기가 사용자 대신 작업을 검토해 대부분의 파일 편집·명령 실행을 묻지 않고 진행합니다. 다른 요금제는 Manual mode가 기본입니다. 설정이나 조직이 다른 시작 권한 모드를 정할 수도 있으며, 언제든 Shift+Tab으로 현재 세션의 권한 모드를 바꿀 수 있습니다.

6단계: git과 함께 사용

git 연산을 대화식으로:

what files have I changed?

commit my changes with a descriptive message

더 복잡한 git 연산도 프롬프트할 수 있습니다: create a new branch called feature/quickstart, show me the last 5 commits, help me resolve merge conflicts

7단계: 버그 수정·기능 추가

자연어로 원하는 것을 설명합니다:

add input validation to the user registration form

기존 이슈 수정:

there's a bug where users can submit empty forms - fix it

Claude Code는 관련 코드를 찾고, 컨텍스트를 이해하고, 해결책을 구현하고, 가능하면 테스트를 실행합니다.

8단계: 다른 일반 워크플로 테스트

리팩터링: refactor the authentication module to use async/await instead of callbacks 테스트 작성: write unit tests for the calculator functions 문서 갱신: update the README with installation instructions 코드 리뷰: review my changes and suggest improvements

도움이 되는 동료에게 말하듯이 Claude에게 이야기하세요. 달성하고 싶은 것을 설명하면 거기까지 도와줍니다.

필수 명령

셸 명령은 터미널에서 Claude Code를 시작·재개하고, 세션 명령은 시작 후 안에서 실행합니다.

셸 명령

명령 역할 예시
claude 인터랙티브 모드 시작 claude
claude "task" 초기 프롬프트와 함께 인터랙티브 모드 시작 claude "fix the build error"
claude -p "query" 일회성 쿼리 실행 후 종료 claude -p "explain this function"
claude -c 현재 디렉터리의 최근 대화 이어가기 claude -c
claude -r 이전 대화 재개 claude -r

세션 명령

명령 역할
/clear 대화 기록 지우기
/help 사용 가능한 명령 표시
/exit 또는 Ctrl+D 두 번 Claude Code 종료

전체 셸 명령 목록은 CLI reference, 세션 명령 목록은 commands reference 참고.

초급자를 위한 팁

  • 요청을 구체적으로 — "fix the bug" 대신 "fix the login bug where users see a blank screen after entering wrong credentials"처럼.
  • 단계별 지침 사용 — 복잡한 태스크를 단계로 나눕니다: 
    1. create a new database table for user profiles
2. create an API endpoint to get and update user profiles
3. build a webpage that allows users to see and edit their information
  • 탐색을 먼저 시키기 — 변경 전에 코드를 이해하게 합니다: analyze the database schema
  • 단축키로 시간 절약 — /로 명령·스킬 확인, Tab으로 명령 완성, ↑로 명령 기록, Shift+Tab으로 권한 모드 순환.

다음 단계

기초를 익혔으니 더 고급 기능을 탐색합니다: How Claude Code works (에이전틱 루프·내장 도구 이해), Best practices (효과적인 프롬프팅·프로젝트 설정), Common workflows, Extend Claude Code (CLAUDE.md·스킬·훅·MCP 커스터마이즈).

도움 받기

  • Claude Code 안에서: /help 또는 "how do I..."
  • 문서: 이 가이드의 다른 문서 둘러보기
  • 커뮤니티: Discord에서 팁·지원

더 알아보기