Claude Code 완벽 가이드: 설치부터 고급 활용까지 (2026)

Claude Code는 터미널에서 실행하는 AI 코딩 에이전트다. npm install -g @anthropic-ai/claude-code 한 줄로 설치하고, 프로젝트 폴더에서 claude 명령어를 입력하면 즉시 사용 가능하다. 단순한 코드 자동완성이 아니라, 파일을 직접 읽고 수정하고 터미널 명령어를 실행하는 자율 에이전트다. 이 가이드는 설치부터 CLAUDE.md 고급 설정, MCP 서버 연동, 서브에이전트 병렬 작업까지 모든 것을 다룬다.

설치 및 초기 설정

1단계: Node.js 확인

Claude Code는 Node.js 18 이상이 필요하다.

node --version   # v18.0.0 이상이어야 함

Node.js가 없거나 버전이 낮으면 nodejs.org에서 최신 LTS 버전을 설치한다.

2단계: Claude Code 설치

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

설치 후 버전 확인:

claude --version

3단계: Anthropic 계정 인증

claude

첫 실행 시 브라우저가 열리면서 Anthropic 계정 로그인을 요청한다. Claude.ai Pro 또는 Max 구독이 있거나, Anthropic API 키가 있으면 인증된다.

API 키로 직접 인증하려면:

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

기본 사용법

대화형 모드

프로젝트 폴더에서 claude를 입력하면 대화형 모드가 시작된다:

프로젝트 루트에서:
$ cd ~/projects/my-app
$ claude

주요 슬래시 커맨드

비대화형 1회성 실행

# 코드 리뷰 요청
claude "이 PR의 diff를 검토하고 보안 이슈를 찾아줘"

# 파일 분석
claude "src/auth/login.ts 파일의 취약점을 찾아줘"

# 테스트 작성
claude "UserService 클래스에 대한 unit test를 작성해줘"

CLAUDE.md — 프로젝트 설정 파일

CLAUDE.md는 Claude Code에게 프로젝트 컨텍스트를 알려주는 설정 파일이다. 프로젝트 루트에 CLAUDE.md를 만들면 모든 세션에서 자동으로 로드된다.

기본 템플릿

# 프로젝트 개요

이 프로젝트는 Next.js 15 + TypeScript로 만든 SaaS 앱입니다.
DB: PostgreSQL (Drizzle ORM), 인증: Clerk, 배포: Vercel.

## 코드 스타일

- TypeScript strict 모드 사용
- 컴포넌트: App Router (서버 컴포넌트 우선)
- CSS: Tailwind CSS (shadcn/ui 컴포넌트)
- 테스트: Vitest + Testing Library
- 절대 `console.log` 커밋 금지

## 디렉토리 구조

- `app/` — Next.js 라우터 (App Router)
- `lib/` — 공유 유틸리티 및 DB 클라이언트
- `components/` — 재사용 가능한 UI 컴포넌트

## 개발 명령어

```bash
bun run dev      # 개발 서버
bun run build    # 프로덕션 빌드
bun run test     # 테스트 실행
bun run typecheck # 타입 체크

중요 제약사항

• DB 마이그레이션은 항상 bun run db:migrate 사용
• API 키는 절대 코드에 하드코딩 금지
• Prisma 대신 Drizzle ORM 사용

### CLAUDE.md 고급 활용

**자주 쓰는 패턴 기록:**
```markdown
## 반복 패턴

새 API 라우트 추가 시 이 파일을 참고: `app/api/_template/route.ts`
새 DB 테이블 추가 시: schema.ts에 추가 → `bun run db:generate` → `bun run db:migrate`

외부 문서 참조:

## 관련 문서

- API 스펙: docs/api-spec.md
- DB 스키마: docs/schema.md
- 배포 가이드: docs/deploy.md

권한 설정 (.claude/settings.json)

Claude Code는 파일 수정, 터미널 실행, 웹 검색 등 강력한 권한을 요청한다. .claude/settings.json으로 세밀하게 제어할 수 있다.

{
  "permissions": {
    "allow": [
      "Bash(bun run *)",
      "Bash(git log *)",
      "Bash(git diff *)",
      "Bash(cat *)",
      "Bash(ls *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)"
    ]
  }
}

팁: /doctor 명령어로 현재 권한 상태를 확인할 수 있다.

MCP 서버 연동

MCP(Model Context Protocol)는 Claude Code가 외부 서비스와 연동할 수 있게 해주는 프로토콜이다. GitHub, Slack, 데이터베이스, 웹 검색 등을 Claude Code에서 직접 제어할 수 있다.

MCP 서버 추가 방법

# GitHub MCP 서버 추가
claude mcp add github npx @modelcontextprotocol/server-github

# Filesystem MCP 서버 (로컬 파일 접근)
claude mcp add filesystem npx @modelcontextprotocol/server-filesystem /path/to/dir

또는 ~/.claude/settings.json에 직접 추가:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "database.db"]
    }
  }
}

한국 개발자에게 유용한 MCP 서버

서브에이전트 활용 (병렬 작업)

Claude Code의 가장 강력한 기능 중 하나다. 서브에이전트를 사용하면 여러 작업을 동시에 실행할 수 있다.

기본 서브에이전트 패턴

Claude Code에게 지시:
"다음 3개 모듈을 동시에 리팩토링해줘:
1. src/auth/login.ts — 타입 안전성 개선
2. src/db/queries.ts — N+1 쿼리 제거
3. src/api/users.ts — 에러 핸들링 추가
각각 별도 서브에이전트로 실행해줘"

Claude Code는 3개의 서브에이전트를 병렬로 생성해 동시에 작업한다. 순차 실행 대비 3배 빠르다.

서브에이전트 실전 활용 사례

테스트 병렬 작성:

"UserService, AuthService, PaymentService 각각의 unit test를 
별도 서브에이전트로 동시에 작성해줘. Vitest 사용."

멀티 파일 리팩토링:

"app/api/ 폴더의 모든 라우트에 Zod 입력 검증을 추가해줘.
파일당 서브에이전트 하나씩 병렬로 처리해줘."

코드베이스 분석:

"다음을 병렬로 분석해줘:
- 보안 취약점 (SQL injection, XSS)
- 성능 문제 (N+1 쿼리, 불필요한 렌더링)
- 타입 에러 (strict 모드 기준)"

Plan Mode (계획 모드)

복잡한 작업 전에 Plan Mode로 실행 계획을 미리 검토할 수 있다.

# Plan Mode 진입
claude --plan

# 또는 대화 중
/plan

Plan Mode에서 Claude Code는:

1. 변경할 파일 목록을 먼저 보여준다
2. 각 파일에서 할 작업을 설명한다
3. 예상되는 부작용을 경고한다

사용자가 승인하면 실제 실행한다. 대규모 리팩토링이나 DB 마이그레이션 전에 반드시 Plan Mode 사용을 권장한다.

실전 워크플로우 — 한국 스타트업 개발자 패턴

아침 코드 리뷰

cd ~/projects/my-app
claude "어제 생성된 PR들의 diff를 요약하고 리뷰 포인트를 알려줘"

버그 수정

claude "에러 로그: 'Cannot read property of undefined at UserService.ts:42'
이 에러를 찾아서 수정하고 관련 테스트도 추가해줘"

새 기능 개발

claude "결제 이력 페이지를 만들어줘:
- app/dashboard/payments/page.tsx
- Drizzle로 payments 테이블 조회
- 페이지네이션 (페이지당 20개)
- 날짜 필터 (이번 달/지난 달/전체)
- shadcn/ui Table 컴포넌트 사용"

배포 전 체크

claude "배포 전 체크리스트 실행:
1. 타입 에러 없는지 확인
2. 테스트 전체 통과 확인
3. 환경 변수 누락 없는지 확인
4. 보안 취약점 스캔"

비용 관리 팁

Claude Code는 Anthropic API를 사용하므로 비용이 발생한다. 효율적으로 사용하려면:

모델 선택:

/model haiku    # 빠르고 저렴 (단순 작업)
/model sonnet   # 기본값 (대부분의 작업)
/model opus     # 복잡한 설계 결정 (비쌈)

컨텍스트 최적화:

• /clear — 불필요한 컨텍스트 초기화
• /compact — 긴 세션 압축
• CLAUDE.md — 반복 설명 제거

비용 절감 추정:

• Haiku: 작업당 ~$0.002
• Sonnet: 작업당 ~$0.02
• Opus: 작업당 ~$0.10-0.30

하루 50번 작업 기준: Sonnet $1/일, Haiku $0.10/일.

자주 묻는 질문

Q: Claude Code와 일반 Claude 채팅의 차이는? Claude 채팅은 코드를 보여주기만 하지만, Claude Code는 실제로 파일을 수정하고 명령어를 실행한다. 코드를 복사-붙여넣기할 필요가 없다.

Q: 회사 코드베이스에서 사용해도 안전한가? Anthropic은 API 요청을 학습 데이터로 사용하지 않는다. 단, 민감한 시크릿(API 키, 비밀번호)이 코드에 있으면 컨텍스트로 전송되므로 주의해야 한다.

Q: VS Code에서 사용할 수 있나? VS Code 터미널에서 claude 명령어를 실행하면 된다. 별도 Extension은 없지만, 터미널 통합으로 충분히 사용 가능하다.

Q: Cursor와의 차이는? Cursor는 VS Code UI 내에서 인라인 코드 수정에 강하다. Claude Code는 터미널 기반으로 자율 에이전트 작업(여러 파일 동시 수정, 명령어 실행, 장기 작업)에 강하다. 상세 비교 참고.

Q: macOS가 아닌 Windows/Linux에서도 되나? 된다. Windows는 WSL2(Windows Subsystem for Linux)에서 사용을 권장한다. Linux는 그냥 터미널에서 사용.

관련 가이드

• Claude Code Hooks 완전 가이드 — 자동화 트리거 설정
• MCP 서버 베스트 15 — 영어 버전 상세 가이드
• 서브에이전트 병렬 작업 — 영어 상세 가이드

더 깊게 배우기

Power Prompts 300: Claude Code 생산성 패턴 — 한국 개발자가 실제로 쓰는 300개 프롬프트 패턴. CLAUDE.md 템플릿, 서브에이전트 워크플로우, 비용 최적화 전략까지.

→ Power Prompts 300 구매 — $29

30일 환불 보장. 즉시 다운로드.