VS Code에서 Claude Code: 확장 사용 방법

기능 섹션에서 다뤘듯, 계획 모드는 큰 변경에 적합합니다. 그때 건너뛴 세부가 하나 있습니다. Claude는 먼저 탐색 명령을 실행하고 전체 계획을 파일로 저장합니다. 어떤 것도 쓰기 전에 댓글을 달아 두세요. 계획 문서는 나중에 대부분을 바꾸게 되더라도 유용합니다.

정밀한 컨텍스트가 필요하면 줄 범위를 포함한 @ 멘션을 사용하세요: @app.ts#5-10처럼 지정하면 특정 영역에 집중합니다. 파일을 프롬프트 창으로 드래그할 때 Shift 를 누르고 있으면 첨부로 추가됩니다. Mac의 Option+K(Windows/Linux의 Alt+K)는 현재 파일과 선택 영역의 @ 멘션을 바로 삽입합니다.

알아두면 좋은 VS Code 키보드 단축키

다음 단축키는 Anthropic의 VS Code 확장 문서에서 가져왔으며, 패널에서 자주 사용하는 것들입니다.

권한 모드 순환은 여전히 CLI에 있습니다. 통합 터미널에서 Shift+Tab을 눌러 기본, 계획, 자동 수락 모드 사이를 전환하세요. 전체 슬래시 명령 목록은 Claude Code 슬래시 명령 가이드를 참고하세요.

체크포인트는 세션 전반에 걸친 Claude의 파일 편집을 추적합니다. 대화의 어떤 메시지 위든 마우스를 올리면 되감기 버튼이 나타납니다. 옵션은 다음과 같습니다: 코드 변경을 유지한 채 대화를 분기, 대화 기록을 유지한 채 코드를 되감기, 또는 둘 다. 체크포인트는 30일 동안 유지됩니다. rm, mv, cp 같은 bash 명령은 체크포인트 대상이 아닙니다. 파괴적 변경에 대한 궁극의 안전망은 여전히 git입니다.

VS Code에서의 디버깅과 리팩터링

두 워크플로는 같은 단계를 따릅니다. 컨텍스트 제공, 제안 변경 검토, 결과 검증. 핵심은 적절한 컨텍스트를 수집하는 데 있습니다.

디버깅

오류를 직접 붙여넣거나 @terminal:name으로 터미널 출력을 참조하세요. 또는 mcp__ide__getDiagnostics를 통해 Claude가 문제 패널에서 직접 가져오도록 하세요. Claude는 근본 원인을 추적하고 diff 형태로 수정안을 제시하며, 테스트 실행으로 결과를 검증합니다.

Claude Code는 VS Code의 네이티브 디버거와 통합되지 않습니다. 브레이크포인트, 단계 실행, 실시간 변수는 지원되지 않습니다. 오류 붙여넣기와 진단 경로로 대부분의 사례를 처리할 수 있습니다. 네이티브 디버거가 꼭 필요하다면, 이를 연결해 주는 커뮤니티 MCP 서버(claude-debugs-for-you, GitHub에서 제공)가 있으나 별도의 설정이 필요합니다.

실시간 웹 디버깅의 경우 @browser 를 사용해 Chrome용 Claude 확장(버전 1.0.36 이상)으로 Chrome과 연결합니다. @browser go to localhost:3000 and check the console for errors 같은 프롬프트로 창 전환 없이 실시간 브라우저 상태를 점검할 수 있습니다.

리팩터リング

Claude는 큰 코드베이스 전반의 함수 이름 변경, 라이브러리 마이그레이션처럼 파일 간 연동 변경을 잘 처리합니다. 이를 무모하지 않게 만드는 것은 바로 diff 리뷰 단계입니다.

여기서는 CLAUDE.md 파일의 중요성이 글 전체 중 가장 큽니다. 프로젝트별 규칙이 로드되지 않으면 Claude는 코드베이스에서 추론한 패턴을 기본값으로 삼는데, 이는 실제로 원하는 것과 다를 수 있습니다. 설정 섹션에서 언급했듯 /init 은 시작용 파일을 제공합니다. 큰 리팩터링 세션 전에 10분 투자해 다듬을 가치가 있습니다.

컨텍스트 압축은 긴 세션의 현실적 한계입니다. 컨텍스트 창이 가득 차면 Claude는 이전 대화를 요약해 자동 압축합니다. 이후에는 초기 결정들을 잃어버릴 수 있습니다. 새 단계로 넘어가기 전에 /compact 를 수동 실행하면 작업 도중 자동 압축이 개입하는 것보다 결과가 예측 가능합니다.

VS Code의 Claude Code vs. 터미널 워크플로

Anthropic 문서는 VS Code 확장을 "VS Code에서 Claude Code를 사용하는 권장 방법"이라고 밝힙니다. 확장은 터미널에서는 불가능한 기능을 제공합니다. 나란히 보는 diff 뷰어, 편집 가능한 마크다운 문서로의 계획 검토, 별도 탭의 다중 대화, 실시간 웹 디버깅을 위한 @browser 등이 그렇습니다.

기능 자체는 터미널이 우위입니다. ! bash 단축키, 탭 완성, 전체 슬래시 명령 세트, tail -200 app.log | claude -p "..." 같은 파이프형 워크플로는 모두 CLI 전용입니다. MCP 서버 구성도 터미널에서만 가능합니다. 확장에서는 /mcp로 기존 서버를 관리할 수 있지만 새로 추가할 수는 없습니다.

두 방식은 상호 배타적이지 않습니다. VS Code 통합 터미널에서 claude를 실행하면 여전히 IDE 통합을 활용할 수 있습니다. diff 보기, 선택 영역 컨텍스트 공유, 진단 공유가 모두 동작합니다. 확장에서 시작한 세션은 claude --resume으로 터미널에서 이어갈 수 있습니다. VS Code diff 뷰어와 진단 브리지를 CLI에 강제로 연결하려면 통합 터미널에서 claude --ide를 실행하세요.

대부분의 개발자는 두 가지를 모두 사용합니다. VS Code는 다중 파일 작업과 면밀한 검토에, 터미널은 빠른 작업과 자동화에. 일부는 모든 것을 터미널에서 처리하기도 하며, 솔직히 그것도 충분히 잘 작동합니다. Cursor를 VS Code보다 선호한다면, Cursor에서의 Claude Code 가이드에서 동일한 확장 워크플로를 확인할 수 있습니다. 또한 전체 CLI 워크플로는 어떤 경우에도 알아두면 좋습니다.

VS Code의 Claude Code vs. GitHub Copilot

처음에 언급했듯, "VS Code의 Claude"는 네이티브 확장, GitHub Copilot 모델 선택기를 통한 접근, 또는 통합 터미널에서의 CLI를 의미할 수 있습니다. 네이티브 확장과 Copilot은 모델은 공유하지만 제품은 다르며, 작동 방식도 꽤 다릅니다.

Copilot을 통해 Claude 모델을 사용할 경우 GitHub의 채팅/완성 패러다임 안에서 구동됩니다. 로컬 OS 샌드박스, 사용자 정의 MCP 통합, 네이티브 터미널 명령은 없습니다. Claude Code 확장을 통해서는 동일한 모델이 최대 100만 토큰 컨텍스트 창으로 실행되며, 파일 전반의 작업을 수행하고, 체크포인트, 계획 모드, MCP 서버에 접근합니다.

두 도구는 서로 다른 일을 위해 만들어졌습니다. Copilot의 핵심 기능은 인라인 자동 완성입니다. Claude Code는 자동 완성을 제공하지 않습니다. Copilot의 에이전트 모드는 많이 발전했지만, 커뮤니티 벤치마크에서는 다중 파일에 걸친 작업에서 다소 뒤처지는 경향이 있습니다. 어느 쪽이 본질적으로 더 낫다고 할 수는 없습니다.

네이티브 확장과 Copilot: 같은 모델, 다른 경험. 이미지: 작성자.

가격 측면에서 보면 Copilot Pro는 월 $10에 프리미엄 요청 300건을 제공합니다. Claude Code Pro는 월 $20입니다. 두 제품을 함께 쓰는 개발자들 사이에서 흔한 조합은 Copilot $10(타이핑 중 자동 완성)과 Claude Code $20(숙고가 필요한 대규모 작업)입니다. 두 제품은 겹침 없이 워크플로의 다른 부분을 담당합니다. Anthropic은 GitHub와 협력해 Copilot 내부에 Claude 모델을 제공하고 있어 자동 완성 측면을 담당합니다.

보안 및 개인정보 보호 고려 사항

Anthropic은 사용자의 코드를 Claude 모델 학습에 사용하지 않습니다. Free, Pro, Max 사용자는 계정 설정에서 데이터 로깅을 완전히 옵트아웃할 수 있습니다. 권한 모드, MCP 서버, VS Code 표면 너머의 샌드박스 세부 정보는 Claude Code 보안 가이드를 참고하세요.

일정 경로 집합은 모드와 무관하게 항상 보호됩니다: .git, .vscode, .idea, .husky, .claude(자체 작업 하위 디렉터리는 예외), 그리고 .gitconfig, .gitmodules 및 여러 셸/도구 구성 파일. 이는 중단 없이 쓰기를 수행하는 자동 수락 모드에서 특히 중요합니다. 이 모드는 settings.json과 tasks.json을 건드릴 수 있습니다. 커밋 전에는 git diff를 꼭 확인하세요.

샌드박싱은 bash 명령을 작업 디렉터리로 격리하고 무단 네트워크 접근을 차단합니다. 기본적으로 꺼져 있으며, /sandbox로 켤 수 있습니다.

자동 모드는 작업별 승인을 분류기로 대체해 실행 전 작업을 검토합니다. 대량 파일 삭제, 무단 엔드포인트로의 데이터 전송, main에 대한 강제 푸시 등을 차단합니다. Anthropic은 이를 --dangerously-skip-permissions의 더 안전한 대안으로 설명합니다.

로컬 대화 기록은 30일 동안 평문으로 ~/.claude/projects/ 아래 저장됩니다(cleanupPeriodDays로 조정 가능). Amazon Bedrock, Google Vertex AI, Microsoft Foundry의 엔터프라이즈 설정은 각 제공업체의 데이터 약관을 따릅니다. 자동 모드는 이러한 제공업체에서는 사용할 수 없으며, Anthropic API 직접 연결이 필요합니다.

일반적인 VS Code 확장 문제 해결

대부분의 설정 문제는 짧은 목록에 속합니다. 저도 하나하나 겪어봤습니다.

• 스파크 아이콘이 보이지 않음: 폴더가 아닌 실제 파일을 여세요. 명령 팔레트에서 Developer: Reload Window를 실행하거나(창 다시 로드), 상태 표시줄(오른쪽 하단)의 스파크 항목을 클릭하세요. 파일이 없어도 동작합니다.

• 확장 충돌: Claude Code가 활성화되지 않으면 다른 AI 확장(Cline, Continue 등)을 일시적으로 비활성화하세요.

• 제한 모드: VS Code 제한 모드에서는 Claude Code가 실행되지 않습니다. 워크스페이스를 신뢰됨으로 표시하세요.

• Windows 파일 잠금: 세션 중간에 쓰기가 실패한다면 탐색기 창을 접고 활성 디버거를 일시 중지한 뒤 대규모 다중 파일 세션을 진행하세요.

• macOS Tahoe의 Cmd+Esc 충돌: 시스템 Game Overlay가 Cmd+Esc를 가로챌 수 있습니다. 포커스 전환이 작동하지 않으면 VS Code 키보드 단축키(Cmd+K Cmd+S)에서 Claude Code: Focus input을 재할당하세요.

• Anthropic 로그인 대신 Bedrock 또는 Vertex 사용: Claude Code를 클라우드 제공업체 엔드포인트로 지정할 수 있습니다. 구독 없이 사용하는 경로는 로컬 및 대체 모델 설정 가이드를 참고하세요.

Anthropic은 전용 문제 해결 가이드도 운영하고 있으니 위의 방법으로 해결되지 않으면 참고하세요.

제한 사항과 트레이드오프

확장은 CLI의 부분집합입니다. 터미널 비교 섹션에서 다룬 대로, 탭 완성, ! bash 단축키, 파이프형 워크플로는 모두 CLI 전용이며, CI 파이프라인용 dontAsk 모드도 마찬가지입니다.

백그라운드 작업 가시성은 제한적입니다. 면밀히 관찰해야 하는 작업은 통합 터미널이 더 투명합니다.

승인은 파일 단위이며 헝크 단위가 아닙니다. 같은 파일에서 어떤 함수는 맞고 다른 함수는 틀렸다면, 일단 모두 수락한 뒤 원치 않는 부분을 수동으로 되돌려야 합니다.

사용 한도는 대부분의 Pro 사용자가 처음 맞닥뜨리는 불만입니다. 속도 제한은 메시지 단위가 아닌 롤링 윈도로 적용되며, 피크 시간대에는 더 빨리 소진됩니다. 가끔 사용하는 용도라면 Pro로 충분하지만, 하루 종일 사용한다면 Max 5x 또는 Max 20x가 현실적입니다. 커뮤니티 추정치에 의존하지 마세요. Anthropic은 정확한 수치를 공개하지 않으며 변동됩니다.

Windows에서는 VS Code의 프로젝트 탐색기와 Claude의 쓰기 작업 사이 파일 잠금으로 인해 macOS나 Linux보다 실패가 잦습니다. 대규모 다중 파일 세션 전에는 탐색기 창을 접고 활성 디버거를 일시 중지하는 것이 예방에 도움이 됩니다.

마무리

VS Code의 Claude Code는 검토 우선 UI를 갖춘 작업 지향형 코딩 에이전트입니다. diff 뷰어, 계획 모드, 체크포인트는 에이전트가 실제로 무엇을 변경했는지 포착하는 것이 빠른 초안보다 더 중요하기 때문에 존재합니다.

터미널 워크플로는 사라지지 않습니다. 스크립트화, 자동화, CLI 중심 작업에는 여전히 더 적합합니다. 하지만 적용 전 제안 변경 사항을 모두 꼼꼼히 읽고 싶다면, 에디터가 더 알맞습니다.

Claude Code는 매주 업데이트되므로 본문 중 일부는 빠르게 구식이 될 수 있습니다. 최신 동향을 따라가려면 Claude Code 모범 사례와 Claude Code 2.1 가이드를 권합니다. 공식 변경 로그에서 릴리스 내역을 확인할 수 있습니다. 여기 내용과 실제 화면이 다르다면 우선 거기를 확인하세요.

Claude 모델과 에이전트 워크플로를 체계적으로 익히고 싶다면 당사의 Introduction to Claude Models 과정을 추천합니다.