> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code for VS Code 사용 튜토리얼

> Claude Code 集成指南 - Ace Data Cloud

Claude Code는 Anthropic이 출시한 **Agentic Coding** 도구로, 세계에서 가장 강력한 프로그래밍 에이전트 중 하나로 알려져 있습니다. Claude Code의 VS Code 확장은 원주율 그래픽 인터페이스를 제공하며, 인라인 Diff 보기, `@`-멘션 참조, 계획 검토 등의 기능을 지원하여 VS Code에서 Claude Code를 사용하는 추천 방법입니다.

이 문서는 AceData Cloud의 프록시 서비스를 통해 VS Code에서 Claude Code 확장을 구성하고 사용하는 방법을 주로 설명합니다.

## 신청 절차

Claude Code를 사용하려면 먼저 [Claude Messages 서비스 페이지](https://platform.acedata.cloud/documents/claude-messages)에서 "Acquire" 버튼을 클릭하여 요청에 필요한 자격 증명을 얻을 수 있습니다:

![](https://cdn.acedata.cloud/nyq0xz.png)

로그인 또는 등록하지 않은 경우 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 로그인 후에는 자동으로 현재 페이지로 돌아옵니다.

첫 신청 시 무료 한도가 제공되어 Claude Code 서비스를 무료로 체험할 수 있습니다.

## 플러그인 설치

### 시스템 요구 사항

* VS Code 1.98.0 이상 버전 (Cursor도 지원)

### 설치 단계

VS Code / Cursor의 확장 마켓에서 `Cmd+Shift+X` (Mac) 또는 `Ctrl+Shift+X` (Windows/Linux)를 눌러 확장 보기를 열고 **Claude Code**를 검색하여 Anthropic 공식에서 발행한 플러그인을 찾아 "Install"을 클릭하여 설치합니다:

![VS Code Marketplace의 Claude Code 플러그인](https://cdn.acedata.cloud/10ddf71320.png)

다음 링크를 통해 직접 설치할 수도 있습니다:

* [VS Code 설치 링크](vscode:extension/anthropic.claude-code)
* [Cursor 설치 링크](cursor:extension/anthropic.claude-code)

설치 후 팝업된 정보 메시지에서 신뢰를 선택하면 설치가 완료됩니다.

> 설치 후 확장이 나타나지 않으면 VS Code를 재시작하거나 명령 팔레트에서 "Developer: Reload Window"를 실행하세요.

## AceData Cloud API 구성

플러그인을 처음 열면 Anthropic 공식 계정으로 로그인하라는 메시지가 표시됩니다. 우리는 공식 로그인을 건너뛰고 AceData Cloud의 프록시 API를 구성하여 사용할 수 있습니다. **공식 구독이 필요 없습니다.**

### 단계 1: 환경 변수 구성

다음 위치 중 하나에서 환경 변수를 구성할 수 있습니다:

**옵션 A: 사용자 수준 구성 (모든 프로젝트에 적용)**

`~/.claude/settings.json`을 편집합니다 (존재하지 않으면 생성) `env` 구성을 추가하고 `{token}`을 AceData Cloud 콘솔에서 가져온 API 토큰으로 교체합니다:

```json theme={null}
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "{token}",
    "ANTHROPIC_BASE_URL": "https://api.acedata.cloud"
  }
}
```

**옵션 B: 프로젝트 수준 구성 (현재 프로젝트에만 적용)**

프로젝트 루트 디렉토리에 `.claude/settings.json` (공유 구성) 또는 `.claude/settings.local.json` (개인 구성, gitignored)을 생성합니다:

```json theme={null}
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "{token}",
    "ANTHROPIC_BASE_URL": "https://api.acedata.cloud"
  }
}
```

> **팁**: API 토큰은 [AceData Cloud 콘솔](https://platform.acedata.cloud/console)에서 확인할 수 있습니다. `ANTHROPIC_AUTH_TOKEN`의 값은 자동으로 `Bearer` 접두사가 추가되어 서버로 전송됩니다. 프로젝트 수준 구성은 사용자 수준 구성보다 우선합니다. 팀 프로젝트에서는 `.claude/settings.json` 공유 구성을 사용하는 것이 좋으며, 개인 민감 정보는 `.claude/settings.local.json`에 보관하세요.

### 단계 2: 로그인 메시지 비활성화 (선택 사항)

매번 열 때 로그인 메시지를 보고 싶지 않다면 VS Code 설정에서 **Disable Login Prompt**를 선택할 수 있습니다:

설정에서 "Claude Code login"을 검색하여 **Disable Login Prompt** 옵션을 찾아 체크하면 됩니다.

구성이 완료되면 Claude Code 플러그인 패널을 다시 열어 정상적으로 사용을 시작할 수 있습니다.

## Claude Code 패널 열기

설치 및 구성이 완료된 후 Claude Code를 여는 방법은 여러 가지가 있습니다:

| 방법            | 작업                                                  |
| ------------- | --------------------------------------------------- |
| **편집기 도구 모음** | 편집기 오른쪽 상단의 ✦ Spark 아이콘 클릭 (파일을 열어야 함)              |
| **상태 표시줄**    | 하단 상태 표시줄 오른쪽의 "✱ Claude Code" 클릭 (파일을 열 필요 없음)     |
| **명령 팔레트**    | `Cmd+Shift+P` / `Ctrl+Shift+P`, "Claude Code" 검색    |
| **단축키**       | `Cmd+Esc` (Mac) / `Ctrl+Esc` (Windows/Linux) 포커스 전환 |

Cursor / Copilot 등의 도구가 사이드바를 사용하는 것과 달리, Claude Code는 기본적으로 **편집 영역 보기**를 채팅 영역으로 사용하여 가시 영역이 더 크고 내용 표시가 더 풍부합니다. 패널을 사이드바나 다른 위치로 드래그할 수도 있습니다.

![VS Code의 Claude Code 패널](https://cdn.acedata.cloud/b84b878420.jpg)

## 기본 사용

### 대화 상호작용

Claude Code 패널에서 자연어로 직접 입력하여 Claude와 상호작용할 수 있습니다. 예를 들어:

* "이 프로젝트의 전체 구조를 분석해줘"
* "이 코드에 버그가 있어, 고쳐줘"
* "이 함수를 리팩토링해서 가독성을 높여줘"
* "이 모듈에 단위 테스트를 작성해줘"

Claude Code는 자동으로 코드베이스의 맥락을 이해하고 파일 간 분석 및 편집을 수행합니다. Claude가 파일을 수정해야 할 경우, Diff 비교 보기를 표시하며, 수정 사항을 수락하거나 거부할 수 있습니다.

![VS Code의 Claude Code 대화 및提示](https://cdn.acedata.cloud/650377f5cc.png)

### 맥락 참조

대화 중에 `@` 기호를 사용하여 특정 파일이나 맥락을 참조할 수 있습니다:

* `@filename.py` — 지정된 파일 참조 (모호한 일치 지원)
* `@src/components/` — 전체 디렉토리 참조 (끝에 슬래시 필요)
* `@terminal:name` — 터미널 출력 참조

편집기에서 코드를 선택한 후 `Option+K` (Mac) / `Alt+K` (Windows/Linux)를 눌러 `@` 참조를 빠르게 삽입할 수 있습니다 (예: `@app.ts#5-10`).

### 슬래시 명령

대화 상자에서 `/` 아이콘을 클릭하거나 직접 `/`를 입력하면 풍부한 내장 기능을 사용할 수 있습니다:

자주 사용하는 명령은 다음과 같습니다:

| 명령         | 기능           |
| ---------- | ------------ |
| `/new`     | 새 대화 시작      |
| `/model`   | 모델 전환        |
| `/compact` | 맥락 압축        |
| `/mcp`     | MCP 서비스 구성   |
| `/config`  | 설정 열기        |
| `/usage`   | 사용량 보기       |
| `/memory`  | Claude 기억 관리 |
| `/help`    | 도움말 표시       |

### 대화 기록 보기

패널 상단의 드롭다운 메뉴를 클릭하면 대화 기록을 볼 수 있으며, 키워드로 검색하거나 시간대별(오늘, 어제, 지난 7일 등)로 탐색할 수 있어 이전 상호작용 내용을 쉽게 되돌아볼 수 있습니다. 임의의 대화를 클릭하면 전체 메시지 기록을 복원할 수 있습니다.

### 코드 변경 검토

Claude가 파일을 수정해야 할 경우, Diff 비교 보기를 표시하여 원본 코드와 수정된 코드의 비교를 보여줍니다. 각 수정 사항을 수락하거나 거부할 수 있으며, Claude에게 원하는 다른 방법을 알려줄 수도 있습니다:
![VS Code 중의 Diff 비교 뷰](https://cdn.acedata.cloud/c42381ea9f.png)

### 권한 모드

패널 하단의 모드 지시기를 통해 다양한 권한 모드를 전환할 수 있습니다:

| 모드                    | 설명                                    |
| --------------------- | ------------------------------------- |
| **Default（Ask）**      | 매번 작업 전에 확인 요청 (기본값)                  |
| **Plan**              | Claude가 먼저 계획을 세우고 승인을 기다린 후, 확인 후 실행 |
| **acceptEdits**       | 파일 편집을 자동으로 수락하지만, 터미널 명령은 여전히 확인 필요  |
| **bypassPermissions** | 모든 권한 알림을 건너뛰고 완전 자동화 (주의해서 사용)       |

### 다중 세션 병렬

명령 패널에서 **Open in New Tab** 또는 **Open in New Window**를 사용하여 여러 개의 독립적인 대화를 시작할 수 있으며, 각 대화는 독립적인 역사와 맥락을 유지하여 서로 다른 작업을 병렬로 처리할 수 있습니다.

## 기타 설정

### 모델 전환

Claude Code는 Claude Sonnet, Claude Opus 등 다양한 모델 전환을 지원합니다. `/model` 명령어를 통해 또는 플러그인 설정의 **Selected Model**에서 구성할 수 있습니다.

### 자동 모드

플러그인 설정에서 **Initial Permission Mode**를 `bypassPermissions`로 설정하면, 활성화 후 Claude Code가 파일 편집, 터미널 명령 등의 작업을 수행할 때 더 이상 개별적으로 팝업 확인을 하지 않고 완전 자동화된 작업 흐름을 구현합니다.

또한 `acceptEdits`로 설정하여 편집을 자동으로 수락하되 터미널 명령은 여전히 확인이 필요한 반자동 모드를 구현할 수 있습니다.

> **주의**: 자동 모드를 활성화하기 전에 그 위험을 이해했는지 확인하고, 신뢰할 수 있는 프로젝트 환경에서 사용하는 것이 좋습니다.

### 터미널에서 CLI 사용

명령줄 스타일을 선호하는 경우, VS Code 설정에서 **Use Terminal**을 선택하면 Claude Code가 CLI 모드로 통합 터미널에서 실행됩니다. 또한 VS Code 통합 터미널을 직접 열고 `claude` 명령을 실행할 수 있습니다.

## 자주 묻는 질문

### 연결 실패 시 어떻게 하나요?

1. `~/.claude/settings.json` 또는 `.claude/settings.json`에서 환경 변수 설정이 올바른지 확인, 특히 `ANTHROPIC_AUTH_TOKEN` 및 `ANTHROPIC_BASE_URL`
2. API 토큰이 유효한지 확인 ( [콘솔](https://platform.acedata.cloud/console)에서 확인 가능)
3. 네트워크 연결이 정상인지 확인하고 `https://api.acedata.cloud`에 접근할 수 있는지 확인
4. VS Code를 재시작한 후 다시 시도

### Spark 아이콘이 나타나지 않나요?

1. 파일이 열려 있는지 확인 (폴더만 여는 것은 충분하지 않음)
2. VS Code 버전이 1.98.0 이상인지 확인
3. 명령 패널에서 「Developer: Reload Window」를 실행
4. 또는 하단 상태 표시줄의 「✱ Claude Code」를 직접 클릭

### 잔여 한도를 어떻게 확인하나요?

[AceData Cloud 콘솔](https://platform.acedata.cloud/console)에 로그인하면 현재 계정의 잔여 한도와 사용 현황을 확인할 수 있습니다.

## 더 알아보기

* 📖 [Claude Code VS Code 공식 문서](https://code.claude.com/docs/en/vs-code)
* ⌨️ [VS Code 명령 및 단축키 참고](https://code.claude.com/docs/en/vs-code#vs-code-commands-and-shortcuts)
* 🔧 [AceData Cloud Claude Code 서비스](https://platform.acedata.cloud/documents/claude-messages)
* 💬 질문이 있으시면 플랫폼 고객 서비스에 문의해 주시기 바랍니다.