Was macht XERJ-Code — Referenz-Coding?
Ein Agent, der eine API nicht kennt, rät, führt aus, scheitert und rät erneut. Jede Runde kostet Output-Tokens, die teuer sind. Dieser Skill ersetzt Runden durch eine Suche: Klone die Repositories, die bereits eine korrekte Implementierung enthalten, indexiere sie mit XERJ und rufe die Passage ab, bevor du schreibst.
Der Trade-Off ist bewusst. Abruf kostet Input-Tokens, die pro Token billiger
und cachebar sind; Schleifen kosten Output-Tokens. Siehe COSTS.md für die
Arithmetik und die Bedingungen, unter denen dieser Trade-Off verliert.
Status, klar gesagt: gemessen, und der Wert ist real, aber schmal. (Vollständige Fallstudie mit echten Tokens und Dollar:
docs/case-studies/reference-coding/CASE_STUDY.md, 2026-08-05.)Der relevante Vergleich ist gegen nativen Claude Code – derselbe Agent mit Werkzeugen, die die Quelle selbst durchsuchen würden – nicht ein bloßes Modell. Gemessen über drei Bereiche, derselbe Agent, ein objektives Urteil (kompiliert + besteht versteckte Tests):
- Unbekannter Code mit einem Vertrag, an den sich das Modell nicht erinnern kann (ein Siegel, ein generationsübergreifendes Handle, eine faule Auffüllung, ein spezifisches Hash-Schema – gemessen über sieben eigens dafür erstellte Bibliotheken, 21 Durchläufe): nativ und xerj lösen beide 21/21; xerj verwendet 1,5× weniger Output-Tokens und kostet 1,3× weniger als nativ, weil der Abruf die Suche ersetzt. Reines Gedächtnis scheitert 1/21 und verbrennt 6,5× die Kosten herumirrend. Dies ist der Gewinn, und er ist entscheidend. Der Compiler kann einen API-Namen über eine Wiederholungsschleife preisgeben, aber niemals einen Vertrag.
- Auswendig gelernten Code (jede gängige öffentliche Crate – selbst eine 256-Werte-Tabelle oder ein Protobuf-artiges Varint): Abruf ist Overhead. Reines Gedächtnis ist am günstigsten; das Einfügen einer großen Referenz kann der schlechteste Arm sein, weil das Modell das wieder ausgibt, was ihm gegeben wurde.
Also: verwende dies, wenn die Referenz Code ist, den das Modell nicht auswendig gelernt hat – dein eigener privater/proprietärer Code, eine interne API, eine nach dem Cutoff-Datum oder Nischenbibliothek. Bei öffentlichen Bibliotheksreferenzen, die das Modell bereits kennt, kostet es mehr, als es spart. Die Lücke zwischen nativ und xerj wächst mit der Korpusgröße (Durchsuchen zieht den gesamten Baum in den Kontext; Abruf zieht eine Passage).
Seit #977 befindet sich die gesamte Schleife
innerhalb der xerj-Binärdatei – xerj corpus add / xerj corpus index /
xerj code – plus das MCP-Tool xerj_code_search für Agenten ohne Shell.
Die alten Wrapper-Skripte (xc-corpus.sh, xc-index.sh, xc.py) sind weg;
Ihre vorhandenen ~/.xerj-code-Korpora und -Indizes funktionieren unverändert (siehe
Migration unten).
Stehende Korpora für dieses Repository (PFLICHT seit 2026-08-06)
Im xerj-Repository ist Abruf-vor-Schreiben erforderlich für nicht-triviale
Entwicklungsarbeit, nicht optional. Jeder untenstehende Korpus hat eine festgelegte,
lizenzgeprüfte Definition in hub/ – xerj corpus add --from hub/<name>.json baut
ihn mit denselben Commits wieder auf, die jeder andere verwendet:
| Korpus | Projekte | Verwende ihn für |
|---|---|---|
xerj-search | lucene, tantivy, meilisearch, quickwit, sonic, elasticsearch | FTS, BM25, Postings, Merge-Policy, Tippfehlertoleranz, Segment-Layout, ES-Drahtsemantik |
xerj-vector | qdrant, usearch, instant-distance, hnswlib | HNSW-Aufbau, Nachbar-Heuristiken, Quantisierung, gefiltertes kNN |
xerj-storage | sled, fjall, redb | WAL, Flush-Epochen, Absturzwiederherstellung, Kompaktion, Seitenallokation |
xerj-columnar | clickhouse | Spaltenspeicherung, Aggregationsausführung, Kompressionscodecs, vektorisierte Scans |
Nur-Ansatz-Quellen: elasticsearch (AGPL-3.0 / SSPL-1.0 / Elastic-2.0)
und sonic (MPL-2.0). Kopiere niemals deren Code in Apache-2.0 XERJ; für ES
würde das Einfügen von Quellcode auch die öffentliche Behauptung des Projekts, „teilt keinen Code mit
Elasticsearch”, falsifizieren. meilisearch ist im Kern MIT, aber BUSL-1.1 für dessen Enterprise Edition-
Teile – überprüfe zuerst den Header/Pfad. Lies das Design,
schreibe unsere eigene Implementierung. Das review.use-Feld jedes Manifests gibt an, in welchen
Eimer ein Repository fällt; hub/README.md erklärt die drei.
Hub-Korpus oder lokaler Korpus
Zwei Arten von Korpora befinden sich auf demselben lokalen Knoten. Jeder beantwortet eine andere Art von Frage:
| Hub-Korpus | Lokaler Korpus | |
|---|---|---|
| was er enthält | öffentliches Material bei einem festgelegten Commit: Quellcode einer Bibliothek, ein Standard, eine Verordnung, ein Beratungsfeed | Dateien, die nur dieser Rechner hat: das Projekt, an dem du arbeitest, private Dokumente, Exporte |
| wann verwenden | du benötigst ein Detail, das du nicht genau aus dem Gedächtnis zitieren kannst | die Antwort ist in deinen eigenen Dateien |
| hinzufügen | xerj corpus add --from ./<slug>.json, dann xerj corpus index <slug> | xerj autoindex <verzeichnis> |
| abfragen | xerj code <slug> "<frage>" · MCP xerj_code_search | xerj search "<wörter>" · xerj def "<symbol>" · MCP xerj_search |
Ein mit xerj autoindex --prefix <p> indexiertes Verzeichnis ist der lokale Pfad in jener Tabelle, kein xerj code-Korpus: xerj corpus list liest ~/.xerj-code und listet <p> erst auf, wenn xerj corpus add das Verzeichnis registriert; die Befehle, die es durchsuchen, sind xerj search --prefix <p> und xerj def --prefix <p>.
Verwende keines für eine Tatsache, die du bereits genau angeben kannst: Bei auswendig gelerntem Inhalt ist der Abruf Overhead (siehe Hinweis zum Status oben).
Ein Hub-Manifest stammt aus einem Checkout des corpus-hub-Branches
(tools/xerj-code/hub/<slug>.json) oder, ohne Checkout, von seiner rohen URL.
Sowohl corpus index als auch code kommunizieren mit einem laufenden Knoten:
curl -fsSLO https://raw.githubusercontent.com/xerj-org/xerj/corpus-hub/tools/xerj-code/hub/<slug>.json
xerj corpus add --from ./<slug>.json # letzte Zeile: next: xerj corpus index <slug>
xerj corpus index <slug> # endet: corpus '<slug>' searchable: <N> records
xerj code <slug> "<frage>" # Passagen, die mit Dateipfad und Zeile beginnen
--from liest eine lokale Datei: v1.0.0-rc.95 holt keine URL, und die Übergabe einer URL
ergibt die Antwort no such manifest.
Auswahl eines Korpus für das vorliegende Projekt
Die vier Engine-Korpora oben sind der festgelegte Satz dieses Repositorys. Der vollständige
live-Katalog ist durchsuchbar unter hub.xerj.org, mit
einer Zeile pro Korpus in hub.xerj.org/llms.txt;
was ein Knoten geladen hat, ist xerj corpus list --url <knoten>. Jeder Korpus ist
auf einen Commit festgelegt, wobei seine Lizenz pro Quelle aufgezeichnet ist. G7 (ein
Fünf-Fragen-Abruf-Gate, dessen Suite vor dem Abruf vorregistriert wurde) wurde für einige
Korpora bewertet und für andere nicht, und jede Hub-Seite gibt an, welche. Wähle nach dem Bereich des Projekts, nicht nach der Größe:
| das Projekt ist… | beginne mit | warum |
|---|---|---|
| eine Such-/Abfrage-Engine | xerj-search | Postings, BM25, Merge-Policy, Segment-Layout, ES-Drahtsemantik |
| Vektorsuche / ANN | xerj-vector, faiss, annoy | HNSW-Aufbau, Nachbar-Heuristiken, Quantisierung, gefiltertes kNN; faiss ist die Referenz-ANN-Implementierung, annoy die Wald-Variante |
| Speicher-Engine / KV | xerj-storage, duckdb, rocksdb, leveldb, badger, lmdb, pebble, valkey-src | WAL, Absturzwiederherstellung, Kompaktion, Seitenallokation; LSM-vs-B-Bäume; pebble für L0-Unterebenen und Bereichslöschsemantik; valkey für die Datenstrukturen eines In-Memory-KV-Servers |
| analytisch / spaltenorientiert | xerj-columnar, duckdb, arrow-rs, parquet-format, iceberg | Spaltenlayout, Codecs, vektorisierte Scans, Tabellenformate |
| ein Datenbankserver | sqlite-src, postgres-src | Parser, Planer, Executors – die beiden am meisten untersuchten Codebasen auf diesem Gebiet |
| Messaging / Konsens | kafka-src, rabbitmq, nats-server, etcd-src, raft-rs, dragonboat | Log-Kompaktion, Zustellsemantik, Quorum/Lease-Korrektheit |
| Überwachung / Zeitreihen | influxdb, prometheus-src | TSDB-Layout, Downsampling, Scrape/Ingest-Pfade |
| TLS / Crypto / Tunnel | rustls, openssl, s2n-tls, boringtun | modern-TLS-von-Hand, Härtungspräzedenzfall, Constant-Time-Muster |
| QUIC / HTTP / Vernetzung | quinn, nghttp2, curl-src, libuv, caddy, envoy, nginx | Protokoll-Zustandsmaschinen, Verbindungspooling, Ereignisschleifen |
| Kompression / Serialisierung | zstd, lz4, brotli, zlib-ng, snappy, protobuf, flatbuffers, capnproto, msgpack-c | Formatdesign, blockierte/Entropie-Codierung, Zero-Copy-Schemata |
| Secrets / Konfigurationsbereitstellung | openbao | KV-Speicher mit Seal/Unseal, Lease-Mechanik |
| API-Design-Überprüfung | rust-api-guidelines, msft-api-guidelines, zalando-restful-api-guidelines, google-eng-practices | Benennung, Fehlerform, Versionierung; Zalando ist das klauselnvollständigste REST-Richtlinienset, google-eng-practices besitzt die Code-Review-Doktrin |
| Protokoll/Spezifikationskonformität | openapi-spec, graphql-spec, json-schema-spec, w3c-css, whatwg-specs, ecma262, nats-protocol, kafka-protocol | der normative Text, an dem eine Implementierung gemessen wird – HTML/DOM/URL-Living-Standards, ECMAScript-Grammatik, Drahtprotokoll-Rahmen |
| das richtige RFC vor dem Lesen finden | ietf-rfc-abstracts | ein Eintrag pro RFC (9.015): Nummer, Titel, Datum, Zusammenfassung – „welches RFC behandelt eigentlich X” ohne vollständige Texte zu ziehen (TLP-5.0) |
| Produktionsbetrieb / SRE | gitlab-runbooks, school-of-sre, tldr-pages, mozilla-ssl-configs, twelve-factor | echte Vorfall-Playbooks, ein vollständiger SRE-Kurslehrplan, Befehlssyntax nach Werkzeug, eingesetzte TLS-Konfigurationen, Bereitstellungsdoktrin |
| Administrieren von Unix-Systemen | freebsd-handbook, openbsd-faq | rc/ZFS/Jail/Netzwerkverfahren, OpenBSDs kanonische FAQ-Positionen |
| Dokumentieren gegen eine gehostete API | github-api-description | die OpenAPI-Beschreibung von github.rest – Feldsemantik, Enum-Werte, Preview-Header |
| Datenspeicher-Betriebsdokumentation | valkey-docs, etcd-docs | Befehlssemantik, Konfigurationsknöpfe, Tuning-Anleitung – die betriebliche Referenz für jede |
| Telemetrie / Observability-Verdrahtung | die semconv-Hälfte von otel-proto (Kandidat – G7 2/5, auf die semantische Spur verschoben) | OpenTelemetry-Semantikkonventionen für Attributnamen; lexikalische Runden konnten die Paraphrase nicht in normative Prosa überbrücken |
| Internationalisierung | unicode-cldr | CLDR-Gebietsschema-Datenstruktur, Kalender/Datum/Zahlen-Skelette |
| Sicherheitsüberprüfung von Rust-Abhängigkeiten | rustsec-advisories, das rust-vulns-Paket (xerj corpus add --from das Hub-Rezept) | ein Texteintrag pro Beratung (1.963: RustSec + crates.io OSV, null Alias-Überlappung): betroffene Versionen, behobene Releases, betroffene Funktionssymbollisten auf 271; das Paket bleibt das Vehikel für das Mining gepatchter Paare (#1111's Fehlerklassenstudie) |
| Sicherheitsüberprüfung von Python-Abhängigkeiten | pysec | PYSEC-Beratungsdatensätze mit betroffenen und behobenen Versionen, CVE/GHSA-Aliase |
| Ökosystemübergreifende Abhängigkeitsprüfung | ghsa-db | GitHub-geprüfte Beratungen (36.263 Texteinträge): CVSS-Vektoren, gepatchte Bereiche, betroffene Pakete in npm/PyPI/Go/Rust/maven und dem Rest |
| Sicherheitsüberprüfung von Go-Modulen | go-vulndb | Vom Go-Team kuratierte Beratungen (4.577): betroffene Pakete und Symbole, behobene Versionen, GO-IDs mit CVE-Aliasen |
| Regex-Denial-of-Service-Präzedenzfall | redos-precedent | 634 regex-spezifische ReDoS-Beratungen (CWE-1337/185-Klasse, nicht bloß CWE-400): die pathologische Eingabe, die betroffene Funktion, die beschränkte Umschreibung |
| Krypto-Fehlgebrauch-Präzedenzfall | crypto-misuse-precedent | 721 CWE-326/327/328/329/347-Klassen-Beratungen: schwache Chiffren, hartcodierte Schlüssel, Nonce-Wiederverwendung, Signaturprüfungs-Umgehung, Padding-Orakel, ECB |
| Schwachstellen-/Fehlertaxonomie | mitre-cwe, mitre-capec | CWE-Schwachstellendefinitionen und CAPEC-Angriffsmuster, ID-Ebene |
| Gegner-Techniken / Erkennungsentwicklung | mitre-attck | ATT&CK v19.2 pro-Technik-Einträge: Technik-IDs, Taktiken, Erkennungsdatenquellen, Verfahrensbeispiele (Enterprise/Mobile/ICS; Software- und Gruppenobjekte außerhalb des Bereichs) |
| Patch-Prioritäts-Triage | cisa-kev | das Katalog bekannter ausgenutzter Schwachstellen, ein Eintrag pro CVE – Ausbeutungsstatus in freier Wildbahn, verbindliche Korrekturtermine |
| Webanwendungssicherheits-Anleitung | owasp-cheatsheets | die Gegenmaßnahmen-Rezepte der Cheat Sheet Series pro Thema – Sitzungsverwaltung, Authentifizierungsgeheimnisse, Fehlerbehandlung, Upload-Handling |
| Planung eines Web-App-Penetrationstests | owasp-wstg | der Katalog des Web Security Testing Guide v4.2: Ziele und Methode pro Test, organisiert nach Kategorie (Authn, Authz, Sitzung, Eingabebehandlung) |
| Triage einer aktiven Kampagne | cisa-alerts | CISA-Beratungs-IOCs, erforderliche Aktionen und Minderungen (Fenster 2025-05..2026-10) |
| Abfragen der Endpunkt-Sichtbarkeit | osquery-config-examples | real eingesetzte osquery-Pakete und Formen geplanter Abfragen |
| Nicht-Software (Steuern, Beschäftigung, britisches Recht) | ecfr-title-12, ecfr-title-29, ecfr-title-26, uk-legislation | konsolidierte aktuelle Verordnung, Abschnitt-pro-Datei |
| Luftfahrt (FARs) | ecfr-title-14 | 14 CFR Abschnitt-pro-Datei: Sichtmindestwerte, Transponder-Luftraum, Inspektionsintervalle, Vorfahrt |
| Seeverkehrsregeln | navrules | COMDTINST M16672.2D pro-Regel-Text – Kollisionsrisiko, enge Kanäle, Kreuzungssituationen, Lichter und Schallsignale |
| Zugängliche UI-Komponenten | govuk-design-system | GOV.UK-Komponentenoptionen und Zugänglichkeitskriterien – die genauen Optionssemantiken (maxwords vs maxlength, Trennzeichen-Text, Fokus-beim-Laden) |
| Pharma / Arzneimittelkennzeichnung | dailymed | FDA-Kennzeichnungsabschnitte: Indikationen, Kontraindikationen, Verabreichungszeitpunkt |
| Klinische Behandlungsleitlinien | cdc-clinical | CDC-STI-Behandlungspläne und -Dosen, Syphilis-Desensibilisierung, klinische Anzeichen von Masern |
| Lebensmittelservice-Sicherheit | fda-food-code | FDA Food Code 2022 Bestimmungen: Handkontaktflächen, Zeit als Mittel der öffentlichen Gesundheitskontrolle, Datumskennzeichnung, Bereitschaft ohne Handschuhe |
| Verkehrsleiteinrichtungen | mutcd | FHWA MUTCD 11. Auflage (Rev 1): Zeichen- und Signal-Anforderungen, Markierungen, typische Anwendungen in Arbeitszonen |
| Bauarbeiten (England) | uk-building-regs | Bauverordnung 2010 (SI 2010/2214) pro Bestimmung: Anforderungen der Teile A–P, Wales-Variationen |
[Fortsetzung folgt …]
Migration von den Wrapper-Skripten (#977)
Wenn du die alten Wrapper-Skripte (xc-corpus.sh, xc-index.sh, xc.py)
verwendet hast, werden deine bestehenden Korpora in ~/.xerj-code und Indizes
automatisch erkannt. Führe einfach Folgendes aus:
xerj corpus list # zeigt vorhandene Korpora an
xerj code <slug> "<frage>" # funktioniert sofort
Die alte MCP-Konfiguration mit xerj_code_search funktioniert ebenfalls nach
der Aktualisierung der Binärdatei; es sind keine Änderungen an der
Konfigurationsdatei erforderlich.
Fehlerbehebung
| Symptom | Höchstwahrscheinliche Ursache | Behebung |
|---|---|---|
xerj corpus add --from <url> schlägt fehl | --from erwartet eine lokale Datei, keine URL | Lade die URL zuerst herunter (z. B. mit curl -fsSLO), dann --from ./datei.json |
xerj corpus index <slug> hängt | Der Knoten läuft nicht | Starte den xerj-Knoten: xerj node oder stelle sicher, dass der Dienst läuft |
xerj code <slug> "<frage>" gibt nichts zurück | Der Korpus ist nicht indexiert oder die Frage ist zu weit gefasst | Überprüfe mit xerj corpus list, ob der Korpus durchsuchbar ist; formuliere die Frage enger |
MCP-Tool xerj_code_search nicht gefunden | Die MCP-Konfiguration verweist auf das alte Skript | Aktualisiere die Konfiguration, um auf xerj direkt zu verweisen, oder verwende den Pfad zur neuen Binärdatei |