skimsearch: 코딩 에이전트에게 grep 출력을 붙여넣는 것을 중단시키세요

Repo: 👉 github.com/bayuh85/skimsearch (MIT, Python 3.10+)

문제점

코딩 에이전트에게 "연체료는 어디에서 계산되나요?"라고 물어보고 무슨 일이 일어나는지 지켜보세요. 이 에이전트는 grep -rn "late fee"를 실행하고, 코드, 문서, 번들링된 의존성(vendored dependencies), 테스트 등 수십 개의 히트 결과를 받아와 그 전체 내용을 컨텍스트에 붙여넣습니다. 그리고 나서 올바른 함수를 찾기 전에 세 개의 잘못된 파일을 엽니다.

이 모든 줄들은 비용을 지불하는 토큰이며, 매번 돌아갈 때마다 다시 읽히면서 실제로 질문에 답하는 몇 안 되는 줄들을 밀어냅니다(crowding out).

skimsearch의 작동 방식

skimsearch는 트리를 한 번 인덱싱한 후, 토큰 예산 내에 맞는 짧은 순위별 스니펫 묶음으로 답변합니다.

인덱스 생성 (Index). skimsearch index는 코드와 문서를 _skim 카드(skim cards)_로 통합합니다. 각 카드는 경로와 라인 범위를 가지며, 하나의 함수, 클래스, 헤딩 또는 텍스트 창에 해당합니다. 이 카드들은 .skimsearch/index.sqlite라는 간결한 SQLite 파일에 저장되며, SQLite FTS5 (BM25)를 사용하여 오프라인으로 순위가 매겨집니다.
검색 (Search). skimsearch search는 가장 좋은 카드를 반환하며, 전체 묶음이 예산(기본값 700 토큰) 안에 머무르도록 잘라냅니다. 어휘 모드(Lexical mode)는 네트워크에 절대 접근하지 않습니다.
질문 (Ask). --mode semantic을 사용하면 저렴한 모델이 서술형 질문을 몇 가지 어휘 탐색(lexical probes)으로 변환한 다음 로컬에서 검색할 수 있게 합니다. --mode ask 역시 자신이 사용한 카드만을 인용하는 짧은 답변을 반환합니다.

이는 .gitignore를 존중하며, .skimignore를 지원하고, 의존성 폴더, lockfile, 그리고 .env나 .pem 같은 비밀 파일을 건너뜁니다.

실제 사용 사례: 연체료 찾기

이 레포지토리는 코드, 문서, 번들링된 폴더, 가짜 .env를 포함하는 작은 샘플 프로젝트인 examples/acme-billing을 제공합니다. 설치하고 인덱싱해 보세요:

git clone https://github.com/bayuh85/skimsearch.git
cd skimsearch
python -m venv .venv
...

출력 결과:

skimsearch  mode=lexical  cards=4  tokens=322/700

1. src/billing/invoices.py:17-28  function apply_late_fee  (python, score 1.71)
...

322 토큰 분량으로, 올바른 함수가 먼저 오고 그 아래에 일치하는 문서들이 배치됩니다. 빌드된 코드와 가짜 .env 파일은 절대 나타나지 않습니다. 에이전트가 읽는 것은 원시적인 grep 덤프 대신 이 내용입니다.

만약 직접적인 답변을 얻고 싶다면:

export ATMOROUTER_API_KEY=ar-your-key-here
skimsearch search "where is the late fee calculated" --path examples/acme-billing --mode ask

Cursor 또는 Claude Code에 연결하기 (MCP)

skimsearch serve는 표준 입출력(stdio) MCP 서버를 실행하고 (누락된 경우 인덱스를 빌드합니다). Claude Code의 경우, 다음 내용을 .mcp.json 파일에 추가하세요:

{
  "mcpServers": {
    "skimsearch": {
...

Cursor는 동일한 블록을 .cursor/mcp.json에서 사용합니다. 에이전트는 두 가지 도구, 즉 skim_search (쿼리, 모드, 예산(budget), 제한(limit), 형식(format))과 skim_status를 얻게 됩니다. 긴 루프에서는 lexical을, 산문 질문에는 ask를 사용하세요.

유용한 명령어

skimsearch index . --force          # 재빌드
skimsearch index . --embed          # /embeddings 벡터도 저장
skimsearch search "session ttl" -C . --budget 500
...

테스트 스위트(44개 테스트)는 완전히 오프라인으로 실행됩니다: pip install -e ".[dev]" && pytest -q.

AtmoRouter에 대하여 (기본 모델 엔드포인트)

Semantic 모드와 ask 모드는 OpenAI 호환 채팅 API를 호출하며, 기본 베이스 URL은 https://atmorouter.dev/v1입니다. AtmoRouter는 저렴한 AI API 게이트웨이이자 OpenRouter의 대안이며, 하나의 키로 109개의 모델을 지원하고 OpenAI와 Anthropic 클라이언트 모두와 호환됩니다. 토큰당 비용을 지불하며, 가격은 공식 요금 대비 평균 83.7% 낮습니다. 또한 QRIS와 USDC를 수락합니다. 이는 이 도구의 역할에 적합한데, 쿼리 재작성은 코딩 모델이 절약하는 토큰보다 훨씬 저렴해야 하기 때문입니다. 기본 모델은 atmo/deepseek-v4.1-flash입니다.

Anthropic Messages API를 선호하십니까? SKIMSEARCH_API_STYLE=anthropic을 설정하세요. 다른 제공업체를 원하십니까? SKIMSEARCH_BASE_URL을 모든 OpenAI 호환 엔드포인트로 지정하세요. 그리고 lexical 검색은 키가 전혀 필요하지 않습니다.

사용해 보기

만약 에이전트가 계속해서 grep 출력물에 빠진다면, 대신 덱(deck)을 제공하세요.

👉 github.com/bayuh85/skimsearch

검색 순위가 낮은 쿼리(query)와 작은 샘플 레포지토리(sample repo)를 함께 제공하는 것이 가장 유용한 피드백입니다.

skimsearch: 코딩 에이전트에게 grep 출력을 붙여넣는 것을 중단시키세요

요약

핵심 포인트

문제점