별첨 B

Claude Code CLI 사용법

이 별첨에서는 Claude Code CLI(명령줄 인터페이스)의 설치, 기본 사용법, 주요 명령어를 설명합니다. 본 핸드북의 메인 도구는 Claude Desktop App이지만, CLI를 사용하면 더 강력한 자동화가 가능합니다.

이 별첨에서 다루는 것

CLI vs Desktop App 비교
Claude Code CLI 설치
기본 사용법 (터미널 대화)
주요 명령어
프로젝트 모드
실용 팁

1. CLI vs Desktop App

Claude를 사용하는 방법에는 두 가지가 있습니다. 하나는 Claude Desktop App(데스크톱 애플리케이션)이고, 다른 하나는 Claude Code CLI(명령줄 인터페이스)입니다. 두 방식은 목적과 사용 방법이 다르며, 각각 장단점이 있습니다.

항목	Claude Desktop App	Claude Code CLI
인터페이스	GUI (그래픽)	터미널 (명령줄)
난이도	쉬움	중급
자동화	제한적	강력 (스크립트 통합)
파일 접근	프로젝트 폴더	전체 시스템
에이전트 지원	Claude만	Claude + 서드파티 백엔드
추천 대상	초보자	중급 이상

Desktop App은 '자동차 자동모드'이고, CLI는 '수동 모드'입니다. CLI는 더 많은 제어가 가능하지만 학습이 필요합니다. 자동모드로 운전을 배우다가, 익숙해지면 수동 모드로 전환하는 것과 같습니다.

본 핸드북의 모든 실습은 Claude Desktop App으로 수행할 수 있습니다. CLI는 선택적입니다. CLI가 필요한 경우, 이 별첨에서 설치와 사용법을 안내해드리겠습니다.

2. Claude Code CLI 설치

Claude Code CLI를 설치하려면 몇 가지 사전 요구사항이 있습니다. 준비가 되면 순서대로 진행해보세요.

사전 요구사항

Node.js 18 이상 — Claude Code CLI는 Node.js 환경에서 동작합니다
Claude Pro 또는 Max 구독 — Anthropic Claude 유료 구독 계정이 필요합니다
터미널 앱 — macOS Terminal, Windows PowerShell, Linux Bash 등

1단계: Node.js 설치 확인

터미널을 열고 다음 명령어를 입력하여 Node.js가 설치되어 있는지 확인합니다:

node --version

예상 결과: v18.x.x 또는 그 이상의 버전 번호가 출력됩니다. 버전이 18 미만이거나 명령어를 찾을 수 없다는 메시지가 나오면 nodejs.org에서 최신 LTS 버전을 설치하세요.

2단계: Claude Code CLI 설치

Node.js가 확인되면, npm을 사용하여 Claude Code CLI를 전역 설치합니다:

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

예상 결과: 패키지가 다운로드되고 설치가 완료됩니다. 몇 분 정도 걸릴 수 있습니다.

3단계: 설치 확인

설치가 완료되면 버전을 확인하여 정상적으로 설치되었는지 검증합니다:

claude --version

예상 결과: Claude Code의 버전 번호가 출력됩니다 (예: 1.0.x). 에러가 나면 2단계를 다시 시도하세요.

4단계: Claude 계정 인증

터미널에서 claude를 처음 실행하면 Anthropic 계정으로 로그인하라는 메시지가 나옵니다:

claude

브라우저가 열리며 Anthropic 로그인 페이지로 이동합니다. Claude Pro 또는 Max 구독 계정으로 로그인하세요. 인증이 완료되면 터미널에서 Claude Code를 사용할 수 있습니다.

운영체제별 참고사항

Windows:

PowerShell을 관리자 권한으로 실행하세요
Node.js 설치 시 "Add to PATH" 옵션을 반드시 체크하세요
설치 후 새 PowerShell 창을 열어야 PATH가 적용됩니다

macOS:

기본 Terminal 앱 또는 iTerm2를 사용하세요
Homebrew가 설치되어 있다면 brew install node로 Node.js를 설치할 수도 있습니다

Linux (Ubuntu/Debian):

sudo apt install nodejs npm 또는 nvm(Node Version Manager)을 사용하세요
전역 설치 시 sudo가 필요할 수 있습니다: sudo npm install -g @anthropic-ai/claude-code

Windows에서는 PowerShell을 관리자 권한으로 실행하여 설치하세요. 일반 사용자 권한으로는 전역 패키지 설치가 실패할 수 있습니다. PowerShell 아이콘을 우클릭하고 "관리자 권한으로 실행"을 선택하세요.

Claude Pro 또는 Max 구독이 없다면 CLI를 사용할 수 없습니다. 무료 Claude 계정은 Claude.ai 웹 인터페이스에서만 사용할 수 있습니다. 구독은 claude.ai에서 신청할 수 있습니다.

3. 기본 사용법

Claude Code CLI의 기본 사용법을 알아보겠습니다. Desktop App과 달리 터미널에서 텍스트로 대화하는 방식입니다.

Claude Code 시작하기

터미널을 열고 다음 명령어를 입력합니다:

claude

Claude Code가 시작되면 프롬프트(> 기호)가 표시되며, 여기에 질문이나 지시를 입력합니다.

대화 방법

프롬프트에 자연어로 질문을 입력하면 됩니다. Desktop App과 동일하게 한국어, 영어 모두 사용 가능합니다.

현재 폴더에 있는 파일 목록을 보여줘

Claude Code는 파일 시스템에 접근할 수 있으므로, "현재 폴더의 파일 읽어줘", "이 파일에서 버그 찾아줘" 같은 요청도 처리할 수 있습니다.

파일 읽기/쓰기 예시

파일 읽기:

README.md 파일의 내용을 읽고 요약해줘

파일 쓰기:

hello.py 파일을 생성해서 "Hello, World!"를 출력하는 파이썬 코드를 작성해줘

클로드 코드(Claude Code)는 파일을 직접 생성하거나 수정할 수 있습니다. 작업 전에 항상 어떤 변경을 할지 안내하고, 승인을 요청합니다.

종료하기

Claude Code를 종료하는 두 가지 방법이 있습니다:

# 방법 1: 명령어로 종료
/exit

# 방법 2: 단축키로 종료
Ctrl + C

4. 주요 명령어

Claude Code CLI에서 사용할 수 있는 주요 명령어를 소개합니다. 이 명령어들은 Claude Code 대화창에서 /로 시작하여 입력합니다.

명령어	설명	예시
`claude`	Claude Code 시작	`claude`
`/help`	도움말 표시	`/help`
`/clear`	대화 내용 초기화	`/clear`
`/exit`	Claude Code 종료	`/exit`
`/model`	사용 모델 변경	`/model claude-sonnet-5`
`/cost`	현재 세션 비용 확인	`/cost`
`/compact`	컨텍스트 압축 (대화 요약)	`/compact`

명령어 사용 예시

/help — 도움말

사용 가능한 모든 명령어 목록과 간단한 설명을 표시합니다:

/help

/clear — 대화 초기화

현재 대화 내용을 모두 지우고 새 대화를 시작합니다. 컨텍스트가 길어져 응답 품질이 떨어질 때 유용합니다:

/clear

/model — 모델 변경

현재 세션에서 사용하는 Claude 모델을 변경합니다. 사용 가능한 모델 목록은 Claude 구독 수준에 따라 다릅니다:

# Sonnet 모델로 변경 (빠르고 비용 효율적)
/model claude-sonnet-5

# Opus 모델로 변경 (가장 강력, 비용 높음)
/model claude-opus-5

/cost — 비용 확인

현재 세션에서 사용된 토큰 수와 예상 비용을 표시합니다. API 사용량을 모니터링할 때 유용합니다:

/cost

/compact — 컨텍스트 압축

대화가 길어지면 Claude의 "기억 용량"인 컨텍스트 윈도우가 꽉 차게 됩니다. /compact는 이전 대화를 요약하여 공간을 확보합니다:

/compact

/compact는 Claude Code 사용에서 가장 중요한 명령어 중 하나입니다. 대화가 길어질 때마다 정기적으로 실행하세요. 그렇지 않으면 Claude가 이전 대화 내용을 잊어버리거나 응답 품질이 저하될 수 있습니다.

5. 프로젝트 모드

Claude Code CLI의 진정한 강점은 프로젝트 모드에서 나타납니다. 프로젝트 폴더에서 Claude Code를 실행하면, Claude가 프로젝트의 파일 구조와 설정을 이해하고 문맥에 맞는 작업을 수행할 수 있습니다.

프로젝트에서 Claude Code 실행하기

1단계: 프로젝트 폴더로 이동

터미널에서 작업할 프로젝트 폴더로 이동합니다:

cd ~/my-project

2단계: Claude Code 실행

프로젝트 폴더에서 Claude Code를 실행합니다:

claude

3단계: 프로젝트 컨텍스트 인식

Claude Code가 자동으로 프로젝트의 파일 구조를 분석합니다. 이제 프로젝트와 관련된 질문을 할 수 있습니다:

이 프로젝트의 구조를 설명해줘

4단계: 에이전트 dispatch

AGENTS.md가 있는 프로젝트에서는 Claude Code가 에이전트를 인식하고 전문 작업을 적절한 에이전트에 위임(dispatch)합니다:

이 프로젝트의 design_spec.md를 생성해줘

Claude Code는 PM 게이트웨이를 통해 design 에이전트를 dispatch하고 작업을 수행합니다.

프로젝트 모드에서는 Claude Code가 AGENTS.md를 읽고 에이전트를 인식합니다. AGENTS.md에 정의된 에이전트 규칙, 권한, 워크플로우에 따라 작업이 자동으로 분배됩니다. 이것이 Claude Code CLI를 사용하는 가장 큰 이유 중 하나입니다.

프로젝트 모드의 장점

파일 컨텍스트 이해 — 프로젝트의 파일 구조, 의존성, 설정 파일을 자동으로 분석합니다
에이전트 워크플로우 — AGENTS.md에 정의된 다중 에이전트 시스템을 Claude가 자동으로 활용합니다
스크립트 통합 — CI/CD 파이프라인이나 자동화 스크립트에 Claude Code를 포함할 수 있습니다
서드파티 백엔드 — DeepSeek, GLM 등 다른 AI 백엔드로 전환하여 비용을 절감할 수 있습니다 (별첨 C 참조)

6. 실용 팁

Claude Code CLI를 더 효과적으로 사용하기 위한 5가지 실용 팁을 소개합니다.

팁 1: 항상 프로젝트 폴더에서 시작하세요

Claude Code를 실행하기 전에 cd 명령어로 프로젝트 폴더로 이동하세요. 프로젝트 폴더 밖에서 실행하면 Claude가 파일 컨텍스트를 파악하지 못합니다:

# 좋은 예
cd ~/my-project
claude

# 나쁜 예 — 홈 디렉토리에서 실행
claude

팁 2: /compact로 컨텍스트를 관리하세요

대화가 길어지면 Claude의 컨텍스트 윈도우가 꽉 찹니다. /compact를 정기적으로 실행하여 대화를 요약하고 공간을 확보하세요. 특히 파일 분석이나 코드 리뷰 후에 실행하면 효과적입니다:

# 대화 10-15회 전환마다 실행
/compact

팁 3: /cost로 비용을 모니터링하세요

Claude Code를 사용하는 동안 비용이 얼마나 발생하는지 확인하세요. 특히 Claude Pro 구독의 사용량 한도를 관리할 때 유용합니다:

# 세션 비용 확인
/cost

팁 4: AGENTS.md를 최신 상태로 유지하세요

프로젝트의 AGENTS.md 파일은 Claude Code의 "지침서"입니다. 에이전트 정의, 권한, 워크플로우가 이 파일에 정의됩니다. AGENTS.md가 구버전이면 Claude가 올바르지 않은 에이전트를 호출할 수 있습니다:

# AGENTS.md 확인
claude
# "현재 프로젝트의 에이전트 목록을 보여줘"

팁 5: Claude Code CLI + 저비용 백엔드 조합

Claude Code CLI의 가장 큰 장점은 서드파티 백엔드를 사용할 수 있다는 것입니다. DeepSeek, GLM, LiteLLM 등 저비용 백엔드를 연결하면 Claude Pro 구독보다 적은 비용으로 Claude Code를 사용할 수 있습니다:

# DeepSeek 백엔드 전환 예시
export ANTHROPIC_API_KEY="your-deepseek-key"
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
claude

자세한 설정 방법은 별첨 C: 저비용 AI 백엔드 연동을 참조하세요.

CLI를 처음 사용할 때는 간단한 질문부터 시작하세요. "현재 폴더의 파일 구조를 보여줘", "이 코드에서 문제점을 찾아줘" 같은 간단한 요청으로 Claude Code의 동작 방식을 익히고, 점차 복잡한 작업으로 확장해가세요.

Claude Code CLI는 처음에는 터미널 환경에 익숙하지 않으면 어려울 수 있습니다. 하지만 기본 명령어 몇 개만 알면 충분히 활용할 수 있습니다. claude로 시작하고, /exit로 종료하고, /compact로 관리하는 것만 기억하셔도 됩니다.