Claude Code LSP 설치: AI가 드디어 코드를 "이해하게" 하다
Claude Code LSP 설치: AI가 드디어 코드를 "이해하게" 하다
장기간 Claude Code를 사용해온 개발자로서, 저는 항상 체감해왔습니다: 너무 똑똑하지만, 너무 맹목적입니다. 똑똑한 점은 구조가 좋은 코드를 생성할 수 있다는 것이고; 맹목적인 점은 당신의 코드가 실제로 어떻게 생겼는지 모른다는 것입니다.
그리고 LSP — Language Server Protocol은 그것이 "눈을 뜨게" 하는 중요한 단계입니다.
LSP란 무엇인가? 한 문장으로 설명
LSP, 전체 이름은 Language Server Protocol입니다. 더 쉽게 말하자면:
편집기와 AI가 코드 이해 능력을 갖추게 하는 "통일된 인터페이스"입니다.
당신이 VS Code에서 익숙하게 사용하는 기능:
- Ctrl 클릭으로 함수 이름 정의로 이동
- 변수 위에 마우스를 올려 타입 보기
- 참조 찾기
LSP가 없으면 Claude Code는 어떤 검색도 "Grep 전역 문자열 매칭"에 의존해야 합니다; LSP가 있으면 Claude Code는 언어 서버에 직접 답을 요청할 수 있습니다 — 정확하고, 빠르며, 낮은 Token 소모.
왜 LSP에 관심을 가져야 하는가?
지난 1년 동안 Claude Code로 코드를 작성하면서 가장 힘든 경험은:
Token 소모가 너무 과장되었습니다.
함수를 수정하는 데 도움을 요청하면, 그것은:
- 전체 프로젝트 Grep
- 다시 Grep 참조
- 다시 Grep 정의
- 다시 Grep 호출 체인
Milvus 팀의 실측 데이터는 문제를 잘 설명해줍니다:
LSP를 활성화한 후 Token 소모가 40% 이상 줄어듭니다.
대규모 프로젝트와 빈번한 리팩토링을 하는 팀에게는 직접적인 비용 최적화입니다.
LSP는 무엇을 할 수 있는가? Claude Code가 의존하는 7가지 핵심 능력
2.0.74 버전부터 Claude Code는 공식적으로 LSP를 활성화하며, 백그라운드에서 자동으로 다음 능력을 호출합니다:
- goToDefinition: 정의로 이동
- findReferences: 참조 찾기
- hover: 타입 및 문서 보기
- documentSymbol: 현재 문서의 함수/클래스/변수 나열
- workspaceSymbol: 전체 프로젝트 기호 검색
- goToImplementation: 인터페이스 구현으로 이동
- incomingCalls / outgoingCalls: 호출 체인 분석
더 중요한 것은:
수동으로 트리거할 필요가 없습니다. Claude Code는 자동으로 LSP를 우선 사용하며, Grep이 아닙니다.
LSP 사용 방법 3가지 (추천 순서)
방법 1: VS Code 통합 (가장 간단하고 안정적)
만약 당신이 이미 VS Code를 사용하고 있다면, 거의 비용이 들지 않습니다:
- VS Code 터미널에서 Claude Code 시작
- 입력 /config
- 설정:
- Diff tool = auto Auto-install IDE extension = true
Claude Code는 VS Code를 자동으로 감지하고, LSP와 통신하기 위한 확장을 자동으로 설치합니다.
적합한 대상: 대다수의 개발자.
방법 2: cclsp (커뮤니티 MCP 솔루션)
만약 VS Code를 사용하지 않거나, 공식 LSP에서 다양한 오류가 발생한다면, 이 방법을 사용할 수 있습니다:
npx cclsp@latest setupcclsp의 최대 장점은:
- 자동으로 행과 열 번호 수정
- 다국어에 적합
- 커뮤니티 유지 관리가 활발함
방법 3: 수동으로 .lsp.json 구성 (고수 전용)
프로젝트 루트 디렉토리에 .lsp.json을 새로 만듭니다:
{ "typescript": { "command": "typescript-language-server", "args": ["--stdio"], "extensionToLanguage": { ".ts": "typescript", ".tsx": "typescriptreact" } }, "python": { "command": "pylsp" } }언어 서버는 별도로 설치해야 합니다, 예를 들어:
npm install -g typescript-language-server pip install python-lsp-server
적합한 대상: 환경을 고도로 맞춤화하고 강박증이 있는 엔지니어.
LSP가 실제로 작동하는지 판단하는 방법은?
현재 Anthropic은 명확한 UI 상태 지시를 제공하지 않지만, 다음과 같이 판단할 수 있습니다:
- Claude Code가 정의로 이동하게 하기: "X 함수는 어디에 정의되어 있나요?" 정확한 파일+행 번호를 반환 = 정상; Grep 결과가 반환 = 실패
- cclsp 테스트 명령 사용
- Token 소모 관찰: 몇 만 Token에서 일, 이천 Token으로 줄어드는 것이 가장 뚜렷한 차이입니다.
누가 정말로 LSP 구성이 필요한가?
구성을 추천하는 경우:
- 프로젝트가 1만 줄을 초과
- 빈번한 리팩토링
- Token 비용에 민감
- Claude Code가 IDE 수준의 코드 이해 능력을 갖추기를 원하는 경우
- 작은 프로젝트, 검색이 빠름
- 주로 새로운 코드 작성, 이전 코드 읽지 않음
- 공식적으로 더 안정적인 버전을 기다림
현재 사용 중에 발생하는 주요 문제 (2025년 12월 상황)
- No LSP server available: 일반적으로 언어 서버가 제대로 설치되지 않았습니다.
- 상태 시각화 없음: UI에서 LSP가 연결되었는지 확인할 수 없습니다.
- 호출 체인 등의 작업이 가끔 실패: 파일 간 참조가 불완전합니다.
마지막으로: LSP는 Claude Code의 "시력 업그레이드 패키지"입니다.
과거 AI가 코드를 작성하는 것은 "더듬거리는 이해"와 같았으며, 본질적으로 검색과 패턴 매칭에 의존할 수밖에 없었습니다. 그러나 LSP가 생기면서, 그것은 처음으로 진정한:
프로젝트 구조 이해 → 정확한 위치 지정 → 저비용 코드 처리
당신이 사용하는 언어가 TypeScript 또는 Python이라면, VS Code 통합 버전을 먼저 시도해보는 것을 강력히 추천합니다. 이것은 Claude Code가 진정한 "유용한 개발 도우미"로 변모하는 중요한 단계입니다.
문제가 발생하면, GitHub의 토론 구역과 커뮤니티 솔루션이 매우 활발하므로 빠르게 해결할 수 있습니다.
