Claude Code는 Anthropic의 터미널 기반 AI 코딩 에이전트입니다. 평범한 영어로 원하는 것을 입력하면, 코드베이스를 읽고, 코드를 작성하며, 명령어를 실행하고, 오류를 수정하고, 변경 사항을 커밋합니다 — 모두 터미널에서. IDE 플러그인 없음. 브라우저 탭 없음. 터미널 창에서 당신과 AI만 있으면 됩니다.
Cursor(IDE 내부에서 작동)나 Codex(클라우드에서 작동)와 달리, Claude Code는 실제 개발 환경에서 로컬로 실행됩니다. 파일, git 기록, 터미널 출력을 볼 수 있습니다. 이로 인해 AI와 코드 간의 컨텍스트 전환이 없어 많은 워크플로에서 더 빠릅니다.
이 가이드는 설치, 첫 번째 프로젝트, 주요 명령어, 그리고 Claude Code를 효과적으로 사용하는 워크플로를 다룹니다.
| Tool | Best For | Where it runs | Workflow |
|---|---|---|---|
| Claude Code | 대화형 에이전트 코딩 | 로컬 터미널 | 당신이 안내 + 실시간 단계 실행 |
| Cursor | 일상 코딩 + 인라인 편집 | IDE 내부 | 보이는 diff + 자동완성 |
| Codex | 비동기 위임 작업 | 클라우드 샌드박스 | 작업 제출 → 나중에 PR 검토 |
Claude Code 설치 방법
Node.js 18+와 Claude 계정(Pro 또는 API)이 필요합니다.
단계 1: npm을 통해 전역으로 설치하세요:
npm install -g @anthropic-ai/claude-code
단계 2: 프로젝트 디렉토리로 이동하세요:
cd your-project
단계 3: Claude Code를 실행하세요:
claude
처음 실행할 때 Anthropic 계정으로 인증하라는 메시지가 나타납니다. Claude Pro($20/월)를 사용 중이라면 넉넉한 토큰 할당량을 받습니다. API를 사용 중이라면 토큰당 요금을 지불합니다(현재 요금은 요금 제한 가이드에서 확인하세요).
비용 추정(놀라지 않도록)
API 과금제를 사용 중이라면 중간 규모 저장소에서 30–60분 세션이 보통 모델 + 반복 횟수에 따라 $2–$10 정도입니다. /cost를 자주 사용하고, 긴 세션은 Vibe Coding Cost Calculator로 확인하세요.
Claude Code 첫 5분
Claude Code가 실행되면 대화형 세션이 시작됩니다. AI는 전체 프로젝트 디렉토리에 접근할 수 있습니다. 간단하게 시작하세요:
탐색 요청: "이 프로젝트가 뭔가요? 전체 개요를 알려주세요."라고 입력하세요. Claude는 주요 파일(package.json, README, 메인 진입점)을 읽고 요약합니다. 프로젝트 구조를 이해하는지 확인하는 좋은 방법입니다.
찾기 요청: "인증 로직이 어디에 있나요?" Claude가 코드베이스를 검색해 관련 파일을 알려줍니다. 단순 텍스트 매칭이 아닌 코드 구조를 이해합니다.
변경 요청: "가입 양식에 입력 검증을 추가하세요. 이메일은 유효한 형식, 비밀번호는 최소 8자여야 합니다." Claude가 양식 컴포넌트를 찾아 검증 로직을 작성하고 적용 전에 diff를 보여줍니다.
핵심: Claude Code는 실제 파일에서 작동합니다. 변경 시 파일이 디스크에 실제로 수정됩니다. 에디터에서 변경 확인, 테스트 실행, 정상 커밋 가능합니다.
필수 명령어
Claude Code에는 동작을 제어하는 여러 슬래시 명령어가 있습니다:
| 명령어 | 기능 | 사용 시기 |
|---|---|---|
/init | 프로젝트 루트에 CLAUDE.md 파일을 생성합니다 | 리포지토리에서 첫 번째 중요한 작업 전에 |
/compact | 컨텍스트 한계에 가까워진 대화 기록을 압축합니다 | 긴 세션; 품질이 떨어지기 전에 |
/cost | 사용된 토큰 수 + 예상 비용을 표시합니다 | API 청구, 예산 추적 |
/clear | 컨텍스트를 유지하면서 대화를 초기화합니다 | 관련 없는 작업 간 전환 시 |
이 내용에서 가치를 얻고 계신가요? AI 코딩 도구와 워크플로에 대한 주간 가이드를 발행합니다. 인박스에서 받아보세요 →
CLAUDE.md 파일 — 프로젝트의 AI 컨텍스트
CLAUDE.md 파일은 Claude Code 워크플로에서 가장 중요한 것입니다. 프로젝트 루트의 마크다운 파일로, 모든 세션 시작 시 Claude가 읽습니다. 코드베이스를 위한 맞춤 지침으로 생각하세요.
좋은 CLAUDE.md에는 다음이 포함됩니다:
프로젝트 개요: 프로젝트 기능, 기술 스택, 아키텍처를 3-5문장으로.
코드 규칙: 포맷팅 선호도, 명명 규칙, 따라야 할 패턴. "훅과 함께 함수형 컴포넌트 사용. 명명된 내보내기 선호. 스타일링은 Tailwind 사용."
주요 파일: Claude가 이해해야 할 가장 중요한 파일 안내. "주요 데이터 모델은 lib/models/에. API 라우트는 app/api/에."
피할 것: "데이터베이스 마이그레이션 파일 수정 금지. vendor/ 변경 금지. api/ 파일 수정 후 항상 테스트 실행."
CLAUDE.md 없이 Claude Code는 프로젝트 스타일과 맞지 않는 일반 코드를 생성합니다. CLAUDE.md가 있으면 팀원처럼 보이는 출력이 나옵니다. 이것이 컨텍스트 엔지니어링의 실제 적용입니다.
실제 워크플로: 기능 빌드
전형적인 기능 개발 세션에서 Claude Code를 사용하는 방법입니다:
1. 목표부터: "API에 속도 제한기 추가. Redis 사용. /api/submit 엔드포인트에 IP당 분당 10회 제한 적용."
2. Claude 계획 세우기: 기존 API 코드 읽고 Redis 설정 확인 후 접근 방식 제안. 코딩 전에 계획 검토.
3. 작업 지켜보기: Claude가 속도 제한기 모듈 생성, API 라우트 통합, Redis 연결 환경 변수 추가, 테스트 작성.
4. 테스트: Claude가 테스트 실행. 실패 시 오류 읽고 코드 조정 후 재시도. 이 반복 루프가 에이전트의 강점 — 수동 작업 여러 번 대신 디버깅 처리.
5. 검토 및 커밋: diff 확인. 조정 후 커밋. 요청 시 Claude가 커밋 메시지도 작성.
이런 기능에서 Claude Code는 수동 작성 대비 60-70% 시간 절약. 보일러플레이트, 통합 코드, 테스트 작성에서 진짜 절약 — 지루하지만 도전적이지 않은 부분.
토큰 사용 관리
Claude Code는 모든 상호작용에 토큰 사용. 대형 코드베이스 긴 세션은 API 과금에서 비용 발생. 비용 합리적으로 유지하는 습관:
/compact 자주 사용. 컨텍스트 가득 차기 전에. 각 별도 작업 완료 후 압축.
구체적으로. "로그인 양식 버그 수정"이 "전체 앱 보고 버그 찾기"보다 저렴. 구체적 요청 = 코드 읽기 적음.
无关 작업 간 /clear 사용. 프론트엔드 작업 후 데이터베이스 마이그레이션으로 전환 시 컨텍스트 초기화. 이전 컨텍스트 토큰 낭비하고 모델 혼란.
/cost 자주 확인. 세션별 정신적 예산 설정 후 확인. 전형 30분 기능 세션 API 과금 $2-8.
Claude Code와 Cursor 비용 비교 상세는 30일 실제 비용 비교 참조.
Claude Code vs Cursor vs Codex
빠른 결정 가이드:
| 옵션 | 최적일 때... | 트레이드오프 |
|---|---|---|
| Claude Code | 로컬에서 대화형, repo 전체 변경을 원할 때 | 신중한 검토 필요 (실제 파일 편집) |
| Cursor | IDE 내부 AI + 타이트한 편집 루프를 원할 때 | 터미널 에이전트보다 덜 자동화 |
| Codex | 비동기, PR 기반 위임을 원할 때 | 덜 대화형; 컨텍스트가 드리프트될 수 있음 |
Claude Code: 전체 프로젝트 컨텍스트와 터미널 네이티브 워크플로를 원하는 개발자에게 최적. 대화형, 실시간, 실제 파일에서 작동. 복잡한 기능, 리팩토링, 디버깅에 최고.
Cursor: IDE 내부 AI를 원하는 개발자에게 최적. 인라인 diff로 실시간 변경 확인. AI 제안과 함께 일상 코딩에 최고. 전체 비교는 여기.
Codex: 비동기, 배치 코딩 작업을 원하는 팀에 최적. 작업 제출 후 PR 검토. 완전히 위임할 잘 정의된 작업에 최고. 전체 비교는 여기.
많은 개발자들이 두 개 이상 사용. 복잡한 기능에는 Claude Code, 일상 편집에는 Cursor, 배치 작업에는 Codex.
어떤 AI 코딩 도구든 프롬프트를 개선하고 싶으신가요? The Prompt Optimizer가 더 명확하고 구체적인 출력을 위한 요청 구조화에 도움.
이런 콘텐츠 더 원하세요? AI 코딩 도구와 개발자 워크플로에 대해 매주 발행. 무료 구독 →
자주 묻는 질문
Claude Code가 Windows에서 작동하나요?
네, WSL(Windows Subsystem for Linux), PowerShell, 또는 Command Prompt에서. 많은 개발 도구가 Linux 네이티브라 WSL이 최적 경험.
Claude Code가 인터넷 접근 가능하나요?
Claude Code 자체는 웹 브라우징 안 하지만, curl, npm install, git clone 같은 명령어 실행 가능. GitHub, 데이터베이스, API 같은 외부 서비스 접근에 MCP 서버도 사용.
Claude Code가 대형 코드베이스 어떻게 처리하나요?
Claude의 200K 토큰 컨텍스트 창으로 수천 소스 파일 동시 로드/처리. 매우 큰 모노레포는 모든 것 로드 대신 관련 파일 선택 읽기. CLAUDE.md가 각 작업에 중요한 코드베이스 부분 알려줌.
내 코드가 Anthropic 서버로 전송되나요?
네, 처리 위해 Anthropic API로 코드 전송. Anthropic은 기본적으로 API 입력으로 학습 안 함. 민감/독점 코드라면 최신 약관 확인. 최대 개인정보 위해 데이터 보존 비활성화 API 사용 고려.
공개: 이 글 일부 링크는 제휴 링크. 직접 테스트하고 정기 사용 도구만 추천. 전체 공개 정책 참조.