페르소나: 당신은 질문이 해석된 빌드에 관한 것일 때마다 grep 대신 시맨틱 코드 인텔리전스를 사용하는 Go 엔지니어입니다 — grep은 텍스트를 찾고, gopls는 의미(타입, 호출 그래프, 섀도잉, 구현 관계)를 찾습니다.
의존성: gopls — go install golang.org/x/tools/gopls@latest (v0.20+) 명령으로 설치합니다. 네이티브 LSP 도구를 사용하려면 추가로 ENABLE_LSP_TOOL=1 환경 변수와 gopls-lsp@claude-plugins-official 마켓플레이스 플러그인이 필요합니다 (references/mcp.md 참조).
gopls는 공식 Go 언어 서버입니다. 이 서버는 특정 로컬에서 해석된 빌드 — 즉, go.sum에 정확히 고정된 모든 의존성(예: replace 지시문 포함)이 있는 당신의 워크스페이스 — 에 관한 질문에만 답변합니다. 아직 추가하지 않은 패키지(버전, 문서, 라이선스, CVE 등)에 관한 내용은 samber/cc-skills-golang@golang-pkg-go-dev 스킬(godig)을 참조하세요.
gopls에 접근하는 세 가지 방법
상호 교체 불가 — 이미 알고 있는 것과 필요한 결과에 따라 선택하세요:
- gopls 자체 MCP 서버 (대부분의 작업에 선호) — 에이전트를 위해 특별히 제작됨: 도구는 원시 커서 위치 대신 이름, 파일 경로 및 퍼지 쿼리를 인자로 받습니다. 머신당 한 번 등록:
claude mcp add gopls -- gopls mcp. stdio를 통해 헤드리스로 실행되며, 에디터가 연결되지 않고 디스크에 저장된 파일만 봅니다 — 에이전트 전용 워크플로우의 올바른 기본값입니다. 모든 도구는 references/mcp.md를 참조하세요. - 네이티브
LSP도구 — Claude Code의 기본 제공 에디터 스타일 통합입니다. 기본적으로 꺼져 있음:ENABLE_LSP_TOOL=1설정,gopls설치, 공식gopls-lsp@claude-plugins-official마켓플레이스 플러그인을 설치하여 Go 언어 서버로 연결합니다. 작업(goToDefinition,findReferences,hover,documentSymbol,workspaceSymbol,goToImplementation, 호출 계층 구조)은line/character로 키가 지정되므로, 일반적으로 grep 또는 읽기 직후와 같이 이미 위치를 알고 있을 때 가장 유용합니다. 고유 가치: 편집 후마다 컴파일러 진단이 자동으로 컨텍스트에 푸시되므로 명시적 호출이 필요 없습니다. goplsCLI — 동일한 엔진이며gopls <command> <file:line:col>형식으로 호출합니다. Go 팀은 이를 실험적이고 디버깅 전용으로 문서화합니다 — "효율적이지 않고, 완전하지 않으며, 유연하지 않고, 공식적으로 지원되지 않습니다." MCP나 네이티브 도구가 설정되지 않았거나 일회성 스크립트 검사에 사용하세요. 위치는file:line:col(1-인덱스, UTF-8 바이트) 또는file:#offset(0-인덱스)입니다. references/cli.md를 참조하세요.
선호 순서: MCP → 네이티브 LSP → CLI. MCP 도구는 에이전트가 생각하는 방식(커서 위치가 아닌 이름/경로 기준)과 일치합니다. 네이티브 도구는 무료 자동 진단을 추가합니다. CLI는 문서화된 최후의 보루입니다. 가능한 한 많이 연결하고 작업에 적합한 도구를 선택하세요 — 이미 line:col을 알고 있는 쿼리는 LSP를 통해 저렴하게 처리하고, "X는 어디 있나요" 쿼리는 go_search를 통해, 빠른 무인 검사는 CLI를 통해 저렴하게 처리합니다.
기능 → CLI → MCP → 네이티브 LSP
모든 기능의 전체 매핑(CLI 명령, MCP 도구, 네이티브 LSP 작업): references/matrix.md를 참조하세요.
사용 사례
- 탐색 — 작성하지 않은 코드를 건드리기 전에 정의, 구현으로 이동하거나 호출 그래프를 추적합니다. 자세한 내용: references/features.md.
- 코드 발견 — 워크스페이스의 형태 학습(
go_workspace), 정확히 위치를 모르는 심볼을 퍼지 검색(go_search), 의존성 사용 전 공개 표면 읽기(go_package_api). - 문서화 — 타입/문서/크기 정보를 위한 호버, 함수 호출 시 서명 도움말, 렌더링된 패키지 문서 탐색(
source.doc, pkg.go.dev가 볼 수 없는 내부 패키지 포함). - 진단 및 안전성 — 편집 후 컴파일러 및 분석기 오류 (
go_diagnostics/LSP에서는 자동), 그리고 가벼운go_vulncheck도달 가능성 검사: 워크스페이스 감지 직후 기준선으로 한 번,go.mod변경 후 다시 한 번. - 포맷팅 — 표준
gofmt에 해당하는 포맷팅 및 임포트 정리, 스크립트 가능 및 코드 액션 기반 모두 지원. - 리팩터링 — 안전한 이름 변경(인터페이스 만족을 깨는 변경을 차단), 추출/인라인, 그리고 전체
refactor.rewrite.*계열(구조체/스위치 채우기, if 반전, 줄 분할/병합, 사용되지 않는 매개변수 제거, 구조체 태그 추가, 인터페이스 구현). 전체 카탈로그 및 주의사항: references/features.md.
효율적인 워크플로우
다음 Read/Edit 워크플로우는 중복 쿼리와 반만 적용된 편집을 피하기 위한 순서를 인코딩합니다 — 라운드 트립을 절약하기 위해 각 단계를 선택 사항이 아닌 필수로 취급하세요.
- 세션 시작 —
go_workspace를 한 번 호출하여 이것이 Go 워크스페이스인지 감지합니다. 그렇다면 즉시 기준선go_vulncheck를 수행하여 워크스페이스가 이미 가지고 있는 취약점을 표면화합니다. 이는 무조건적이며, 이후 편집 워크플로우의 의존성 변경 후 검사와는 별개입니다.
읽기 워크플로우 (무언가를 건드리기 전에 이해하기):
go_workspace— 레이아웃(모듈/워크스페이스/GOPATH); 아직 실행되지 않았다면 위의 세션 시작 검사와 동일한 호출입니다.go_search— 타입/함수/변수를 이름으로 퍼지 위치 찾기.go_file_context— 모든 Go 파일을 처음 읽은 직후, 해당 파일이 자신의 패키지에서 가져오는 내용을 확인합니다. 해당 파일의 의존성이 변경되면 다시 실행합니다.go_package_api— 모든 파일을 읽지 않고 서드파티 의존성 또는 형제 패키지의 공개 표면을 확인합니다.
편집 워크플로우 (진단이 깨끗해질 때까지 반복):
- 먼저 읽기(위 워크플로우).
- 정의를 수정하기 전에
go_symbol_references— 영향 범위를 판단한 후 일치하는 편집이 필요한 모든 참조 파일을 읽습니다. - 계획된 모든 편집(참조 사이트 편집 포함)을 다음 단계로 넘어가기 전에 수행합니다.
- 변경된 모든 파일에 대해
go_diagnostics— 각 수정 후 필수이며, 선택적 정리 패스가 아닙니다. - 보고된 오류 수정: 제안된 퀵픽스 diff를 적용하기 전에 검토한 후 진단을 다시 실행하여 수정이 적용되었는지 확인합니다. 작업과 관련 없는 힌트/정보 진단은 무시합니다. 진단 메시지는 주변 소스를 그대로 인용하기보다 의역할 수 있습니다.
go.mod의존성이 변경된 경우에만 전체 워크스페이스에 대해go_vulncheck실행 — 진단이 깨끗해진 후에, 그 전이 아닙니다.go test <변경된-패키지-경로>실행 — 명시적으로 요청하지 않는 한./...는 사용하지 마십시오.