ultradoc — 소스 코드에서 기억이 아닌 근거를 바탕으로 답변

ultradoc — 소스 코드에서 기억이 아닌 근거를 바탕으로 답변은(는) 무엇을 하나요?

ultradoc은 오픈소스 프로젝트에 대한 정밀한 질문에 근거 있는 증거를 검색하고 이를 기반으로 추론하여 답변합니다. 결정론적 엔진(scripts/ultradoc.mjs, 제로 의존성 Node)이 검색과 색인을 코드로 수행하고, 여러분의 역할은 검색된 증거를 읽고 정확하고 인용된 답변을 작성하는 것입니다. 모든 주장은 실제 출처를 가리켜야 합니다. 이는 강제됩니다: ultradoc check는 어떤 인용이든 검색된 증거에 해석되지 않으면 실패합니다.

핵심 규칙: 라이브러리에 대한 자신의 지식으로 답변하지 마십시오. 학습 데이터는 오래되었고 API를 환각합니다. ultradoc이 실제 저장소, 이슈, PR, 문서, 웹에서 검색한 증거만을 바탕으로 답변하십시오. 증거가 해당 내용을 다루지 않는다면 그렇게 말하고 추가로 검색하십시오. 절대 추측하지 마십시오.

스크립트

단일 파일로 커밋된, 의존성 없는 번들: node scripts/ultradoc.mjs <명령어>. npm install도, API 키도 필요 없습니다. --help를 실행하면 전체 명령어 목록을 확인할 수 있습니다. 주요 명령어:

• ask --repo <URL|경로> --q "<질문>" [--sources ...] [--package <p>] [--semantic] [--docs-url <u>] 임의의 git URL을 클론(/tmp/ultradoc/<슬러그>에 캐시됨)하고, 선택한 모든 소스에서 인덱싱 및 검색을 수행한 후 증거 도시에(EVIDENCE.md, evidence.json, meta.json)를 실행 폴더에 씁니다. 이 폴더는 클론 옆 <클론>/.ultradoc/runs/<id>에 유지됩니다(--out을 전달하지 않는 한, 커밋이 고정된 안정적인 홈으로 여러 질문에 걸쳐 재사용됨). 기본 소스: code,issues,prs,docs (저장소만으로 답변하기 어려운 경우 web,so 추가; "X가 언제 추가/변경되었는지"에 대한 질문은 releases,history 추가; 커뮤니티 Q&A는 discussions 추가 — gh CLI 필요). 모노레포에서는 --package <이름|디렉토리>로 코드/문서 검색을 하나의 워크스페이스 패키지로 범위를 한정합니다.
• code|issues|prs|docs|releases|history|discussions|so --repo <...> --q "..." — 하나의 소스에 집중하여 증거를 stdout으로 출력합니다(도시에 없음). 부족한 영역을 확장할 때 사용합니다. history는 클론에서 git pickaxe(log -S/-G)를 실행합니다. 원격 저장소에서 처음 호출하면 전체 히스토리를 한 번 가져옵니다.
• web --repo <...> [--q "..."] [--url <u,...>] — 키 없는 웹 검색(SearchNG → DuckDuckGo → your WebSearch) + 가져오기/추출. --url을 전달하면 자신의 WebSearch로 찾은 특정 페이지를 근거로 사용할 수 있습니다.
• overview --repo <...> [--refresh] — 저장소의 캐시된 마크다운 요약(무엇인지, 워크스페이스 패키지, 레이아웃, 공개 API, 문서 맵)을 한 번 생성합니다. 클론 옆에 캐시되며 커밋이 변경되지 않는 한 재사용됩니다. 여러 질문에 걸쳐 방향을 잡기 위해 읽을 수 있습니다. 증거로 인용할 수 없는 탐색 맵입니다.
• doc --repo <...> [--package <p>] [--sources ...] — 근거 있는 참조 문서를 스캐폴딩합니다: 결정론적 섹션 개요(개요, 설치, 공개 API/패키지별, 설정, 아키텍처), 섹션별로 검색된 하나의 도시에를 병합한 단일 evidence.json, 그리고 DOC.todo.md 작업 목록. 인용된 산문을 DOC.md에 작성하고 check는 답변처럼 검증합니다. <클론>/.ultradoc/doc/에 저장됩니다. 아래 "문서 생성"을 참조하세요.
• check --run <도시에-디렉토리> — ANSWER.md(또는 doc 실행의 DOC.md)의 인용을 도시에의 evidence.json과 비교하여 검증합니다. 종료 코드가 0이 아니면 근거 없음입니다. --answer <파일>로 특정 파일을 검증합니다.
• index --repo <...> — 구조적 인덱스를 빌드/출력합니다(디버깅/검사). 모노레포에서 발견된 워크스페이스 패키지를 나열합니다.
• semantic up|down|status — 선택적 로컬 벡터 백엔드(아래 참조).

워크플로우

이 작업은 종단 간 여러분이 소유합니다: 근거가 있는 인용된 답변 하나를 반환하고, 절반만 검색된 도시에를 넘겨주지 마십시오. 그러나 검색과 검증 작업은 독립적이고 거의 비용이 들지 않는 호출 집합입니다. 여러분의 하네스가 허용할 때 병렬화하십시오(한 메시지에서 독립적인 드릴을 배치 처리하고, 가능하면 서브에이전트 또는 워크플로우로 분산) 그렇지 않으면 인라인으로 수행하십시오. 증거가 완전해질 때까지 여러 라운드에 걸쳐 반복하십시오; 완료될 때까지 반환하지 마십시오. references/orchestration.md를 참조하세요.

1. 대상 식별. 프로젝트와 정확한 질문을 식별합니다. 이름만 있는 경우 정식 저장소 URL을 찾습니다(WebSearch 사용, 또는 모호한 경우 사용자에게 문의). 사용자가 관심 있는 버전/브랜치를 기록합니다(--ref).

   같은 저장소에 대해 여러 질문이 있습니까? overview --repo <url>을 한 번 실행하고 출력된 캐시된 OVERVIEW.md를 읽으십시오: 저장소(패키지, 레이아웃, 공개 API, 문서)를 매핑하여 후속 질문이 처음부터 다시 방향을 잡는 대신 동일한 클론+인덱스를 재사용할 수 있습니다. 증거로 인용하지 마십시오 — 탐색용입니다.

   모노레포입니까? ask/index/overview가 워크스페이스 패키지를 보고하면(예: socialgouv/code-du-travail-numerique → @cdt/frontend, @socialgouv/modeles-social, …), 질문과 관련된 하위 시스템과 이름/디렉토리가 일치하는 패키지를 선택하고 --package <이름|디렉토리>를 추가하여 검색이 다른 패키지에 묻히지 않도록 하십시오. 패키지 이름이 명확하게 일치하지 않으면 먼저 범위 없이 ask를 한 번 실행하고, 상위 결과가 어떤 패키지에 모여 있는지 확인한 다음, 해당 패키지로 범위를 좁혀 다시 실행하십시오. 알 수 없는 패키지 이름은 오류를 발생시키고 존재하는 패키지를 나열합니다.

2. 검색. 먼저, 개발자처럼 생각하고 질문에 대해 2~3개의 쿼리 변형을 도출하십시오. 엔진은 글자 그대로 검색하므로 문구가 중요합니다:

   • 자연어 문구("재시도 백오프"),
   • 코드베이스에서 사용할 식별자 형태(retryBackoff, retry_backoff, MAX_RETRIES),
   • 사용자가 인용한 리터럴 오류 메시지, 옵션 또는 플래그 이름.

   여러 부분으로 구성된 질문입니까? 지금 하위 질문으로 분할하십시오. 각각은 자체 증거가 필요하거나 마지막에 명시적인 "알 수 없음"이 필요합니다. 하위 질문별로 적용 범위를 추적하십시오.

   엔진은 이미 복수형과 악센트("retries"/"retry", "délai"/"delai")를 접고, 식별자를 하위 토큰으로 분할하며, 키워드 이름의 파일을 우선시합니다. 따라서 변형은 동의어와 식별자에 사용하고("heartbeat" vs ping, "pool" vs connectionLimit), 같은 단어의 굴절에 사용하지 마십시오. 또한 어휘 검색이 얇을 때를 알아야 합니다: 저장소에 문자 그대로 나타나는 단어가 필요합니다. 개념적이거나 "왜 이런 방식으로 설계되었는지"에 대한 질문은 code가 답을 제공할 것으로 기대하는 대신 docs, discussions, web(또는 --semantic)으로 시작하십시오.

   가장 좋은 변형과 적합한 소스로 ask를 실행하십시오:

   node scripts/ultradoc.mjs ask --repo <url> --q "<정밀한 질문>" --sources code,issues,prs,docs
   

   ultradoc은 자체 README/매니페스트에서 프로젝트의 공식 문서 URL을 자동으로 발견하고(저장소 내 정식 docs/ 트리를 우선시) 이를 기준으로 근거를 제공합니다. 재정의하려면 --docs-url <url>을 전달하십시오. 질문이 개념적이거나 저장소가 빈약할 때 web,so를 추가하고; 무엇이 언제/왜/어떤 버전에서 변경되었는지에 대한 질문일 때 releases,history를 추가하십시오. 명령어는 도시에 경로를 출력합니다. 그런 다음 나머지 변형 × 드릴 소스를 팬아웃으로 처리하십시오 — 한 메시지에서 이러한 독립적인 드릴을 병렬 호출로 실행하십시오(또는 셀당 하나의 서브에이전트). references/orchestration.md를 참조하세요.

3. 도시에 읽기. 실행 폴더에서 EVIDENCE.md를 여십시오. 각 항목에는 id([E1], [E2], …), 출처 ref, 및 스니펫이 있습니다. 이것이 증거입니다 — 실제 코드/이슈/PR/문서 텍스트를 읽으십시오.

4. 부족한 부분 집중 탐색. 하위 질문이 주제에 맞는 항목이 ~2개 미만이거나, 질문된 기호/동작을 실제로 포함하는 항목이 없을 때 얇은 상태입니다. 도시에가 얇아 보일 때까지 기다리지 말고 처음부터 변형 드릴을 병렬로 실행하십시오(드릴은 거의 비용이 들지 않습니다: 클론과 인덱스는 캐시됩니다). 소스 전체에 팬아웃하십시오:

   • code --repo <...> --q "<기호 또는 동작>" 더 많은 코드 영역을 가져옵니다.
   • issues/prs 관련 토론과 진행 중인 변경 사항을 읽습니다.
   • releases(변경 로그 + 릴리스 노트) 및 history(git pickaxe) 질문이 무엇이 언제/왜/어떤 버전에서 변경되었는지에 대한 경우.
   • discussions 커뮤니티 Q&A 및 디자인 스레드(gh CLI 필요).
   • web(또는 your WebSearch → web --url <u>) 외부 참조. 반복 방법은 references/retrieval-playbook.md, 병렬 실행 방법은 references/orchestration.md를 참조하세요.

   작성 전 분류. 검색은 재현율 중심이므로 도시에는 단지 키워드를 공유하는 주제와 무관한 항목을 포함할 것입니다. 테스트: 항목의 스니펫이 질문된 기호/동작을 명명하거나 동일한 메커니즘을 설명하는 경우에만 질문과 관련이 있습니다. 키워드를 공유하는 것만으로는 충분하지 않습니다. 이 테스트를 통과하는 증거 ID를 나열하고 나머지는 무시하십시오 — 주제와 무관한 항목은 단지 존재한다고 해서 인용되어서는 안 됩니다. 분류 후 핵심 주장을 지지하는 항목이 ~2개 미만이면 다시 검색하십시오.

   다시 읽지 말고 다시 질의하십시오. 상위 3개의 코드 항목이 주제와 무관하다면 계속 목록을 읽지 말고, 2단계의 다음 식별자 형태 변형으로 code --q를 다시 실행하십시오. 두 번 연속으로 주제와 무관한 도시에는 저장소에 답변이 없는 것이 아니라 문구가 잘못되었음을 의미합니다.

   고갈될 때까지 반복하십시오. 라운드로 드릴하십시오(최대 ~3회). 라운드에서 새로운 주제 관련 증거가 나오지 않거나, 모든 하위 질문에 ≥2개의 지지 항목이 있을 때 중단하십시오. 그런 다음 분류하고 작성하십시오. 제한 후에도 여전히 지원되지 않는 하위 질문은 명시적인 알 수 없음이며, 절대 기억에서 채우지 마십시오.

5. 답변 작성. 동일한 실행 폴더에 ANSWER.md를 만드십시오. 정확하고 간결하게 작성하십시오. 모든 사실적 주장을 증거 ID로 인용하십시오. 예를 들어 재시도는 지터가 있는 지수 백오프를 사용합니다 [E1], PR #79에서 이를 다시 작성 중입니다 [E7]. references/citation-format.md를 참조하세요. 버전이 중요할 때 meta.json에 표시된 커밋에 답변을 고정하십시오. 2단계의 모든 하위 질문을 다루십시오. 증거가 해결하지 못한 것은 명시적인 알 수 없음으로 표시하십시오 — 기억에서 채우지 마십시오.

6. 검증 (두 가지 계층).

   • 구조적: node scripts/ultradoc.mjs check --run <도시에-디렉토리>. 증거로 해석되지 않는 인용 또는 인용이 없는 답변에서 실패합니다. 수정하고 통과할 때까지 다시 실행하십시오.
   • 의미론적 (적대적 지지 확인): node scripts/ultradoc.mjs verify --run <도시에-디렉토리>는 주장↔증거 작업 목록(VERIFY.todo.json + VERIFY.md)을 작성합니다. 각 쌍을 회의론자로서 판단하십시오: 인용된 스니펫이 주장을 문자 그대로 뒷받침하지 않는 한 기본값은 unsupported/refuted이며, verdict를 supported · partial · refuted · unsupported로 설정합니다(짧은 설명 포함). 쌍당 하나의 회의론자를 실행하십시오(가능한 경우 서브에이전트로 분산, 각각 해당 평결을 반환), 그렇지 않으면 각 쌍을 인라인으로 판단하십시오 — 모든 평결을 단일 verdicts.json에 수집하고(references/orchestration.md 참조), 다음을 실행하십시오:

     node scripts/ultradoc.mjs verify --apply verdicts.json --run <도시에-디렉토리>
     node scripts/ultradoc.mjs check  --semantic --run <도시에-디렉토리>
     

     이는 해결되지 않은/출처 없는(구조적) 및 반박되거나 지원되지 않는 모든 주장에서 실패합니다 — 인용이 해석되지만 실제로 주장을 뒷받침하지 않는 간극을 메웁니다. 주장을 수정하고(재인용, 약화, 삭제 또는 더 나은 항목 검색) 통과할 때까지 재검증하십시오. 또한 references/answer-rubric.md에 대해 완전성/최신성/알 수 없음 측면에서 자체 검토하십시오.

7. 제시. 사용자에게 근거 있는 답변과 함께 인용 및 링크(파일:줄, 이슈/PR 번호, 증거의 문서/SO/웹 URL) 및 검증된 커밋을 제공하십시오.

문서 생성

사용자가 하나의 답변이 아닌 전체 프로젝트(또는 전체 패키지) 문서를 원할 때 doc을 사용하십시오. 이는 섹션 개요에 걸쳐 팬아웃된 동일한 근거 기반 루프입니다:

1. 스캐폴딩. node scripts/ultradoc.mjs doc --repo <url> [--package <p>]. 엔진은 결정론적 개요(개요, 설치/사용법, 공개 API 또는 워크스페이스 패키지당 하나의 섹션, 설정, 아키텍처)를 구축하고, 섹션별 도시에를 검색하여 이를 전역 [E#] ID가 있는 하나의 evidence.json으로 병합하고, DOC.todo.md(섹션별 작업 목록) + DOC.plan.json을 작성합니다. --sources code,docs,issues,prs를 추가하여 코드+문서 이상으로 섹션을 근거할 수 있습니다. <클론>/.ultradoc/doc/에 저장됩니다.
2. 각 섹션 작성. DOC.todo.md와 EVIDENCE.md를 읽은 다음 실행 폴더에 DOC.md를 작성하십시오: 개요 항목당 하나의 섹션, 모든 주장은 [E#]로 인용. 증거가 빈약한 섹션은 팬아웃 단위입니다 — 드릴하거나(code|docs|issues …) 간극을 명시적인 알 수 없음으로 표시하십시오. 절대 기억에서 작성하지 마십시오. 섹션별 작업은 병렬화됩니다 — references/orchestration.md를 참조하세요.
3. 검증 및 제시. node scripts/ultradoc.mjs check --run <doc-디렉토리>(그리고 verify + check --semantic for the support gate, 정확히 6단계와 동일 — 둘 다 DOC.md를 자동 감지합니다). 근거가 확보될 때까지 수정한 다음, DOC.md를 해당 커밋에 고정하여 제시하십시오.

선택적 의미론적 모드 (완전 로컬, API 키 불필요)

결정론적 Tier-1 검색(ripgrep + 기호 인덱스)이 기본값이며 아무것도 필요하지 않습니다. 더 모호하고 개념적인 질문을 위해 로컬 의미론적 검색을 활성화할 수 있습니다:

node scripts/ultradoc.mjs semantic up      # docker compose: Qdrant + Ollama (+ SearXNG)
node scripts/ultradoc.mjs ask --repo <url> --q "..." --semantic

모든 것은 로컬 Docker 컨테이너에서 실행됩니다 — 키가 없으며, 데이터가 머신을 떠나지 않습니다. 스택이 작동하지 않으면 --semantic이 공지를 기록하고 Tier-1으로 폴백합니다. references/semantic-setup.md를 참조하세요.

참조

• references/orchestration.md — 검색 드릴과 검증을 호출/서브에이전트에 걸쳐 병렬화하는 방법, 반환 및 평결 조합 계약과 순차적 폴백.
• references/retrieval-playbook.md — 소스를 선택하고 완전한 답변으로 반복하는 방법.
• references/citation-format.md — check가 강제하는 인용 문법.
• references/answer-rubric.md — 제시하기 전 의미론적 자체 검토.
• references/provider-apis.md — 호스트별로 이슈/PR을 가져오는 방법, 키 없음.

…

[truncated for translation]