DEV Community

Sangmin Lee
Sangmin Lee

Posted on • Originally published at claudeguide.io

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

#mcp

Originally published at claudeguide.io/claude-code-korean-guide

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

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

설치 및 초기 설정

1단계: Node.js 확인

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

node --version   # v18.0.0 이상이어야 함
Enter fullscreen mode Exit fullscreen mode

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

2단계: Claude Code 설치 

npm install -g @anthropic-ai/claude-code
Enter fullscreen mode Exit fullscreen mode

설치 후 버전 확인:

claude --version
Enter fullscreen mode Exit fullscreen mode

3단계: Anthropic 계정 인증 

claude
Enter fullscreen mode Exit fullscreen mode

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

API 키로 직접 인증하려면:

export ANTHROPIC_API_KEY="sk-ant-api03-..."
claude
Enter fullscreen mode Exit fullscreen mode

기본 사용법

대화형 모드

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

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

주요 슬래시 커맨드

명령어 기능
/help 사용 가능한 모든 커맨드 목록
/clear 현재 대화 컨텍스트 초기화
/compact 컨텍스트 압축 (긴 세션용)
/doctor 환경 진단 (권한, MCP 상태 등)
/init CLAUDE.md 초기화
/model 사용 모델 전환 (Haiku/Sonnet/Opus)

비대화형 1회성 실행 

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

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

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

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 컴포넌트

## 개발 명령어
Enter fullscreen mode Exit fullscreen mode


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


## 중요 제약사항

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


markdown

CLAUDE.md 고급 활용

자주 쓰는 패턴 기록:

## 반복 패턴

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

외부 문서 참조:

## 관련 문서

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

권한 설정 (.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 *)"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

팁: /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
Enter fullscreen mode Exit fullscreen mode

또는 ~/.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"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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

MCP 서버 용도 설치 명령
@modelcontextprotocol/server-github PR 리뷰, 이슈 관리 npx @modelcontextprotocol/server-github
@modelcontextprotocol/server-filesystem 대용량 파일 접근 npx @modelcontextprotocol/server-filesystem
@modelcontextprotocol/server-postgres DB 직접 쿼리 npx @modelcontextprotocol/server-postgres
@modelcontextprotocol/server-brave-search 웹 검색 npx @modelcontextprotocol/server-brave-search

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

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

기본 서브에이전트 패턴 

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

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

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

테스트 병렬 작성:

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

멀티 파일 리팩토링:

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

코드베이스 분석:

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

Plan Mode (계획 모드)

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

# Plan Mode 진입
claude --plan

# 또는 대화 중
/plan
Enter fullscreen mode Exit fullscreen mode

Plan Mode에서 Claude Code는:

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

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

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

아침 코드 리뷰 

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

버그 수정 

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

새 기능 개발 

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

배포 전 체크 

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

비용 관리 팁

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

모델 선택:

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

컨텍스트 최적화:

  • /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는 그냥 터미널에서 사용.

관련 가이드

더 깊게 배우기

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

→ Power Prompts 300 구매 — $29

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

Top comments (0)