claudekit / guides / getting-started
[ Guide · Beginner · 12분 ]

Claude Code 처음 시작하기

published · updated

Claude Code를 처음 설치하는 사용자를 위한 입문 가이드. 설치 방법, 구독 옵션, 처음 익혀야 할 명령어와 사용 가능한 환경을 한 번에 정리합니다.

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는 실행 중인 작업을 중단합니다. 실행 중인 작업이 없으면 첫 번째 누름은 입력을 지우고, 두 번째 누름에 종료합니다.

전체 목록은 CLI 참조와 명령 참조를 참고하세요.

초보자 팁

  • 구체적으로 요청하기 — “버그 수정”보다 “잘못된 자격 증명 입력 후 빈 화면이 나오는 로그인 버그 수정”
  • 단계별 지침 — 복잡한 작업은 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 제대로 쓰기 가이드를 참고하세요.

다음 단계

§ 16

자주 묻는 질문

자주 묻는 질문
§ 16.1
Claude Code는 무엇인가요?
Anthropic의 AI 기반 코딩 도구로, 터미널, 웹, 데스크톱 앱, VS Code, JetBrains, Slack, CI/CD 등 여러 인터페이스에서 사용할 수 있습니다. 자연어로 코드를 읽고 수정, 실행, 리뷰까지 자율적으로 처리합니다.
§ 16.2
사용하려면 무엇이 필요한가요?
터미널 또는 명령 프롬프트, 작업할 코드 프로젝트, 그리고 Claude 구독(Pro, Max, Team, Enterprise) 또는 Claude Console 계정 또는 지원되는 클라우드 제공자(Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry) 액세스가 필요합니다. 무료 claude.ai 플랜에는 Claude Code가 포함되지 않습니다.
§ 16.3
어떻게 설치하나요?
공식 문서가 권장하는 Native Install이 가장 간단합니다. macOS/Linux/WSL은 `curl -fsSL https://claude.ai/install.sh | bash`, Windows PowerShell은 `irm https://claude.ai/install.ps1 | iex`로 설치하면 자동 업데이트도 함께 활성화됩니다. Homebrew(`brew install --cask claude-code`), WinGet(`winget install Anthropic.ClaudeCode`), npm으로도 설치할 수 있지만 Homebrew와 WinGet은 기본적으로 자동 업데이트되지 않습니다.
§ 16.4
처음 어떤 명령어부터 익히면 되나요?
`claude`(대화형 모드), `claude -p "query"`(일회성 쿼리), `claude -c`(가장 최근 대화 계속), `claude -r`(이전 대화 재개), `/help`, `/clear`를 먼저 알아두면 됩니다. 사용 가능한 명령과 스킬은 `/`를 입력하면 목록으로 볼 수 있습니다.
§ 16.5
터미널 외 다른 환경에서도 쓸 수 있나요?
네. 웹(claude.ai/code), 데스크톱 앱, VS Code, JetBrains IDE, Slack, GitHub Actions, GitLab CI/CD에서 모두 사용할 수 있습니다.