TechLog
블로그로 돌아가기

Claude Code에서 LSP 설정하기 — 코드 탐색 속도를 50배 빠르게

(수정됨: 2026년 3월 10일)
tipclaude code

Claude Code는 기본적으로 코드베이스를 탐색할 때 grep과 glob을 사용합니다. 텍스트 기반 검색이라 "이 함수 정의가 어디 있지?"라고 물으면 수십 개의 매치를 하나씩 읽어가며 찾아야 하죠. 30~60초가 걸리는 작업이 LSP를 활성화하면 약 50ms로 줄어듭니다. IDE에서 "Go to Definition"이 동작하는 것과 같은 원리입니다.

이 글에서는 Claude Code에 LSP를 설정하고 언어별 서버를 설치하는 방법을 간단하게 정리합니다.

LSP란?

Language Server Protocol은 Microsoft가 2016년에 만든 표준 프로토콜입니다. 에디터와 언어 서버 사이의 통신 규약으로, VS Code에서 함수 위에 마우스를 올리면 타입 정보가 뜨고, "Go to Definition"으로 정의부로 점프하고, 빨간 밑줄로 에러를 알려주는 것이 모두 LSP 덕분입니다.

Claude Code에 LSP를 연결하면 동일한 기능을 AI가 사용하게 됩니다:

  • goToDefinition — 심볼의 정확한 정의 위치로 이동
  • findReferences — 함수/변수가 사용된 모든 곳 탐색
  • hover — 타입 정보 확인
  • diagnostics — 파일 수정 후 실시간 에러 감지

사전 준비

  • Claude Code v2.0.74 이상 (claude --version으로 확인)
  • 사용할 언어의 Language Server 바이너리가 $PATH에 존재해야 함

Step 1: LSP 도구 활성화

~/.claude/settings.json에 ENABLE_LSP_TOOL 환경변수를 추가합니다:

JSON
{
  "env": {
    "ENABLE_LSP_TOOL": "1"
  }
}

쉘 프로파일(.zshrc, .bashrc)에도 fallback으로 추가해두면 안전합니다:

Bash
export ENABLE_LSP_TOOL=1

참고: ENABLE_LSP_TOOL은 v2.0.74에서 공식 changelog에 등장했으며, 이전에는 GitHub Issue #15619를 통해 커뮤니티에서 발견된 플래그였습니다. 향후 버전에서 변경되거나 불필요해질 수 있습니다.

Step 2: Language Server 바이너리 설치

사용하는 언어에 맞는 Language Server를 설치합니다. Claude Code가 사용하는 서버는 VS Code 등 IDE에서 쓰는 것과 동일합니다.

TypeScript / JavaScript

Bash
npm install -g @vtsls/language-server typescript

Python

Bash
pip install pyright
# 또는
npm install -g pyright

Go

Bash
go install golang.org/x/tools/gopls@latest

$GOPATH/bin이 $PATH에 포함되어 있는지 확인하세요.

Rust

Bash
rustup component add rust-analyzer

Dart

Bash
# Flutter SDK에 포함되어 있음
# dart language-server 경로가 $PATH에 있는지 확인

기타 언어

Java(jdtls), C/C++(clangd), C#(roslyn), PHP(intelephense), Kotlin(kotlin-lsp), Ruby(solargraph) 등도 지원됩니다. 각 언어 서버를 설치하고 $PATH에 등록하면 됩니다.

Step 3: LSP 플러그인 설치

Claude Code는 플러그인 마켓플레이스 시스템을 통해 LSP 서버를 관리합니다. 공식 Anthropic 마켓플레이스(claude-plugins-official)는 자동으로 사용 가능합니다.

공식 마켓플레이스에서 설치

Claude Code 세션 내에서 /plugin 명령을 실행하고, 원하는 언어의 플러그인을 선택하여 설치합니다:

TEXT
/plugin

Browse 탭에서 사용할 플러그인을 스페이스바로 선택하고 설치합니다.

CLI로 직접 설치

Bash
claude plugin install pyright-lsp@claude-plugins-official
claude plugin install typescript-lsp@claude-plugins-official
claude plugin install gopls-lsp@claude-plugins-official

서드파티 마켓플레이스 (선택사항)

더 많은 언어를 지원하는 커뮤니티 마켓플레이스도 있습니다:

Bash
claude plugin marketplace add boostvolt/claude-code-lsps

claude plugin marketplace add Piebald-AI/claude-code-lsps

이 마켓플레이스는 Dart, Vue, OCaml, Ada 등 추가 언어를 지원합니다.

플러그인 활성화 확인

설치 후 플러그인이 disabled 상태일 수 있습니다. 이것이 가장 흔한 문제입니다:

Bash
claude plugin list
# Status: disabled인 플러그인이 있다면:
claude plugin enable <플러그인명>

settings.json에 명시적으로 활성화해두면 더 확실합니다:

JSON
{
  "env": {
    "ENABLE_LSP_TOOL": "1"
  },
  "enabledPlugins": {
    "pyright-lsp@claude-plugins-official": true,
    "typescript-lsp@claude-plugins-official": true
  }
}

Step 4: 확인 및 재시작

설정을 마쳤으면 Claude Code를 재시작합니다. 디버그 로그에서 LSP 서버 로딩을 확인할 수 있습니다:

TEXT
~/.claude/debug/latest

로그에서 Total LSP servers loaded: N을 검색합니다. N > 0이면 성공입니다.

실제로 동작하는지 테스트해보세요:

TEXT
> 이 프로젝트에서 ConfigManager 클래스가 어디에 정의되어 있어?

LSP가 활성화되면 ● LSP(operation: "goToDefinition", ...) 같은 로그가 보이면서 정확한 파일과 라인 번호를 바로 반환합니다.

트러블슈팅

증상해결 방법
"No LSP server available for file type"해당 언어의 바이너리가 $PATH에 있는지 확인, 플러그인이 enabled인지 확인
플러그인 설치 후에도 동작 안 함Claude Code 재시작 필수
/plugin Errors 탭에 "Executable not found"Language Server 바이너리 재설치 및 PATH 확인
LSP가 가끔만 사용됨CLAUDE.md에 "코드 탐색 시 LSP를 우선 사용하세요" 지시를 추가

CLAUDE.md에 LSP 우선 사용 지시 추가

Claude Code는 기본 시스템 프롬프트에서 grep/glob을 먼저 사용하도록 되어 있습니다. LSP 사용 빈도를 높이려면 프로젝트 루트의 CLAUDE.md에 다음을 추가하세요:

Markdown
## 코드 탐색

- 함수 정의 찾기, 참조 탐색, 타입 확인 시 LSP 도구를 우선 사용하세요.
- grep/glob은 텍스트 검색이나 파일 탐색에만 사용하세요.

다만 시스템 프롬프트와 경쟁하기 때문에 항상 LSP가 우선 선택되지는 않을 수 있습니다. LSP와 grep은 대체 관계가 아니라 상호 보완 관계로 이해하는 것이 좋습니다.

마무리

설정에 2분이면 충분합니다. LSP를 활성화하면 Claude Code가 코드의 구조를 텍스트가 아닌 의미 단위로 이해하게 되어, 대규모 코드베이스에서 정의 탐색과 리팩토링이 훨씬 정확하고 빨라집니다. 아직 실험적 기능에 가까운 면이 있지만, 한번 설정해두면 확실히 체감되는 차이입니다.

댓글