IDE에서 쓰는 Claude Code: 플러그인이 주는 것과 자주 막히는 곳

플러그인을 설치하고, 버튼을 찾아서 눌러 봅니다. 그러면 첫인상은 대개 이렇습니다. 별도의 터미널 창으로 전환하지 않고 claude를 실행하는 방법이구나. 물론 편리합니다. 하지만 버튼 하나 때문에 플러그인을 따로 설치한다는 건 좀 이상한 일이겠죠.

이 첫인상은 틀렸습니다. IDE 안의 터미널은 플러그인 이전에도 있었고, 거기에 claude를 직접 입력하는 걸 막는 사람도 없었습니다. 플러그인이 하는 일은 따로 있습니다. 에이전트와 에디터를 연결해서 서로를 볼 수 있게 해 줍니다. 지금 무엇을 열어 두고 무엇을 선택했는지, 린터가 무엇을 지적하는지, 제안된 수정이 줄 단위로 어떻게 생겼는지. 이런 걸 더 이상 여러분이 일일이 설명해 줄 필요가 없어집니다. 버튼 하나로 실행하는 기능은 이 묶음에서 가장 재미없는 부분입니다.

Claude Code는 원래 터미널 도구라서 IDE 없이도 잘 동작합니다. 터미널을 열고 claude를 입력한 다음, 평소 쓰는 말로 적으면 됩니다.

차이는 에이전트가 실행되느냐 마느냐에 있지 않습니다. 에이전트의 작업을 무엇으로 확인하느냐에 있습니다. 에이전트는 디스크의 파일을 실제로 바꿉니다. 에디터가 닫혀 있으면 여러분 손에 남는 건 보고뿐입니다. "메서드 세 개에 오류 처리를 추가했습니다". 그럴듯하게 들립니다. 그런데 대조해 볼 대상이 없습니다.

플러그인은 바로 이 틈을 메웁니다. 아래에서는 플러그인이 무엇을 주는지, 그리고 사람들이 어디서 가장 자주 막히는지 살펴봅니다.

1. 에디터와 연결하면 얻는 것

공식 플러그인이 할 수 있는 일은 다섯 가지입니다. 애초에 이 모든 걸 만든 이유가 된 기능부터 차례대로 보겠습니다.

• IDE 창에서 보는 diff. diff는 변경 사항 목록입니다. 어떤 줄이 삭제되고 어떤 줄이 추가됐는지, 이전 버전과 새 버전 사이에 무엇이 바뀌었는지를 보여 줍니다. 에이전트의 수정은 터미널의 텍스트가 아니라 에디터의 익숙한 diff 뷰어에서 열립니다. 왼쪽이 이전, 오른쪽이 이후입니다.
• 선택 영역 컨텍스트. 열려 있는 탭과 선택한 코드 조각이 알아서 에이전트에게 전달됩니다. 코드를 채팅에 복사해 넣고 어느 부분 얘기인지 말로 설명할 필요가 없습니다.
• 에이전트에게 코드 보내기. 코드 조각을 선택하고 단축키를 누르면 딱 그 줄들을 가리키는 참조가 @src/auth.ts#L1-99 같은 형태로 프롬프트에 들어갑니다.
• IDE 진단 정보. 에디터가 빨간 줄로 표시하는 린터 오류와 구문 오류는 여러분이 따로 설명하지 않아도 Claude가 IDE에서 직접 가져올 수 있습니다. 이 기능은 보통 가장 늦게 알게 되는데, 사실 가장 유용한 기능 중 하나입니다. 다만 수정할 때마다 오류를 자동으로 확인하지는 않으므로, 필요하면 파일의 오류를 확인해 달라고 요청하세요.
• 빠른 실행. IDE 패널의 Claude 로고나 단축키를 누르면, 에디터를 떠나지 않고 에이전트가 열립니다.

2. 설치: 한 가지가 아니라 두 가지

가장 많이 막히는 곳이 여기입니다. 플러그인 안에 Claude Code가 들어 있는 게 아닙니다. 플러그인은 IDE의 통합 터미널에서 claude 명령을 실행하고 거기에 연결됩니다. 그러니 두 가지를 모두 설치해야 합니다.

1. Claude Code 자체 - 설치되어 있지 않으면 플러그인이 솔직하게 Cannot launch Claude Code라고 알려 줍니다.
2. Anthropic PBC의 Claude Code [Beta] 플러그인 - Marketplace에서 설치하며, 설치 후에는 IDE를 완전히 재시작하는 게 좋습니다. 재시작을 한 번 더 해야 할 때도 있습니다.

claude가 설치되어 있는데 IDE가 찾는 위치에 있지 않다면, Settings → Tools → Claude Code [Beta] → Claude command에 전체 경로를 적어 주면 됩니다.

3. 바로 필요한 단축키

표의 마지막 줄은 장식이 아닙니다. 단축키가 항상 동작하지는 않습니다. 운영체제가 키 조합을 가로채기도 하고, 다른 플러그인이 가로채기도 합니다. 고장도 아니고 IDE를 고칠 이유도 아닙니다. 마우스로 여세요. 조금 느리지만 어디서나 됩니다.

오래 찾을 필요는 없습니다. 플러그인 아이콘은 인터페이스 곳곳에서 보는 바로 그 Claude 로고입니다. 다른 것과 헷갈릴 일은 없습니다.

Send to Claude Code

두 번째 단축키가 가장 자주 쓰입니다. 코드 조각을 선택하고 Ctrl+Alt+K를 누르면, 딱 그 줄들을 가리키는 참조가 에이전트의 프롬프트로 들어갑니다. 선택 영역의 작업 메뉴에도 같은 기능이 Send to Claude Code 항목으로 있습니다.

프롬프트에는 이런 줄이 나타납니다. 파일 경로와 줄 범위입니다.

@presentations/assets/slides.css#L29-30

그다음 이 줄 뒤에 할 일을 평소 말투로 덧붙이면 됩니다.

@presentations/assets/slides.css#L29-30 margin-left 지워 주세요, 이것 때문에 좁은 화면에서 레이아웃이 깨져요

양쪽 모두 이득입니다. 에이전트는 파일을 찾느라 단계를 쓰지 않고, 여러분은 그 검색에 컨텍스트를 쓰지 않습니다.

플러그인이 없다면

줄 참조는 IDE 자체 기능으로도 만들 수 있습니다. 해당 줄에서 마우스 오른쪽 클릭 - Copy / Paste Special - Copy Reference. 그러면 클립보드에 src/utils/slides.js:16이 들어갑니다.

형식은 다릅니다. @가 없고 콜론으로 구분합니다. 이건 파일을 컨텍스트에 자동으로 넣어 주는 게 아니라 그냥 요청 속 텍스트일 뿐입니다. 그래도 "여기를 봐" 하는 표시로는 충분히 통합니다. 에이전트가 경로를 읽고 필요한 위치를 스스로 엽니다.

4. 두 가지 실행 방법과 /ide 명령

IDE의 내장 터미널에서 claude를 실행하면 모든 기능이 알아서 켜집니다. 따로 할 일은 없습니다.

외부 터미널(별도 창, Windows Terminal, iTerm)에서 실행했다면, 직접 지시하기 전까지는 에디터와 연결되지 않습니다.

# 열려 있는 IDE에 Claude Code 연결하기
/ide

저라면 그냥 IDE 터미널에서 에이전트를 실행하는 걸 습관으로 삼겠습니다. 그러면 /ide를 떠올릴 일 자체가 없습니다. 이 명령이 필요한 경우는 딱 하나, 터미널이 외부에 있을 때뿐입니다.

실행하는 폴더에 대해서도 한 가지 덧붙이겠습니다. 에이전트는 자신이 시작된 위치의 파일을 봅니다. 옆 폴더에서 실행하면 엉뚱한 파일로 작업하게 됩니다. 여러분의 프로젝트라면 IDE에 열려 있는 것과 같은 프로젝트 루트에서 실행하세요.

코스 과제는 다릅니다. 에이전트는 과제 폴더에서 실행하세요. codegym-project의 루트가 아닙니다. 이 프로젝트에서는 과제 하나하나가 자기 파일과 에이전트용 규칙을 가진 별도의 폴더라서, 프로젝트 루트에서 실행하면 코스 전체가 한꺼번에 에이전트의 시야에 들어옵니다.

5. diff를 어디에 보여 줄까

변경 사항을 정확히 어디에 보여 줄지는 고정된 게 아니라 설정에 달려 있습니다.

# Claude Code 설정 열기
/config

여기에 diff tool 항목이 있습니다. 값이 auto이면 수정 내용을 IDE에서 보여 주고, terminal이면 터미널에 그대로 둡니다. 이 항목은 에이전트가 IDE에 연결되어 있을 때만 나타나므로, 외부 터미널에서는 먼저 /ide를 실행하세요. diff가 고집스럽게 터미널에만 나온다면 플러그인에서 고장을 찾을 게 아니라 이 설정을 봐야 합니다.

터미널에서는 diff가 대략 이런 텍스트로 나옵니다.

diff --git a/src/main/java/RefundQueue.java b/src/main/java/RefundQueue.java
index 3a7f2bc..9d41a80 100644
--- a/src/main/java/RefundQueue.java
+++ b/src/main/java/RefundQueue.java
@@ -42,7 +42,7 @@ void prioritize(RefundRequest refundRequest) {
-    if (refundRequest.isUrgent()) {
+    if (refundRequest.isUrgent() || refundRequest.amount() > 100) {
         moveToTop(refundRequest);
     }
 }

읽는 법은 이렇습니다. 마이너스가 붙은 줄은 원래 있던 것이고, 플러스가 붙은 줄은 바뀐 결과입니다. 나머지는 전부 어느 파일인지, 몇 번째 줄부터 보여 주는 조각인지 알려 주는 부가 헤더입니다.

이제 IDE 표시를 켤 만한 진짜 이유입니다. Claude가 수정할 때마다 허락을 구하는 모드에서는, 그 질문이 터미널의 텍스트로만 오지 않습니다. IDEA가 Reject와 Apply 버튼이 있는 자체 diff 창에서 변경 사항을 열어 줍니다. 파일 전체의 맥락 속에서 강조 표시된 줄을 보고 그 자리에서 결정하면 됩니다.

콘솔의 텍스트 diff와는 비교 자체가 안 됩니다. 구문 강조가 있고, 주변 줄이 보이고, 익숙한 탐색 기능도 그대로 쓸 수 있습니다. "받아들일까 말까"를 코드에 대한 설명이 아니라 코드를 보고 결정하게 됩니다.

6. 흔히 겪는 함정 세 가지

Esc로 에이전트가 멈추지 않는다

JetBrains 터미널에서 Esc 키는 기본적으로 포커스를 에디터로 옮기기 때문에, Claude Code까지 아예 전달되지 않습니다. 곤란한 상황입니다. 에이전트가 엉뚱한 일을 하고 있어서 Esc를 누르는데 아무 일도 일어나지 않으니까요.

한 번만 고치면 됩니다. Settings → Tools → Terminal에서 Move focus to the editor with Escape 체크를 해제하세요. 저라면 이런 일을 처음 겪을 때까지 기다리지 않고 플러그인을 설치하자마자 바로 해 두겠습니다.

"No available IDEs detected"

에이전트가 에디터를 보지 못하는 상태입니다. 다음을 순서대로 확인하세요. 플러그인이 설치되어 있고 활성화되어 있는지, IDE를 완전히 재시작했는지, claude를 외부 창이 아니라 내장 터미널에서 실행했는지.

WSL: 에이전트는 Linux에, IDE는 Windows에

같은 오류의 특수한 경우입니다. Claude Code는 WSL2에서, IDE는 Windows에서 돌아가고 있다면 보통 WSL2의 네트워크 격리나 방화벽이 연결을 막습니다. 방화벽 규칙을 추가하거나 WSL2를 mirrored networking 모드로 전환하면 해결되며, 두 방법 모두 플러그인 문서에 자세히 나와 있습니다. mirrored networking은 Windows 11 22H2 이상에서만 지원되므로, Windows 10에서는 방화벽 규칙만 남습니다.

7. 결국 무엇을 위한 것인가

IDE와의 연결이 주는 핵심은 이것입니다. 에이전트가 무엇을 하는지, 하고 있는 그 순간에 볼 수 있습니다. 그다음 리듬은 이렇게 흘러갑니다.

1. Claude가 변경을 제안합니다.
2. 여러분이 diff를 보고 받아들일지 말지 결정합니다.
3. Git이 여러분이 받아들인 것을 기록합니다.

세 번째 단계는 여기서 짚고만 넘어갑니다. Git 리듬, 커밋과 되돌리기는 그 자체로 큰 주제라서 코스 뒷부분에서 다시 다룹니다. 지금은 한 가지만 기억하면 충분합니다. 저장 지점은 여러분이 확인한 뒤에 생기지, 그 전에 생기지 않습니다.

이 사이클이 매끄럽게 돌아가는 건 도식 속에서만입니다. 실제로 일할 때는 절반쯤이 변수 이름 변경 같은 수정이라 보지도 않고 받아들이고, 어떤 수정 하나에는 10분쯤 붙잡혀 있다가 다시 해 달라고 하게 됩니다. 그래도 괜찮습니다. 핵심은 모든 줄을 꼼꼼히 읽는 게 아니라, 수정이 이상해 보이는 순간에 확인할 수 있는 수단이 있다는 것입니다.

에디터가 없으면 그런 수단 자체가 없습니다. 코드가 아니라 설명과 대조할 수밖에 없습니다.