⚡ SigMap — AI 코딩 에이전트를 위한 결정론적 코드 근거 계층

한 문장 요약

SigMap은 보이는 그대로의, 검증 가능한 코드베이스 인덱스를 구축하는 오픈소스 CLI 도구입니다. LLM, 임베딩 기술, 벡터 데이터베이스에 의존하지 않으며, 동일한 저장소에 대해 매번 **완전히 동일한(바이트 수준으로 안정적인) "서명 및 증거 맵"**을 생성합니다. 이를 통해 AI 코딩 에이전트(Claude, Cursor, Aider 등)가 올바른 파일, 심볼, 줄 번호를 빠르게 찾고, AI의 답변이 실제로 코드에 기반한 것인지 검증할 수 있습니다.

해결하려는 문제

• 기존의 "에이전트 기반 grep" 루프는 재현 불가능하며, AI는 실제 코드를 모른 채 파일이나 함수 이름을 환각하는 경우가 많습니다
• 임베딩/벡터 데이터베이스 방식은 추가 인프라(벡터 DB, 인덱스 파이프라인)를 유지해야 하고 결과가 불확실합니다
• SigMap은 제로 종속성, 오프라인, 결정론적 대안으로 해결합니다: 벡터 DB 없이 텍스트 서명 + TF-IDF 순위만 사용하고, 인덱스 파이프라인을 다시 실행할 필요 없이 npx sigmap 한 줄로 재생성합니다

작동 방식(파이프라인)

Ask → Rank → Context → Validate → Judge → Learn

1. Ask — CLI 명령(예: sigmap ask "Where is auth handled?")으로 관련성 순위가 매겨진 파일 목록을 반환합니다
2. Rank — TF-IDF 알고리즘이 코드베이스의 각 파일과 쿼리 벡터를 점수화합니다
3. Context — 컴팩트한 심볼 서명을 AI의 컨텍스트 파일(CLAUDE.md, .cursorrules 등)에 씁니다
4. Validate — 범위 내에 있는 파일을 확인합니다
5. Judge — AI 답변의 "근거성"을 점수화합니다
6. Learn — sigmap weights로 문제 해결에 반복적으로 도움이 되는 파일에 더 높은 가중치를 부여할 수 있습니다

38개 언어(TypeScript, Python, Go, Rust 등)를 지원하며 모두 외부 종속성이 없습니다.

플래그십 기능: sigmap verify

이것은 대표 기능입니다("grounding flagship"이라고도 설명됨):

sigmap verify answer.md      # 지어낸 것을 보고합니다
sigmap verify answer.md --json   # 기계 판독 가능한 보고서, 문제가 있으면 종료 코드 1(CI 게이트용)

출력 예:

L12  [Fake file]    src/auth/session-store.js does not exist
L27  [Fake symbol]  authorize() — did you mean authenticate()?

AI 답변에서 존재하지 않는 파일, 가져오기, 가져오기 이름, 심볼, 테스트, npm 스크립트를 줄 단위로 표시할 수 있습니다. 또한 저장소와 현재 실제로 설치된 타사 라이브러리를 모두 인덱싱합니다.

에이전트와의 통합

• 다양한 어댑터 컨텍스트 생성 지원: copilot(기본), claude, cursor, windsurf, openai, gemini, codex 등
• MCP 서버(22개 온디맨드 도구)를 제공하여 Claude Code / Cursor가 세션 중에 실시간으로 호출할 수 있습니다: search_signatures, get_lines, verify_suggestion, get_diff_context, query_knowledge_map 등
• Evidence Pack: 결정론적 JSON 아티팩트(Markdown 출력도 가능). "이것을 프롬프트에 붙여넣기" 수동 작업을 대체하며 CI나 에이전트가 직접 읽을 수 있습니다
• IDE 확장: VS Code, JetBrains, Neovim

"왜 임베딩을 사용하지 않는가" 비교

	Embeddings	SigMap
벡터 DB 필요	✅	❌
인프라 필요	✅	❌
결과 결정적	❌	✅
오프라인 사용 가능	❌	✅

벤치마크(README가 주장하는 데이터)

문서에 제공된 지표(모두 benchmarks/latest.json에서 가져온 것으로 주장, 수기 아님):

• hit@5 80.4%(검색 코퍼스, 18개 저장소)
• 단일 grep 기준선 대비: 92.8% vs 40% — 2.32배 향상
• 생성된 맵이 전체 저장소보다 평균 95.7% 작음
• 작업 성공률 에이전트 지표 61.9%(검색 순위 기반 모델링)
• 작업당 프롬프트 수가 2.84에서 1.58로 감소(재시도 44.4% 감소, 모델링)

저자는 또한 38개 언어 모두가 동일한 깊이로 지원되는 것은 아니라고 정직하게 밝힙니다: AST 완전 파싱 레이어, 앵커 정규식 레이어, 앵커 없는 줄 단위 목록 레이어로 나뉩니다(후자의 형식은 KNOWN_LIMITATIONS.md에 설명됨).

참고: 위 설명은 모두 이 README의 자체 주장에 기반하며 독립적으로 검증되지 않았습니다.

관련 분야 및 평가

이것은 LLM/에이전트 프로그래밍 워크플로우를 위한 결정론적 코드 인덱싱 및 검증 도구입니다. LLM 애플리케이션 계층의 실용적인 기반 시설로, 핵심은 훈련/추론이 아니라 "AI를 프로덕션 코드에서 신뢰할 수 있게 만드는 것"에 있습니다. 그 가치 제안(임베딩 없음, 벡터 DB 없음, 결정론적, 오프라인, 제로 종속성)은 현실적이고 차별화되며, README가 벤치마크 방법과 한계에 대해 정직한 태도도 플러스 요인입니다. 단일 개발자가 제로 종속성 프로젝트를 유지하면서 엔지니어링 완성도(CLI, MCP, IDE 확장, 벤치마크 스위트)가 상당히 우수합니다.