Cursor 없이 VS Code에서 Claude Code 에이전트 워크플로우 구축하기

VS Code와 Claude Code로 에이전트 워크플로우 구성하기

Cursor 같은 별도 IDE로 갈아타지 않아도 됩니다. 익숙한 VS Code 환경을 유지하면서 Anthropic 공식 Claude Code 확장 프로그램을 설치하면, 코드 설명·리팩토링·디버깅을 Claude와 협업하는 에이전트 워크플로우를 바로 구성할 수 있습니다. 이 글에서는 설치부터 CLAUDE.md 기반 컨텍스트 관리, 실전 워크플로우 예시까지 단계별로 안내합니다.

왜 VS Code + Claude Code인가

기존 VS Code 환경에는 이미 익숙한 단축키, 수십 개의 확장 프로그램, 팀 공유 설정이 쌓여 있습니다. 새 IDE로 이전하면 이 자산을 처음부터 다시 구성해야 합니다. Anthropic이 공식 제공하는 "Claude Code for VS Code" 확장 프로그램은 이 환경 위에 에이전트 기능을 얹는 방식으로 동작하므로, 기존 워크플로우를 크게 바꾸지 않아도 됩니다 ¹.

다만 한 가지 전제를 짚고 넘어갑니다. "에이전트 워크플로우"라는 표현이 완전한 자율 실행을 연상시킬 수 있지만, 현재 Claude Code는 사용자가 방향을 설정하고 Claude가 실행하는 협업 모델입니다. 제안된 변경 사항은 반드시 사용자 승인을 거칩니다 ².

설치 및 초기 설정

1. 확장 프로그램 설치

Visual Studio Marketplace에서 'Claude Code for VS Code'를 검색하거나 아래 링크에서 직접 설치합니다 ³. 게시자가 Anthropic인지 확인하는 것이 좋습니다.

2. 계정 인증

설치 후 Anthropic 계정(Pro, Max, Team, Enterprise 플랜)으로 로그인합니다. 작성 시점(2026-07) 기준으로 별도 API 키 없이 계정 로그인만으로 인증이 가능합니다 ⁴. 요금제별 제공 기능은 Anthropic 정책에 따라 변동될 수 있으므로, 최신 내용은 공식 문서에서 확인하시기 바랍니다.

3. CLI와의 관계

확장 프로그램은 자체 CLI를 번들로 포함하고 있어 대부분의 에이전트 기능을 VS Code 내에서 사용할 수 있습니다. 다만 일부 고급 기능이나 스크립팅 작업은 독립형 CLI를 별도로 설치해야 할 수 있습니다 ¹.

주요 에이전트 기능

코드베이스 탐색 및 이해 Claude는 프로젝트 구조를 스스로 파악하고, 특정 기능의 위치나 변경 영향 범위를 분석합니다 ⁵.

파일 읽기·쓰기 및 터미널 명령 실행 파일을 직접 수정하거나 터미널 명령을 실행하여 테스트 실행, 환경 설정 등의 작업을 수행할 수 있습니다 ¹.

사용자 정의 슬래시 명령 CLAUDE.md 또는 별도 파일에 특정 작업 지침·템플릿을 정의하면, /<command> 형태의 슬래시 명령으로 반복 작업을 빠르게 실행할 수 있습니다 ¹⁶.

멀티 채팅 지원 (VS Code 1.128+) 2026년 7월 출시된 VS Code 1.128부터 Claude 에이전트 세션에서 멀티 채팅을 지원합니다 ⁶. 한 채팅에서 리팩토링을 논의하면서 다른 채팅에서 테스트 코드를 작성하는 식으로 병렬 작업이 가능합니다.

실전 워크플로우

코드 설명 및 문서화

기존 코드에 docstring이 부족하거나 온보딩 문서가 없을 때 유용합니다. 대상 함수나 파일을 지정하고 설명을 요청하면, Claude가 코드를 분석하여 docstring 초안이나 README 섹션을 제안합니다.

def calculate_complex_metrics(data_points: list[dict]) -> dict:
    """
    주어진 데이터 포인트 목록을 기반으로 통계 지표를 계산합니다.
    각 데이터 포인트는 'value', 'category', 'timestamp' 키를 포함해야 합니다.
    """
    if not data_points:
        return {}

    values = [dp['value'] for dp in data_points]
    # ... 계산 로직 ...

    return {"average": sum(values) / len(values)}

# Claude에게 이 함수의 docstring 보강이나
# README 섹션 초안 작성을 요청할 수 있습니다.

CLAUDE.md에 "모든 공개 함수에는 상세한 docstring이 필요하다"고 명시해 두면, 이후 새 함수 작성 시 Claude가 이 규칙을 반영한 코드를 제안합니다 ¹⁵.

레거시 코드 리팩토링

특정 파일이나 함수를 지정하여 리팩토링을 요청하면, Claude가 변경 사항을 VS Code의 사이드바이사이드(side-by-side) Diff 뷰로 제시합니다. 개발자는 제안 내용을 검토한 뒤 승인 여부를 결정합니다.

최종 결정권은 사람이 가지는 구조이므로, Claude의 제안을 그대로 적용할지 일부만 반영할지 선택할 수 있습니다 ².

버그 디버깅

테스트 실패 로그를 Claude에게 붙여넣고 원인 분석과 수정 제안을 요청합니다. Claude는 관련 파일을 탐색하여 잠재적 원인을 식별하고 수정 코드를 인라인 Diff로 제시합니다. VS Code 통합 터미널에서 수정 후 테스트 명령을 바로 실행하여 결과를 확인할 수 있습니다.

프로젝트 컨텍스트 관리: `CLAUDE.md`

프로젝트 루트에 CLAUDE.md 파일을 두면, Claude가 세션 시작 시 이를 참조하여 프로젝트 아키텍처·코딩 표준·주요 라이브러리 사용 방식 등을 파악합니다 ¹⁵. 새 팀원에게 온보딩 문서를 건네는 것과 비슷한 역할입니다.

단, CLAUDE.md가 모든 암묵적인 규칙을 자동으로 파악하지는 못합니다. 중요한 결정 사항이나 도메인 지식은 명시적으로 문서화해야 Claude가 올바르게 반영합니다 ⁴.

한계와 고려사항

도입 전에 아래 사항을 확인하시기 바랍니다.

자율성의 범위: Claude Code는 완전 자율 실행 도구가 아닙니다. 사용자가 방향을 설정하고 Claude가 실행하는 협업 구조이며, 모든 변경 사항은 사람의 검토를 거칩니다 ².
CLI 전용 기능: 일부 고급 에이전트 기능은 독립형 CLI를 별도로 설치해야 사용할 수 있습니다 ¹.
CLAUDE.md의 한계: 파일에 명시되지 않은 암묵적 규칙은 Claude가 파악하지 못할 수 있습니다. 중요한 정보는 반드시 명시적으로 기록해야 합니다 ⁴.
성능 수치 부재: 확장 프로그램의 응답 속도나 리소스 사용량에 대한 공식 벤치마크는 작성 시점(2026-07) 기준으로 확인되지 않습니다.
요금 및 기능 변동: 플랜별 제공 기능과 요금은 Anthropic 정책에 따라 변경될 수 있습니다. 최신 정보는 공식 문서에서 확인하시기 바랍니다.

정리

VS Code + Claude Code 조합은 기존 개발 환경을 유지하면서 에이전트 기능을 추가하려는 개발자에게 현실적인 선택지입니다. CLAUDE.md로 프로젝트 컨텍스트를 관리하고, Diff 뷰와 통합 터미널을 활용하면 코드 설명·리팩토링·디버깅 작업을 Claude와 효율적으로 분담할 수 있습니다. 다만 에이전트의 자율성에는 명확한 한계가 있으며, 중요한 결정은 여전히 개발자의 몫입니다.