ultraindex — 전체 저장소의 AI 분석 백과사전 구축 및 탐색
대규모 저장소에서는 컨텍스트 창이 중요한 내용을 찾기도 전에 가득 차버립니다.
ultraindex는 작업 분할을 통해 이를 해결합니다: 결정론적이고 의존성이 없는 엔진(node scripts/ultraindex.mjs <command> — npm install 불필요, API 키 불필요, 전체 사용법은 --help)이 기계적 작업 — 프로젝트 스캔, 링크 그래프 구축, 백과사전 레이아웃 — 을 수행하고; 여러분은 이해 — 근거 기반의 인용된 분석 — 을 수행하며, 이후 저장소를 직접 읽는 대신 결과물을 탐색합니다.
핵심 규칙:
- 엔진은 코드 뷰와 그래프(
ui:gen영역)를 소유합니다 — 빌드할 때마다 재생성되며, 직접 수정하지 마십시오.- 여러분은 비즈니스 뷰(
ui:human영역)를 소유합니다.build는 재빌드 및 이름 변경 시 여러분의 산문을 보존합니다.- 기억이 아닌 증거에 기반하여 분석하십시오.
dossier가 보여주는 실제 소스에서만 분석을 작성하고,[file:line]형식으로 인용하며,check는 해결되지 않는 모든 인용에 대해 실패합니다 — 그러니 추측하지 마십시오.- 최소한만 로드하십시오. 한 번에 하나의 항목(또는 하나의
dossier)만 읽으십시오 — 이것이 의도된 패턴이며, 모듈별 보강 서브 에이전트가 정확히 수행하는 작업입니다.graph.json이나 전체encyclopedia/디렉토리를 컨텍스트에 일괄 로드하지 마십시오 — 이는 목적을 무색하게 합니다.
대부분의 명령어는 --json을 지원합니다 — 결과를 산문으로 읽기보다 이 플래그로 분기 처리할 때 선호하십시오.
상황별 경로
다음 순서로 현재 상황을 파악하고, 해당하는 상세 워크플로의 참조 문서를 읽으십시오:
-
인덱스가 없는 경우 — 저장소 루트에
.ultraindex/또는docs/ultraindex/가 없습니다(내부에graph.json이 있는지 확인). 인덱스를 구축한 다음, 최상위 모듈을 보강하십시오: references/generate.md를 읽으십시오. -
인덱스가 존재하는 경우 — 먼저 신선도를 확인하십시오.
node scripts/ultraindex.mjs check --out <index-dir> --json을 실행하십시오. 오래되었거나 손상되었다고 보고하면build를 다시 실행하십시오(여러분의 산문은 유지됩니다). 그런 다음 계속 진행하십시오. 작업과 관련 없는 파일만 변경된 경우, 진행하고 그 사실을 기록할 수 있습니다. -
사용자가 작업이나 질문이 있는 경우 ("X는 어디에 있나요", "Z는 어떻게 동작하나요", "어떤 파일을 변경해야 하나요") — 인덱스를 탐색하고, 인덱스가 가리키는 파일만 열며, 확인된 인용으로 답변의 근거를 제시하십시오: references/navigate.md를 읽으십시오.
-
답변이 높은 신뢰도를 요구하는 경우 (감사, 보안, 정확성이 중요한 주장), 또는 사용자가 답변을 확인/판정하도록 요청한 경우 —
check --answer가 통과한 후(인용이 해결됨), 의미 검증 게이트로 에스컬레이션하여 각 인용된 발췌문이 단순히 존재하는 것뿐만 아니라 해당 주장을 지원함을 증명하십시오: references/verify.md를 읽으십시오. -
사용자가 색인/분석/문서화를 요청했거나,
status --json이 보강되지 않은 허브를 보여주고 충분한 예산이 있는 경우 — 상태 기반 보강 루프(dossier → 인용된 분석 작성 → check)를 실행하십시오. 대규모 저장소에서는 호스트가 서브 에이전트를 지원하는 경우 큐에서 모듈당 하나의 서브 에이전트로 병렬화됩니다: references/generate.md를 읽으십시오. -
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, packageexports맵), 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의 가상 파일 시스템은 범위 밖입니다(워크스페이스 이름은 여전히 해석됨). - 끊어진 엣지는 보통 저장소 자체에 깨진 임포트나 오래된 문서 링크가 있음을 의미합니다 — 이는 무시하지 말고 보고해야 할 발견 사항입니다.