Open source · Apache 2.0 · Java 17+

O código é o log.
Pare de escrever instruções de log.

O NarrativeTrace transforma o seu código em execução em narrativas legíveis: traces de execução para quem depura, traces estruturais sem valores para os agentes de IA que escrevem código, e uma linha de base que quebra o build quando o comportamento muda.

Comece em 5 minutos Ver no GitHub

implementation("ai.narrativetrace:narrativetrace-core:0.1.0")

build/narrativetrace/customer_places_order.md 
# Customer places order- OrderService.placeOrder("C-42", qty: 5) — 4.2ms  - Customers.verifyGoodStanding("C-42") → true  - PricingService.calculate(5) → 49.95  - PaymentService.charge(card: [REDACTED])    → PaymentConfirmation(txId="T-9")  - OrderRepository.save(Order{…})    → Order{id=ORD-1001, total=49.95} // Nenhuma instrução de log foi escrita para isto.
0linhas de log na sua lógica de negócio
~10 nsde overhead por chamada com o tracing desligado
15–30%menos tokens quando agentes de IA leem seu código
0dependências de runtime no núcleo

Antes e depois

Apague o log. Mantenha a história.

Instruções de log são um terço de uma classe de serviço típica — e ainda assim deixam passar justamente o que você precisava. O NarrativeTrace captura nomes de método, parâmetros, valores de retorno e a estrutura de chamadas automaticamente. O código que você já escreveu é a narrativa.

Antes — logs por toda parte

public Order placeOrder(String customerId, int qty) {
    log.info("Placing order for {} qty {}", customerId, qty);
    customers.verifyGoodStanding(customerId);
    log.debug("Customer in good standing");
    var price = pricing.calculate(qty);
    log.info("Calculated price: {}", price);
    var order = repository.save(new Order(customerId, price));
    log.info("Order saved: {}", order.getId());
    return order;
}

Depois — o código é o log

public Order placeOrder(String customerId, int qty) {
    customers.verifyGoodStanding(customerId);
    var price = pricing.calculate(qty);
    return repository.save(new Order(customerId, price));
}

// Zero linhas de log.
// O NarrativeTrace captura a narrativa
// automaticamente.

Trace gerado — Markdown, JSON, prosa, diagrama de sequência e um .nt sem valores para a IA

trace narrativo 
- OrderService.placeOrder("C-42", 5)
  - Customers.verifyGoodStanding("C-42") → true
  - PricingService.calculate(5) → 49.95
  - OrderRepository.save(Order{…}) → Order{id=ORD-1001, total=49.95}

O mesmo trace em prosa — para relatórios de bug, stakeholders e contexto de LLM

new ProseRenderer().render(trace) 
The order service places an order for customer id "C-42", quantity 5:
  Customers verify good standing for customer id "C-42", returning true.
  The pricing service calculates for quantity 5, returning 49.95.
  The order repository saves the order Order{…}, returning Order{id=ORD-1001, total=49.95}.
  Returns Order{id=ORD-1001, total=49.95}.

A prosa lê exatamente tão bem quanto os seus nomes. DataProcessor.process(a, b) sai como The data processor processes a: 0, b: 0 — preciso e inútil. É por isso que a pontuação de clareza existe: ela avalia cada nome a partir da narrativa de execução, para que o código aprenda a contar a própria história. Diagnóstico de clareza →

Testes de aprovação narrativa 0.2.0 · próxima versão

Testes pegam valores errados.
Narrativas pegam comportamentos errados.

Depois de cada execução, o NarrativeTrace compara a estrutura de chamadas de cada cenário com a última execução verde e diz o que mudou — em uma linha. Ative o modo de aprovação e uma mudança não aprovada (uma chamada nova, uma chamada que sumiu, um resultado diferente) quebra o build com um diff legível até que alguém a aprove. Os testes estavam verdes; o comportamento mudou mesmo assim. Agora você sabe.

./gradlew test — a cada execução, sem configuração 
NarrativeTrace — Suite complete
  5 scenarios recorded
  Clarity: 100% high | 0% moderate | 0% low
  Reports: build/narrativetrace
  Since last green: 4 scenarios unchanged · 1 changed:
    "Customer places order" (−1 call Customers.verifyGoodStanding)
approval.set(true) — a refatoração precisa ser aprovada 
Narrative changed against the approved baseline
  src/test/narratives/OrderServiceTest/customer_places_order.approved.nt

  - OrderService.placeOrder(customerId, qty) → value
-   - Customers.verifyGoodStanding(customerId) → value
    - PricingService.calculate(qty) → value
    - PaymentService.charge(card) → value
    - OrderRepository.save(order) → value

  revise o .received.nt e depois: ./gradlew approveNarratives

Uma linha depois de cada execução

Sem configuração. O arquivo .nt que cada teste já escreve é a linha de base do último verde; um teste que falha imprime o que mudou desde então — quase sempre o caminho mais curto até o bug — em vez do trace inteiro.

Aprove o comportamento, não só o código

Commite uma linha de base por cenário. Uma refatoração — sua ou do seu agente — que altere a estrutura falha até que alguém revise o diff e rode approveNarratives. O diff do código é detalhe de implementação; o diff da narrativa é a revisão.

Sem valores, por design

As linhas de base contêm apenas nomes e estrutura: nada de dados de fixture, nada de PII, nenhuma superfície de injeção. Sobrevivem a mudanças nos dados de teste, podem ser commitadas com segurança e entregues a um agente de IA como especificação de referência.

Como funcionam os testes de aprovação

Para desenvolvimento assistido por IA

Seu agente de IA sabe ler o código.
Agora ele pode vê-lo rodar.

Vibe coding funciona até algo quebrar e ninguém — pessoa ou agente — saber o que realmente aconteceu em tempo de execução. O NarrativeTrace dá aos agentes de código a verdade do runtime: a árvore de chamadas real, não um palpite reconstruído da leitura estática.

Verdade do runtime, não suposição

Agentes que depuram só a partir do fonte inferem o comportamento — e inferem errado. Um trace narrativo mostra o que rodou, em que ordem, com quais parâmetros e resultados. Cole-o no contexto de qualquer agente, ou anexe os arquivos de trace por teste que o seu CI já produz.

Mais lógica por janela de contexto

Instruções de log são tokens de ruído. Removê-las deixa uma classe de serviço 15–30% mais barata para um agente ler — e cada linha de um trace carrega sinal, porque foi gerada a partir de nomes, não de prosa.

Um trace que não pode envenenar o agente 0.2.0

Cada teste também escreve um trace estrutural .nt: a árvore de chamadas com todos os valores de runtime removidos. Zero superfície de prompt injection, zero PII, uma fração dos tokens — seguro para colar em um agente ou commitar no repositório. Segurança por construção, não por filtro.

Como funciona a separação

Servidor MCP Pro Em breve

Claude Code, Cursor e Copilot vão consultar traces, grafos de dependências de runtime e dados de clareza diretamente pelo Model Context Protocol — somente leitura, com níveis de saída escalonados que entregam só a estrutura por padrão.

Ver o design do MCP

Este site também é amigável para agentes: aponte o seu assistente para llms.txt ou llms-full.txt e ele adota o NarrativeTrace por você.

Para modernização de sistemas legados

Migre o sistema que ninguém entende — com provas.

Agentes de IA baratearam as reescritas; o caro é verificá-las. Envolva um sistema legado em traces e você obtém o comportamento real dele em runtime — antes de mudar qualquer coisa — e a prova de equivalência depois.

Faça um raio-X da arquitetura que você realmente tem

Anexe o agente Java a uma aplicação sem modificação — o exemplo de referência é um WAR EJB sem dependências no WildFly, rastreado com um único flag -javaagent — ou rode a suíte JUnit 4 que você já tem. Sem mudanças no fonte, sem arqueologia de documentação.

Agente sem código

Prove que o comportamento não mudou

Fixe o comportamento de cada cenário em uma linha de base sem valores antes de tocar em qualquer coisa — de graça. Depois compare conjuntos inteiros de traces de antes e depois de um port ou de uma reescrita com IA, com cada divergência classificada por risco Pro. A equivalência deixa de ser uma sensação e vira um relatório.

Diffs de migração

Exponha o acoplamento oculto Pro

Grafos de dependências de runtime agregados de execuções reais: arestas sólidas para dependências sempre chamadas, tracejadas para as condicionais, com frequências. Dependências circulares e “god services” não têm onde se esconder.

Grafos de dependências

Encontre o código que pior se lê

Se o trace não lê bem, o código está mentindo sobre si mesmo. A pontuação de clareza avalia os nomes a partir da narrativa de execução e explica cada nota — uma observação por elemento, sugestões de renomeação, abreviações por extenso (chk → check). Aponte a sua refatoração, ou a do seu agente, primeiro para os piores cantos. Gratuito.

Diagnóstico de clareza

Linguagem do domínio 0.2.0 · próxima versão

Sua linguagem ubíqua, colhida de execuções reais.

Os nomes são o trace. O NarrativeTrace os transforma em um glossário vivo que o seu time curadoria e faz valer no CI — e renderiza a mesma execução como prosa no idioma do seu time. Os dados em si nunca são tocados.

uma execução · um glossário 
O serviço de pedidos realiza um pedido para o id de cliente "C-42", quantidade 2:
  O serviço de clientes busca o cliente com id de cliente "C-42", retornando Cliente[id=C-42, nível=GOLD].
  O serviço de estoque reserva o id de produto "SKU-KB", quantidade 2, retornando Reserva[id de produto=SKU-KB, quantidade=2].
  O serviço de pagamentos cobra do id de cliente "C-42" o valor 179.98, retornando Confirmação de pagamento[id de transação=TXN-1].
  Retorna Resultado do pedido[id de pedido=ORD-1, total cobrado=179.98].

Colha o glossário

O glossaryScan constrói um glossary.json por repositório a partir das classes compiladas e das execuções de teste, organizado por contexto delimitado. Definições, traduções e sinônimos obsoletos são seus para curar; a coleta nunca os sobrescreve.

Faça valer no CI

Um método que usa um sinônimo obsoleto é sinalizado na saída da execução — openAccountWithOverdraft → use openOverdraftAccount — e o clarityCheck pode quebrar o build por isso. Deriva de vocabulário é erro de build, não comentário de code review.

Prosa no seu idioma

A execução inteira se lê como frases — serviços, ações, parâmetros — em chinês, espanhol ou português. Nomes de tipos e campos vêm do mesmo glossário; os dados em si permanecem idênticos byte a byte. Chinês simplificado, espanhol e português chegam primeiro; mais idiomas estão a caminho.

Glossário e traces traduzidos

Como funciona

Três passos até a sua primeira narrativa

1

Adicione duas dependências

dependencies {
  implementation(
    "ai.narrativetrace:narrativetrace-core:0.1.0")
  implementation(
    "ai.narrativetrace:narrativetrace-proxy:0.1.0")
}
2

Encapsule um serviço — ou automatize

var context = new ThreadLocalNarrativeContext();
var service = NarrativeTraceProxy.trace(
    orderService, OrderService.class, context);

// ou, com Spring:
@EnableNarrativeTrace(
    basePackages = "com.example.app")
3

Leia a história

service.placeOrder("C-42", 5);

System.out.println(
  new IndentedTextRenderer()
      .render(context.captureTrace()));

// JUnit 5/4: cada teste escreve
// o próprio arquivo de trace.

Edições

Gratuito para pessoas. Pago para escala com IA e compliance.

O limite é simples: ler traces como desenvolvedor é gratuito, para sempre, sob Apache 2.0. Análise entre execuções, integração com IA em escala, fluxos de aprovação em equipe e auditoria com nível de compliance são pagos.

Open Source Disponível agora

Tudo o que uma pessoa desenvolvendo precisa, com zero dependências de runtime no núcleo.

  • Tracing automático: proxy, agente Java, Spring, servlet
  • Os cinco níveis de captura, alternáveis em runtime
  • Anotações @Narrated, @OnError, @NotTraced + ocultação
  • Arquivos de trace por teste no JUnit 5 e JUnit 4: Markdown, JSON, prosa, diagramas de sequência
  • Pontuação de clareza, gate clarityCheck e ponte SLF4J
  • Testes de aprovação e traces .nt sem valores — 0.2.0
  • Glossário de domínio, traces traduzidos, OpenTelemetry, Micronaut — 0.2.0
Começar

Pro Acesso antecipado

Análise entre traces, integração com IA e compliance para times.

  • Resumos de fluxo e análise de frequência de caminhos
  • Diffs de migração com classificação de risco
  • Grafos de dependências de runtime
  • Eventos de auditoria e SecOps com motor de políticas
  • Servidor MCP e saída escalonada para agentes de código — em breve
  • Governança de aprovações: diffs semânticos, bots de revisão em PR, linhas de base assinadas — planejado
Solicitar acesso antecipado

Platform Em breve

Backend gerenciado para as narrativas de cada serviço, ambiente e execução.

  • Ingestão OTLP gerenciada para traces
  • Armazenamento e busca multi-tenant
  • Dashboards de time e políticas de retenção
  • Relatórios de clareza e auditoria para toda a organização
Entrar na lista de espera

A comparação completa está na visão geral do Pro. Os artefatos open source estão no Maven Central sob ai.narrativetrace.

Integrações

Encontra a sua stack onde ela está

Spring Boot 0.1.0
JUnit 5 0.1.0
JUnit 4 0.1.0
Agente Java 0.1.0
SLF4J 0.1.0
Micrometer 0.1.0
Servlet 0.1.0
Clarity CLI 0.1.0
Plugin Gradle 0.2.0
Jakarta EE / WildFly 0.2.0
Micronaut 0.2.0
OpenTelemetry 0.2.0

Além do Java

Uma arquitetura, todos os runtimes

Captura narrativa, saída para dois consumidores e diagnóstico de clareza — o mesmo design, portado. O port para .NET já emite o mesmo artefato .nt sem valores, então as linhas de base de aprovação viajam entre plataformas.

JavaDisponível agora
.NETEm desenvolvimento
TypeScriptEm desenvolvimento
SwiftEm desenvolvimento
PythonPlanejado

Dê voz ao seu código.

Cinco minutos até a sua primeira narrativa. Nenhuma instrução de log foi escrita na criação desta biblioteca.

Começar Dê uma estrela no GitHub