클로드 코드 다운부터 CLI·스킬 세팅까지 완전 가이드 (2026)

클로드 코드란 무엇인가요? — 30초 핵심 개요

클로드 코드를 설치하려면 Node.js 18 이상 환경에서 npm install -g @anthropic-ai/claude-code를 실행합니다. macOS·Linux는 바로 사용 가능하고, Windows는 WSL2 내부에서 설치해야 합니다. 설치 후 claude를 실행하면 브라우저 OAuth 인증이 시작되며, 인증을 마치면 곧바로 터미널에서 AI 코딩 세션을 열 수 있습니다.

클로드 코드(Claude Code)는 Anthropic이 만든 터미널 기반 AI 코딩 어시스턴트입니다. 코드 편집기 플러그인이 아니라 CLI 도구이기 때문에, 프로젝트 디렉터리에서 claude 명령어를 실행하면 바로 대화형 AI 세션이 시작됩니다. 파일 읽기·쓰기, 명령어 실행, 코드 리뷰, 테스트 생성 등을 자연어로 지시할 수 있습니다.

Plinth Prep은 Anthropic과 제휴·후원 관계가 없는 독립 학습 사이트입니다. 이 글은 공식 문서와 실제 설치 경험을 바탕으로 작성한 실전 가이드입니다.

클로드 코드의 핵심 특징은 세 가지입니다.

• 터미널 네이티브 — IDE 없이도 동작하며 SSH 원격 서버에서도 사용할 수 있습니다.
• 컨텍스트 인식 — 프로젝트 루트의 CLAUDE.md 파일을 자동으로 읽어 프로젝트 구조와 규칙을 파악합니다.
• 스킬 확장 — 슬래시 명령어(스킬)로 기능을 빠르게 호출하고, MCP 서버로 외부 도구와 연동할 수 있습니다.

클로드 코드 다운로드: macOS·Windows(WSL2)·Linux 설치 방법은?

클로드 코드는 npm 패키지로 배포됩니다. 설치 전에 Node.js 18 이상이 필요합니다.

1단계: Node.js 버전 확인

node --version

출력이 v18.x.x 미만이거나 명령어가 없으면 Node.js를 먼저 설치해야 합니다. nvm을 사용하는 경우 아래 명령어로 빠르게 업그레이드할 수 있습니다.

nvm install 20 && nvm use 20

2단계: 클로드 코드 설치

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

설치가 완료되면 버전을 확인합니다.

claude --version

플랫폼별 주의사항

macOS — 기본 터미널 또는 iTerm2에서 바로 실행할 수 있습니다. Homebrew로 설치한 Node.js를 사용하는 경우 PATH 설정이 자동으로 완료됩니다.

Windows — 네이티브 Windows 터미널은 지원하지 않습니다. WSL2(Windows Subsystem for Linux)를 먼저 설치한 다음, WSL2 내부에서 Node.js와 클로드 코드를 설치해야 합니다.

# WSL2 Ubuntu에서 실행
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code

Linux — Ubuntu, Debian, Fedora 등 주요 배포판에서 동일한 npm 명령어로 설치할 수 있습니다. 권한 문제가 발생하면 아래 오류 해결 섹션을 참고하세요.

클로드 코드 CLI 인증은 어떻게 하나요?

설치 후 처음 claude를 실행하면 인증 절차가 시작됩니다.

방법 1: 브라우저 OAuth (권장)

터미널에서 claude를 입력하면 브라우저가 열리고 claude.ai 계정으로 로그인하라는 안내가 나옵니다. claude.ai 계정이 있으면 이 방법이 가장 간단합니다. 로그인이 완료되면 터미널로 자동 복귀됩니다.

claude

방법 2: API 키 인증

API 키를 직접 사용하려면 환경 변수를 설정합니다. Anthropic Console에서 API 키를 발급받을 수 있습니다.

export ANTHROPIC_API_KEY="sk-ant-..."

영구적으로 적용하려면 ~/.bashrc 또는 ~/.zshrc에 위 줄을 추가하세요.

첫 실행 확인

인증이 완료되면 프로젝트 디렉터리로 이동한 다음 claude를 실행합니다.

cd ~/my-project
claude

대화형 프롬프트가 나타나면 설치와 인증이 모두 정상적으로 완료된 것입니다. 이제 "이 프로젝트의 README를 요약해줘" 같은 자연어 명령을 바로 사용할 수 있습니다.

설치 직후 바로 쓸 수 있는 클로드 코드 스킬에는 어떤 것이 있나요?

클로드 코드 스킬은 슬래시(/)로 시작하는 단축 명령어입니다. 복잡한 지시 없이 자주 사용하는 작업을 빠르게 실행할 수 있습니다.

1. /init — 프로젝트 컨텍스트 자동 생성

프로젝트 루트에서 실행하면 클로드 코드가 디렉터리 구조를 분석하고 CLAUDE.md 파일을 자동으로 생성합니다. 이 파일은 이후 세션에서 자동으로 읽히므로 프로젝트 규칙, 폴더 구조, 주의사항을 한 번만 작성해 두면 매번 설명할 필요가 없습니다.

/init

2. /review — 현재 변경사항 코드 리뷰

git diff를 기준으로 변경된 코드를 분석하고 잠재적인 버그, 스타일 문제, 개선 사항을 제안합니다. PR을 올리기 전 빠른 셀프 리뷰에 유용합니다.

/review

3. /run — 명령어 실행 및 결과 해석

테스트 실행, 빌드, 린트 결과를 클로드 코드가 직접 실행하고 오류 메시지를 해석해 수정 방안을 제안합니다.

/run npm test

4. /compact — 대화 컨텍스트 압축

긴 세션에서 컨텍스트 창이 가득 찰 때 사용합니다. 대화 내용을 요약해 토큰 사용량을 줄이면서 세션을 이어갈 수 있습니다.

/compact

5. /help — 사용 가능한 명령어 목록

현재 사용 가능한 모든 스킬과 명령어를 확인합니다. 새 버전에서 추가된 기능을 발견할 때도 유용합니다.

/help

클로드 코드 맥스 플랜은 언제 필요한가요?

클로드 코드는 claude.ai 계정의 플랜에 따라 사용량 한도가 달라집니다.

• Free 플랜 — 제한적인 일일 사용량으로 간단한 작업과 기능 탐색에 적합합니다.
• Pro 플랜 — 일반적인 개발 작업에 충분한 사용량을 제공합니다. 대부분의 개인 개발자에게 출발점으로 권장합니다.
• Max 플랜 — Pro 대비 더 높은 사용량 한도를 제공합니다. 대용량 코드베이스 분석, 장시간 자동화 세션, 팀 단위 업무에 적합합니다.

Max 플랜이 필요한 시점을 판단하는 기준은 다음과 같습니다.

• Pro 플랜에서 사용량 한도 알림이 자주 발생할 때
• 수만 줄 이상의 대형 프로젝트를 한 세션에서 분석할 때
• CI/CD 파이프라인에 클로드 코드를 연동해 자동화할 때
• 여러 마이크로서비스를 동시에 다뤄야 할 때

정확한 플랜별 한도와 가격은 수시로 변경될 수 있으므로 Anthropic 공식 사이트에서 최신 정보를 확인하세요.

클로드 코드 설치·실행 중 자주 나오는 오류와 해결 방법은?

오류 1: claude: command not found

npm 전역 설치 경로가 PATH에 등록되지 않아서 발생합니다. 아래 명령어로 경로를 확인하고 추가합니다.

npm config get prefix

export PATH="$(npm config get prefix)/bin:$PATH"

영구 적용을 위해 위 줄을 ~/.bashrc 또는 ~/.zshrc에 추가한 다음 터미널을 재시작하세요.

오류 2: npm EACCES (권한 거부)

전역 npm 디렉터리에 쓰기 권한이 없을 때 발생합니다. sudo 대신 npm 기본 디렉터리를 홈 폴더로 변경하는 방법을 권장합니다.

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @anthropic-ai/claude-code

오류 3: Node.js 버전 불일치

Node.js 18 미만에서는 클로드 코드가 동작하지 않습니다. node --version으로 버전을 확인하고 nvm으로 업그레이드합니다.

nvm install 20 && nvm use 20
npm install -g @anthropic-ai/claude-code

오류 4: 인증 실패 (Authentication failed)

API 키가 잘못 설정되었거나 만료된 경우입니다. 환경 변수를 다시 확인합니다.

echo $ANTHROPIC_API_KEY

값이 비어 있거나 잘못된 경우 export ANTHROPIC_API_KEY="sk-ant-..."를 다시 실행하세요. OAuth 방식이라면 claude를 재실행해 브라우저 인증을 다시 진행합니다.

다음 단계: MCP 서버 연동과 체계적인 학습으로 이어가기

기본 설치와 스킬 사용에 익숙해졌다면 MCP(Model Context Protocol) 서버 연동으로 클로드 코드의 기능을 확장할 수 있습니다. MCP 서버는 클로드 코드가 외부 도구(데이터베이스, API, 파일 시스템 등)와 직접 통신할 수 있도록 해주는 프로토콜입니다.

MCP 서버 추가하기

MCP 서버를 추가하는 기본 명령어는 다음과 같습니다.

claude mcp add <이름> <명령어>

추가된 MCP 서버 목록을 확인합니다.

claude mcp list

직접 MCP 서버를 만들고 싶다면 Anthropic 공식 MCP SDK 문서를 참고하세요.

예를 들어 파일 시스템 MCP 서버를 추가하면 클로드 코드가 지정한 디렉터리를 직접 읽고 쓸 수 있습니다. GitHub MCP 서버를 연동하면 이슈 조회, PR 생성을 터미널에서 바로 처리할 수 있습니다.

CLAUDE.md로 팀 규칙 공유하기

프로젝트 루트의 CLAUDE.md에 코딩 컨벤션, 아키텍처 설명, 금지 패턴을 작성해 두면 팀원 모두가 동일한 컨텍스트로 클로드 코드를 사용할 수 있습니다. git으로 관리하면 컨텍스트도 버전 관리가 됩니다.

체계적인 학습으로 이어가기

클로드 코드 설치와 기본 사용법을 익혔다면 Claude 플랫폼의 전체 구조를 체계적으로 학습하는 것이 다음 단계입니다. AI 개발 역량을 공식적으로 검증하고 싶다면 CCA-F(Claude Certified Architect — Foundations) 시험을 목표로 삼는 것도 좋은 방법입니다. Plinth Prep에서는 CCA-F 준비에 필요한 학습 자료와 연습 문제를 제공합니다.