AI 코딩 도구 시장이 Cursor, Windsurf, Google Antigravity 등으로 빠르게 확장되고 있습니다. 이들은 모두 에디터 기반 — VS Code 포크이거나 독자 IDE입니다.

Claude Code는 접근이 다릅니다. 에디터가 없습니다. 터미널에서 claude를 입력하면 대화가 시작되고, AI가 직접 파일 시스템과 셸에 접근합니다. 에디터는 여러분이 이미 쓰고 있는 것을 그대로 씁니다 — VS Code든 Vim이든 IntelliJ든 상관없습니다.

이 글에서는 설치부터 CLAUDE.md 설정, 고급 확장 기능까지 실전에서 바로 쓸 수 있는 수준으로 정리합니다.

Claude Code가 다른 AI 코딩 도구와 다른 점

구분	Claude Code	Cursor / Windsurf	Google Antigravity
실행 환경	터미널 (CLI)	VS Code 포크 에디터	독자 IDE (웹 기반)
AI 모델	Claude Opus 4.6 / Sonnet 4.6	Claude, GPT 등 선택	Gemini 3.1 Pro
파일 접근	직접 Read/Write/Edit 도구 사용	에디터 내장 API	에이전트 직접 접근
에디터 종속	없음 (어떤 에디터든 병행)	VS Code 필수	Antigravity 전용
확장 시스템	CLAUDE.md + Hooks + MCP + Skills	.cursorrules + MCP	Rules + Workflows + Skills
가격	Pro $20/월부터 (API 종량제도 가능)	월 $20 ~ $40	무료 (프리뷰)

핵심 차이는 “에디터를 바꾸지 않아도 된다”는 점입니다. 터미널 하나만 열면 되기 때문에, 이미 익숙한 개발 환경을 그대로 유지하면서 AI 어시스턴트를 추가하는 형태입니다.

설치 및 초기 설정

필수 조건

• Node.js 18 이상
• 다음 중 하나: Anthropic API 키, Claude Pro ($20/월), Claude Max ($100/월 또는 $200/월)

플랜별 차이

플랜	월 요금	Claude Code 사용	비고
API 종량제	사용량 기반	가능	Sonnet 4.6: 입력 $3/출력 $15 (100만 토큰당)
Pro	$20	가능	claude.ai와 사용량 공유, 5시간 롤링 한도
Max 5x	$100	가능	Pro 대비 5배 사용량
Max 20x	$200	가능	Pro 대비 20배 사용량

Pro 플랜에서도 Claude Code를 쓸 수 있습니다. 다만 claude.ai 웹과 사용량 한도를 공유하고, Claude Code는 하나의 작업에 여러 API 호출을 하므로 체감 한도가 웹 채팅보다 적습니다. 하루 수 시간 이상 사용한다면 Max 플랜이 현실적입니다. 모든 플랜에서 한도 초과 시 Extra Usage로 표준 API 요금이 자동 과금됩니다.

설치

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

설치가 끝나면 프로젝트 디렉터리에서 claude를 실행합니다:

cd my-project
claude

첫 실행 시 인증 과정을 거칩니다. API 키를 직접 입력하거나, Pro/Max 구독이 있으면 브라우저 OAuth로 연결됩니다.

첫 대화 시작하기

$ claude
╭──────────────────────────────────────╮
│ ✻ Welcome to Claude Code!            │
│                                      │
│ /help for help, /status for status   │
╰──────────────────────────────────────╯

> 이 프로젝트의 구조를 분석해줘

Claude Code는 프로젝트의 파일 구조, package.json, 설정 파일 등을 읽고 전체적인 아키텍처를 파악합니다. 첫 번째 대화에서는 /init 명령어로 CLAUDE.md 파일을 자동 생성하는 것을 추천합니다:

> /init

이 명령은 프로젝트를 분석한 뒤 CLAUDE.md 초안을 만들어 줍니다. 여기서부터 본격적인 커스터마이징이 시작됩니다.

<img src="../../assets/blog/claude-code/config.png" alt="CLAUDE.md Configuration 3D Icon" width="800" height="800" style="display: block; margin: 40px auto; border-radius: 20px; box-shadow: 0 20px 40px rgba(0,0,0,0.3);" />

## CLAUDE.md — AI 에이전트의 행동 규칙서

CLAUDE.md는 Claude Code의 가장 중요한 설정 파일입니다. 프로젝트 루트에 두면 <strong>매 대화 시작 시 자동으로 로드</strong>되어 시스템 프롬프트처럼 작동합니다.

### 계층 구조

CLAUDE.md는 3단계 계층을 갖습니다:

~/.claude/CLAUDE.md ← 전역 (모든 프로젝트에 적용) ./CLAUDE.md ← 프로젝트 루트 ./src/components/CLAUDE.md ← 서브디렉터리 (해당 폴더 작업 시만 로드)

전역 파일에는 개인 선호도(언어, 코딩 스타일)를, 프로젝트 파일에는 해당 프로젝트 고유 규칙을, 서브디렉터리 파일에는 특정 모듈의 컨벤션을 넣습니다.

### 실전 CLAUDE.md 예시

아래는 실제 프로젝트에서 사용 중인 CLAUDE.md 구조입니다:

```markdown
# 프로젝트: my-saas-app

## 기술 스택
- Next.js 15 (App Router)
- TypeScript strict mode
- Tailwind CSS v4
- Prisma + PostgreSQL

## 코딩 컨벤션
- 컴포넌트: PascalCase, 한 파일에 한 컴포넌트
- 유틸 함수: camelCase, src/lib/ 디렉터리
- any 타입 사용 금지
- console.log 커밋 금지

## 워크플로우
1. 기능 요청 시 plan.md부터 작성
2. 사용자 승인 후 구현 시작
3. 구현 완료 후 타입 체크 실행: npx tsc --noEmit
4. 테스트 실행: npm test

## 금지 사항
- node_modules, .env 파일 수정 금지
- 기존 API 엔드포인트의 응답 형식 변경 금지
- package.json의 의존성 임의 추가 금지

이 파일이 있으면 매번 “TypeScript로 작성해줘”, “plan부터 세워줘”라고 반복할 필요가 없습니다. Claude Code가 항상 이 규칙을 따릅니다.

핵심 슬래시 커맨드

터미널에서 /를 입력하면 사용 가능한 커맨드 목록이 나타납니다. 자주 쓰는 것들을 정리합니다:

커맨드	기능
/init	프로젝트 분석 후 CLAUDE.md 자동 생성
/help	도움말 표시
/status	현재 모델, 토큰 사용량, 권한 상태 확인
/model	사용할 모델 변경 (Opus ↔ Sonnet ↔ Haiku)
/compact	대화 컨텍스트 압축 (토큰 절약)
/clear	대화 초기화
/cost	현재 세션 비용 확인
/btw	대화 히스토리에 남지 않는 사이드 질문

/btw — 작업을 끊지 않는 사이드 질문

Claude Code가 대규모 리팩터링 중일 때, 갑자기 “이 프로젝트 DB가 뭐였지?” 같은 질문이 떠오를 수 있습니다. 일반 메시지로 보내면 작업이 중단되고, 질문과 응답이 컨텍스트 윈도우에 쌓여 토큰을 소비합니다.

/btw는 이 문제를 해결합니다:

> /btw 이 프로젝트에서 사용하는 ORM이 뭐야?

응답은 닫을 수 있는 오버레이 형태로 표시되고, 대화 히스토리에 기록되지 않습니다. 메인 작업은 중단 없이 계속 진행됩니다.

모델 선택 전략

/model opus     ← 복잡한 아키텍처 설계, 대규모 리팩터링
/model sonnet   ← 일반적인 기능 구현, 버그 수정 (기본값)
/model haiku    ← 단순 질문, 코드 설명, 포맷팅

Opus는 Sonnet 대비 토큰 비용이 약 5배입니다. 모든 작업에 Opus를 쓸 필요 없이, 계획 수립은 Opus, 구현은 Sonnet, 단순 질문은 Haiku로 분리하면 비용을 크게 줄일 수 있습니다.

권한 시스템 — 안전장치가 내장되어 있다

Claude Code는 파일 수정이나 셸 명령 실행 전에 사용자 승인을 요청합니다. 이것이 다른 AI 코딩 도구와의 큰 차이점입니다.

Claude wants to edit src/components/Header.tsx
Allow? (y/n/always)

y는 이번 한 번, always는 같은 유형의 작업을 이후 자동 승인합니다. 권한 설정은 settings.json에서 세밀하게 제어할 수 있습니다:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm test)",
      "Bash(npx tsc*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)"
    ]
  }
}

읽기 도구는 항상 허용하고, 특정 명령만 자동 승인하며, 위험한 명령은 차단하는 구조입니다.

Hooks — 자동 검증 파이프라인

Hooks는 Claude Code의 특정 이벤트 시점에 셸 명령을 자동 실행하는 시스템입니다. CI/CD의 git hooks와 비슷한 개념이지만, AI 에이전트의 행동에 반응한다는 점이 다릅니다.

지원하는 Hook 이벤트

Hook	실행 시점
PreToolUse	도구 실행 직전 (차단 가능)
PostToolUse	도구 실행 직후
Notification	알림 발생 시
Stop	에이전트가 응답을 완료한 직후
SubagentStop	서브에이전트가 완료된 직후

실전 예시: 파일 저장 후 자동 린트

settings.json에 다음을 추가합니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ],
    "Stop": [
      {
        "command": "npx tsc --noEmit 2>&1 | head -20"
      }
    ]
  }
}

이 설정으로 Claude Code가 파일을 수정할 때마다 ESLint가 자동 실행되고, 응답이 끝날 때마다 타입 체크가 돌아갑니다. 수동으로 “린트 돌려줘”, “타입 체크해줘”라고 말할 필요가 없어집니다.

MCP 서버 — 외부 도구와 연결

MCP(Model Context Protocol)는 Claude Code가 외부 서비스의 도구를 호출할 수 있게 해주는 프로토콜입니다. GitHub API, 데이터베이스, Slack 등을 Claude Code에서 직접 사용할 수 있습니다.

MCP 서버 추가

claude mcp add github -- npx -y @modelcontextprotocol/server-github
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres

추가된 서버는 claude mcp list로 확인할 수 있습니다:

$ claude mcp list
github: connected (tools: create_issue, search_repos, ...)
postgres: connected (tools: query, list_tables, ...)

이제 대화에서 “이 버그를 GitHub 이슈로 등록해줘”라고 하면, Claude Code가 MCP를 통해 직접 이슈를 생성합니다.

플러그인 — 기능 확장 패키지

플러그인은 Skills, Hooks, MCP 서버, 커스텀 슬래시 커맨드를 하나의 패키지로 묶어 설치하는 시스템입니다. npm 패키지를 설치하듯, CLI 한 줄로 Claude Code에 새 기능을 추가할 수 있습니다.

플러그인 설치

# 공식 마켓플레이스에서 설치
claude plugin install huggingface-skills@claude-plugins-official

# 프로젝트 스코프로 설치 (팀원과 공유됨, .claude/settings.json에 기록)
claude plugin install qodo-skills@claude-plugins-official --scope project

설치된 플러그인 확인과 관리:

# 목록 확인
claude plugin list

# 비활성화 / 활성화
claude plugin disable huggingface-skills
claude plugin enable huggingface-skills

# 업데이트 / 제거
claude plugin update huggingface-skills
claude plugin uninstall huggingface-skills

마켓플레이스

기본으로 Anthropic 공식 마켓플레이스(anthropics/claude-plugins-official)가 등록되어 있으며, 46개 이상의 플러그인이 포함되어 있습니다. 서드파티 마켓플레이스도 추가할 수 있습니다:

# 서드파티 마켓플레이스 추가
claude plugin marketplace add https://github.com/my-org/claude-plugins

# 등록된 마켓플레이스 확인
claude plugin marketplace list

플러그인의 내부 구조

플러그인은 아래와 같은 디렉터리 구조를 갖습니다:

my-plugin/
  .claude-plugin/
    plugin.json        # 필수: 이름, 버전, 설명 등 메타데이터
  commands/            # 커스텀 슬래시 커맨드
  agents/              # 특화 에이전트 정의
  skills/              # 스킬 (SKILL.md)
  hooks/               # 후크
  .mcp.json            # MCP 서버 설정

plugin.json에는 name, version, description이 필수이고, 나머지 디렉터리는 필요한 것만 포함하면 됩니다. 플러그인 하나가 Skills + Hooks + MCP를 동시에 제공할 수 있다는 점이 개별 설정 대비 편리합니다.

대화 중에 /plugin 커맨드를 입력하면 인터랙티브 플러그인 매니저가 열립니다.

Skills — 재사용 가능한 워크플로우 만들기

Skills는 .claude/skills/ 디렉터리에 마크다운 파일로 저장하는 재사용 프롬프트입니다. Antigravity의 Workflows와 유사한 개념이지만, Claude Code가 맥락에 따라 자동으로 호출 여부를 판단한다는 점이 다릅니다.

스킬 저장 위치

~/.claude/skills/deploy/SKILL.md           ← 전역: 모든 프로젝트에서 사용
.claude/skills/create-blog-post/SKILL.md   ← 프로젝트: 이 프로젝트에서만 사용

SKILL.md 작성법

---
name: deploy
description: >
  프로젝트를 프로덕션에 배포합니다. 사용자가 "배포해줘",
  "deploy", "프로덕션 반영" 같은 요청을 할 때 사용합니다.
---

# 배포 워크플로우

1. `npx tsc --noEmit`으로 타입 체크
2. `npm run build`로 빌드
3. 빌드 성공 시 `npm run deploy` 실행
4. 배포 URL을 사용자에게 보고

frontmatter의 name은 슬래시 커맨드 이름이 됩니다 (위 예시에서 /deploy). description은 Claude Code가 자동 호출 판단에 사용하므로, 언제 이 스킬을 써야 하는지를 구체적으로 적어야 합니다.

자동 호출 vs 수동 호출

기본적으로 Claude Code는 description을 읽고, 사용자의 요청이 스킬에 해당하면 자동으로 호출합니다. 배포나 커밋처럼 부작용이 있는 스킬은 자동 호출을 막을 수 있습니다:

---
name: deploy
description: "프로젝트를 프로덕션에 배포합니다."
disable-model-invocation: true
---

disable-model-invocation: true를 설정하면 사용자가 /deploy를 직접 입력해야만 실행됩니다.

실전 예시: 블로그 포스트 자동 생성 스킬

이 블로그에서 실제로 사용 중인 스킬 구조입니다:

.claude/skills/create-blog-post/
  SKILL.md              # 워크플로우 정의
  scripts/              # 이미지 생성 등 보조 스크립트
  references/           # frontmatter 규칙, SEO 체크리스트 등 참조 문서

SKILL.md 안에서 참조 문서를 references/seo-checklist.md처럼 상대 경로로 불러올 수 있어, 긴 규칙을 SKILL.md 본문에 전부 넣지 않아도 됩니다. SKILL.md는 500줄 이하로 유지하는 것이 권장됩니다.

스킬 생성을 도와주는 플러그인

스킬을 처음 만들 때 구조가 헷갈린다면 skill-creator 플러그인을 설치하세요:

claude plugin install skill-creator@claude-plugins-official

설치 후 “블로그 포스트를 자동 생성하는 스킬을 만들어줘”라고 요청하면, SKILL.md의 초안부터 디렉터리 구조까지 자동으로 생성해 줍니다.

실전 워크플로우: 기능 구현 A to Z

실제로 Claude Code를 사용해 기능을 구현하는 전체 흐름을 보여드립니다.

1. 프로젝트 진입 및 컨텍스트 파악

cd my-project
claude
> 이 프로젝트의 인증 시스템 구조를 분석해줘

Claude Code가 관련 파일을 읽고 아키텍처를 설명합니다.

2. 계획 수립

> 소셜 로그인(Google, GitHub) 기능을 추가하는 plan.md를 작성해줘

CLAUDE.md에 “plan부터 작성” 규칙이 있으면, Claude Code가 코드 대신 계획서를 먼저 생성합니다.

3. 계획 검토 후 실행

plan.md를 검토하고 수정한 뒤:

> plan.md 대로 구현해줘

Claude Code가 파일 생성, 수정, 패키지 설치, 타입 체크까지 순차적으로 수행합니다.

4. 중간 피드백

> GitHub 로그인의 콜백 URL이 잘못됐어. /api/auth/callback/github 이어야 해

구체적인 피드백을 주면 해당 부분만 수정합니다.

5. 마무리

> 테스트 돌려줘
> 이 변경사항으로 커밋 만들어줘

Hooks 설정이 되어 있으면 테스트와 린트가 자동으로 실행된 상태이므로, 커밋만 하면 됩니다.

비용 최적화 팁

Pro 플랜이든 API 종량제든, 토큰을 덜 쓸수록 더 많은 작업을 할 수 있습니다.

1. /compact를 적극 활용하세요. 대화가 길어지면 컨텍스트 윈도우가 차면서 토큰 소비가 급증합니다. 중간중간 /compact로 압축하면 핵심 내용은 유지하면서 토큰을 절약할 수 있습니다.

2. /btw로 사이드 질문을 분리하세요. 작업 중 떠오른 단발성 질문은 /btw로 보내면 대화 히스토리에 쌓이지 않습니다. 컨텍스트 윈도우가 커지는 것을 막아 장기 세션에서 비용 차이가 큽니다.

3. 모델을 작업 유형에 맞게 전환하세요. 단순한 파일 수정이나 질문에 Opus를 쓰면 낭비입니다. /model sonnet이나 /model haiku로 전환하는 습관을 들이세요.

4. CLAUDE.md를 잘 써두면 반복 설명이 줄어듭니다. “TypeScript strict 모드로 작성해줘”를 매번 말하는 것과 CLAUDE.md에 한 번 적어두는 것은, 누적 토큰 차이가 상당합니다.

5. 플랜을 사용량에 맞게 선택하세요. 가볍게 쓴다면 Pro ($20/월)로 충분합니다. 하루 수 시간 이상 사용한다면 Max 5x ($100/월) 또는 Max 20x ($200/월)가 경제적입니다. 모든 플랜에서 한도 초과 시 Extra Usage가 표준 API 요금으로 자동 과금되므로, 갑자기 사용이 차단되지는 않습니다.

Cursor AI vs Claude Code: 둘 다 쓰는 게 정답

이 블로그에서 Cursor AI 설정 가이드를 다룬 적이 있습니다. Cursor와 Claude Code는 경쟁 관계라기보다 상호 보완 관계입니다.

상황	추천 도구
UI 컴포넌트 수정, CSS 미세 조정	Cursor — 시각적 피드백이 중요
대규모 리팩터링, 멀티 파일 수정	Claude Code — 파일 시스템 직접 접근
새 프로젝트 스캐폴딩	Claude Code — 디렉터리 구조부터 생성
코드 리뷰, 디버깅	둘 다 — Cursor는 인라인, Claude Code는 전체 맥락
CI/CD 파이프라인 작업	Claude Code — 터미널 네이티브

Antigravity Rules 설정 가이드에서 다룬 것처럼, 각 도구의 규칙 시스템(CLAUDE.md, .cursorrules, Rules/Workflows)을 프로젝트에 맞게 설정해두면 어떤 도구를 쓰든 일관된 결과물을 얻을 수 있습니다.

자주 묻는 질문 (FAQ)

Claude Code는 무료인가요?

무료가 아닙니다. 가장 저렴한 옵션은 Claude Pro ($20/월)로, claude.ai와 사용량을 공유하며 5시간 롤링 한도가 적용됩니다. API 종량제(Sonnet 4.6 기준 입력 $3/출력 $15, 100만 토큰당)나 Max 플랜($100/월 또는 $200/월)도 선택할 수 있습니다.

CLAUDE.md와 .cursorrules의 차이는 무엇인가요?

역할은 동일합니다 — AI 에이전트에게 프로젝트 규칙을 전달하는 설정 파일입니다. CLAUDE.md는 Claude Code 전용이고 마크다운 형식입니다. .cursorrules는 Cursor AI 전용이며 평문 형식입니다. 두 도구를 함께 사용한다면 두 파일 모두 프로젝트에 두고, 내용을 동기화하면 됩니다.

VS Code에서도 Claude Code를 쓸 수 있나요?

네. Claude Code는 VS Code 확장 프로그램도 제공합니다. 터미널 패널에서 Claude Code를 실행하거나, 전용 확장을 설치하면 에디터 내에서 직접 대화할 수 있습니다. JetBrains IDE용 확장도 있습니다.

Hooks 설정이 잘못되면 위험하지 않나요?

Hooks는 Claude Code가 아닌 로컬 셸에서 실행됩니다. 즉, 여러분의 시스템 환경에서 돌아가는 일반 셸 명령어입니다. settings.json에서 설정하며, 잘못된 Hook은 에러 메시지를 반환할 뿐 Claude Code의 동작을 망가뜨리지 않습니다. 단, rm -rf 같은 위험한 명령을 Hook에 넣지 않도록 주의하세요.

MCP 서버는 어디서 찾나요?

공식 MCP 서버 목록은 modelcontextprotocol.io에서 확인할 수 있습니다. GitHub, PostgreSQL, Slack, 파일 시스템 등 다양한 서버가 제공되며, 직접 만들 수도 있습니다.

플러그인과 스킬의 차이는 무엇인가요?

스킬은 SKILL.md 파일 하나로 만드는 재사용 프롬프트입니다. 플러그인은 스킬, Hooks, MCP 서버, 커스텀 커맨드를 하나의 패키지로 묶은 것입니다. 간단한 워크플로우는 스킬로 충분하고, 외부 도구 연동이나 자동 검증까지 포함해야 한다면 플러그인이 적합합니다.

커스텀 스킬을 만드는 가장 빠른 방법은?

skill-creator 플러그인(claude plugin install skill-creator@claude-plugins-official)을 설치한 뒤, “~하는 스킬을 만들어줘”라고 요청하면 SKILL.md 초안과 디렉터리 구조를 자동 생성해 줍니다.

---