Community라이팅 & 에디팅github.com

ultraindex

전체 저장소(코드 + 문서)를 탐색 가능하고 AI가 분석한 백과사전으로 색인하여, AI가 큰 코드베이스에서 컨텍스트 창을 채우지 않고 작업할 수 있게 합니다. 근거 기반의 인용 확인 분석과 선택적 로컬(Ollama) 의미 검색을 제공하는 단일 자동 라우팅 skills.sh 스킬입니다.

ultraindex란 무엇인가요?

ultraindex는 대규모 저장소에서 AI가 컨텍스트 창 한계로 인해 핵심 코드를 찾지 못하는 문제를 해결합니다. 이 스킬은 저장소를 스캔하고 링크 그래프를 구축하며 백과사전을 생성하는 결정론적 엔진(`node scripts/ultraindex.mjs`)과, 실제 소스 파일을 기반으로 인용된 분석을 작성하는 AI의 역할을 분리합니다. 한 번에 하나의 모듈만 읽도록 설계되어 컨텍스트를 효율적으로 사용하며, `check` 명령어는 모든 인용이 실제로 존재하는지 검증하여 환각을 방지합니다. JS/TS, Python, Go, Rust, Java 등 다양한 언어를 위한 AST 기반 정확한 심볼 추출과 임포트 그래프를 지원하며, 선택적으로 Ollama나 다른 제공자를 통해 의미 검색(벡터 임베딩)을 추가할 수 있습니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트 및 개발자 도구 환경에서 작동하며, 저장소 루트에 `.ultraindex/` 또는 `docs/ultraindex/` 디렉토리를 생성하여 동료나 CI/CD에서 공유 가능한 검토 가능한 인덱스를 만듭니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add maxgfr/ultraindex

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

ultraindex — 전체 저장소의 AI 분석 백과사전 구축 및 탐색

대규모 저장소에서는 컨텍스트 창이 중요한 내용을 찾기도 전에 가득 차버립니다. ultraindex는 작업 분할을 통해 이를 해결합니다: 결정론적이고 의존성이 없는 엔진(node scripts/ultraindex.mjs <command> — npm install 불필요, API 키 불필요, 전체 사용법은 --help)이 기계적 작업 — 프로젝트 스캔, 링크 그래프 구축, 백과사전 레이아웃 — 을 수행하고; 여러분은 이해 — 근거 기반의 인용된 분석 — 을 수행하며, 이후 저장소를 직접 읽는 대신 결과물을 탐색합니다.

핵심 규칙:

  1. 엔진은 코드 뷰와 그래프(ui:gen 영역)를 소유합니다 — 빌드할 때마다 재생성되며, 직접 수정하지 마십시오.
  2. 여러분은 비즈니스 뷰(ui:human 영역)를 소유합니다. build는 재빌드 및 이름 변경 시 여러분의 산문을 보존합니다.
  3. 기억이 아닌 증거에 기반하여 분석하십시오. dossier가 보여주는 실제 소스에서만 분석을 작성하고, [file:line] 형식으로 인용하며, check는 해결되지 않는 모든 인용에 대해 실패합니다 — 그러니 추측하지 마십시오.
  4. 최소한만 로드하십시오. 한 번에 하나의 항목(또는 하나의 dossier)만 읽으십시오 — 이것이 의도된 패턴이며, 모듈별 보강 서브 에이전트가 정확히 수행하는 작업입니다. graph.json이나 전체 encyclopedia/ 디렉토리를 컨텍스트에 일괄 로드하지 마십시오 — 이는 목적을 무색하게 합니다.

대부분의 명령어는 --json을 지원합니다 — 결과를 산문으로 읽기보다 이 플래그로 분기 처리할 때 선호하십시오.

상황별 경로

다음 순서로 현재 상황을 파악하고, 해당하는 상세 워크플로의 참조 문서를 읽으십시오:

  1. 인덱스가 없는 경우 — 저장소 루트에 .ultraindex/ 또는 docs/ultraindex/가 없습니다(내부에 graph.json이 있는지 확인). 인덱스를 구축한 다음, 최상위 모듈을 보강하십시오: references/generate.md를 읽으십시오.

  2. 인덱스가 존재하는 경우 — 먼저 신선도를 확인하십시오. node scripts/ultraindex.mjs check --out <index-dir> --json을 실행하십시오. 오래되었거나 손상되었다고 보고하면 build를 다시 실행하십시오(여러분의 산문은 유지됩니다). 그런 다음 계속 진행하십시오. 작업과 관련 없는 파일만 변경된 경우, 진행하고 그 사실을 기록할 수 있습니다.

  3. 사용자가 작업이나 질문이 있는 경우 ("X는 어디에 있나요", "Z는 어떻게 동작하나요", "어떤 파일을 변경해야 하나요") — 인덱스를 탐색하고, 인덱스가 가리키는 파일만 열며, 확인된 인용으로 답변의 근거를 제시하십시오: references/navigate.md를 읽으십시오.

  4. 답변이 높은 신뢰도를 요구하는 경우 (감사, 보안, 정확성이 중요한 주장), 또는 사용자가 답변을 확인/판정하도록 요청한 경우 — check --answer가 통과한 후(인용이 해결됨), 의미 검증 게이트로 에스컬레이션하여 각 인용된 발췌문이 단순히 존재하는 것뿐만 아니라 해당 주장을 지원함을 증명하십시오: references/verify.md를 읽으십시오.

  5. 사용자가 색인/분석/문서화를 요청했거나, status --json이 보강되지 않은 허브를 보여주고 충분한 예산이 있는 경우 — 상태 기반 보강 루프(dossier → 인용된 분석 작성 → check)를 실행하십시오. 대규모 저장소에서는 호스트가 서브 에이전트를 지원하는 경우 큐에서 모듈당 하나의 서브 에이전트로 병렬화됩니다: references/generate.md를 읽으십시오.

  6. find가 계속 누락되거나, 사용자가 의미 검색/더 나은 검색을 원하는 경우 — 선택적 임베딩 레이어(docker compose, embed, 하이브리드 find)를 설정하십시오: references/semantic.md를 읽으십시오.

일반적인 첫 방문은 1 → 5 → 3으로 연결됩니다; 재방문은 보통 2 → 3입니다; 높은 신뢰도의 답변은 → 4를 추가합니다.

명령어 치트 시트

  • build --repo <dir> [--out .ultraindex] [--include/--exclude <glob>] [--max-bytes <n>] [--max-files <n>] [--no-cache] [--no-mermaid] — 저장소를 스캔하고 인덱스를 (재)작성합니다. 멱등적이며, 보강된 산문을 유지합니다. 증분 방식(변경되지 않은 파일의 추출을 재사용)으로 동작하며, --max-files로 인한 잘림을 경고합니다. --out docs/ultraindex는 커밋 가능하고 PR 검토 가능한 인덱스를 생성합니다.
  • map [--module <slug>] [--json] — INDEX.md(또는 하나의 항목, 또는 모듈 테이블)를 출력합니다.
  • find "<query>" [--k <n>] — 모듈의 순위를 매기고, 열어야 할 정확한 파일을 출력합니다. 기본적으로 어휘 검색(IDF 용어 가중치 포함)을 사용하며, vectors.json이 존재할 경우 하이브리드(+ 의미 검색)로 동작합니다.
  • neighbors <file|module> [--depth <n>] — 대상에 연결되거나 연결되는 항목을 표시합니다.
  • symbols "<name>" [--json] — 심볼이 정의된 위치(file:line, 종류, 소속 모듈)와 참조하는 파일을 표시합니다. 식별자 하위 토큰 기준 퍼지 매칭을 지원합니다.
  • impact <file|module> [--depth <n>] [--json] — 역의존성 클로저: 대상을 임포트하거나 사용하는 모든 것을 표시합니다. "이것을 변경하면 무엇이 깨질까?"
  • status — 보강해야 할 정확한 순서의 작업 큐를 표시합니다.
  • dossier <slug> — 모듈의 근거 패킷(실제 소스 + 이웃; 예: root와 같은 문서/설정 전용 모듈은 코드를 표시하지 않음 — 대신 README/설정을 인용하여 보강).
  • ask "<question>" — 질문에 답변하기 위한 근거 있는 증거를 조합합니다.
  • check [--answer <file>] [--semantic] — 신선도 + 무결성 + 근거 검증(인용이 해결되어야 함). 0이 아닌 종료 코드는 오래됨, 손상 또는 근거 부족을 의미합니다. --semantic은 검증 게이트도 포함시킵니다(인용된 발췌문이 주장을 반박하거나, 전적으로 판정되었으나 지지 증거가 없는 주장은 실패). 원시 verdicts[]에서 평결을 다시 축소하고 모든 판정된 발췌문을 라이브 저장소에서 다시 읽습니다 — 조작된 요약이나 변경된 소스는 결코 통과하지 못합니다.
  • verify --answer <file> [--apply <verdicts.json>] [--max-verify <n>] — check --answer 위의 높은 신뢰도 게이트입니다: 주장↔인용 작업 목록을 생성하여 적대적 지지 확인을 수행한 후, --apply가 여러분의 평결을 통과/실패 게이트로 축소합니다. 자세한 내용은 references/verify.md를 참조하십시오.
  • embed [--force] — 의미 검색 find를 위한 vectors.json을 구축/갱신합니다(제공자 필요 — references/semantic.md 참조).

범위 참고 사항

  • 키 없음, 네트워크 없음, 결정론적(선택적 의미 계층은 유일한 예외이며, 제공자가 없으면 어휘 검색으로 대체됨). 변경되지 않은 저장소의 두 빌드는 manifest.json의 builtAt 생성 타임스탬프를 제외하고 바이트 단위로 동일합니다. vectors.json도 제외됩니다(부동 소수점 값은 제공자에 따라 다름).
  • AST 기반 정확한 심볼: JS/TS/TSX, Python, Go, Rust, Java, C, C++, C#, Ruby, PHP를 위한 커밋된 tree-sitter 문법 사용 — 실제 중첩, 정확한 종류, 구조적 내보내기. 다른 언어는 정규 표현식 추출기로 대체됩니다(여전히 검색 가능). 문법 wasm은 번들에 포함되어 있으므로 스킬 사용 시 npm install이 여전히 필요하지 않습니다(설치 자체는 약 17 MiB wasm으로 더 무거움).
  • 임포트 엣지: JS/TS(tsconfig paths, package exports 맵), Python, Go(다중 모듈 + replace), Rust(mod/use), Java(패키지), C/C++(#include "..."), Ruby(require_relative/require), PHP(composer PSR-4 + 상대 require), C#(using → namespace). 또한 파일이 다른 파일의 고유 내보내기 심볼을 임포트 없이 참조하는 경우 보수적인 코드→코드 use 엣지를 추가합니다. 나머지 언어는 임포트 엣지가 없습니다. Yarn PnP의 가상 파일 시스템은 범위 밖입니다(워크스페이스 이름은 여전히 해석됨).
  • 끊어진 엣지는 보통 저장소 자체에 깨진 임포트나 오래된 문서 링크가 있음을 의미합니다 — 이는 무시하지 말고 보고해야 할 발견 사항입니다.

관련 스킬