O que XERJ.code — codificação por referência faz?
Um agente que não conhece uma API adivinha, executa, falha e adivinha novamente. Cada volta custa saída de tokens, que são os mais caros. Esta habilidade substitui voltas por uma consulta: clone os repositórios que já contêm uma implementação correta, indexe-os com XERJ e recupere o trecho antes de escrever.
A troca é deliberada. A recuperação gasta entrada de tokens, que são mais baratos por
token e armazenáveis em cache; os loops gastam saída de tokens. Consulte COSTS.md para
a aritmética e as condições sob as quais esta troca perde.
Status, dito claramente: medido, e o valor é real, mas estreito. (Estudo de caso completo com tokens e dólares reais:
docs/case-studies/reference-coding/CASE_STUDY.md, 05-08-2026.)A comparação que importa é contra o Claude Code nativo — o mesmo agente com ferramentas que fariam grep na própria fonte — não um modelo puro. Medido em três regimes, mesmo agente, um veredito objetivo (compila + passa testes ocultos):
- Código desconhecido com um contrato que o modelo não consegue lembrar (um selo, um identificador geracional, um reabastecimento preguiçoso, um esquema de hash específico — medido em sete bibliotecas feitas sob medida, 21 execuções): nativo e xerj ambos resolvem 21/21; xerj usa 1,5× menos tokens de saída e custa 1,3× menos que o nativo, porque a recuperação substitui o grep. A memória pura falha em 1/21 e queima 6,5× o custo se debatendo. Esta é a vitória, e é decisiva. O compilador pode vazar um nome de API através de um loop de repetição, mas nunca um contrato.
- Código memorizado (qualquer crate pública popular — até mesmo uma tabela de 256 valores, ou um varint estilo protobuf): a recuperação é sobrecarga. A memória pura é a mais barata; injetar uma referência grande pode ser o pior braço, porque o modelo reemite o que recebeu.
Portanto: use isto quando a referência for código que o modelo não memorizou — seu próprio código privado/proprietário, uma API interna, uma biblioteca pós-corte ou de nicho. Em referências de bibliotecas públicas que o modelo já conhece, custa mais do que economiza. A diferença nativo-vs-xerj cresce com o tamanho do corpus (grep puxa a árvore inteira para o contexto; a recuperação puxa um trecho).
Desde #977 todo o loop está
dentro do binário xerj — xerj corpus add / xerj corpus index /
xerj code — mais a ferramenta MCP xerj_code_search para agentes sem um shell.
Os scripts wrapper antigos (xc-corpus.sh, xc-index.sh, xc.py) foram removidos; seus
corpora e índices ~/.xerj-code existentes funcionam inalterados (consulte
Migração abaixo).
Corpora padrão para este repositório (OBRIGATÓRIO desde 06-08-2026)
No repositório xerj, a recuperação-antes-de-escrever é obrigatória para trabalho
não trivial no mecanismo, não opcional. Cada corpus abaixo tem uma definição fixa e revisada por licença
em hub/ — xerj corpus add --from hub/<nome>.json o reconstrói
nos mesmos commits que qualquer outro está usando:
| corpus | projetos | use para |
|---|---|---|
xerj-search | lucene, tantivy, meilisearch, quickwit, sonic, elasticsearch | FTS, BM25, postings, política de merge, tolerância a erros de digitação, layout de segmento, semântica de fio ES |
xerj-vector | qdrant, usearch, instant-distance, hnswlib | Construção HNSW, heurísticas de vizinhança, quantização, kNN filtrado |
xerj-storage | sled, fjall, redb | WAL, épocas de descarga, recuperação de falhas, compactação, alocação de páginas |
xerj-columnar | clickhouse | Armazenamento colunar, execução de agregação, codecs de compressão, varreduras vetorizadas |
Fontes apenas para abordagem: elasticsearch (AGPL-3.0 / SSPL-1.0 / Elastic-2.0)
e sonic (MPL-2.0). Nunca copie o código deles para o XERJ Apache-2.0; para ES,
colar a fonte também falsificaria a alegação pública do projeto de "não compartilha código com
Elasticsearch". meilisearch é MIT no núcleo, mas BUSL-1.1 para suas partes da
Enterprise Edition — verifique o cabeçalho/caminho primeiro. Leia o design,
escreva nossa própria implementação. O campo review.use de cada manifesto diz em qual
balde um repositório está; hub/README.md explica os três.
Corpus do hub ou corpus local
Dois tipos de corpus residem no mesmo nó local. Cada um responde a um tipo diferente de pergunta:
| corpus do hub | corpus local | |
|---|---|---|
| o que contém | material público em um commit fixo: o código-fonte de uma biblioteca, um padrão, um regulamento, um feed de avisos | arquivos que apenas esta máquina tem: o projeto em que você está trabalhando, documentos privados, exportações |
| quando usar | quando você precisa de um detalhe que não consegue citar exatamente de memória | a resposta está em seus próprios arquivos |
| como adicionar | xerj corpus add --from ./<slug>.json, depois xerj corpus index <slug> | xerj autoindex <pasta> |
| como consultar | xerj code <slug> "<pergunta>" · MCP xerj_code_search | xerj search "<palavras>" · xerj def "<símbolo>" · MCP xerj_search |
Uma pasta indexada com xerj autoindex --prefix <p> é o caminho local nessa tabela, não um corpus xerj code: xerj corpus list lê ~/.xerj-code e não lista <p> até que xerj corpus add registre a pasta, e os comandos que a pesquisam são xerj search --prefix <p> e xerj def --prefix <p>.
Não use nenhum dos dois para um fato que você já pode declarar exatamente: em conteúdo memorizado, a recuperação é sobrecarga (consulte a nota de status acima).
Um manifesto do hub vem de um checkout do branch corpus-hub
(tools/xerj-code/hub/<slug>.json) ou, sem checkout, de sua URL bruta.
Tanto corpus index quanto code falam com um nó em execução:
curl -fsSLO https://raw.githubusercontent.com/xerj-org/xerj/corpus-hub/tools/xerj-code/hub/<slug>.json
xerj corpus add --from ./<slug>.json # última linha: next: xerj corpus index <slug>
xerj corpus index <slug> # termina: corpus '<slug>' searchable: <N> records
xerj code <slug> "<pergunta>" # trechos encabeçados pelo caminho do arquivo e linha
--from lê um arquivo local: v1.0.0-rc.95 não busca uma URL, e passar uma
responde no such manifest.
Escolhendo um corpus para o projeto em questão
Os quatro corpora do mecanismo acima são o conjunto padrão deste repositório. O catálogo
completo ao vivo é navegável em hub.xerj.org, com
uma linha por corpus em hub.xerj.org/llms.txt;
o que um nó carregou é xerj corpus list --url <node>. Cada corpus está
fixado em um commit com sua licença registrada por fonte. G7 (um
portão de recuperação de cinco perguntas cujo conjunto foi pré-registrado antes da recuperação
ser executada) foi avaliado para alguns corpora e não para outros, e cada página do hub diz
quais. Escolha pelo domínio do projeto, não pelo tamanho:
| o projeto é… | comece com | por que |
|---|---|---|
| um mecanismo de busca / consulta | xerj-search | postings, BM25, política de merge, layout de segmento, semântica de fio ES |
| busca vetorial / ANN | xerj-vector, faiss, annoy | Construção HNSW, heurísticas de vizinhança, quantização, kNN filtrado; faiss é a implementação ANN de referência, annoy a variante florestal |
| mecanismo de armazenamento / KV | xerj-storage, duckdb, rocksdb, leveldb, badger, lmdb, pebble, valkey-src | WAL, recuperação de falhas, compactação, alocação de páginas; árvores LSM-vs-B; pebble para subníveis L0 e semântica de exclusão de intervalo; valkey para estruturas de dados de um servidor KV em memória |
| analítico / colunar | xerj-columnar, duckdb, arrow-rs, parquet-format, iceberg | Layout colunar, codecs, varreduras vetorizadas, formatos de tabela |
| um servidor de banco de dados | sqlite-src, postgres-src | Parsers, planejadores, executores — as duas bases de código mais estudadas no campo |
| mensageria / consenso | kafka-src, rabbitmq, nats-server, etcd-src, raft-rs, dragonboat | Compactação de log, semântica de entrega, correção de quórum/arrendamento |
| monitoramento / séries temporais | influxdb, prometheus-src | Layout TSDB, redução de amostragem, caminhos de raspagem/ingestão |
| TLS / criptografia / túneis | rustls, openssl, s2n-tls, boringtun | TLS-moderno-feito-à-mão, precedente de endurecimento, padrões de tempo constante |
| QUIC / HTTP / rede | quinn, nghttp2, curl-src, libuv, caddy, envoy, nginx | Máquinas de estado de protocolo, pooling de conexão, loops de evento |
| compressão / serialização | zstd, lz4, brotli, zlib-ng, snappy, protobuf, flatbuffers, capnproto, msgpack-c | Design de formato, codificação bloqueada/entrópica, esquemas de cópia zero |
| serviço de configuração / segredos | openbao | Armazenamento KV com selo/deselo, maquinário de arrendamento |
| revisão de design de API | rust-api-guidelines, msft-api-guidelines, zalando-restful-api-guidelines, google-eng-practices | Nomenclatura, forma de erro, versionamento; Zalando é o conjunto de políticas REST mais completo em cláusulas, google-eng-practices possui a doutrina de revisão de código |
| conformidade com protocolo/especificação | openapi-spec, graphql-spec, json-schema-spec, w3c-css, whatwg-specs, ecma262, nats-protocol, kafka-protocol | O texto normativo contra o qual uma implementação é julgada — padrões vivos HTML/DOM/URL, gramática ECMAScript, estruturação de protocolo de fio |
| localizar o RFC certo antes de lê-lo | ietf-rfc-abstracts | Um registro por RFC (9.015): número, título, data, resumo — "qual RFC realmente cobre X" sem puxar textos completos (TLP-5.0) |
| operações de produção / SRE | gitlab-runbooks, school-of-sre, tldr-pages, mozilla-ssl-configs, twelve-factor | Runbooks reais de incidentes, um currículo completo de curso SRE, sintaxe de comando por ferramenta, configurações TLS implantadas, doutrina de implantação |
| administração de sistemas Unix | freebsd-handbook, openbsd-faq | Procedimentos rc/ZFS/jail/rede, posições canônicas do FAQ do OpenBSD |
| documentação contra uma API hospedada | github-api-description | A descrição OpenAPI de github.rest — semântica de campos, valores de enumeração, cabeçalhos de pré-visualização |
| documentação de operações de armazenamento de dados | valkey-docs, etcd-docs | Semântica de comandos, opções de configuração, orientação de ajuste — a referência operacional para cada um |
| fiação de telemetria / observabilidade | a metade semconv de otel-proto (candidato — G7 2/5, estacionado na faixa semântica) | Convenções semânticas OpenTelemetry para nomes de atributos; rodadas lexicais não conseguiram ponte entre paráfrase e prosa normativa |
| internacionalização | unicode-cldr | Estrutura de dados de localidade CLDR, esqueletos de calendário/número/data |
| revisão de segurança de dependências Rust | rustsec-advisories, o pacote rust-vulns (xerj corpus add --from a receita do hub) | Um registro de texto por aviso (1.963: RustSec + OSV do crates.io, sobreposição de alias zero): versões afetadas, versões corrigidas, listas de símbolos de função afetada em 271; o pacote continua sendo o veículo para mineração de pares corrigidos (estudo de classe de defeito #1111) |
| revisão de segurança de dependências Python | pysec | Registros de aviso PYSEC com versões afetadas e corrigidas, aliases CVE/GHSA |
| auditoria de dependência entre ecossistemas | ghsa-db | Avisos revisados pelo GitHub (36.263 registros de texto): vetores CVSS, intervalos corrigidos, pacotes afetados em npm/PyPI/Go/Rust/maven e o resto |
| revisão de segurança de módulos Go | go-vulndb | Avisos curados pela equipe Go (4.577): pacotes e símbolos afetados, versões corrigidas, IDs GO com aliases CVE |
| precedente de negação de serviço por regex | redos-precedent | 634 avisos ReDoS específicos de regex (classe CWE-1337/185, não CWE-400 puro): a entrada patológica, a função afetada, a reescrita limitada |
| precedente de uso indevido de criptografia | crypto-misuse-precedent | 721 avisos das classes CWE-326/327/328/329/347: cifras fracas, chaves fixas em código, reutilização de nonce, bypass de verificação de assinatura, oráculos de preenchimento, ECB |
| taxonomia de vulnerabilidade / fraqueza | mitre-cwe, mitre-capec | Definições de fraqueza CWE e padrões de ataque CAPEC, nível de ID |
| técnicas de adversário / engenharia de detecção | mitre-attck | Registros por técnica ATT&CK v19.2: IDs de técnica, táticas, fontes de dados de detecção, exemplos de procedimento (empresa/móvel/ics; objetos de software e grupo fora do escopo) |
| triagem de prioridade de patch | cisa-kev | O catálogo Known Exploited Vulnerabilities, um registro por CVE — status de exploração na natureza, datas de remediação vinculativas |
| guia de segurança de aplicações web | owasp-cheatsheets | As receitas de contramedidas da Cheat Sheet Series por tópico — gerenciamento de sessão, segredos de autenticação, tratamento de erros, tratamento de upload |
| planejamento de teste de penetração em aplicação web | owasp-wstg | O catálogo do Web Security Testing Guide v4.2: objetivos e método por teste, organizado por categoria (authn, authz, sessão, tratamento de entrada) |
| triagem de uma campanha ativa | cisa-alerts | IOCs de aviso CISA, ações necessárias e mitigações (janela maio/2025..outubro/2026) |
| consulta à visibilidade de endpoints | osquery-config-examples | Pacotes osquery implantados reais e formas de consultas agendadas |
| não software (impostos, emprego, lei do Reino Unido) | ecfr-title-12, ecfr-title-29, ecfr-title-26, uk-legislation | Regulamentação atual consolidada, seção por arquivo |
| aviação (FARs) | ecfr-title-14 | 14 CFR seção por arquivo: mínimos de visibilidade, espaço aéreo de transponder, intervalos de inspeção, direito de passagem |
| regras de trânsito marítimo | navrules | Texto por regra COMDTINST M16672.2D — risco de colisão, canais estreitos, situações de cruzamento, sinais de luz e som |
| componentes de UI acessíveis | govuk-design-system | Opções de componente do GOV.UK e critérios de acessibilidade — a semântica exata das opções (maxwords vs maxlength, texto do divisor, focus-on-load) |
| rótulos de medicamentos / farmacêuticos | dailymed | Seções de rótulo FDA: indicações, contraindicações, tempo de administração |
| orientação de tratamento clínico | cdc-clinical | Regimes e doses de tratamento STI do CDC, dessensibilização para sífilis, sinais clínicos de sarampo |
| segurança de serviços alimentícios | fda-food-code | Disposições do FDA Food Code 2022: superfícies de contato manual, Tempo como Controle de Saúde Pública, marcação de data, prontidão para mãos nuas |
| dispositivos de controle de tráfego | mutcd | FHWA MUTCD 11ª Ed (Rev 1): autorizações de placas e sinais, marcações, aplicações típicas de zona de obras |
| obras de construção (Inglaterra) | uk-building-regs | Building Regulations 2010 (SI 2010/2214) por disposição: requisitos Partes A–P, variações do País de Gales |