XERJ.code — codificación de referencia
Un agente que no conoce una API adivina, ejecuta, falla y vuelve a adivinar. Cada vuelta cuesta tokens de salida, que son el tipo caro. Esta habilidad reemplaza vueltas con una búsqueda: clona los repositorios que ya contienen una implementación correcta, indézalos con XERJ y recupera el pasaje antes de escribir.
El intercambio es deliberado. La recuperación gasta tokens de entrada, que son
más baratos por token y almacenables en caché; los bucles gastan tokens de salida. Consulta COSTS.md para la
aritmética y las condiciones bajo las cuales este intercambio pierde.
Estado, dicho claramente: medido, y el valor es real pero limitado. (Estudio de caso completo con tokens y dólares reales:
docs/case-studies/reference-coding/CASE_STUDY.md, 2026-08-05.)La comparación que importa es contra Claude Code nativo — el mismo agente con herramientas que buscarían en el código fuente por sí mismo — no un modelo desnudo. Medido en tres regímenes, mismo agente, un veredicto objetivo (compila + pasa pruebas ocultas):
- Código desconocido con un contrato que el modelo no puede recordar (un sello, un identificador generacional, un relleno perezoso, un esquema hash específico — medido en siete bibliotecas creadas para este propósito, 21 ejecuciones): nativo y xerj resuelven 21/21; xerj usa 1.5× menos tokens de salida y cuesta 1.3× menos que nativo, porque la recuperación reemplaza la búsqueda. La memoria pura falla en 1/21 y quema 6.5× el costo en intentos fallidos. Esta es la ventaja, y es decisiva. El compilador puede filtrar un nombre de API a través de un bucle de reintento, pero nunca un contrato.
- Código memorizado (cualquier crate pública popular — incluso una tabla de 256 valores, o un varint al estilo protobuf): la recuperación es una sobrecarga. La memoria pura es la más barata; inyectar una referencia grande puede ser el peor caso, porque el modelo reemite lo que se le entregó.
Por lo tanto: usa esto cuando la referencia sea código que el modelo no ha memorizado — tu propio código privado/propietario, una API interna, una biblioteca posterior a la fecha de corte o especializada. En referencias de bibliotecas públicas que el modelo ya conoce, cuesta más de lo que ahorra. La brecha nativo-vs-xerj crece con el tamaño del corpus (la búsqueda grep arrastra todo el árbol al contexto; la recuperación extrae un solo pasaje).
Desde #977, todo el bucle está
dentro del binario xerj — xerj corpus add / xerj corpus index /
xerj code — más la herramienta MCP xerj_code_search para agentes sin un
shell. Los scripts contenedores antiguos (xc-corpus.sh, xc-index.sh, xc.py) han
desaparecido; tus corpus e índices existentes en ~/.xerj-code funcionan sin cambios (consulta
Migración más abajo).
Corpora permanentes para este repositorio (OBLIGATORIO desde 2026-08-06)
En el repositorio xerj, la recuperación-antes-de-escribir es obligatoria para trabajo de
motor no trivial, no opcional. Cada corpus a continuación tiene una definición fija y revisada
por licencia en hub/ — xerj corpus add --from hub/<nombre>.json lo reconstruye
en los mismos commits que cualquier otro está usando:
| corpus | proyectos | úsalo para |
|---|---|---|
xerj-search | lucene, tantivy, meilisearch, quickwit, sonic, elasticsearch | FTS, BM25, postings, política de fusión, tolerancia a errores tipográficos, diseño de segmentos, semántica de cable ES |
xerj-vector | qdrant, usearch, instant-distance, hnswlib | Construcción HNSW, heurísticas de vecinos, cuantización, kNN filtrada |
xerj-storage | sled, fjall, redb | WAL, épocas de vaciado, recuperación tras caída, compactación, asignación de páginas |
xerj-columnar | clickhouse | Almacenamiento columnar, ejecución de agregaciones, códecs de compresión, escaneos vectorizados |
Fuentes solo de enfoque: elasticsearch (AGPL-3.0 / SSPL-1.0 / Elastic-2.0)
y sonic (MPL-2.0). Nunca copies su código en XERJ (Apache-2.0); para ES,
pegar código fuente también falsificaría la afirmación pública del proyecto de "no comparte código con
Elasticsearch". meilisearch es MIT en el núcleo pero BUSL-1.1 para sus partes de
Enterprise Edition — verifica primero el encabezado/ruta. Lee el diseño,
escribe nuestra propia implementación. El campo review.use de cada manifiesto
dice en qué categoría está un repositorio; hub/README.md explica las tres.
Corpus del hub o corpus local
Dos tipos de corpus residen en el mismo nodo local. Cada uno responde a un tipo diferente de pregunta:
| corpus del hub | corpus local | |
|---|---|---|
| qué contiene | material público en un commit fijo: el código fuente de una biblioteca, un estándar, una regulación, un feed de asesoramiento | archivos que solo esta máquina tiene: el proyecto en el que estás trabajando, documentos privados, exportaciones |
| cuándo usarlo | cuando necesitas un detalle que no puedes citar exactamente de memoria | la respuesta está en tus propios archivos |
| cómo agregarlo | xerj corpus add --from ./<slug>.json, luego xerj corpus index <slug> | xerj autoindex <carpeta> |
| cómo consultarlo | xerj code <slug> "<pregunta>" · MCP xerj_code_search | xerj search "<palabras>" · xerj def "<símbolo>" · MCP xerj_search |
Una carpeta indexada con xerj autoindex --prefix <p> es la ruta local en esa tabla, no un corpus xerj code: xerj corpus list lee ~/.xerj-code y no lista <p> hasta que xerj corpus add registre la carpeta, y los comandos que la buscan son xerj search --prefix <p> y xerj def --prefix <p>.
No uses ninguno para un hecho que ya puedas establecer exactamente: en contenido memorizado, la recuperación es una sobrecarga (consulta la nota de estado anterior).
Un manifiesto del hub proviene de un checkout de la rama corpus-hub
(tools/xerj-code/hub/<slug>.json) o, sin un checkout, de su URL sin procesar.
Tanto corpus index como code se comunican con un nodo en ejecución:
curl -fsSLO https://raw.githubusercontent.com/xerj-org/xerj/corpus-hub/tools/xerj-code/hub/<slug>.json
xerj corpus add --from ./<slug>.json # última línea: next: xerj corpus index <slug>
xerj corpus index <slug> # termina: corpus '<slug>' searchable: <N> records
xerj code <slug> "<pregunta>" # pasajes encabezados por ruta de archivo y línea
--from lee un archivo local: v1.0.0-rc.95 no obtiene una URL, y pasar una
responde no such manifest.
Elegir un corpus para el proyecto en cuestión
Los cuatro corpora de motor anteriores son el conjunto permanente de este repositorio. El catálogo
completo en vivo se puede navegar en hub.xerj.org, con
una línea por corpus en hub.xerj.org/llms.txt;
lo que un nodo ha cargado es xerj corpus list --url <node>. Cada corpus está
fijado a un commit con su licencia registrada por fuente. G7 (una
compuerta de recuperación de cinco preguntas cuyo conjunto fue pre-registrado antes de que
la recuperación se ejecutara) ha sido calificado para algunos corpora y no para otros, y cada
página del hub dice cuáles. Elige por el dominio del proyecto, no por el tamaño:
| el proyecto es… | empieza con | por qué |
|---|---|---|
| un motor de búsqueda / consultas | xerj-search | postings, BM25, política de fusión, diseño de segmentos, semántica de cable ES |
| búsqueda vectorial / ANN | xerj-vector, faiss, annoy | Construcción HNSW, heurísticas de vecinos, cuantización, kNN filtrada; faiss es la implementación ANN de referencia, annoy la variante de bosque |
| motor de almacenamiento / KV | xerj-storage, duckdb, rocksdb, leveldb, badger, lmdb, pebble, valkey-src | WAL, recuperación tras caída, compactación, asignación de páginas; árboles LSM-vs-B; pebble para subniveles L0 y semántica de eliminación por rango; valkey para las estructuras de datos de un servidor KV en memoria |
| analítico / columnar | xerj-columnar, duckdb, arrow-rs, parquet-format, iceberg | Diseño columnar, códecs, escaneos vectorizados, formatos de tabla |
| un servidor de base de datos | sqlite-src, postgres-src | Analizadores sintácticos, planificadores, ejecutores — las dos bases de código más estudiadas en el campo |
| mensajería / consenso | kafka-src, rabbitmq, nats-server, etcd-src, raft-rs, dragonboat | Compactación de registros, semántica de entrega, corrección de cuórum/arrendamiento |
| monitoreo / series temporales | influxdb, prometheus-src | Diseño TSDB, reducción de muestreo, rutas de recolección/ingesta |
| TLS / criptografía / túneles | rustls, openssl, s2n-tls, boringtun | TLS-moderno-a-mano, precedentes de endurecimiento, patrones de tiempo constante |
| QUIC / HTTP / redes | quinn, nghttp2, curl-src, libuv, caddy, envoy, nginx | Máquinas de estado de protocolo, agrupación de conexiones, bucles de eventos |
| compresión / serialización | zstd, lz4, brotli, zlib-ng, snappy, protobuf, flatbuffers, capnproto, msgpack-c | Diseño de formato, codificación por bloques/entropía, esquemas de copia cero |
| servidor de secretos / configuración | openbao | Almacén KV con sellado/desellado, maquinaria de arrendamiento |
| revisión de diseño de API | rust-api-guidelines, msft-api-guidelines, zalando-restful-api-guidelines, google-eng-practices | Nomenclatura, forma de error, versionado; Zalando es el conjunto de políticas REST más completo en cláusulas, google-eng-practices es dueño de la doctrina de revisión de código |
| conformidad con protocolos/especificaciones | openapi-spec, graphql-spec, json-schema-spec, w3c-css, whatwg-specs, ecma262, nats-protocol, kafka-protocol | El texto normativo contra el que se juzga una implementación — estándares vivos HTML/DOM/URL, gramática ECMAScript, formato de protocolo de cable |
| localizar el RFC correcto antes de leerlo | ietf-rfc-abstracts | Un registro por RFC (9,015): número, título, fecha, resumen — "qué RFC cubre realmente X" sin extraer textos completos (TLP-5.0) |
| operaciones de producción / SRE | gitlab-runbooks, school-of-sre, tldr-pages, mozilla-ssl-configs, twelve-factor | Libros de jugadas de incidentes reales, un plan de estudios completo de SRE, sintaxis de comandos por herramienta, configuraciones TLS desplegadas, doctrina de despliegue |
| administración de sistemas Unix | freebsd-handbook, openbsd-faq | Procedimientos rc/ZFS/jail/redes, las posiciones canónicas de las FAQ de OpenBSD |
| documentación contra una API alojada | github-api-description | La descripción OpenAPI de github.rest — semántica de campos, valores de enumeración, encabezados de vista previa |
| documentos de operaciones de almacén de datos | valkey-docs, etcd-docs | Semántica de comandos, perillas de configuración, guía de ajuste — la referencia operativa para cada uno |
| cableado de telemetría / observabilidad | la mitad semconv de otel-proto (candidato — G7 2/5, estacionado en el carril semántico) | Convenciones semánticas de OpenTelemetry para nombres de atributos; las rondas léxicas no pudieron cerrar la paráfrasis a prosa normativa |
| internacionalización | unicode-cldr | Estructura de datos de configuración regional CLDR, esqueletos de calendario/número/fecha |
| revisión de seguridad de dependencias Rust | rustsec-advisories, el paquete rust-vulns (xerj corpus add --from la receta del hub) | Un registro de texto por aviso (1,963: RustSec + OSV de crates.io, sin superposición de alias): versiones afectadas, versiones corregidas, listas de símbolos de funciones afectadas en 271; el paquete sigue siendo el vehículo para la minería de pares parcheados (estudio de clase de defecto #1111) |
| revisión de seguridad de dependencias Python | pysec | Registros de aviso PYSEC con versiones afectadas y corregidas, alias CVE/GHSA |
| auditoría de dependencias entre ecosistemas | ghsa-db | Avisos revisados por GitHub (36,263 registros de texto): vectores CVSS, rangos parcheados, paquetes afectados en npm/PyPI/Go/Rust/maven y el resto |
| revisión de seguridad de módulos Go | go-vulndb | Avisos seleccionados por el equipo de Go (4,577): paquetes y símbolos afectados, versiones corregidas, IDs GO con alias CVE |
| precedente de denegación de servicio por expresiones regulares | redos-precedent | 634 avisos de ReDoS específicos de expresiones regulares (clase CWE-1337/185, no CWE-400 desnuda): la entrada patológica, la función afectada, la reescritura acotada |
| precedente de mal uso criptográfico | crypto-misuse-precedent | 721 avisos clase CWE-326/327/328/329/347: cifrados débiles, claves codificadas, reutilización de nonce, bypass de verificación de firma, oráculos de relleno, ECB |
| taxonomía de vulnerabilidades / debilidades | mitre-cwe, mitre-capec | Definiciones de debilidades CWE y patrones de ataque CAPEC, a nivel de id |
| técnicas de adversario / ingeniería de detección | mitre-attck | Registros por técnica ATT&CK v19.2: ids de técnica, tácticas, fuentes de datos de detección, ejemplos de procedimiento (empresarial/móvil/ics; objetos de software y grupo fuera del alcance) |
| priorización de parches | cisa-kev | El catálogo de Vulnerabilidades Explotadas Conocidas, un registro por CVE — estado de explotación en la naturaleza, fechas de remediación vinculantes |
| guía de seguridad de aplicaciones web | owasp-cheatsheets | Las recetas de contramedidas de la Serie de Hojas de Referencia por tema — gestión de sesiones, secretos de autenticación, manejo de errores, manejo de subidas |
| planificación de una prueba de penetración de aplicaciones web | owasp-wstg | El catálogo de la Guía de Pruebas de Seguridad Web v4.2: objetivos y método por prueba, organizados por categoría (autenticación, autorización, sesión, manejo de entrada) |
| evaluación de una campaña activa | cisa-alerts | IOCs de avisos CISA, acciones requeridas y mitigaciones (ventana 2025-05..2026-10) |
| consulta de visibilidad de endpoints | osquery-config-examples | Paquetes osquery reales desplegados y formas de consulta programada |
| no software (impuestos, empleo, ley del Reino Unido) | ecfr-title-12, ecfr-title-29, ecfr-title-26, uk-legislation | Regulación actual consolidada, sección por archivo |
| aviación (FARs) | ecfr-title-14 | 14 CFR sección por archivo: mínimos de visibilidad, espacio aéreo de transpondedor, intervalos de inspección, derecho de paso |
| reglas de navegación marítima | navrules | Texto por regla COMDTINST M16672.2D — riesgo de colisión, canales angostos, situaciones de cruce, luces y señales de sonido |
| componentes de UI accesibles | govuk-design-system | Opciones de componentes GOV.UK y criterios de accesibilidad — la semántica de opciones exacta (maxwords vs maxlength, texto de divisor, focus-on-load) |
| etiquetas de medicamentos farmacéuticos | dailymed | Secciones de etiquetas FDA: indicaciones, contraindicaciones, momento de administración |
| guía de tratamiento clínico | cdc-clinical | Regímenes y dosis de tratamiento de ITS del CDC, desensibilización a la sífilis, signos clínicos de sarampión |
| seguridad en servicios de alimentos | fda-food-code | Disposiciones del Código de Alimentos FDA 2022: superficies de contacto manual, Tiempo como Control de Salud Pública, marcado de fechas, preparación sin manos |
| dispositivos de control de tráfico | mutcd | MUTCD 11.ª Edición (Rev 1) de la FHWA: autorizaciones de señales y semáforos, marcas, aplicaciones típicas de zonas de trabajo |
| obras de construcción (Inglaterra) | uk-building-regs | Reglamento de Construcción 2010 (SI 2010/2214) por disposición: requisitos de las Partes A–P, variaciones de Gales |
Uso
1. Agregar un corpus (una vez por corpus)
# desde el repositorio xerj
xerj corpus add --from tools/xerj-code/hub/xerj-search.json
O desde la URL sin procesar:
curl -fsSLO https://raw.githubusercontent.com/xerj-org/xerj/corpus-hub/tools/xerj-code/hub/xerj-search.json
xerj corpus add --from xerj-search.json
2. Indexar el corpus (una vez por corpus, repetir cuando se actualice la referencia)
xerj corpus index xerj-search
3. Consultar el código antes de escribir
# Pregunta sobre un diseño o función
xerj code xerj-search "¿Cómo maneja Lucene la eliminación de documentos de un segmento?
# Obtener pasajes para una tarea
xerj code xerj-storage "Estrategias de compactación en sled y fjall"
4. Indexar tu propio código (opcional)
xerj autoindex /ruta/a/tu/proyecto
xerj search "algoritmo de cruce de Armstrong"
Herramienta MCP
Para agentes sin un shell (por ejemplo, Claude Code Desktop), la habilidad expone
la herramienta xerj_code_search. El agente la llama con un nombre de corpus y
una pregunta en lenguaje natural; devuelve pasajes encabezados por ruta de archivo
y línea.
Migración desde los scripts contenedores (#977)
Si anteriormente usaste xc-corpus.sh, xc-index.sh o xc.py, tus
datos en ~/.xerj-code son totalmente compatibles. El nuevo flujo es:
xc-corpus.sh add <manifiesto>→xerj corpus add --from <manifiesto>xc-corpus.sh index <slug>→xerj corpus index <slug>xc.py search <slug> <pregunta>→xerj code <slug> "<pregunta>"xc.py search local <palabras>→xerj search "<palabras>"
Los scripts antiguos ya no existen; usa el binario xerj. Los nombres de los
corpus y los índices son los mismos. No se requiere ninguna migración de datos.
Cuándo usar (y cuándo no)
Valor máximo:
- Tu propia base de código privada o propietaria.
- APIs internas o de terceros especializadas que el modelo no conoce.
- Algoritmos o protocolos no triviales que el modelo probablemente no recuerde palabra por palabra.
- Cuando estás en un bucle de reintento de más de 2 iteraciones.
Valor mínimo o negativo:
- APIs públicas populares (por ejemplo, la biblioteca estándar de Rust, el núcleo de Python,
requests). - Contenido que el modelo haya memorizado (por ejemplo, tablas de búsqueda pequeñas, formatos comunes).
- Cuando el costo de la consulta de recuperación supera el costo del bucle de reintento. La brecha crece con el tamaño del corpus; para un solo pasaje, la recuperación puede ser más costosa que un grep directo.
Advertencia sobre licencias
Los manifiestos del hub registran la licencia de cada fuente. Los repositorios
clonados por xerj corpus index son solo de lectura local; no se copia código
en el repositorio xerj. Sin embargo, la recuperación de pasajes puede incluir
código con licencias restrictivas (AGPL, SSPL, BUSL, MPL, etc.) en la salida
que el agente recibe. Asegúrate de cumplir con los términos de la licencia del
proyecto original al usar el código recuperado. No copies código sujeto a
licencias que entren en conflicto con la licencia Apache-2.0 de XERJ.
Referencias adicionales
- Estudio de caso: Codificación de referencia
- Análisis de costos
- Documentación de XERJ:
xerj helpyxerj help code - Catálogo del hub: hub.xerj.org
- Repositorio: xerj-org/xerj