Claude Code는 Anthropic의 명령줄 코딩 에이전트로, 코드베이스를 읽고, 파일을 편집하며, 명령을 실행하고, 백엔드에서 LLM API에 연결합니다. 이 가이드는 전체 CLI 문서를 다룹니다: 설정 방법, 사용 가능한 플래그와 슬래시 명령어, 사용자 정의 슬래시 명령어 작성 방법, 그리고 기본 Anthropic 엔드포인트 대신 Novita AI로 API 호출을 라우팅하는 방법.
Claude Code란 무엇인가요?
Claude Code는 CLI, VS Code 확장, JetBrains 플러그인, 데스크톱 앱 및 브라우저 인터페이스로 제공되는 에이전트 코딩 도구입니다. 모든 표면은 동일한 기본 엔진을 공유합니다: Claude Code는 LLM API 백엔드에 연결하고, 프로젝트를 읽으며, 테스트 작성, 여러 파일에 걸친 리팩토링, 풀 리퀘스트 생성, git 관리와 같은 다단계 작업을 실행합니다.
CLI는 가장 유연한 표면입니다. Unix 규칙을 따릅니다 — 로그를 파이프로 전달하거나, -p 플래그로 CI에서 실행하거나, 다른 도구와 체이닝할 수 있습니다. 구성은 파일(CLAUDE.md, .claude/settings.json, 환경 변수)에 저장되므로 자동화된 컨텍스트에서 예측 가능하게 동작합니다.
내부적으로 Claude Code는 모든 요청을 Anthropic 호환 API 엔드포인트로 보냅니다. 기본 엔드포인트는 api.anthropic.com이지만, 단일 환경 변수로 Novita AI를 포함한 모든 Anthropic 호환 제공자로 리디렉션할 수 있습니다.
Claude Code 설정
설치
macOS, Linux 및 WSL에서 권장되는 방법은 네이티브 설치 프로그램입니다:
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell에서:
irm https://claude.ai/install.ps1 | iex
네이티브 설치는 백그라운드에서 자동으로 업데이트됩니다.
npm을 선호하는 경우 Node.js 18 이상이 필요합니다:
node --version # 18 이상이어야 함
npm install -g @anthropic-ai/claude-code
Homebrew (macOS)는 안정적인 릴리스 채널을 추적합니다:
brew install --cask claude-code
Homebrew는 자동 업데이트되지 않습니다. 최신 버전을 원하면 brew upgrade claude-code를 실행하세요.
첫 실행
프로젝트 디렉토리로 이동하여 대화형 세션을 시작합니다:
cd your-project
claude
처음 사용 시 Claude Code는 로그인을 요청합니다. 인증 후 프로젝트를 읽고 명령을 기다립니다.
프로젝트 설정
새 리포지토리에서 /init을 실행하여 시작용 CLAUDE.md 파일을 생성합니다. Claude Code는 모든 세션 시작 시 CLAUDE.md를 읽으므로, 코딩 표준, 선호 라이브러리, 아키텍처 노트 및 리뷰 체크리스트를 넣기에 적합한 장소입니다.
/init
/init 후에는 /memory를 사용하여 파일을 편집하거나 자동 메모리를 활성화할 수 있습니다. 자동 메모리는 Claude가 프로젝트에 대해 관찰한 내용을 세션 간에 저장합니다.
CLI 명령어 참조
Claude Code의 최상위 셸 명령어는 세션을 시작하고, 인증을 관리하며, 백그라운드 작업을 처리합니다. 가장 유용한 명령어 일부는 다음과 같습니다:
| 명령어 | 설명 |
|---|---|
claude |
현재 디렉토리에서 대화형 세션 시작 |
claude "query" |
초기 프롬프트로 세션 시작 |
claude -p "query" |
쿼리를 실행하고 종료 (비대화형 / SDK 모드) |
cat file | claude -p "query" |
파일 내용을 쿼리에 파이프 |
claude -c |
현재 디렉토리에서 가장 최근 세션 계속 |
claude -r "name" "query" |
이름 또는 ID로 세션 재개 |
claude update |
최신 버전으로 업데이트 |
claude install stable |
특정 버전 설치 또는 재설치 |
claude auth login |
Anthropic 계정에 로그인 |
claude auth login --console |
구독 대신 API 키 결제로 로그인 |
claude auth status |
인증 상태 표시 |
claude agents --json |
에이전트 보기 열기, 활성 세션을 JSON으로 출력 |
claude mcp |
MCP 서버 구성 |
claude daemon status |
백그라운드 세션 감독자 상태 확인 |
하위 명령어를 잘못 입력하면 Claude Code가 가장 가까운 일치 항목을 제안합니다: claude udpate는 Did you mean claude update?를 출력합니다.
CLI 플래그 참조
플래그는 세션에서 Claude Code의 동작 방식을 수정합니다. claude 뒤에 모든 호출에서 전달합니다. 가장 일반적으로 필요한 플래그 목록:
| 플래그 | 기능 |
|---|---|
-p, --print |
비대화형 모드; 응답 출력 후 종료 |
-c, --continue |
가장 최근 대화 불러오기 |
-r, --resume |
ID 또는 이름으로 세션 재개 |
--model |
이 세션의 모델 설정 (sonnet, opus, haiku 또는 전체 모델 ID) |
--permission-mode |
권한 모드로 시작: default, plan, auto, acceptEdits, bypassPermissions |
--add-dir |
추가 디렉토리에 파일 액세스 권한 부여 |
--system-prompt |
시스템 프롬프트를 완전히 대체 |
--append-system-prompt |
기본 시스템 프롬프트에 추가 |
--max-turns |
-p 모드에서 에이전트 턴 수 제한 |
--max-budget-usd |
-p 모드에서 API 비용 상한 설정 |
--output-format |
-p 모드의 출력 형식: text, json, stream-json |
--bg |
백그라운드 에이전트로 시작, 즉시 반환 |
--worktree, -w |
격리된 git 워크트리에서 시작 |
--bare |
더 빠른 스크립트 호출을 위해 훅, 스킬, 플러그인, MCP 자동 검색 건너뛰기 |
--verbose |
전체 턴별 출력 표시 |
--mcp-config |
JSON 파일에서 MCP 서버 불러오기 |
--effort |
추론 노력 수준 설정: low, medium, high, xhigh, max |
--print + --output-format json 조합은 스크립팅의 표준 패턴입니다. 예산 제약이 있는 CI 파이프라인의 경우 --max-budget-usd 및 --max-turns와 함께 사용하세요.
슬래시 명령어 문서
슬래시 명령어는 활성 세션 내에서 실행됩니다. /를 입력하면 모든 명령어를 볼 수 있고, / 뒤에 문자를 입력하면 필터링됩니다. 명령어는 메시지 시작 부분에서만 작동합니다.
세션 및 컨텍스트 관리
| 명령어 | 목적 |
|---|---|
/clear |
새 대화 시작; 이전 세션은 /resume에 유지 |
/compact |
대화를 요약하여 컨텍스트 창 공간 확보 |
/context |
컨텍스트 사용량 시각화 및 최적화 제안 확인 |
/resume |
이름 또는 선택기에서 이전 세션 다시 열기 |
/branch |
다른 방향을 시도하기 위해 대화 포크 |
/rewind |
코드와 대화를 체크포인트로 되감기 |
프로젝트 설정
| 명령어 | 목적 |
|---|---|
/init |
프로젝트용 시작 CLAUDE.md 생성 |
/memory |
CLAUDE.md 파일 편집 및 자동 메모리 관리 |
/mcp |
MCP 서버 연결을 대화형으로 관리 |
/agents |
하위 에이전트 설정 구성 |
/permissions |
도구에 대한 허용, 확인, 거부 규칙 설정 |
/hooks |
훅 구성 보기 |
개발 워크플로우
| 명령어 | 목적 |
|---|---|
/plan |
큰 변경 전에 계획 모드 진입 |
/model |
활성 모델 전환 |
/effort |
추론 노력 수준 조정 |
/diff |
대화형 diff 뷰어 열기 |
/code-review [--fix] |
현재 diff 검토; --fix는 발견 사항 적용 |
/security-review |
보류 중인 변경 사항에 대한 심층 보안 검사 |
/batch <instruction> |
큰 변경을 분해하여 병렬 워크트리에서 실행 |
/background |
세션을 분리하여 백그라운드 에이전트로 실행 |
유틸리티
| 명령어 | 목적 |
|---|---|
/help |
사용 가능한 명령어 표시 |
/doctor |
설치 및 설정 문제 진단 |
/usage |
세션 비용 및 요금제 사용량 표시 |
/export |
대화를 일반 텍스트로 내보내기 |
/config |
설정을 열거나 직접 값 설정: /config thinking=false |
/skills |
사용 가능한 스킬 목록 |
사용자 정의 슬래시 명령어
사용자 정의 슬래시 명령어(현재는 스킬이라고 함)를 사용하면 팀이 공유할 수 있는 반복 가능한 절차를 패키징할 수 있습니다.
사용자 정의 명령어 생성 방법
.claude/skills/ 디렉토리(프로젝트 수준) 또는 ~/.claude/skills/(개인, 모든 프로젝트에서 사용 가능) 아래에 디렉토리를 생성합니다:
mkdir -p .claude/skills/review-pr
해당 디렉토리 안에 SKILL.md 파일을 생성합니다:
---
description: 보안 문제 및 테스트 범위 격차에 대해 GitHub PR을 검토합니다. 사용자가 PR을 검토하거나 풀 리퀘스트 품질을 확인하도록 요청할 때 사용하세요.
---
## 지침
다음 우선순위로 풀 리퀘스트를 검토하세요:
1. 보안 취약점 식별: 주입 위험, 인증 격차, 데이터 노출.
2. 새로운 코드 경로에 대한 테스트 범위 확인.
3. 시스템 경계에서 누락된 오류 처리 플래그 지정.
결과를 보안, 범위, 기타의 세 섹션으로 요약하세요. 통과 검사에는 ✓, 문제에는 ⚠를 사용하세요.
이렇게 하면 직접 호출할 수 있는 /review-pr 명령어가 생성됩니다:
/review-pr
Claude는 설명과 일치하는 요청을 하면 자동으로 스킬을 로드합니다.
스킬 위치 및 우선순위
스킬은 우선순위 순서를 따릅니다: 엔터프라이즈가 개인을 재정의하고, 개인이 프로젝트를 재정의합니다. 프로젝트 스킬은 .claude/skills/에 있습니다. 개인 스킬(모든 프로젝트에서 사용 가능)은 ~/.claude/skills/에 넣습니다.
~/.claude/skills/ → 개인, 모든 프로젝트
.claude/skills/ → 이 프로젝트만
.claude/commands/의 사용자 정의 명령어는 여전히 작동합니다. .claude/commands/deploy.md의 파일과 .claude/skills/deploy/SKILL.md의 스킬은 모두 /deploy를 생성하며 동일하게 동작합니다.
동적 컨텍스트 주입
스킬은 Claude가 프롬프트를 보기 전에 실시간 데이터를 주입할 수 있습니다. ! 접두사는 셸 명령을 실행하고 그 출력을 인라인으로 삽입합니다:
---
description: 커밋되지 않은 변경 사항을 요약하고 위험을 플래그 지정합니다.
---
## 현재 diff
!`git diff HEAD`
## 지침
변경 사항을 글머리 기호로 요약하세요. 위험을 플래그 지정하세요: 누락된 오류 처리, 하드코딩된 값, 테스트되지 않은 경로.
이 스킬을 실행하면 Claude Code가 git diff HEAD를 실행하고 해당 줄을 실제 diff 출력으로 대체합니다. Claude는 도구 호출을 통해 요청할 필요 없이 실제 작업 트리 상태를 확인합니다.
Novita AI를 LLM 백엔드로 사용하기
Claude Code는 모든 API 트래픽을 ANTHROPIC_BASE_URL 환경 변수를 통해 라우팅합니다. 이 값을 Novita AI의 Anthropic 호환 엔드포인트로 설정하면 기본 Anthropic 엔드포인트보다 훨씬 낮은 토큰당 비용으로 DeepSeek, Kimi, Qwen, GLM 변형을 포함한 다양한 모델에 액세스할 수 있습니다.
Novita AI API 키 받기
Novita AI 계정에 가입하면 무료 평가판 크레딧을 받을 수 있습니다. 키 관리 페이지로 이동하여 새 키 만들기 를 클릭하고 키를 즉시 복사하세요.
환경 변수 설정
Mac 및 Linux:
export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<Your Novita API Key>"
export ANTHROPIC_MODEL="deepseek/deepseek-v4-flash"
export ANTHROPIC_SMALL_FAST_MODEL="deepseek/deepseek-v4-flash"
Windows (명령 프롬프트):
set ANTHROPIC_BASE_URL=https://api.novita.ai/anthropic
set ANTHROPIC_AUTH_TOKEN=<Your Novita API Key>
set ANTHROPIC_MODEL=deepseek/deepseek-v4-flash
set ANTHROPIC_SMALL_FAST_MODEL=deepseek/deepseek-v4-flash
Mac/Linux에서 영구적으로 설정하려면 export 줄을 ~/.bashrc 또는 ~/.zshrc에 추가하세요.
ANTHROPIC_SMALL_FAST_MODEL은 Claude Code가 파일 조회 및 빠른 요약과 같은 빠른 내부 작업에 사용하는 경량 모델을 제어합니다. 동일한 모델 ID로 설정하면 모든 트래픽이 하나의 결제 계정에서 처리됩니다.
Claude Code 시작
환경 변수를 설정한 후 평소처럼 Claude Code를 시작합니다:
cd your-project
claude
Claude Code는 지정한 모델로 Novita AI의 엔드포인트에 연결합니다. 대화형 세션은 동일하게 작동합니다 — 모든 CLI 플래그, 슬래시 명령어 및 사용자 정의 스킬은 사용 중인 백엔드에 관계없이 동일하게 동작합니다.
스크립팅 및 CI의 경우 동일한 접근 방식이 적용됩니다:
cat logs.txt | claude -p "find any error patterns" --output-format json
Novita AI의 LLM API는 도구 사용, 구조화된 출력 및 스트리밍을 포함한 전체 Anthropic 메시지 형식을 지원하므로 모든 Claude Code 기능이 수정 없이 작동합니다.
격리된 실행을 위한 에이전트 샌드박스
Claude Code 위에 자동화된 파이프라인을 구축하는 경우 Novita AI의 Agent Sandbox는 에이전트를 프로그래밍 방식으로 실행하기 위한 격리된 firecracker 기반 실행 환경을 제공합니다. 이는 개발 머신에서 직접 실행하는 대신 실행 격리가 필요한 CI 워크플로우, 백그라운드 에이전트 및 다중 에이전트 설정과 관련이 있습니다.
IDE 도구로서의 Claude Code
Claude Code는 편집기와 직접 통합되며, 사람들이 "claude code는 ide"라고 말할 때 의미하는 바입니다. 독립형 IDE가 아니라 기존 환경에 포함되는 코딩 에이전트입니다.
VS Code 및 Cursor
VS Code Marketplace에서 Claude Code 확장을 설치하거나 (“Claude Code” 검색) Cursor 마켓플레이스에서 설치하세요. 설치 후 명령 팔레트(Cmd+Shift+P / Ctrl+Shift+P)를 열고 "Claude Code"를 입력한 다음 새 탭에서 열기 를 선택하세요.
VS Code 통합은 편집기 패널에 인라인 diff 리뷰, @-파일 언급, 편집 전 계획 리뷰 및 대화 기록을 추가합니다. 확장과 함께 통합 터미널에서 Claude Code를 사용할 수도 있습니다.
JetBrains
JetBrains Marketplace에서 Claude Code 플러그인을 설치하고 IDE를 다시 시작하세요. 플러그인은 CLI가 별도로 설치되어 있어야 합니다. IntelliJ IDEA, PyCharm, WebStorm 및 기타 JetBrains IDE에서 대화형 diff 보기 및 선택 컨텍스트 공유를 제공합니다.
데스크톱 앱 및 웹
Claude Code 데스크톱 앱(macOS 및 Windows)을 사용하면 diff를 시각적으로 검토하고, 여러 세션을 나란히 실행하며, 반복 작업을 예약할 수 있습니다. claude.ai/code의 웹 인터페이스는 로컬 설정 없이 브라우저에서 세션을 실행하며, 로컬에 없는 리포지토리나 원격으로 모니터링할 수 있는 장기 실행 작업을 시작하는 데 유용합니다.
FAQ
ANTHROPIC_BASE_URL이란 무엇이고 왜 중요한가요?
ANTHROPIC_BASE_URL은 Claude Code가 요청을 보낼 API 엔드포인트를 지정합니다. 기본값은 api.anthropic.com입니다. https://api.novita.ai/anthropic으로 설정하면 모든 트래픽이 Novita AI의 Anthropic 호환 엔드포인트로 라우팅되며, 다른 가격대의 대체 모델을 사용할 수 있습니다. 환경 변수 하나만 설정하면 되며 코드 변경이나 플러그인이 필요하지 않습니다.
CLI 플래그와 슬래시 명령어의 차이점은 무엇인가요?
CLI 플래그(--model, --permission-mode, --max-turns 등)는 셸에서 claude 바이너리를 실행할 때 설정됩니다. 세션이 시작되기 전에 구성합니다. 슬래시 명령어(/model, /plan, /compact 등)는 활성 세션 내에서 실행되며 대화 중 동작을 변경합니다.
Claude Code를 Claude 구독 없이 사용할 수 있나요?
네. claude auth login --console은 Anthropic Console API 키 결제로 로그인하며, 구독이 아닌 토큰당 과금을 사용합니다. ANTHROPIC_BASE_URL을 통해 Novita AI로 라우팅하는 경우 Novita AI 계정만 있으면 됩니다. Anthropic 계정에 요금이 청구되지 않습니다.
사용자 정의 슬래시 명령어와 CLAUDE.md의 차이점은 무엇인가요?
CLAUDE.md 콘텐츠는 모든 세션 시작 시 로드되어 전체 세션 동안 컨텍스트에 유지됩니다. 스킬(사용자 정의 명령어)은 호출될 때만 로드되므로, 긴 참조 자료는 실제로 필요할 때까지 토큰 비용이 추가되지 않습니다. CLAUDE.md에는 Claude가 항상 알아야 하는 프로젝트 정보(코딩 표준, 빌드 명령어, 아키텍처 노트)를 넣으세요. 스킬에는 필요할 때 실행하는 절차(PR 검토 체크리스트, 배포 단계, 테스트 생성 워크플로우)를 넣으세요.
Claude Code는 CI에서 작동하나요?
네. 비대화형 모드와 구조화된 출력을 위해 claude -p "query" --output-format json을 사용하세요. 비용을 제한하려면 --max-budget-usd를 추가하고, 실행 시간을 제한하려면 --max-turns를 추가하세요. --bare 플래그는 스크립트 컨텍스트에서 더 빠른 시작을 위해 훅, 스킬 및 플러그인의 자동 검색을 건너뜁니다. Claude Code는 공식 워크플로우 템플릿을 통해 GitHub Actions 및 GitLab CI/CD와도 통합됩니다.
Novita AI는 개발자가 간단한 API를 사용하여 AI 모델을 쉽게 배포할 수 있는 AI 클라우드 플랫폼이며, 구축 및 확장을 위한 저렴하고 안정적인 GPU 클라우드를 제공합니다.
