Quick Reference
VS Code 확장은 편집기 안에서 Claude Code의 대화·계획·diff 검토를 제공하는 그래픽 표면입니다. VS Code 1.94 이상과 유료 Claude 구독 또는 Claude Console 계정이 필요합니다. 확장 패널에는 자체 CLI가 포함되지만, 통합 터미널에서 claude를 실행하려면 독립 CLI 설치가 별도로 필요합니다.
| 작업 | 확장에서 바로 하는 일 | CLI가 더 직접적인 경우 |
|---|---|---|
| 특정 코드 검토 | 선택 영역 자동 공유, @파일#줄 참조, side-by-side diff | 파일 전체 검색·셸 파이프가 필요한 경우 |
| 계획 검토·수정 | Plan에서 계획 문서를 열어 주석으로 피드백 | 비대화형 실행·자동화가 필요한 경우 |
| 세션 관리 | 탭·창별 대화, 과거 세션·원격 세션 재개 | 터미널에서 --resume 등 CLI 흐름을 쓸 때 |
| MCP 설정 | 기존 서버를 /mcp로 관리 | 서버 추가와 전체 설정은 CLI가 필요할 때가 많습니다. |
선택 코드가 중요할 때
1. 편집기에서 범위를 선택한다.
2. Prompt footer에서 선택 줄 수와 공개 상태를 확인한다.
3. Option+K(macOS) / Alt+K(Windows·Linux)로 @-mention을 넣는다.
4. 목표·수정 허용 범위·검증 명령을 함께 요청한다.설치와 문맥 전달
VS Code의 Extensions 화면에서 Claude Code를 설치하고, 처음 열 때 브라우저에서 로그인합니다. 설치 뒤 Spark 아이콘이 보이지 않으면 창을 다시 열거나 Command Palette에서 Developer: Reload Window를 실행합니다. 편집기 도구 모음의 Spark 아이콘은 파일을 열었을 때만 나타나지만, Activity Bar와 상태 표시줄에서도 세션을 열 수 있습니다.
코드를 선택하면 확장은 선택한 텍스트를 자동으로 문맥에 포함합니다. Prompt footer의 선택 표시를 눌러 공유 여부를 끌 수 있으므로, 민감한 코드나 너무 큰 범위를 보낼 때는 전송 전에 표시를 확인합니다. Option+K 또는 Alt+K는 현재 파일과 선택 줄을 @app.ts#5-10 같은 명시적인 참조로 넣습니다. 대화가 길거나 재검토를 요청할 때는 선택 자동 공유에만 기대지 말고 이 참조를 남기는 편이 안전합니다.
@src/auth/session.ts#40-90
이 범위에서 null 처리 때문에 실패할 수 있는 경로를 설명해 줘.
수정이 필요하면 auth/ 아래 파일만 바꾸고, 수정 전 변경 계획과 수정 후 테스트 명령을 보여 줘.변경과 권한 검토
확장은 파일 변경 전에 기존 내용과 제안 내용을 나란히 보여 주고 승인을 묻습니다. diff 안에서 제안 내용을 직접 고치고 승인하면 Claude는 그 수정 사실을 전달받으므로, 원래 제안과 실제 적용 결과가 다를 수 있습니다. Plan 모드에서는 변경 전에 계획 문서가 열리며, 그 안에 주석으로 피드백을 남길 수 있습니다.
claudeCode.initialPermissionMode의 기본값은 default이며, 확장에서는 manual이라는 이름으로도 보입니다. plan, acceptEdits, bypassPermissions 같은 모드는 승인 폭을 바꾸므로, 신뢰하지 않은 저장소에서는 VS Code Restricted Mode와 수동 승인을 우선하고 diff를 직접 읽습니다. 자동 편집 권한을 켜면 settings.json, tasks.json처럼 VS Code가 자동 실행할 수 있는 구성 파일도 바뀔 수 있습니다.
확장 설정과 CLI 설정
VS Code 확장 설정은 패널 동작, 기본 권한 모드, 통합 터미널 사용 같은 IDE 표면을 관리합니다. 반면 ~/.claude/settings.json의 Claude Code 설정은 확장과 CLI가 함께 쓰며, 허용 명령, 환경 변수, hook, MCP 서버를 관리합니다. 같은 이름의 설정처럼 보여도 어디에서 읽히는지 다르므로 문제를 한 곳에서만 고치지 않습니다.
| 구분 | 대표 설정 | 주의할 점 |
|---|---|---|
| VS Code 확장 | claudeCode.initialPermissionMode, useTerminal, IDE 키보드 단축키 | 확장의 새 대화와 화면 동작을 바꿉니다. |
| Claude Code 공통 설정 | ~/.claude/settings.json, MCP, hook, 허용 명령 | 확장과 CLI 양쪽에 영향을 줄 수 있습니다. |
| 독립 CLI | 셸 PATH의 claude | 확장 설치만으로는 통합 터미널에서 쓸 수 없습니다. |
확장은 모든 CLI 기능을 그대로 옮긴 것이 아닙니다. CLI는 모든 명령·skill, ! Bash 단축키, 탭 완성을 제공하지만, 확장은 지원하는 명령·skill의 일부만 표시합니다. CLI 전용 기능이 필요하면 독립 CLI를 설치한 뒤 VS Code 통합 터미널에서 claude를 실행합니다.
자주 틀리는 부분
IDE가 선택한 줄을 보인다는 것과 안전하게 제한됐다는 것은 다릅니다. 선택 영역 밖의 도구 호출·파일 검색·공통 설정은 별도 권한 경계를 따릅니다. 민감한 저장소에서는 요청 범위, 권한 모드, 실제 diff와 실행 명령을 함께 확인해야 합니다.
확장이 로그인 화면으로 돌아갈 때
- VS Code를 터미널의 code .으로 열어 환경 변수를 상속했는지 확인한다.
- 그래도 안 되면 Claude 계정 로그인으로 인증하고 창을 다시 불러온다.
통합 터미널에서 claude를 찾지 못할 때
- 확장 패널은 자체 CLI를 쓰지만 PATH에는 추가하지 않습니다.
- 독립 CLI를 설치한 뒤 새 터미널에서 claude --version을 확인합니다.참고 링크
1 sources