VS Code 클로드 코드(Claude Code) 확장 연동하기: 맥 사용자를 위한 안내

VS Code 클로드 코드(Claude Code) 확장은 편집기 안에서 클로드 코드를 쓰도록 연결해 주는 확장 프로그램입니다. 2026년 10월 4일 기준 확장이 실행에 필요한 프로그램을 내장하고 있어, 터미널 명령어나 Node.js 설치 없이 확장 설치와 브라우저 로그인만으로 시작할 수 있습니다.

이 글은 맥과 VS Code 조합을 기준으로 합니다. 명령을 직접 입력하려면 터미널 설치 가이드, 윈도우를 쓴다면 윈도우용 확장 안내로 이동하면 됩니다. 도구의 역할부터 알고 싶다면 클로드 코드 소개를 먼저 읽어도 좋습니다.

먼저 준비할 편집기와 계정

VS Code는 파일을 열고 수정하는 무료 편집기입니다. 공식 다운로드 페이지에서 설치합니다. 이미 설치했다면 Code > About Visual Studio Code에서 버전을 봅니다. 2026년 10월 4일 공식 사용 문서는 1.94.0 이상, 확장 마켓은 1.98.0 이상을 표시하므로 마켓의 더 높은 요구 조건을 충족하는 최신 안정 버전을 사용합니다.

Claude Code는 무료 Claude 웹 계정만으로 이용할 수 없습니다. Pro, Max, Team, Enterprise 구독이나 AI를 프로그램에서 호출하는 API 사용량을 관리하는 Claude Console 계정 등 지원되는 이용 방식이 필요합니다. Console의 API 사용료는 구독과 별도입니다. 회사 계정에서는 조직이 배정한 접근 권한을 확인합니다. 구독했다고 사용량이 무제한이 되지는 않으며 요금과 한도는 공식 요금 페이지에서 확인합니다.

이 글의 브라우저 로그인 경로에는 API 키를 직접 입력하지 않습니다. 외부 클라우드 제공자나 API 키로 연결하는 방식은 별도 설정이 필요합니다.

확장은 패널을 실행하는 프로그램을 포함합니다. Git이나 Node.js 전체를 대신 설치하는 것은 아닙니다. 이번 메모 실습에는 둘을 먼저 설치할 필요가 없으며, 특정 프로젝트를 실행할 때 필요한 개발 도구는 그때 준비합니다. 터미널의 공식 네이티브 설치도 Homebrew와 Node.js가 필요하지 않습니다. Homebrew는 맥 프로그램을 명령으로 설치하고 관리하는 별도 도구이며 이 확장 연습의 준비물이 아닙니다.

연습 폴더와 메모 만들기

Finder에서 문서 폴더 등 찾기 쉬운 곳을 열고 File > New Folder로 claude-vscode-practice라는 빈 폴더를 만듭니다. 메뉴가 한국어라면 파일 > 새로운 폴더입니다. 같은 이름의 폴더가 있으면 기존 자료를 건드리지 않고 끝에 -2를 붙여 새로 만듭니다. VS Code의 File > Open Folder로 이 폴더를 엽니다. 신뢰 여부를 묻는다면 자신이 방금 만든 빈 폴더인지 확인한 뒤 이 폴더를 신뢰합니다.

VS Code에서 File > New Text File로 새 파일을 만들고 다음을 입력합니다.

⌘ Command는 맥 키보드의 Command 키를 뜻합니다. Command를 누른 채 S를 눌러 방금 연 폴더 안에 practice-note.md로 저장합니다. .md는 제목과 목록을 간단한 기호로 쓰는 마크다운 파일의 확장자입니다. 이 실습에서는 일반 글처럼 입력해도 됩니다. 왼쪽 파일 목록에 파일이 나타나고 다시 클릭했을 때 세 줄이 보이면 준비됐습니다.

VS Code 확장 설치 3단계

준비물이 갖춰졌다면 설치는 3단계입니다.

1. VS Code에서 ⌘ Command + Shift + X를 눌러 확장(Extensions) 화면을 여세요.
2. 검색창에 "Claude Code"를 입력하세요.
3. 게시자가 Anthropic으로 표시된 확장을 찾아 Install 버튼을 누르세요.

비슷한 이름의 확장이 여럿 검색될 수 있습니다. 설치 수만으로 판단하지 말고 공식 확장 마켓 페이지의 식별자 anthropic.claude-code와 게시자 Anthropic을 확인합니다.

✅ 성공 신호: 설치가 끝나면 VS Code 왼쪽 사이드바에 스파크(✱) 모양 아이콘이 새로 생깁니다. 아이콘이 바로 보이지 않으면 ⌘ Command + Shift + P를 눌러 "Developer: Reload Window"를 실행하세요.

아래 이미지는 앤트로픽 공식 문서에 실린 확장 실행 화면입니다. 편집기 오른쪽에 클로드 코드 대화 패널이 붙어 있는 구조입니다.

첫 로그인과 첫 대화 시작

설치 후 처음 패널을 열면 로그인 화면이 나타납니다.

1. 파일을 하나 연 상태에서 편집기 오른쪽 위의 스파크(✱) 아이콘을 누르세요. 파일이 열려 있지 않다면 화면 오른쪽 아래 상태 표시줄의 ✱ Claude Code를 눌러도 됩니다.
2. 패널에 나타난 Sign in 버튼을 누르면 브라우저가 열립니다. 클로드 계정으로 로그인을 마치고 VS Code로 돌아오세요.
3. 메모 본문을 쓰는 편집기가 아니라 Claude Code 대화 패널의 입력창에서 @를 입력하고 practice-note.md를 골라 파일 참조를 붙입니다. 이어서 “이 파일의 할 일 두 개를 그대로 읽어 줘. 파일은 수정하지 마.”라고 보냅니다. 답에 책 10쪽과 산책 20분이 모두 있으면 파일 읽기를 확인한 것입니다.

아래 이미지는 편집기 위쪽 도구 막대에 표시되는 스파크 아이콘의 위치입니다.

다음 요청 전에 입력창 아래 권한 모드를 Manual로 바꿉니다. 파일 수정 전에 제안 내용을 확인하는 모드입니다. Auto나 Edit automatically에서는 별도 질문 없이 파일이 바뀔 수 있습니다. 기존 허용 규칙도 영향을 주므로 현재 표시된 모드를 먼저 봅니다.

같은 파일을 지정해 “산책 20분 하기를 산책 30분 하기로 바꿔 줘. 다른 줄과 파일은 수정하지 마.”라고 요청합니다. 변경 제안에서 대상 파일과 숫자를 확인하고 해당 변경을 허용합니다. 관계없는 수정을 제안하면 거절하고 범위를 다시 말합니다. 작업 중 멈추려면 대화 입력창 옆 중지 버튼을 누릅니다.

위 이미지는 기존 공식 문서의 예시이며, 현재 버전에서는 버튼과 모드 이름이 다를 수 있습니다. 색이 칠해진 부분은 변경 제안입니다. 화면 전체를 외울 필요 없이 바뀌는 파일 이름과 문장부터 확인합니다.

✅ 성공 신호: VS Code 왼쪽 목록에서 practice-note.md를 다시 열었을 때 책 10쪽은 그대로이고 산책만 30분이면 됩니다. AI의 완료 답변만 보고 넘어가지 않습니다. 파일 탭에 저장하지 않은 변경을 뜻하는 점 표시가 있으면 내용을 확인한 뒤 ⌘ Command + S로 저장합니다.

막히는 지점별 확인 순서

확장 설치 뒤에는 폴더 신뢰, 아이콘 표시, 계정과 연결 상태를 나눠 확인합니다.

1. 제한 모드(Restricted Mode)에서 확장이 동작하지 않는 문제

인터넷에서 내려받은 폴더를 처음 열면 VS Code가 "이 폴더의 작성자를 신뢰합니까?"라고 묻고, 신뢰하지 않음을 선택하면 제한 모드로 열립니다. 클로드 코드 확장은 제한 모드에서 동작하지 않습니다. 방금 만든 연습 폴더가 제한 모드라면 화면 위쪽의 제한 모드 안내 배너를 누르거나 ⌘ Command + Shift + P > "Workspaces: Manage Workspace Trust"에서 해당 연습 폴더를 신뢰로 바꿉니다. 출처를 모르는 폴더는 제한 모드를 유지하고, 이번에는 자신이 만든 연습 폴더에서 진행합니다. 상위 폴더 전체를 신뢰할 필요는 없습니다.

2. 스파크 아이콘이 보이지 않는 문제

편집기 위쪽의 스파크 아이콘은 파일이 열려 있을 때만 나타납니다. 폴더만 열어 둔 상태라면 저장한 practice-note.md를 엽니다. 그래도 보이지 않으면 다음 순서로 확인합니다.

• ⌘ Command + Shift + P > "Developer: Reload Window" 실행
• 확장 상세 화면에서 현재 창에 활성화되어 있는지 확인
• VS Code 버전이 마켓의 요구 조건을 충족하는지 확인 (Code > About Visual Studio Code)
• ⌘ Command + Shift + P에서 Claude Code를 검색해 Open in New Tab 같은 열기 명령 실행

3. 패널은 열리는데 답이 오지 않는 문제

로그인 계정과 이용 한도, 표시된 연결 오류를 확인합니다. 파일을 못 찾는다면 연습 폴더가 열려 있는지와 실제 저장한 파일 이름부터 봅니다. 설치 오류와 계정 오류를 구분하지 않은 채 다른 확장을 모두 끄거나 재설치를 반복하지 않습니다.

4. 맥에서 ⌘ Command + Esc가 동작하지 않는 문제

이 단축키는 편집기와 Claude 입력창 사이를 오가는 데 씁니다. macOS Tahoe 이상에서는 게임 오버레이 단축키가 먼저 동작할 수 있습니다. 처음 연습할 때는 입력칸을 마우스로 클릭해도 됩니다.

단축키를 바꾸려면 VS Code에서 ⌘ Command + K를 누른 뒤 ⌘ Command + S를 눌러 Keyboard Shortcuts를 열고 Claude Code: Focus input을 검색해 다른 키를 지정합니다. 기존 게임 오버레이 단축키가 필요 없을 때는 시스템 설정 > 키보드 > 키보드 단축키 > 게임 제어기에서 해당 체크를 해제하는 방법도 있습니다. 아이콘 클릭으로는 정상 작동한다면 단축키 문제만으로 확장을 다시 설치하지 않습니다.

확장과 터미널 CLI의 차이

확장을 설치해도 터미널에서 claude 명령이 바로 동작하지는 않습니다. 확장은 자체 실행용 프로그램을 내부에만 갖고 있어서, 터미널에서 쓰려면 CLI(명령줄 도구)를 따로 설치해야 합니다.

이번 메모 실습은 확장으로 진행할 수 있습니다. 터미널 전용 기능이 필요해지면 CLI를 추가합니다. 대화를 이어 갈 때는 같은 컴퓨터의 같은 프로젝트에서 저장된 기록을 선택하며, 다른 PC까지 자동으로 같은 기록이 생기는 것은 아닙니다.

다음에 혼자 반복하는 방법

다음 날 VS Code에서 같은 연습 폴더와 practice-note.md를 엽니다. Claude Code 패널에서 파일을 지정하고 “현재 할 일을 읽어 줘”라고 요청합니다. 어제 수정한 산책 30분을 읽으면 저장된 파일을 다시 찾은 것입니다.

이번에는 책 10쪽을 15쪽으로 바꾸도록 요청하고 실제 파일을 다시 엽니다. 작업 흐름은 파일 선택, 요청, 변경 검토, 실제 내용 확인 순서입니다. 확장을 매번 다시 설치하지 않습니다.

한 줄만 질문하려면 편집기에서 그 줄을 선택한 뒤 Option + K로 참조를 붙일 수 있습니다. 수정 전 계획을 보고 싶으면 Plan 모드에서 원하는 변경을 설명합니다. 계획을 검토하고 실행으로 넘어간 뒤에도 결과 파일 확인은 필요합니다.

자주 묻는 질문

확장만 설치했는데 터미널의 claude 명령이 안 됩니다

확장 패널이 동작한다면 이것만으로 설치 실패는 아닙니다. 터미널의 claude 명령은 별도로 설치합니다. 지금 연습은 확장만으로 진행할 수 있습니다.

확장과 터미널 설치 중 하나를 지워야 하나요?

둘을 함께 사용할 수 있습니다. 확장은 대화 패널, 별도 CLI는 터미널에서 사용합니다. 같은 맥과 프로젝트의 저장된 대화를 이어서 선택할 수 있습니다.

Cursor에서도 같은 확장을 쓸 수 있나요?

공식 문서는 Cursor와 여러 VS Code 계열 편집기를 안내합니다. 편집기의 확장 화면에서 공식 식별자와 호환 조건을 확인합니다. 설치가 지원되지 않으면 터미널 CLI를 사용하는 방법이 있습니다.

Sources

• Use Claude Code in VS Code (앤트로픽 공식 문서)
• Plans & Pricing (클로드 공식 요금 페이지)
• Visual Studio Code 공식 다운로드
• 공식 확장 마켓과 버전 요구 조건
• VS Code 폴더 신뢰와 제한 모드

3줄 요약

1. 맥 VS Code에 공식 Claude Code 확장을 설치하고 지원 계정으로 로그인합니다.

2. 직접 만든 메모 파일을 지정해 읽고 Manual 모드에서 한 줄을 바꾼 뒤 실제 내용을 확인합니다.

3. 확장과 터미널 설치는 별도이며 오류가 나면 확장 활성 상태와 폴더 신뢰 및 계정 조건을 확인합니다.