AI 에이전트를 위한 코드 인텔리전스 인프라스트럭처

AI 에이전트를 위한 코드 인텔리전스 인프라스트럭처 (Code intelligence infrastructure). 65개의 도구, 30개의 CI 검증 언어, 24개의 에이전트 워크플로우. 단일 Go 바이너리.

curl -fsSL https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.sh | sh && agent-lsp init

agent-lsp는 기존의 LSP 서버(gopls, rust-analyzer, jdtls 등)를 에이전트 네이티브 워크플로우로 오케스트레이션(orchestrate)하는 **MCP 서버 (MCP server)**입니다.

LSP 서버가 아닙니다 — 이는 언어 서버를 관리하고, MCP 도구를 통해 배치 작업(batch operations), 추측적 편집(speculative editing), 다단계 워크플로우(multi-step workflows)를 노출하는 오케스트레이션 계층(orchestration layer)입니다.

아키텍처 (Architecture):

언어 서버 (Language servers) (gopls, rust-analyzer 등) → 코드 인텔리전스 제공
agent-lsp (MCP 서버) → 워크플로우 오케스트레이션, 웜 런타임 (warm runtime) 유지
AI 에이전트 (AI agents) → MCP 프로토콜을 통해 소비

지속적인 웜 런타임 (Persistent warm runtime)

언어 서버는 에이전트 세션 전반에 걸쳐 인덱싱된 상태를 유지합니다. 첫 번째 세션: 워크스페이스를 인덱싱합니다 (일반적인 프로젝트의 경우 약 10초 소요). 이후 세션: 즉시 실행됩니다. 각 요청마다 콜드 스타트(cold-start) 페널티가 없습니다.

배치 작업 (Batch operations)

blast_radius

→ 한 번의 호출로 모든 export와 모든 caller를 반환합니다 (테스트용과 비테스트용으로 분할됨). 오케스트레이션이 없다면: 20개 이상의 순차적인 LSP 호출이 필요합니다.

추측적 편집 (Speculative editing)

simulate_edit

→ 메모리 내에서 변경 사항을 미리 보고, 진단 델타(diagnostic delta)를 확인한 후, 적용하거나 폐기합니다. 디스크를 건드리기 전에 편집 내용을 테스트하십시오.

워크플로우 오케스트레이션 (Workflow orchestration)

LSP 작업을 완전한 파이프라인으로 체이닝(chain)하는 24가지 기술:

/lsp-refactor

→ 영향 분석 (impact analysis) → 미리보기 (preview) → 적용 (apply) → 빌드 검증 (verify build) → 테스트 실행 (run tests)

/lsp-safe-edit

→ 미리보기 (preview) → 진단 차이 (diagnostic diff) → 안전할 경우 적용 (apply if safe)

/lsp-verify

→ LSP 진단 (LSP diagnostics) → 빌드 (build) → 테스트 스위트 (test suite)

다중 언어, 단일 세션 (Multi-language, single session)

하나의 agent-lsp 프로세스가 .go는 gopls로, .ts는 tsserver로, .py는 pyright로 라우팅합니다. 프로젝트 간의 재설정이 필요 없습니다. 세션은 파일과 리포지토리(repositories) 전반에 걸쳐 유지됩니다.

Tip

토큰 최적화된 출력 (Token-optimized output): 도구 응답을 JSON 대신 GCF로 인코딩합니다. 도구에 따라 30~84%의 토큰을 절감할 수 있으며 (세션 중복 제거 (session dedup) 적용 시 최대 92.7%), 모든 프론티어 모델 (frontier model)에서 100%의 LLM 이해도를 보입니다. JSON의 평균 이해도가 53.4%인 복잡한 코드 그래프 (code graphs) 환경에서도 91.2%의 이해도를 기록했습니다. 도구별 측정된 절감 수치는 아래를 참조하세요.

구성 요소의 결합 방식 (How the pieces fit together): LSP (Language Server Protocol, 언어 서버 프로토콜)는 에디터가 코드 인텔리전스(완성, 진단, 정의로 이동 등)를 얻는 방식입니다. MCP (Model Context Protocol, 모델 컨텍스트 프로토콜)는 Claude Code와 같은 AI 도구가 외부 도구를 발견하고 호출하는 표준 방식입니다. agent-lsp는 이 둘을 연결합니다. 즉, AI 에이전트가 접근 가능한 언어 서버 인텔리전스를 제공합니다.

• 에이전트 기반 코드 생성 시스템 구축
• 대규모 코드베이스 전반의 리팩터링 (refactors) 자동화
• 프로그래밍 방식의 코드 인텔리전스가 필요한 CI 툴링
• 순차적인 LSP 호출이 너무 느리거나 복잡한 모든 워크플로우

우리는 AI 에이전트들에게 10가지 코딩 작업(호출자 찾기, 안전한 이름 변경, 편집 미리보기, 데드 코드 탐지)에 대해 agent-lsp를 평가하고 솔직한 의견을 작성하도록 요청했습니다. 네 가지 서로 다른 모델이 네 차례 독립적인 평가를 수행했으며, 결론은 모두 동일했습니다.

Claude (Opus 4.6): "리팩터링, 영향 분석(impact analysis), 또는 안전한 편집이 포함된 모든 워크플로우에 agent-lsp를 추천합니다. 눈에 띄는 도구로는 blast_radius (grep 명령어를 5~10번 실행해야 복제할 수 있는 테스트/비테스트 파티셔닝을 포함하여 단 한 번의 호출로 영향 범위를 파악), go_to_implementation (grep으로는 절대 할 수 없는 타입 체크 기반의 인터페이스 충족 확인), 그리고 시뮬레이션 세션 워크플로우(디스크를 건드리지 않고 추측성 타입 체크를 수행하며, 이는 grep이나 read로 대응할 수 있는 방법이 전혀 없음)가 있습니다."

Cursor (auto): "대규모 리팩터링과 코드 탐색에 agent-lsp를 추천합니다. 이름 변경(rename), 참조(references), 구현(implementations), 호출 계층(call hierarchy), 그리고 시뮬레이션 도구들이 취약한 grep 방식이나 수동 편집 작업을 대폭 제거하여 변경 사항을 더 안전하게 만들어 주기 때문입니다."

GPT-5.5 (via Codex): "심볼 인식(symbol-aware) 작업에는 agent-lsp를 추천합니다. 참조(references), 구현(implementations), 이름 변경 미리보기(rename previews), 진단(diagnostics), 그리고 대규모 파일 구조 파악이 grep/read 루프 방식보다 실질적으로 더 빠르고 오류가 적습니다."

Gemini 2.5 Pro (via Gemini CLI): "agent-lsp를 강력히 추천합니다. 표준 텍스트 검색 도구로는 도저히 따라올 수 없는 수준의 의미론적 인식(semantic awareness)을 제공하기 때문입니다. 높은 신뢰도로 이름을 변경하고, 인터페이스 구현을 찾으며, 디스크에 쓰지 않고도 편집의 진단적 영향(diagnostic impact)을 미리 확인할 수 있는 능력은 회귀(regressions)를 유발할 위험을 크게 줄여줍니다."

다른 모든 MCP-LSP 구현체들은 설정 파일에 지원되는 언어를 나열합니다. 하지만 그중 어느 것도 실제 언어 서버(language server)를 CI에서 실행하여 제대로 작동하는지 검증하지 않습니다.

agent-lsp CI는 푸시(push)가 발생할 때마다 실제 피스처(fixture) 코드베이스를 대상으로 30개의 실제 언어 서버를 실행합니다: Go, Python, TypeScript, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, Scala, Zig, Lua, Elixir, Gleam, Clojure, Dart, Terraform, Nix, Prisma, SQL, MongoDB 등이 포함됩니다. 우리가 "gopls와 호환된다"라고 말할 때, 그것은 막연한 기대가 아니라 검증된 자동화된 주장입니다.

디스크에 쓰기 전에 메모리 상에서 변경 사항을 시뮬레이션합니다. 다른 어떤 MCP-LSP 구현체도 이 기능을 가지고 있지 않습니다.

preview_edit

모든 편집의 진단적 영향(diagnostic impact)을 미리 보여줍니다. 파일이 수정되기 전에 무엇이 깨지는지 정확히 확인할 수 있습니다. simulate_chain

연쇄적인 편집 시퀀스(함수 이름 변경, 모든 호출자 업데이트, 반환 타입 변경 등)를 평가하고, 어떤 단계에서 처음으로 오류가 발생하는지 보고합니다.

8개의 투기적 실행(speculative execution) 도구. 전체 워크플로우는 docs/guide/speculative-execution.md를 참조하세요.

구조화된 LSP 응답은 동일한 작업에 대해 grep/read 방식보다 토큰을 5~34배 적게 사용합니다. HashiCorp Consul(319K 라인)의 경우, 영향 범위 분석(blast-radius analysis) 시 grep을 사용하면 17.7MB가 소모되는 반면 LSP를 사용하면 841KB만 소모되어, 5,534회의 도구 호출을 119회로 줄여줍니다. 절감 효과는 코드베이스 크기에 따라 확장됩니다. 5개의 코드베이스에 걸친 전체 실험 결과는 docs/guide/token-savings.md를 참조하세요.

도구 응답은 JSON 대신 GCF (Graph Compact Format)로 인코딩됩니다. GCF는 필드 이름 반복, 식별자 반복, 그리고 레코드당 발생하는 구조적 오버헤드(structural overhead)를 제거합니다.

프로필 (Profile)	도구 (Tools)	JSON 대비 절감률 (Savings vs JSON)
Tabular	66개 도구 전체	30-51%
...		92.7% (5번째 호출)

GCF는 기본적으로 활성화되어 있습니다. JSON으로 되돌리려면 다음을 실행하세요:

export AGENT_LSP_OUTPUT_FORMAT=json

벤치마크: go run scripts/gcf-benchmark.go

아키텍처에 대한 자세한 내용은 docs/guide/gcf-integration.md를 참조하세요.

GCF: gcformat.com · Spec · Go · Python · TypeScript · Playground

AI 에이전트는 전체 그림을 볼 수 없기 때문에 잘못된 코드 변경을 수행합니다. 예를 들어, 누가 이 함수를 호출하는지, 이름을 변경하면 무엇이 깨지는지, 빌드가 여전히 통과하는지 등을 알 수 없습니다. 언어 서버(Language servers)가 그 답을 가지고 있지만, 가공되지 않은 LSP 도구들은 20회 이상의 순차적 호출과 복잡한 오케스트레이션(orchestration) 로직을 요구합니다.

agent-lsp는 정확한 다단계 작업(multi-step operations)을 단일 호출과 스킬(skills)로 인코딩하여 이 문제를 해결합니다. blast_radius는 에이전트가 20회 이상의 호출을 거쳐야 할 작업을 한 번에 수행합니다. /lsp-refactor는 프롬프트마다 오케스트레이션을 할 필요 없이 영향 분석(impact) → 미리보기(preview) → 적용(apply) → 검증(verify) → 테스트(test)를 체인(chain) 형태로 연결합니다.

Python 및 TypeScript 프로젝트는 find_references가 작동하기 전에 몇 분간의 백그라운드 인덱싱(indexing)이 필요합니다. agent-lsp는 세션 간에도 유지되는 지속적인 데몬 브로커(daemon broker)를 자동으로 생성하여 워크스페이스의 인덱싱 상태를 유지합니다. 첫 번째 세션에서는 데몬이 시작되고 인덱싱을 수행합니다 (FastAPI의 경우 약 10초 소요). 이후 세션에서는 이미 활성화된(warm) 데몬에 즉시 연결됩니다. 30분 동안 활동이 없으면 자동으로 종료됩니다. Go, Rust 및 기타 빠른 인덱싱 언어들은 이 과정을 완전히 건너뜁니다 (오버헤드 제로).

스킬(Skills)은 에이전트에게 올바른 작업 순서를 알려줍니다. 단계 강제(Phase enforcement)를 통해 런타임(runtime)에서 에이전트가 지침을 따르기를 신뢰하는 대신, 위반 사항을 직접 *차단(block)*합니다.

에이전트가 스킬을 활성화하면, 모든 도구 호출은 현재 단계의 권한에 따라 검사됩니다. apply_edit를 호출할 때

폭발 반경 (blast-radius) 분석 중에 발생하는 오류는 조용히 진행되지 않습니다. 대신 구체적인 복구 가이드가 포함된 오류를 반환합니다 ("먼저 blast_radius 단계를 완료하십시오. 허용된 도구: [blast_radius, find_references]"). 에이전트가 이후 단계의 도구를 호출함에 따라 단계는 자동으로 진행됩니다.

다른 MCP 도구 제공자 중 런타임에 워크플로우 순서를 강제하는 곳은 없습니다. docs/guide/phase-enforcement.md를 참조하십시오.

인스펙터(Inspector)는 4가지 동시성 패밀리(goroutine, thread, async, actor) 내 25개 언어에 걸쳐 작동하는 4가지 동시성 검사를 포함합니다:

복구되지 않은 동시 진입 (Unrecovered concurrent entry): recovery가 없는 goroutine/thread/task
검증되지 않은 공유 상태 (Unchecked shared state): sync.Map, ConcurrentHashMap에 대한 가공되지 않은 타입 단언 (type assertions)
닫히지 않은 채널 (Channel never closed): 생성되었으나 결코 닫히지 않은 channel/queue (goroutine 누수)
동기화 없는 공유 필드 (Shared field without sync): 동기화 없이 동시성 컨텍스트에서 액세스되는 필드

blast_radius는

부모 타입에 mutex가 있는 경우 심볼에 sync_guarded: true를

주석으로 달아줍니다. find_callers는

cross_concurrent: true 옵션을 사용하여

goroutine/thread 경계를 가로지르는 호출 체인을 추적합니다. /lsp-concurrency-audit

스킬은 모든 타입에 대해 필드 수준의 안전성 보고서를 생성합니다.

심볼 편집 도구 (replace_symbol_body,

insert_after_symbol,

insert_before_symbol,

safe_delete_symbol)는 자동으로 errors_after 및 warnings_after 횟수를 반환합니다. 에이전트는 별도의 get_diagnostics 호출 없이도 편집이 무언가를 망가뜨렸는지 즉시 알 수 있습니다.

safe_apply_edit는 미리보기(preview)와 적용(apply)을 한 번의 호출로 결합합니다. 투기적으로(speculatively) 미리보기를 수행하고, net_delta == 0(새로운 오류 없음)인 경우에만 디스크에 적용합니다. 세 번의 호출 대신 한 번의 도구 호출로 해결됩니다.

AI 도구	전송 방식 (Transport)	설정 (Setup)
Claude Code	stdio	agent-lsp init
...
복사하여 붙여넣을 수 있는 설정은 docs/getting-started/mcp-clients.md를 참조하십시오.

Raw tools는 무시됩니다. Skills가 사용됩니다. 각 Skill은 올바른 tool 시퀀스를 인코딩하여, 프롬프트마다 오케스트레이션(orchestration) 지침을 내리지 않아도 워크플로우가 실제로 실행되도록 합니다. Skills는 AgentSkills 슬래시 명령어(slash commands)로 사용할 수 있으며, 모든 MCP client를 위해 prompts/list / prompts/get을 통한 MCP 프롬프트로도 사용할 수 있습니다.

전체 설명 및 사용 가이드는 docs/guide/skills.md를 참조하십시오.

변경하기 전에

Skill	목적
/lsp-impact	심볼(symbol) 또는 파일을 수정하기 전 영향 범위(Blast-radius) 분석
/lsp-implement	인터페이스(interface)의 모든 구체적인 구현체(concrete implementations) 찾기
/lsp-dead-code	정리(cleanup) 전 참조가 없는 export(zero-reference exports) 탐지

안전한 편집

Skill	목적
/lsp-safe-edit	디스크 쓰기 전 추측적 미리보기(Speculative preview); 수정 전/후 진단 차이(diagnostic diff) 비교; 에러 발생 시 코드 액션(code actions) 노출
/lsp-simulate	파일을 건드리지 않고 메모리 내에서 변경 사항 테스트
/lsp-edit-symbol	파일이나 위치를 알지 못해도 이름이 지정된 심볼을 편집
/lsp-edit-export	export된 심볼을 안전하게 편집하며, 먼저 모든 호출자(callers)를 찾음
/lsp-rename	prepare_rename 안전 게이트; 모든 위치 미리보기, 확인, 원자적(atomically) 적용

시작하기

Skill	목적
/lsp-onboard	첫 세션 프로젝트 온보딩: 언어 탐지, 패키지 매핑, 엔트리 포인트(entry points) 및 핫스팟(hotspots) 찾기, 진단(diagnostics) 확인

생소한 코드 이해하기

Skill	목적
/lsp-explore	"이 심볼에 대해 알려줘": 호버(hover) + 구현체 + 호출 계층 구조(call hierarchy) + 참조를 한 번에 수행
/lsp-understand	심볼 또는 파일에 대한 심층 코드 맵(Code Map): 타입 정보, 호출 계층 구조, 참조, 소스
/lsp-docs	3단계 문서화: 호버(hover) → 오프라인 툴체인(offline toolchain) → 소스
/lsp-cross-repo	소비자 리포지토리(consumer repos) 전체에서 라이브러리 심볼의 모든 사용처 찾기
/lsp-local-symbols	파일 범위의 심볼 목록, 사용처 검색 및 타입 정보

편집 후

기술 (Skill)	목적 (Purpose)
/lsp-verify	모든 편집 후 진단 (Diagnostics) + 빌드 + 테스트
/lsp-fix-all	파일 내의 모든 진단 항목에 대해 빠른 수정 (quick-fix) 코드 액션 적용
/lsp-test-correlation	편집된 파일을 커버하는 테스트만 찾아 실행
/lsp-format-code	언어 서버 포매터 (language server formatter)를 통해 파일 또는 선택 영역 포맷팅

코드 생성 (Generating code)

기술 (Skill)	목적 (Purpose)
/lsp-generate	서버 측 코드 생성 트리거 (인터페이스 스텁 (interface stubs), 테스트 스켈레톤 (test skeletons), 모의 객체 (mocks))
/lsp-extract-function	코드 액션을 통해 코드 블록을 이름이 지정된 함수로 추출

전체 워크플로우 (Full workflow)

기술 (Skill)	목적 (Purpose)
/lsp-refactor	엔드 투 엔드 (End-to-end) 리팩터링: 영향 범위 (blast-radius) → 미리보기 (preview) → 적용 (apply) → 검증 (verify) → 테스트 (test)
/lsp-inspect	전체 코드 품질 감사 (12가지 체크 항목): 데드 심볼 (dead symbols), 테스트 커버리지 (test coverage), 에러 핸들링 (error handling), 문서 드리프트 (doc drift), 동시성 안전성 (concurrency safety)
/lsp-concurrency-audit	특정 타입에 대한 필드 수준의 동시성 안전성 감사: 동시 액세스를 추적하고 동기화되지 않은 필드 표시

Stdio 모드 (MCP 클라이언트가 컨테이너를 직접 실행):

# Go
docker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:go go:gopls
# TypeScript
...

HTTP 모드 (지속적인 서비스, 원격 클라이언트가 HTTP+SSE를 통해 연결):

-p 8080:8080 \
-v /your/project:/workspace \
...

이미지는 기본적으로 루트가 아닌 사용자 (uid 65532)로 실행됩니다. AGENT_LSP_TOKEN을 환경 변수를 통해 설정하십시오. 명령줄에서 --token을 사용하지 마십시오. 이미지는 Docker Hub(blackwellsystems/agent-lsp)로도 미러링됩니다.