claude_code_vs 딥다이브
— Claude Code를 Visual Studio에 붙이는 "프로토콜 브리지"

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

한 문장으로: "Claude Code의 두뇌(CLI)는 그대로 두고, Visual Studio라는 새 몸(IDE)에 신경을 연결하는 어댑터"다. 모델 호출도, 에이전트 루프도, 스킬·플러그인도 이 확장은 만들지 않는다 — 그건 전부 CLI가 공짜로 제공한다.

2왜 주목받는가

왜 TrendShift에 오르고 개발자들이 주목하는가.

이 레포가 화제가 된 배경에는 실제로 비어 있던 구멍이 있다. Anthropic 공식 이슈 claude-code#15942에서 "Visual Studio(VS Code 아님) 통합이 없다"는 요청이 쌓였는데, 공식 지원을 기다리는 대신 한 개발자가 문서도 없는 프로토콜을 역설계해 직접 메웠다는 점이 인상적이다.

3기술 스택 전체 지도

VSIX 확장이 무엇으로, 어떤 제약 위에 만들어졌는가.

이 레포는 순수 C# (.NET) 기반 Visual Studio 확장이다. 외부 의존을 최소화하고 VS SDK가 기본 제공하는 것만 쓴 점이 특징이다. 약 4,600줄 / 37개 C# 파일로, 두 개의 어셈블리(Protocol + VSIX)로 나뉜다.

두 어셈블리의 분리

4아키텍처 심화 — 프로토콜 브리지의 해부

CLI의 한 번의 요청이 VS diff 창에 닿기까지의 전체 경로.

핵심은 두 개의 채널이다. ① CLI ↔ 확장 사이의 WebSocket(MCP) 채널과, ② 수정을 가로채는 PreToolUse 훅 → HTTP POST /permission 채널. 둘이 합쳐져 "VS diff = 유일한 승인 게이트"가 완성된다.

핵심 설계 패턴 4가지

5디렉토리 구조 해부

37개 C# 파일이 책임별로 어떻게 나뉘는가.

구조에서 읽히는 의도: Protocol(재사용)과 VSIX(VS 종속)의 칼 같은 분리, 도구 하나당 파일 하나(IIdeTool 구현), 그리고 테스트용 spike/를 따로 둬 VS를 띄우지 않고도 프로토콜 회귀를 빠르게 잡는다. demo/의 "의도된 컴파일 에러"는 데모 GIF가 항상 똑같이 재현되도록 만든 장치다.

6학습 포인트 (기술별)

이 레포를 읽으며 실제로 손에 남기면 좋은 것들.

MCP / JSON-RPC 프로토콜 직접 구현

이 레포의 가장 큰 가치. McpServer.cs는 initialize → tools/list → tools/call로 이어지는 MCP 핸드셰이크를 손으로 짠다. 라이브러리 없이 JSON-RPC 한 프레임을 받아 어떻게 처리하는지 보면 MCP의 실체가 또렷해진다.

// McpServer.HandleAsync — 한 프레임을 받아 메서드별 분기
switch (method)
{
    case "initialize":  // 클라이언트 protocolVersion을 그대로 에코
        return Response(id, BuildInitializeResult(@params));
    case "tools/list":  // 우리가 가진 12개 IDE 도구 목록 반환
        return Response(id, BuildToolsList());
    case "tools/call":  // 실제 도구 호출 (openDiff·getDiagnostics…)
        return Response(id, await BuildToolCallResultAsync(@params, ct));
    case "ping":  return Response(id, new JObject());
}

배울 핵심: 요청(id 있음) vs 알림(id 없음) 구분, 버전 에코(protocolVersion을 받은 그대로 돌려주기), 반환 포맷(평문 문자열은 그대로, 객체는 JSON 래핑, 에러는 MCP isError 플래그).

로컬 서버 보안의 기본기

"내 PC에서만 도는데 보안이 왜 필요?"의 답이 여기 있다. 서버는 ① 127.0.0.1에만 바인딩(외부 접근 차단), ② HTTP 업그레이드 단계에서 인증 토큰 검증(소켓이 열리기 전에 401로 거절), ③ 토큰은 절대 로그에 안 남김. 로컬 서비스도 같은 PC의 다른 프로세스가 노릴 수 있다는 위협 모델을 보여준다.

// 소켓을 만들기 전에 인증부터 — 미인증 클라이언트는 소켓조차 못 받음
var presented = ctx.Request.Headers[AuthHeader];
if (!string.Equals(presented, _authToken, StringComparison.Ordinal))
{
    ctx.Response.StatusCode = 401;   // 토큰 값은 로그에 안 찍음
    ctx.Response.Close();
    return;
}

훅(Hook)으로 외부 도구의 흐름에 끼어들기

PowerShell 훅(vs-permission-hook.ps1)은 CLI의 PreToolUse 시점에 끼어들어 수정 내용을 가로챈다. 여기서 배울 디테일: UTF-8 인코딩 함정. stdin·파일·HTTP 본문을 모두 명시적으로 UTF-8로 다루지 않으면 em-dash·스마트 따옴표가 깨져 diff 재구성이 실패한다 — 실무에서 자주 만나는 미묘한 버그.

7시스템 요구사항

이 확장을 쓰거나 빌드하려면 무엇이 필요한가.

8직접 해볼 수 있는 실습 과제

레포를 "읽기"에서 "이해하기"로 바꾸는 난이도별 과제.

9관련 기술 심화 학습 로드맵

이 레포를 온전히 이해하기 위한 4주 코스.

10핵심 키워드 사전

레포를 읽다 막히는 용어 빠른 참조.

11참고 링크

• GitHub: firish/claude_code_vs
• 발단이 된 이슈: claude-code#15942 (Visual Studio 통합 요청)
• 마켓플레이스: Claude Code for Visual Studio
• Claude Code 공식 문서: docs.claude.com/claude-code
• MCP 사양: modelcontextprotocol.io
• JSON-RPC 2.0: jsonrpc.org/specification
• VS 확장 개발: Microsoft VSSDK 문서