XERJ.code — 참조 코딩
API를 모르는 에이전트는 추측하고, 실행하고, 실패하고, 다시 추측합니다. 각 반복은 출력 토큰을 소모하며, 이는 비용이 많이 드는 종류입니다. 이 스킬은 반복을 조회로 대체합니다. 이미 올바른 구현을 포함하는 저장소를 복제하고, XERJ로 인덱싱한 후, 코드를 작성하기 전에 해당 구문을 검색합니다.
이는 의도적인 트레이드오프입니다. 검색은 토큰당 비용이 저렴하고 캐싱 가능한
입력 토큰을 사용하는 반면, 반복은 출력 토큰을 소모합니다. 산술 및
이 트레이드오프가 실패하는 조건에 대해서는
COSTS.md를 참조하세요.
상태, 솔직히 말하면: 측정되었으며, 가치는 분명하지만 좁습니다. (실제 토큰 및 비용에 대한 전체 사례 연구:
docs/case-studies/reference-coding/CASE_STUDY.md, 2026-08-05.)중요한 비교는 네이티브 Claude Code — 소스 자체를 grep할 도구를 가진 동일한 에이전트 — 대비이며, 베어 모델과의 비교가 아닙니다. 세 가지 영역에서 동일한 에이전트로 측정된 단일 객관적 판정(컴파일 성공 + 숨은 테스트 통과):
- 모델이 기억하지 못하는 계약을 가진 익숙하지 않은 코드 (씰, 세대 핸들, 지연 리필, 특정 해시 체계 — 7개의 목적별 라이브러리, 21회 실행): 네이티브와 xerj 모두 21/21 해결; xerj는 네이티브보다 출력 토큰을 1.5배 적게 사용하고 비용은 1.3배 저렴합니다. 검색이 grep을 대체하기 때문입니다. 순수 메모리는 21회 중 1회 실패하고 6.5배의 비용을 소모하며 헤맵니다. 이것이 승리이며, 결정적입니다. 컴파일러는 재시도 루프를 통해 API 이름을 누출할 수 있지만, 계약은 절대 누출하지 않습니다.
- 암기된 코드 (널리 알려진 공개 크레이트 — 256값 테이블이나 protobuf 스타일 varint 등): 검색은 오버헤드입니다. 순수 메모리가 가장 저렴합니다. 큰 참조를 주입하는 것은 모델이 제공받은 것을 그대로 다시 출력하기 때문에 최악의 조건이 될 수 있습니다.
따라서: 참조가 모델이 암기하지 않은 코드일 때 사용하십시오 — 자체 비공개/독점 코드, 내부 API, 컷오프 이후 또는 틈새 라이브러리. 모델이 이미 알고 있는 공개 라이브러리 참조에서는 절약보다 비용이 더 듭니다. 네이티브 대비 xerj의 차이는 말뭉치 크기에 따라 증가합니다(grep은 전체 트리를 컨텍스트로 가져오고, 검색은 하나의 구문을 가져옵니다).
#977 이후 전체 루프는
xerj 바이너리 내부에 있습니다 — xerj corpus add / xerj corpus index /
xerj code — 그리고 셸이 없는 에이전트를 위한 xerj_code_search MCP 도구가
있습니다. 이전 래퍼 스크립트(xc-corpus.sh, xc-index.sh, xc.py)는
제거되었습니다. 기존 ~/.xerj-code 말뭉치와 인덱스는 변경 없이 작동합니다
(아래 마이그레이션 참조).
이 저장소의 상시 말뭉치 (2026-08-06부터 필수)
xerj 저장소에서, 작성 전 검색은 사소한 엔진 작업에 필수이며 선택 사항이
아닙니다. 아래 각 말뭉치는 hub/에 고정되고 라이선스 검토된 정의가
있습니다 — xerj corpus add --from hub/<name>.json은 다른 사람이 사용하는
동일한 커밋으로 이를 재구축합니다:
| 말뭉치 | 프로젝트 | 용도 |
|---|---|---|
xerj-search | lucene, tantivy, meilisearch, quickwit, sonic, elasticsearch | FTS, BM25, 포스팅, 병합 정책, 오타 허용, 세그먼트 레이아웃, ES 유선 의미론 |
xerj-vector | qdrant, usearch, instant-distance, hnswlib | HNSW 구축, 이웃 휴리스틱, 양자화, 필터링된 kNN |
xerj-storage | sled, fjall, redb | WAL, 플러시 에포크, 충돌 복구, 컴팩션, 페이지 할당 |
xerj-columnar | clickhouse | 컬럼 스토리지, 집계 실행, 압축 코덱, 벡터화된 스캔 |
참고 전용 소스: elasticsearch (AGPL-3.0 / SSPL-1.0 / Elastic-2.0)
및 sonic (MPL-2.0). Apache-2.0 XERJ에 코드를 복사하지 마십시오. ES의
경우 소스를 붙여넣으면 프로젝트의 "Elasticsearch와 코드를 공유하지 않음"
이라는 공개 주장을 위조하게 됩니다. meilisearch는 코어는 MIT이지만
Enterprise Edition 부분은 BUSL-1.1입니다 — 먼저 헤더/경로를 확인하세요.
디자인을 읽고 자체 구현을 작성하십시오. 각 매니페스트의 review.use 필드는
저장소가 속한 버킷을 나타냅니다. hub/README.md는 세 가지를 설명합니다.
허브 말뭉치 또는 로컬 말뭉치
두 종류의 말뭉치는 동일한 로컬 노드에 있습니다. 각각은 다른 종류의 질문에 답변합니다:
| 허브 말뭉치 | 로컬 말뭉치 | |
|---|---|---|
| 내용 | 고정된 커밋의 공개 자료: 라이브러리 소스, 표준, 규정, 권고 피드 | 이 시스템에만 있는 파일: 작업 중인 프로젝트, 개인 문서, 내보내기 |
| 사용 시기 | 기억에서 정확히 인용할 수 없는 세부 정보가 필요할 때 | 답변이 자신의 파일에 있을 때 |
| 추가 방법 | xerj corpus add --from ./<slug>.json, 그 다음 xerj corpus index <slug> | xerj autoindex <folder> |
| 쿼리 방법 | xerj code <slug> "<question>" · MCP xerj_code_search | xerj search "<words>" · xerj def "<symbol>" · MCP xerj_search |
xerj autoindex --prefix <p>로 인덱싱된 폴더는 해당 테이블의 로컬 경로이며,
xerj code 말뭉치가 아닙니다. xerj corpus list는 ~/.xerj-code를 읽고
xerj corpus add가 해당 폴더를 등록할 때까지 <p>를 나열하지 않습니다.
검색 명령어는 xerj search --prefix <p> 및 xerj def --prefix <p>입니다.
이미 정확히 진술할 수 있는 사실에는 둘 다 사용하지 마십시오. 암기된 내용에서 검색은 오버헤드입니다(위 상태 참고 참조).
허브 매니페스트는 corpus-hub 브랜치 체크아웃
(tools/xerj-code/hub/<slug>.json) 또는 체크아웃 없이 원시 URL에서
가져옵니다. corpus index 및 code는 모두 실행 중인 노드와 통신합니다:
curl -fsSLO https://raw.githubusercontent.com/xerj-org/xerj/corpus-hub/tools/xerj-code/hub/<slug>.json
xerj corpus add --from ./<slug>.json # 마지막 줄: 다음: xerj corpus index <slug>
xerj corpus index <slug> # 종료: 말뭉치 '<slug>' 검색 가능: <N> 레코드
xerj code <slug> "<question>" # 파일 경로와 줄 번호가 앞에 붙은 구절들
--from은 로컬 파일을 읽습니다. v1.0.0-rc.95는 URL을 가져오지 않으며,
URL을 전달하면 해당 매니페스트 없음으로 응답합니다.
현재 프로젝트에 적합한 말뭉치 선택
위의 네 가지 엔진 말뭉치는 이 저장소의 상시 세트입니다. 전체 라이브
카탈로그는 **hub.xerj.org**에서 탐색할 수 있으며,
hub.xerj.org/llms.txt에 말뭉치당 한 줄씩
있습니다. 노드가 로드한 것은 xerj corpus list --url <node>입니다. 모든
말뭉치는 소스별로 라이선스가 기록된 커밋으로 고정됩니다. G7 (검색
실행 전에 사전 등록된 5개 질문 검색 게이트)은 일부 말뭉치에 대해
평가되었고 다른 말뭉치는 평가되지 않았으며, 각 허브 페이지에 표시됩니다.
크기가 아닌 프로젝트의 도메인으로 선택하십시오:
| 프로젝트가… | 다음으로 시작 | 이유 |
|---|---|---|
| 검색/쿼리 엔진 | xerj-search | 포스팅, BM25, 병합 정책, 세그먼트 레이아웃, ES 유선 의미론 |
| 벡터 검색 / ANN | xerj-vector, faiss, annoy | HNSW 구축, 이웃 휴리스틱, 양자화, 필터링된 kNN; faiss는 참조 ANN 구현, annoy는 포레스트 변형 |
| 스토리지 엔진 / KV | xerj-storage, duckdb, rocksdb, leveldb, badger, lmdb, pebble, valkey-src | WAL, 충돌 복구, 컴팩션, 페이지 할당; LSM-vs-B 트리; pebble은 L0 하위 수준 및 범위 삭제 의미론, valkey은 인메모리 KV 서버의 데이터 구조 |
| 분석 / 컬럼형 | xerj-columnar, duckdb, arrow-rs, parquet-format, iceberg | 컬럼 레이아웃, 코덱, 벡터화된 스캔, 테이블 포맷 |
| 데이터베이스 서버 | sqlite-src, postgres-src | 파서, 플래너, 실행기 — 이 분야에서 가장 많이 연구된 두 코드베이스 |
| 메시징 / 합의 | kafka-src, rabbitmq, nats-server, etcd-src, raft-rs, dragonboat | 로그 컴팩션, 전달 의미론, 쿼럼/임대 정확성 |
| 모니터링 / 시계열 | influxdb, prometheus-src | TSDB 레이아웃, 다운샘플링, 스크랩/수집 경로 |
| TLS / 암호화 / 터널 | rustls, openssl, s2n-tls, boringtun | 직접 현대-TLS, 강화 선례, 상수 시간 패턴 |
| QUIC / HTTP / 네트워킹 | quinn, nghttp2, curl-src, libuv, caddy, envoy, nginx | 프로토콜 상태 기계, 연결 풀링, 이벤트 루프 |
| 압축 / 직렬화 | zstd, lz4, brotli, zlib-ng, snappy, protobuf, flatbuffers, capnproto, msgpack-c | 포맷 설계, 블록/엔트로피 코딩, 제로 카피 스키마 |
| 비밀 / 설정 제공 | openbao | 씰/언씰이 있는 KV 저장소, 임대 메커니즘 |
| API 설계 검토 | rust-api-guidelines, msft-api-guidelines, zalando-restful-api-guidelines, google-eng-practices | 명명, 오류 형태, 버전 관리; Zalando가 가장 조항이 완전한 REST 정책 세트, google-eng-practices가 코드 검토 원칙을 소유 |
| 프로토콜/사양 적합성 | openapi-spec, graphql-spec, json-schema-spec, w3c-css, whatwg-specs, ecma262, nats-protocol, kafka-protocol | 구현이 평가되는 기준 규범 텍스트 — HTML/DOM/URL 실시간 표준, ECMAScript 문법, 유선 프로토콜 프레이밍 |
| 읽기 전에 올바른 RFC 찾기 | ietf-rfc-abstracts | RFC당 하나의 레코드 (9,015개): 번호, 제목, 날짜, 초록 — 전체 텍스트를 가져오지 않고 "X를 실제로 다루는 RFC" (TLP-5.0) |
| 프로덕션 운영 / SRE | gitlab-runbooks, school-of-sre, tldr-pages, mozilla-ssl-configs, twelve-factor | 실제 인시던트 플레이북, 전체 SRE 과정 커리큘럼, 도구별 명령 구문, 배포된 TLS 구성, 배포 원칙 |
| Unix 시스템 관리 | freebsd-handbook, openbsd-faq | rc/ZFS/jail/네트워킹 절차, OpenBSD의 표준 FAQ 입장 |
| 호스팅된 API에 대한 문서 | github-api-description | github.rest의 OpenAPI 설명 — 필드 의미론, 열거형 값, 미리보기 헤더 |
| 데이터스토어 운영 문서 | valkey-docs, etcd-docs | 명령 의미론, 구성 옵션, 튜닝 지침 — 각각에 대한 운영 참조 |
| 원격 측정 / 관찰 가능성 배선 | otel-proto의 semconv 절반 (후보 — G7 2/5, 의미론 레인으로 이동) | 속성 이름에 대한 OpenTelemetry 의미론 규칙; 어휘 라운드가 의역에서 규범 산문으로 연결할 수 없음 |
| 국제화 | unicode-cldr | CLDR 로케일 데이터 구조, 달력/숫자/날짜 스켈레톤 |
| Rust 종속성 보안 검토 | rustsec-advisories, rust-vulns 팩 (xerj corpus add --from 허브 레시피 사용) | 권고당 하나의 텍스트 레코드 (1,963개: RustSec + crates.io OSV, 별칭 중복 없음): 영향을 받는 버전, 수정된 릴리스, 271개에 대한 영향을 받는 함수 기호 목록; 팩은 패치된 쌍 마이닝을 위한 수단을 유지 (#1111의 결함 클래스 연구) |
| Python 종속성 보안 검토 | pysec | 영향을 받는 버전과 수정된 버전, CVE/GHSA 별칭이 있는 PYSEC 권고 레코드 |
| 교차 에코시스템 종속성 감사 | ghsa-db | GitHub 검토된 권고 (36,263개 텍스트 레코드): CVSS 벡터, 패치된 범위, npm/PyPI/Go/Rust/maven 등 영향을 받는 패키지 |
| Go 모듈 보안 검토 | go-vulndb | Go 팀 선별 권고 (4,577개): 영향을 받는 패키지 및 기호, 수정된 버전, CVE 별칭이 있는 GO ID |
| 정규식 서비스 거부 선례 | redos-precedent | 634개의 ReDoS 특정 권고 (CWE-1337/185 클래스, 일반 CWE-400 아님): 병리적 입력, 영향을 받는 함수, 제한된 재작성 |
| 암호화 오용 선례 | crypto-misuse-precedent | 721개의 CWE-326/327/328/329/347 클래스 권고: 약한 암호, 하드코딩된 키, 논스 재사용, 서명 확인 우회, 패딩 오라클, ECB |
| 취약점/약점 분류법 | mitre-cwe, mitre-capec | CWE 약점 정의 및 CAPEC 공격 패턴, ID 수준 |
| 공격자 기법 / 탐지 엔지니어링 | mitre-attck | ATT&CK v19.2 기법당 레코드: 기법 ID, 전술, 탐지 데이터 소스, 절차 예제 (엔터프라이즈/모바일/ICS; 소프트웨어 및 그룹 개체는 범위 밖) |
| 패치 우선순위 분류 | cisa-kev | 알려진 악용 취약점 카탈로그, CVE당 하나의 레코드 — 실제 악용 상태, 필수 수정 날짜 |
| 웹 애플리케이션 보안 방법 | owasp-cheatsheets | 주제별 Cheat Sheet Series의 대응 방법 — 세션 관리, 인증 비밀, 오류 처리, 업로드 처리 |
| 웹 앱 침투 테스트 계획 | owasp-wstg | 웹 보안 테스트 가이드 v4.2 카탈로그: 테스트별 목표 및 방법, 범주별 구성 (authn, authz, 세션, 입력 처리) |
| 활성 캠페인 분류 | cisa-alerts | CISA 권고 IOCs, 필요한 조치 및 완화 (2025-05..2026-10 기간) |
| 엔드포인트 가시성 쿼리 | osquery-config-examples | 실제 배포된 osquery 팩 및 예약된 쿼리 형태 |
| 비소프트웨어 (세금, 고용, 영국법) | ecfr-title-12, ecfr-title-29, ecfr-title-26, uk-legislation | 통합된 현재 규정, 파일당 섹션 |
| 항공 (FARs) | ecfr-title-14 | 14 CFR 파일당 섹션: 가시성 최저치, 트랜스폰더 영공, 검사 간격, 통행 우선권 |
| 해상 충돌 방지 규칙 | navrules | COMDTINST M16672.2D 규칙당 텍스트 — 충돌 위험, 좁은 수로, 교차 상황, 등화 및 음향 신호 |
| 접근 가능한 UI 구성 요소 | govuk-design-system | GOV.UK 구성 요소 옵션 및 접근성 기준 — 정확한 옵션 의미론 (maxwords vs maxlength, 구분선 텍스트, 로드 시 포커스) |
| 제약 / 의약품 라벨 | dailymed | FDA 라벨 섹션: 적응증, 금기, 투여 시기 |
| 임상 치료 지침 | cdc-clinical | CDC STI 치료 요법 및 용량, 매독 둔감화, 홍역 임상 징후 |
| 식품 서비스 안전 | fda-food-code | FDA 식품 규정 2022 조항: 손 접촉 표면, 공중 보건 관리로서의 시간, 날짜 표시, 맨손 준비 |
| 교통 통제 장치 | mutcd | FHWA MUTCD 11판 (Rev 1): 표지판 및 신호 warrants, 표식, 작업 구역 일반 적용 |
| 건축 공사 (잉글랜드) | uk-building-regs | 건축 규정 2010 (SI 2010/2214) 조항별: A~P부 요구 사항, 웨일즈 변형 |