Ontem eu abri o Claude Code e mandei um prompt. Um prompt só. Sem ir e voltar, sem corrigir, sem guiar. Colei e fui fazer café:

create a compiler from Brainfuck to JVM in Node.js with no dependencies. Full Node.js.

the interface should be ./compiler somefile.bf SomeFile

i should be able to run SomeFile just by running "java SomeFile"

every brainfuck command should be accepted and the produced .class must not have a warning.
You must test everything, from the parser to the generation of the .class.

Quando voltei, três minutos depois, o compilador estava pronto. 51 testes passando, .class válido, Hello World rodando sem um warning no stderr. Um prompt. Três minutos.

Minha primeira reação foi rir. A segunda foi ficar quieto.

O que ele gerou

O compilador do Claude é um arquivo só, ~300 linhas. Parser, constant pool, geração de bytecode, StackMapTable, montagem do .class - tudo junto. Funciona. Os oito comandos do Brainfuck compilam corretamente pra bytecode JVM. Os loops geram ifeq/goto com offsets corretos. O append_frame na StackMapTable declara as variáveis locais certas. O javap -v mostra uma classe válida.

A suíte de testes é decente: testa o parser isolado, o constant pool, a geração de bytecode, a StackMapTable, a estrutura do .class, e faz 19 testes de integração que compilam Brainfuck, rodam com java, e verificam a saída. Hello World, loops aninhados, input, wrapping de célula, todos os 8 comandos juntos.

Funciona. Sem truque, sem gambiarra. Ele até acertou o append_frame de primeira - ok, na segunda tentativa. Na primeira ele usou same_frame e tomou um VerifyError, igual aconteceu comigo. Mas corrigiu sozinho em segundos.

Onde o meu é melhor

O BrainJuck não é só um compilador que funciona. Ele é um compilador que pensa.

O parser do Claude pega +++ e gera três iadd separados. O meu parser combina em um increment(3) e gera um sipush 3 + iadd. Menos bytecode, menos trabalho pra JVM.

O BrainJuck tem uma camada de IR entre o parsing e a geração de código. Isso significa que eu posso adicionar otimizações sem mexer no gerador de bytecode. O Claude foi direto do parsing pro bytecode - funciona, mas é rígido.

O meu rastreia a posição do ponteiro em tempo de compilação. >>><< vira move_head(1) com posição absoluta. O do Claude gera cinco iinc separados. De novo - funciona, mas é ingênuo.

A arquitetura tem separação real: index.js pro parser, class_generator.js pra montagem do .class, helpers/jvm.js pros opcodes. O do Claude enfiou tudo num arquivo. Pra 300 linhas até que dá. Pra evoluir, não dá.

Onde o dele é melhor

A cobertura de testes. Tenho que admitir.

Eu tenho 6 testes unitários e 1 teste de integração. O Claude gerou 51 testes cobrindo cada camada individualmente. Testa edge cases que eu nem pensei - loop vazio [], loops consecutivos [][], wrapping de célula, programa vazio.

Meu teste de integração é sólido - compila o Hello World, roda com java, verifica stdout e stderr. Mas é um cenário só. O Claude testou 19 cenários diferentes de integração.

O que realmente importa

Aqui é onde a coisa fica honesta.

O compilador do Claude funciona. Se alguém me pedisse “preciso de um compilador de Brainfuck pra JVM até amanhã” e eu usasse o Claude, o trabalho estaria entregue. Ninguém olharia pro .class gerado e saberia que foi feito em 3 minutos.

Mas eu não saberia nada.

Eu não saberia que o constant pool é 1-indexed e que a entrada 0 não existe. Não saberia que baload faz sign-extend pra int. Não saberia que o slot 0 das variáveis locais é reservado pros argumentos do método. Não saberia que o offset_delta da StackMapTable é calculado em relação ao frame anterior, não ao início do método. Não saberia a diferença entre same_frame e append_frame, nem por que o primeiro frame de um método com branches precisa ser append_frame se você declarou variáveis locais depois da assinatura.

Nada disso. Minha cabeça estaria vazia.

Quando eu estava debugando o BrainJuck às duas da manhã, comparando hex dump com a spec da JVM, errando cálculo de offset pela décima vez - aquilo era conhecimento entrando. Cada VerifyError era uma lição. Cada byte errado no hex dump que eu encontrava era uma conexão nova no meu cérebro.

O Claude não precisou debugar nada disso. Ele já sabia. Ele foi treinado com a spec da JVM, com milhares de implementações parecidas, com décadas de conhecimento acumulado. Pra ele, gerar uma StackMapTable correta é interpolação. Pra mim, foi o chefe de fase do projeto.

Não é sobre a IA ser ruim

Eu uso IA pra programar. Uso Claude Code praticamente todo dia. Não sou contra, não acho que vai destruir a profissão, não tenho medo de perder o emprego. Que fique claro.

Mas tem uma diferença entre usar a IA pra acelerar um trabalho que você entende e usar a IA pra fazer um trabalho que você não entende. No primeiro caso, você ganha tempo. No segundo, você ganha uma ilusão.

O BrainJuck demorou semanas. O compilador do Claude demorou 3 minutos. O resultado final é parecido - os dois geram .class válido, os dois compilam Hello World, os dois passam no verificador da JVM. Mas depois daquelas semanas, eu sei como a JVM funciona por dentro. Sei ler bytecode, sei o que um VerifyError significa, sei dissecar um .class com xxd. Essas semanas me deram algo que nenhum prompt dá.

O compilador do Claude é melhor testado que o meu. É mais rápido de produzir. Se eu quisesse, eu poderia pegar o código dele e melhorar - adicionar as otimizações que o meu tem, separar em módulos, evoluir a arquitetura.

Mas eu nunca teria a base pra fazer isso se não tivesse passado por aquelas semanas primeiro.

O teste real

Se eu te der o compilador do Claude e pedir pra você adicionar uma otimização - combinar [-] num clear cell direto no bytecode - você conseguiria? Se aparecer um VerifyError novo, você saberia por onde começar?

Se você construiu o seu, a resposta é sim. Se a IA construiu pra você, a resposta honesta é provavelmente não.

Esse é o ponto. Não é que a IA faz código ruim. O código é bom. É que código bom que você não entende é tão útil quanto código ruim que você não entende. Nos dois casos, quando quebrar, você tá perdido.

Pra quem tá aprendendo

Se você é dev e quer entender compiladores, máquinas virtuais, bytecode - faz na mão. Pelo menos uma vez. Não precisa ser Brainfuck, não precisa ser JVM. Pega qualquer linguagem simples e compila pra qualquer target. O importante é passar pelo processo.

Depois que você entendeu, aí sim - usa a IA pra ir mais rápido, pra testar mais cenários, pra explorar variações. A IA é uma ferramenta absurda quando você sabe o que tá fazendo. Quando você não sabe, ela é só um gerador de confiança falsa.

O BrainJuck tá no GitHub. Lê o código, brinque, quebre. E se der vontade, faz o seu.

Por hoje é só. Abraços.

This is the story of a bug that looked like a Node.js regression but turned out to be a V8 garbage collection change. It took bisecting across Node commits, rebuilding with different V8 versions, analyzing heap snapshots, and finally patching V8’s Torque source to prove the root cause.

The bug

The report was straightforward. This code leaks memory on Node 24+ but works fine on Node 22:

const ac = new AbortController();

let i = 0;
function run() {
  AbortSignal.any([ac.signal]);

  if (++i % 100_000 === 0) {
    const mem = process.memoryUsage().rss / 1024 / 1024;
    console.log(`${i} - ${mem.toFixed(2)} MiB`);
  }

  setImmediate(run);
}

run();

On Node 22 (V8 12.4): memory stable at ~97 MiB. On Node 26 (V8 14.3): memory grows linearly past 2 GB until the process crashes.

How AbortSignal.any() works internally

When you call AbortSignal.any([signal1, signal2]), Node creates a new “composite” signal that aborts when any of the source signals abort. Internally, this involves:

1. Create a new AbortSignal (the composite result)
2. For each source signal, add a WeakRef to the result in kDependantSignals
3. Register with a FinalizationRegistry so that when the composite signal is GC’d, the dead WeakRef gets cleaned up from the source’s kDependantSignals

Step 3 is where the problem lives. Each call to AbortSignal.any() calls FinalizationRegistry.register(), which creates a V8-internal WeakCell object.

What a WeakCell is

FinalizationRegistry is a JavaScript API that lets you register a callback to run when an object is garbage collected. Under the hood, V8 tracks this with WeakCell objects - internal structures that hold a weak reference to the target, the held value, and links into the registry’s internal lists.

When you call registry.register(target, heldValue), V8 creates a WeakCell and adds it to the registry. When target is GC’d, V8 moves the WeakCell to the “cleared cells” list and schedules the cleanup callback.

The key question is: where does V8 allocate this WeakCell?

The V8 change

In V8 12.4, the WeakCell allocation in src/builtins/finalization-registry.tq looked like this:

// Allocate the WeakCell object in the old space, because 1) WeakCell weakness
// handling is only implemented in the old space 2) they're supposedly
// long-living. TODO(marja, gsathya): Support WeakCells in Scavenger.
const cell = new (Pretenured) WeakCell{
    map: GetWeakCellMap(),
    finalization_registry: finalizationRegistry,
    target: target,
    holdings: heldValue,
    // ...
};

Pretenured means “allocate directly in old space, skip the nursery.”

In September 2025, V8 commit 5abdd62d579b by Omer Katz removed this flag:

const cell = new WeakCell{
    map: GetWeakCellMap(),
    finalization_registry: finalizationRegistry,
    target: target,
    holdings: heldValue,
    // ...
};

The commit message: “Young WeakCells are supported out of the box and there’s no correctness need to pretenure them. Having WeakCell allocated as young also simplifies followup planned changes.”

The associated bug is chromium:340777103: “FinalizationRegistry-s are treated as strong roots on minor GCs.”

Young generation vs old generation

V8’s heap is split into two regions with different garbage collection strategies.

The young generation (also called the nursery) is small - a few megabytes. Most objects are allocated here. V8 collects it with the scavenger (minor GC), which runs fast and frequently. Objects that survive a scavenge get promoted to old generation.

The old generation is large - up to whatever --max-old-space-size allows. It’s collected by the mark-compact collector (major GC), which is slower but thorough. Long-lived objects end up here.

Most of the time, short-lived objects are born in young space, die there, and the scavenger reclaims them cheaply. That’s the generational hypothesis: most objects die young.

Pretenured bypasses this entirely. The object goes straight to old generation, skipping the nursery. V8 originally did this for WeakCell because “WeakCell weakness handling is only implemented in the old space” - the scavenger didn’t know how to deal with them. The comment in the code had a TODO saying to fix this eventually.

When V8 did add scavenger support for WeakCells, they removed Pretenured. WeakCells now land in young generation like everything else.

Why this causes the leak

The bug title says it: “FinalizationRegistry-s are treated as strong roots on minor GCs.”

During a scavenge (minor GC), the FinalizationRegistry treats its active WeakCell entries as strong roots. This means the scavenger won’t collect them - it promotes them to old generation instead. So the cycle looks like:

1. AbortSignal.any() is called
2. FinalizationRegistry.register() creates a WeakCell in young generation
3. Minor GC runs - the WeakCell is a strong root, so it survives and gets promoted
4. The composite signal (the WeakCell’s target) also can’t be collected while the WeakCell is alive in young space
5. Eventually a major GC runs and clears everything
6. But at high call rates, steps 1-4 repeat faster than step 5

With Pretenured, step 2 put the WeakCell directly in old space. There was no young-generation pressure, no promotion overhead, and old-space GC handled everything efficiently.

Proving it

We can prove this by patching V8 14.3 to restore Pretenured. One word change in deps/v8/src/builtins/finalization-registry.tq:

-  const cell = new WeakCell{
+  const cell = new (Pretenured) WeakCell{

Rebuild Node and run the reproduction:

V8 14.3 (stock):           V8 14.3 (Pretenured restored):
100k: 159 MiB              100k: 147 MiB
200k: 207 MiB              200k: 159 MiB
300k: 254 MiB              300k: 161 MiB
400k: 304 MiB              400k: 163 MiB
500k: 359 MiB (growing)    500k: 162 MiB (stable)

One word. That’s the difference between a stable 162 MiB and unbounded growth past 2 GB.

The heap snapshot

A heap snapshot after 200k calls + explicit GC on stock V8 14.3 shows what’s being retained:

200k AbortSignal objects survive GC. They should be unreachable, but the WeakCell entries keep them alive through the strong-root treatment during scavenges.

What to take away

1. FinalizationRegistry is not free. Each register() call creates a V8-internal WeakCell. On current V8, these WeakCells are young-generation objects treated as strong roots during minor GC.

2. Don’t use FinalizationRegistry in hot paths. If you’re calling register() thousands of times per second, you’ll outpace the garbage collector. Use it as a safety net, not as your primary cleanup mechanism.

3. When debugging memory leaks across Node versions, check the V8 version. The same JavaScript code can behave differently because of GC implementation changes that aren’t visible from the JS side.

4. Heap snapshots show V8 internals. The system / WeakCell entries in a heap snapshot are not visible from JavaScript - they’re V8’s internal bookkeeping. But they consume real memory.

Eu já era colaborador do Node na época. Mas tinha uma diferença entre saber explicar o event loop e ter visto ele rodar. Eu queria a segunda coisa.

Daí eu fiz o que qualquer pessoa razoável faria: compilei o Node do zero, compilei o libuv do zero, enfiei console.log e std::cout em tudo que é canto do código fonte e fiquei olhando o que acontecia.

O que todo mundo te ensina (e o que tá errado)

Se você pesquisar “Node.js event loop” vai encontrar mil diagramas bonitos. A maioria te mostra uma caixa com uma fila de eventos, uma call stack, e setas girando. Parece simples. Parece limpo.

É mentira.

Não é uma fila simples. Não é uma pilha girando. E muitas operações de rede nem passam por threads separadas - rodam direto no kernel do sistema operacional.

Quem me abriu os olhos pra isso foi o Bert Belder - um dos criadores do libuv - numa palestra de 2017:

Morning Keynote: Everything You Need to Know About Node.js Event Loop - Bert Belder, IBM

Tem 9 anos. Ele começa corrigindo exatamente esses equívocos que a gente repete sem questionar. Eu já tinha assistido dezenas de vídeos sobre event loop e nenhum chegou perto desse.

A estrutura real do event loop

O que o Belder explica - e que eu confirmei enfiando prints no código - é que o event loop do Node tem fases bem definidas. Não é uma fila genérica. Cada volta do loop passa por:

1. Timers - verifica se algum setTimeout ou setInterval expirou
2. I/O (o Belder chama de “Unicorn”) - a fase principal, onde o libuv lida com rede, disco e processos filhos
3. setImmediate - executa os callbacks agendados com setImmediate
4. Close handlers - limpeza de sockets fechados

E aqui vem o que pra mim é o maior gotcha do event loop: entre cada fase, código JavaScript é executado. O Node drena a fila de microtasks do V8 (Promises resolvidas) e também os callbacks de process.nextTick. Ou seja, entre Timers e I/O, entre I/O e setImmediate, entre setImmediate e Close handlers - sempre tem esse passo intermediário onde JS roda.

A maioria dos diagramas que você encontra por aí não mostra isso. Eles te dão as 4 fases bonitinhas e pronto. Mas na prática, o libuv não sabe nada sobre microtasks - isso é conceito do V8. O libuv cuida das fases do loop, e o Node é quem costura as duas coisas: depois que cada fase do libuv termina, o Node pede pro V8 drenar as microtasks pendentes e drena o nextTick também. É nessa costura que mora a confusão.

NOTA: O thread pool do libuv (geralmente 4 threads) só entra em ação pra operações que o sistema operacional não consegue fazer de forma assíncrona nativamente - como manipulação de arquivos e pesquisas DNS. Operações de rede usam mecanismos do kernel como epoll (Linux) e kqueue (macOS) diretamente.

Prints em C++ e JavaScript

O jeito “certo” de fazer isso seria com lldb (no macOS) - breakpoints, inspecionar a stack, seguir o fluxo sem modificar o código. Hoje em dia com IA fica ainda mais fácil: você pode pedir pro Claude usar lldb pra debugar, analisar stack traces, navegar pelo código fonte. Eu mesmo usei IA assim pra resolver segmentation faults enquanto trabalhava em implementações no Node.

Mas pra esse experimento eu escolhi console.log e std::cout. A técnica mais primitiva que existe. Qualquer pessoa sabe colocar um print - e pra entender o fluxo do event loop era mais que suficiente.

Em src/api/embed_helpers.cc, no coração do loop:

do {
  if (env->is_stopping()) break;
  std::cout << "node called uv_run() in SpinEventLoopInternal" << std::endl;
  uv_run(env->event_loop(), UV_RUN_DEFAULT);

  std::cout << "Gotta drain tasks" << std::endl;
  platform->DrainTasks(isolate);

  more = uv_loop_alive(env->event_loop());
  // ...
} while (more && !env->is_stopping());

Em src/api/callback.cc, onde os ticks são processados:

if (!tick_info->has_tick_scheduled()) {
  std::cout << "No tick scheduled, draining microtask queue" << std::endl;
  context->GetMicrotaskQueue()->PerformCheckpoint(isolate);
}

// ...
std::cout << "Tick callback being called from C++" << std::endl;

No lado JavaScript, em lib/internal/process/task_queues.js:

function processTicksAndRejections() {
  let tock;
  // all the next tick callbacks are processed here
  do {
    while ((tock = queue.shift()) !== null) {
      // ...
      callback();
      qLength--;
    }
    runMicrotasks();
  } while (!queue.isEmpty() || processPromiseRejections());
}

Daí eu criei scripts de teste pra observar a ordem de execução. Que nem esse aqui:

const { styleText } = require('node:util');

function printMessage(message) {
  const text = styleText(['cyanBright', 'bold'], `\t\t\t\t${message}\n`)
  process.stdout.write(text);
}

new Promise((resolve) => {
  printMessage('(0) Promise constructor was called')
  resolve('(1) Promise resolved');
}).then(printMessage);

setTimeout(() => {
  printMessage('(2) settimeout was called');
  process.nextTick(() => {
    printMessage('(2.1) nextTick inside setTimeout was called');
  });
}, 100);

setImmediate(() => {
  printMessage('(3) setImmediate was called');
  process.nextTick(() => {
    printMessage('(3.1) nextTick inside setImmediate was called');
  });
});

process.nextTick(() => {
  printMessage('(4) nextTick was called');
});

printMessage('(5) This log comes first');

Executando com meu Node compilado cheio de prints eu conseguia ver o que tava acontecendo por baixo. Cada std::cout no C++ casava com o que eu via no JavaScript. A ficha caiu.

nextTick: o nome mais mentiroso do Node

Agora a parte que me incomodou.

O process.nextTick não executa no “próximo tick”. Ele executa no tick atual. O nome é uma mentira descarada.

Olha o que acontece quando você aninha nextTick:

process.nextTick(() => {
  printMessage('(1) nextTick was called');

  process.nextTick(() => {
    printMessage('(2) inner nextTick was called');

    process.nextTick(() => {
      printMessage('(4) inner-inner nextTick was called');
    });
  });
});

setImmediate(() => {
  printMessage('(3) setImmediate was called');
});

O setImmediate ali no (3)? Ele não executa enquanto tiver nextTick pendente. Porque cada nextTick novo que é agendado dentro de outro nextTick entra na mesma fila que tá sendo drenada naquele momento. É que nem ir ao supermercado e a cada item que você coloca no carrinho aparecer mais dois na lista - você nunca sai do corredor.

Isso é por design, claro. O nextTick drena completamente antes de qualquer fase do event loop continuar. Mas chamar isso de “next tick”? É como chamar o freio de mão de “acelerador reserva”.

Eu “corrigi” o Node

Já que eu tava com o código aberto na minha frente, pensei: por que não?

Criei o process.nesteTick. Faz a mesma coisa que o nextTick, mas com um nome honesto.

“Neste” em português significa “in this” - ou seja, nesteTick = “neste tick” = “neste ciclo atual”. Que é exatamente o que ele faz.

Em lib/internal/process/task_queues.js:

function nesteTick(callback) {
  nextTick(callback);
}

E registrei em lib/internal/bootstrap/node.js:

const { nextTick, runNextTicks, nesteTick } = setupTaskQueue();
process.nextTick = nextTick;
process.nesteTick = nesteTick;

Daí o script de demonstração:

process.nesteTick(() => {
  printMessage('(1) nesteTick was called');

  process.nesteTick(() => {
    printMessage('(2) inner nesteTick was called');

    process.nesteTick(() => {
      printMessage('(4) inner-inner nesteTick was called');
    });
  });
});

setImmediate(() => {
  printMessage('(3) setImmediate was called');
});

Funciona igualzinho. Mas agora o nome não te engana.

O que ficou depois

Eu poderia ter lido mais 10 artigos sobre event loop. Poderia ter assistido mais 20 vídeos. Mas nada substituiu abrir o código, compilar, e ver as coisas acontecendo.

Colocar uns prints no código fonte e observar o fluxo? Você para de repetir frases decoradas e começa a saber.

Se você trabalha com Node todo dia e nunca olhou o código fonte - nem que seja com grep pra achar onde as coisas acontecem - tenta. O código do Node é mais legível do que você imagina.

Recursos

• Morning Keynote: Everything You Need to Know About Node.js Event Loop - Bert Belder
• Meu branch com os experimentos - o código com todos os prints e o nesteTick Por hoje é só. Abraços.

Brainfuck foi a escolha óbvia.

Esse é o primeiro post de uma série de três onde a gente vai construir, do zero, um compilador que transforma código Brainfuck em bytecode JVM executável. Sem dependências externas, sem framework, só Node.js puro. No final da série, você vai ter um compilador que gera arquivos .class válidos que rodam direto no java.

O código completo tá no GitHub. Nesse primeiro post, a gente vai construir o interpretador - que é a base pra tudo que vem depois.

O que é Brainfuck

Brainfuck é uma linguagem de programação esotérica criada em 1993 por Urban Müller. Ela tem 8 comandos. Oito. E ainda assim é Turing-completa - ou seja, em teoria, você pode computar qualquer coisa que qualquer outra linguagem computa.

O modelo de execução é simples:

• Uma fita de memória com 30.000 células, cada uma armazenando um byte (0-255)
• Um ponteiro que aponta pra célula atual
• Entrada e saída (stdin/stdout)

Os 8 comandos:

Qualquer outro caractere é ignorado - o que significa que você pode escrever comentários livremente no meio do código.

Um exemplo simples

Pra imprimir a letra “A” (código ASCII 65), você precisa colocar o valor 65 na célula e usar .:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .

São 65 sinais de + seguidos de um .. Funciona, mas é feio. Uma forma mais elegante:

++++++++[>++++++++<-]>+.

O que isso faz:

1. Coloca 8 na célula 0
2. Entra no loop [...]
3. Move pra célula 1, soma 8, volta pra célula 0, subtrai 1
4. O loop roda 8 vezes, então célula 1 fica com 64 (8 x 8)
5. Move pra célula 1, soma 1 (agora é 65)
6. Imprime: “A”

Esse padrão de multiplicação com loops é a base de qualquer programa Brainfuck não-trivial.

Fase 1: o tokenizer

O tokenizer é a parte mais simples de todo o projeto. A gente precisa pegar o código fonte e extrair só os caracteres válidos, descartando tudo que não é um dos 8 comandos.

const VALID_TOKENS = new Set(['+', '-', '>', '<', '[', ']', '.', ',']);

function tokenizeBrainfuck(code) {
  const tokens = [];

  for (let i = 0; i < code.length; i++) {
    if (VALID_TOKENS.has(code[i])) {
      tokens.push(code[i]);
    }
  }

  return tokens;
}

Dado o input ++[>+<-] este texto é ignorado ., o tokenizer retorna:

['+', '+', '[', '>', '+', '<', '-', ']', '.']

Simples assim. Todos os espaços, letras e pontuação que não são comandos Brainfuck somem.

Fase 2: o parser e a Representação Intermediária

Em vez de executar os tokens diretamente, a gente vai transformar eles numa Representação Intermediária (IR). A IR é uma lista de instruções que descrevem o programa de forma mais estruturada.

Por que não executar os tokens diretamente? Dois motivos:

1. Otimização: podemos combinar operações consecutivas. ++++ não precisa ser 4 instruções separadas - é uma instrução só com valor 4.
2. Desacoplamento: a IR permite que a gente separe o parser do backend. Hoje o backend é um interpretador JavaScript, mas na parte 3 da série vai ser um gerador de bytecode JVM. A IR é a mesma.

As instruções da IR

Combinando operações consecutivas

A otimização mais importante do parser é combinar operações do mesmo tipo. A função handleSubsequent faz isso:

function handleSubsequent(tokens, charMap, token, pos) {
  let value = charMap[token];
  let newPos = pos;

  while (newPos + 1 < tokens.length && tokens[newPos + 1] in charMap) {
    newPos++;
    value += charMap[tokens[newPos]];
  }

  return { inc: value, newPos };
}

O charMap mapeia cada token pro seu valor numérico. Pra incrementos: {'+': 1, '-': -1}. Pra movimentos: {'>': 1, '<': -1}.

O que isso nos dá na prática:

Essa otimização é simples mas faz diferença. Um “Hello World” em Brainfuck tem centenas de + e - consecutivos.

Resolvendo os jumps

A parte mais complicada do parser é resolver os pares [ e ]. A gente usa uma pilha (loopStack) pra rastrear os colchetes abertos:

function parseBrainfuck(code) {
  const tokens = tokenizeBrainfuck(code);
  const instructions = [];
  const loopStack = [];
  let pointer = 0;

  for (let pos = 0; pos < tokens.length; pos++) {
    const token = tokens[pos];

    switch (token) {
      case '+':
      case '-': {
        const result = handleSubsequent(tokens, {'+': 1, '-': -1}, token, pos);
        if (result.inc !== 0) {
          instructions.push({ type: 'increment', inc: result.inc });
        }
        pos = result.newPos;
        break;
      }

      case '>':
      case '<': {
        const result = handleSubsequent(tokens, {'>': 1, '<': -1}, token, pos);
        pointer += result.inc;
        if (result.inc !== 0) {
          instructions.push({ type: 'move_head', head: pointer });
        }
        pos = result.newPos;
        break;
      }

      case '.':
        instructions.push({ type: 'output' });
        break;

      case ',':
        instructions.push({ type: 'input' });
        break;

      case '[':
        loopStack.push(instructions.length);
        instructions.push({ type: 'jump_eqz', jmp: -1 }); // placeholder
        break;

      case ']': {
        const openIndex = loopStack.pop();
        if (openIndex === undefined) {
          throw new Error('Unmatched ]');
        }
        instructions[openIndex].jmp = instructions.length + 1;
        instructions.push({ type: 'jump_neqz', jmp: openIndex + 1 });
        break;
      }
    }
  }

  if (loopStack.length > 0) {
    throw new Error('Unmatched [');
  }

  instructions.push({ type: 'halt' });
  return instructions;
}

O truque é o seguinte:

1. Quando encontra [, empilha o índice da instrução atual e emite um jump_eqz com destino -1 (placeholder).
2. Quando encontra ], desempilha o índice do [ correspondente.
3. Atualiza o jmp do [ pra apontar pra instrução depois do ].
4. O ] aponta de volta pra instrução depois do [.

Visualmente:

Instruções:  [0]  [1]  [2]  [3]  [4]  [5]  [6]
             inc  jeqz inc  inc  jneqz inc  halt
                  jmp→5          jmp→2

O jump_eqz na posição 1 pula pra posição 5 (saída do loop) se a célula é zero. O jump_neqz na posição 4 volta pra posição 2 (início do corpo do loop) se a célula não é zero.

O ponteiro absoluto

Uma decisão de design que vale mencionar: o move_head usa posição absoluta, não relativa. O parser mantém uma variável pointer que rastreia a posição virtual do ponteiro durante o parsing.

Isso simplifica a geração de bytecode lá na parte 3, porque na JVM a gente pode simplesmente fazer sipush valor; istore_2 pra definir o ponteiro, sem precisar carregar o valor atual e somar.

Fase 3: o interpretador

Com a IR pronta, o interpretador é direto. É um loop de fetch-decode-execute:

function executeBrainfuck(code, memory = new Uint8Array(30000)) {
  const instructions = parseBrainfuck(code);
  let pointer = 0;
  let pc = 0;
  const output = [];

  while (pc < instructions.length) {
    const instruction = instructions[pc];

    if (instruction.type === 'halt') break;

    switch (instruction.type) {
      case 'increment':
        memory[pointer] = (memory[pointer] + instruction.inc) & 0xFF;
        break;

      case 'move_head':
        pointer = instruction.head;
        break;

      case 'output':
        process.stdout.write(String.fromCharCode(memory[pointer]));
        break;

      case 'input':
        // lê um byte de stdin
        memory[pointer] = readByte();
        break;

      case 'jump_eqz':
        if (memory[pointer] === 0) {
          pc = instruction.jmp;
          continue; // pula o pc++ no final
        }
        break;

      case 'jump_neqz':
        if (memory[pointer] !== 0) {
          pc = instruction.jmp;
          continue;
        }
        break;
    }

    pc++;
  }

  return { cells: memory, currentCell: pointer };
}

Alguns detalhes que vale notar.

O & 0xFF no incremento garante que o valor fica no range de um byte (0-255). Se uma célula tá com 255 e você incrementa, ela volta pra 0. Se tá com 0 e decrementa, vai pra 255. É o comportamento esperado de Brainfuck.

O continue nos jumps é necessário porque a gente não quer incrementar o pc quando um salto é tomado. O jmp já aponta pra instrução correta. Sem o continue, o pc++ no final do loop rodaria e a gente pularia uma instrução.

O String.fromCharCode transforma o valor numérico da célula no caractere ASCII correspondente. Célula com 65 imprime “A”, com 72 imprime “H”.

Testando

Pra verificar que tudo funciona, a gente pode rodar o clássico “Hello, World!” em Brainfuck:

++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>
---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++.

Se tudo deu certo, o output é Hello, World!.

Você pode testar manualmente ou escrever testes automatizados. O projeto BrainJuck usa o test runner nativo do Node.js (node:test):

import { describe, it } from 'node:test';
import assert from 'node:assert';

describe('tokenizer', () => {
  it('extrai apenas tokens válidos', () => {
    const tokens = tokenizeBrainfuck('++ comentario >> .');
    assert.deepStrictEqual(tokens, ['+', '+', '>', '>', '.']);
  });
});

describe('parser', () => {
  it('combina incrementos consecutivos', () => {
    const ir = parseBrainfuck('++++---');
    assert.equal(ir[0].type, 'increment');
    assert.equal(ir[0].inc, 1);
  });

  it('elimina movimentos que se cancelam', () => {
    const ir = parseBrainfuck('>><<');
    assert.equal(ir[0].type, 'halt');
  });
});

Recapitulando

Até aqui a gente construiu:

1. Um tokenizer que extrai os 8 comandos válidos do código fonte
2. Um parser que transforma tokens em IR, com otimizações de combinação
3. Um interpretador que executa a IR

O pipeline completo:

Código fonte (.bf) -> Tokenizer -> Parser -> IR -> Interpretador -> Output

A IR é o que conecta o parser ao backend. No próximo post, a gente vai trocar o interpretador por um gerador de bytecode JVM. Mas antes disso, a gente precisa entender o formato .class da JVM - que é o assunto da parte 2.

O código desse post tá em geeksilva97/brainjuck. Os commits relevantes são os primeiros do projeto - em especial o a171e9a (functional brainfuck) e o 437d37c (the simplest parser ever).

Por hoje é só. Abraços.

Quando você roda javac Hello.java, o compilador gera um Hello.class. Esse arquivo é binário - não é texto, não é JSON, não é XML. São bytes crus numa estrutura muito específica definida na especificação da JVM.

Nesse post, a gente vai abrir um .class com xxd, entender cada byte, e construir um gerador que monta essa estrutura do zero em Node.js.

Antes de tudo: big endian

A JVM usa big endian pra representar números de múltiplos bytes. Isso é importante porque o processador do seu computador (x86/ARM) provavelmente usa little endian, que é a ordem inversa.

Qual a diferença? Imagina o número 30.000 (em hex: 0x7530). Ele ocupa 2 bytes:

Big endian coloca o byte mais significativo primeiro. Little endian coloca o menos significativo primeiro.

No nosso gerador, toda vez que a gente escrever um número de 2 ou 4 bytes, precisa respeitar essa ordem. A função pra converter um número de 16 bits (2 bytes) pra big endian:

function intTo2Bytes(num) {
  return [(num >> 8) & 0xFF, num & 0xFF];
}

O >> 8 desloca 8 bits pra direita, pegando o byte alto. O & 0xFF mascara o byte baixo. Pra 4 bytes, a lógica é a mesma mas com mais shifts.

Se você errar a ordem dos bytes, a JVM vai ler valores completamente errados. Um 0x7530 (30.000) vira 0x3075 (12.405) se os bytes ficarem invertidos. Então se o seu .class gerado dá erros estranhos no constant pool, confere se você tá escrevendo big endian.

Dissecando um .class

Vamos criar o programa Java mais simples possível:

public class Hello {
  public static void main(String[] args) {
    return;
  }
}

Compila com javac Hello.java e abre o binário com xxd Hello.class:

00000000: cafe babe 0000 0034 000d 0a00 0200 0307  .......4........
00000010: 0004 0c00 0500 0601 0010 6a61 7661 2f6c  ..........java/l
00000020: 616e 672f 4f62 6a65 6374 0100 063c 696e  ang/Object...<in
00000030: 6974 3e01 0003 2829 5607 0008 0100 0548  it>...()V......H
00000040: 656c 6c6f 0100 0443 6f64 6501 0004 6d61  ello...Code...ma
00000050: 696e 0100 1628 5b4c 6a61 7661 2f6c 616e  in...([Ljava/lan
00000060: 672f 5374 7269 6e67 3b29 5600 2100 0700  g/String;)V.!...

Parece caótico, mas tem uma estrutura definida. Vamos ler byte por byte.

O magic number

Os primeiros 4 bytes de todo .class são sempre CA FE BA BE. É o magic number que identifica o arquivo como um ClassFile da JVM. Se esses bytes não estiverem lá, a JVM recusa o arquivo imediatamente.

cafe babe

A história diz que os criadores do Java escolheram CAFEBABE porque lembravam de um café que frequentavam. Verdade ou não, é memorável.

Versão

Os 4 bytes seguintes indicam a versão do formato:

0000 0034

• 0000 - minor version: 0
• 0034 - major version: 52 (decimal)

Major version 52 é Java 8. A versão é importante porque determina quais features o .class pode usar. A partir da versão 50 (Java 6), por exemplo, a StackMapTable é obrigatória - mas esse é assunto da parte 3.

O constant pool

Aqui é onde mora a complexidade. O constant pool é uma tabela que armazena todas as constantes do programa: nomes de classes, nomes de métodos, strings, descritores de tipo. Tudo que o bytecode referencia é guardado aqui.

Os próximos 2 bytes indicam o tamanho:

000d

0x000d = 13. Mas atenção: o constant pool usa indexação começando em 1, e o count é sempre n + 1. Então temos 12 entries (indices 1 a 12).

Cada entry começa com um byte de tag que indica o tipo:

Vou destrinchar as primeiras entries do nosso Hello.class:

Entry 1 (começa no byte 0x0a):

0a 00 02 00 03

• Tag 0x0a = 10 = CONSTANT_Methodref
• Class index: 0x0002 = 2
• NameAndType index: 0x0003 = 3

Isso é uma referência ao método Object.<init>()V - o construtor da classe pai.

Entry 2:

07 00 04

• Tag 0x07 = 7 = CONSTANT_Class
• Name index: 0x0004 = 4 (aponta pra um Utf8 com o nome da classe)

Entry 4:

01 0010 6a617661 2f6c616e 672f4f62 6a656374

• Tag 0x01 = 1 = CONSTANT_Utf8
• Length: 0x0010 = 16 bytes
• Conteúdo: java/lang/Object

Percebe o padrão? O Methodref aponta pro Class, que aponta pro Utf8. É uma estrutura de referências indiretas. O bytecode nunca guarda strings diretamente - tudo passa pelo constant pool.

Os descritores de tipo

Uma coisa que confunde no começo: a JVM usa uma notação própria pra tipos. Não é void main(String[] args), é ([Ljava/lang/String;)V.

As regras:

Pra métodos, o formato é (parâmetros)retorno. Então:

Esses descritores aparecem no constant pool e o bytecode referencia eles pelo índice.

Depois do constant pool

O resto do ClassFile segue:

0021              - Access flags (ACC_PUBLIC | ACC_SUPER)
0007              - This class (índice no constant pool)
0002              - Super class (java/lang/Object)
0000              - Interfaces count: 0
0000              - Fields count: 0
0002              - Methods count: 2

Depois vêm os métodos (cada um com seus atributos de código) e por fim os atributos da classe.

Uma coisa que eu não esperava: mesmo o programa mais simples tem 2 métodos. O main que a gente escreveu e o construtor <init> que o Java gera automaticamente. No nosso gerador, a gente também precisa criar esse construtor.

Construindo o gerador

Agora que a gente entende a estrutura, vamos construir um gerador em Node.js. A ideia é montar o .class byte por byte num buffer.

Escrevendo bytes

Primeiro, as primitivas de escrita:

class ClassFileGenerator {
  constructor() {
    this.buffer = [];
    this.constantPool = [];
    this.constantPoolMap = {};
  }

  writeU1(value) {
    this.buffer.push(value & 0xFF);
  }

  writeU2(value) {
    this.buffer.push((value >> 8) & 0xFF);
    this.buffer.push(value & 0xFF);
  }

  writeU4(value) {
    this.buffer.push((value >> 24) & 0xFF);
    this.buffer.push((value >> 16) & 0xFF);
    this.buffer.push((value >> 8) & 0xFF);
    this.buffer.push(value & 0xFF);
  }

  writeBytes(bytes) {
    for (const b of bytes) {
      this.buffer.push(b);
    }
  }
}

U1, U2, U4 - 1, 2 e 4 bytes sem sinal. Tudo em big endian, que é o que a JVM espera. Repara que writeU2 e writeU4 usam shifts pra separar os bytes na ordem correta - byte mais significativo primeiro.

Gerenciando o constant pool

O constant pool precisa de deduplicação. Se dois métodos referenciam a mesma string "java/lang/Object", ela deve aparecer uma vez só. A gente usa um mapa pra controlar isso:

addUtf8Constant(str) {
  const key = `utf8:${str}`;
  if (this.constantPoolMap[key]) {
    return this.constantPoolMap[key];
  }

  this.constantPool.push({ tag: 1, value: str });
  const index = this.constantPool.length;
  this.constantPoolMap[key] = index;
  return index;
}

addClassConstant(nameIndex) {
  const key = `class:${nameIndex}`;
  if (this.constantPoolMap[key]) {
    return this.constantPoolMap[key];
  }

  this.constantPool.push({ tag: 7, nameIndex });
  const index = this.constantPool.length;
  this.constantPoolMap[key] = index;
  return index;
}

O mesmo padrão se repete pra addMethodrefConstant, addFieldrefConstant, addNameAndTypeConstant. Cada tipo tem seu tag e seus campos, mas a lógica de deduplicação é a mesma.

O índice retornado é a posição no array + 1, porque o constant pool da JVM é 1-indexed.

Montando o ClassFile

Pra gerar o .class do nosso compilador Brainfuck, a gente precisa de várias entries no constant pool. Especificamente, pra fazer System.out.print(char) e System.in.read(), que são as operações de I/O do Brainfuck:

// System.out (pra output do brainfuck)
const systemClassName = this.addUtf8Constant('java/lang/System');
const systemClass = this.addClassConstant(systemClassName);
const outFieldName = this.addUtf8Constant('out');
const printStreamDesc = this.addUtf8Constant('Ljava/io/PrintStream;');
const outNaT = this.addNameAndTypeConstant(outFieldName, printStreamDesc);
const outFieldRef = this.addFieldrefConstant(systemClass, outNaT);

// PrintStream.print(char)
const printStreamClassName = this.addUtf8Constant('java/io/PrintStream');
const printStreamClass = this.addClassConstant(printStreamClassName);
const printName = this.addUtf8Constant('print');
const printDesc = this.addUtf8Constant('(C)V');
const printNaT = this.addNameAndTypeConstant(printName, printDesc);
const printMethodRef = this.addMethodrefConstant(printStreamClass, printNaT);

Parece bastante coisa, e é. Cada referência de método ou campo na JVM exige essa cadeia: Utf8, depois Class, depois NameAndType, depois Methodref ou Fieldref. Mas depois que você monta uma vez, o padrão fica automático.

O construtor

Todo .class precisa de um construtor, mesmo que ele não faça nada. O construtor default em bytecode é:

aload_0             // carrega 'this' (local_0)
invokespecial #X    // chama Object.<init>()V
return              // retorna

Onde #X é o índice do Methodref pro construtor de Object no constant pool.

Em bytes:

// bytecode do construtor
const constructorCode = [
  0x2a,       // aload_0
  0xb7,       // invokespecial
  ...intTo2Bytes(objectInitMethodRef),
  0xb1        // return
];

O método main

O main é onde o bytecode do Brainfuck vai ficar. A declaração dele no ClassFile:

// access flags: ACC_PUBLIC | ACC_STATIC
this.writeU2(0x0009);
// name index: "main"
this.writeU2(mainNameIndex);
// descriptor index: "([Ljava/lang/String;)V"
this.writeU2(mainDescIndex);
// attributes count: 1 (o atributo Code)
this.writeU2(1);

O atributo Code contém o bytecode real:

// atributo Code
this.writeU2(codeAttrNameIndex);   // nome "Code" no constant pool
this.writeU4(codeAttrLength);      // tamanho total do atributo
this.writeU2(4);                   // max_stack
this.writeU2(3);                   // max_locals (args, cells, pointer)
this.writeU4(codeLength);          // tamanho do bytecode
this.writeBytes(jvmInstructions);  // o bytecode em si
this.writeU2(0);                   // exception table length
this.writeU2(stackMapEntries);     // attributes count (0 ou 1)
// se tiver StackMapTable, escreve aqui

O max_locals é 3 porque temos: slot 0 pro String[] args, slot 1 pro byte[] (memória do Brainfuck), e slot 2 pro int (ponteiro). Eu descobri isso na marra - quando coloquei 1, a JVM deu VerifyError: Local variable table overflow.

Gerando o arquivo

No final, a gente junta tudo e escreve:

const classBytes = generator.generateHelloWorldClass(
  className,
  ({ symbolicConstantPool }) => {
    return brainfuckIRToJVM(ir, {
      input: { /* refs do System.in */ },
      output: { /* refs do System.out */ }
    });
  }
);

fs.writeFileSync(`${className}.class`, new Uint8Array(classBytes));

O callback makeInstructions recebe o constant pool já montado e retorna o bytecode gerado. Essa separação permite que o gerador de ClassFile não saiba nada sobre Brainfuck - ele só sabe montar a estrutura do .class.

Inspecionando com javap

Depois de gerar o .class, você pode inspecionar ele com javap -v pra confirmar que a estrutura tá correta:

javap -v CompiledBrainfuck.class

Isso mostra o constant pool, os métodos, o bytecode decodificado, e os atributos. É a melhor ferramenta de debug que você vai ter nesse projeto. Quando algo der errado (e vai dar), roda o javap e compara com um .class gerado pelo javac.

Outra ferramenta que eu usei muito: xxd com offsets específicos. Quando o javap reclamava de algo, eu ia direto no byte:

xxd -s 270 -l 4 CompiledBrainfuck.class

Isso mostra 4 bytes a partir da posição 270. Útil pra conferir se um valor específico tá sendo escrito certo.

Recapitulando

Nesse post a gente viu:

• O formato binário do ClassFile da JVM, byte por byte
• Por que big endian importa e como escrever números de múltiplos bytes na ordem certa
• Como o constant pool funciona (Utf8, Class, Methodref, NameAndType)
• Os descritores de tipo da JVM (([Ljava/lang/String;)V)
• Como montar um gerador de .class do zero em Node.js

Na parte 3, a gente vai gerar bytecode JVM a partir da IR do Brainfuck. E vai ter que lidar com a StackMapTable, que quase me fez desistir.

Commits relevantes: 234b285 (class generator creates base structure), 31dd14d (massive refactoring in the JVM bytecode reader), e 1231ffc (beat u jvm) - que foi quando eu finalmente entendi o formato.

Por hoje é só. Abraços.

Esse é o post mais denso da série. No final, você vai rodar java CompiledBrainfuck e ver um “Hello, World!” gerado pelo seu próprio compilador.

O modelo de memória no bytecode

Antes de traduzir cada instrução, a gente precisa decidir como mapear o modelo do Brainfuck (fita de memória + ponteiro) pros conceitos da JVM.

Na JVM, um método tem variáveis locais numeradas a partir de 0. No nosso main(String[] args):

O slot 0 é reservado pros argumentos - eu tentei usar ele pra memória e a JVM deu VerifyError. Também tentei colocar o byte[] e o int no mesmo slot e descobri que a JVM não deixa misturar tipos num slot. Faz sentido quando você pensa na verificação de tipos, mas na hora foi confuso.

O preâmbulo do bytecode aloca essas variáveis:

// sipush 30000    - coloca 30000 na stack
// newarray byte   - cria byte[30000]
// astore_1        - guarda no slot 1
// iconst_0        - coloca 0 na stack
// istore_2        - guarda no slot 2 (ponteiro = 0)

const preamble = [
  0x11, 0x75, 0x30,  // sipush 30000
  0xbc, 0x08,        // newarray byte (T_BYTE = 8)
  0x4c,              // astore_1
  0x03,              // iconst_0
  0x3d               // istore_2
];

São 8 bytes. Todo bytecode gerado começa com esse preâmbulo.

Traduzindo cada instrução da IR

Cada instrução da IR vira uma sequência de opcodes JVM.

increment(n)

A operação cells[head] += n em bytecode:

aload_1       0x2b    // carrega o array (slot 1) na stack
iload_2       0x1c    // carrega o ponteiro (slot 2) na stack
dup2          0x5c    // duplica os dois valores no topo
baload        0x33    // pega cells[head] (consome array + index, empilha o byte)
sipush n      0x11    // coloca n na stack
iadd          0x60    // soma
i2b           0x91    // converte de int pra byte (trunca pra 8 bits)
bastore       0x54    // guarda o resultado em cells[head]

O dup2 é o truque aqui. O baload consome a referência do array e o índice da stack, mas a gente ainda precisa deles pro bastore depois. Então duplica antes de carregar o valor.

Em JavaScript:

function increment(n) {
  return [
    0x2b,                    // aload_1
    0x1c,                    // iload_2
    0x5c,                    // dup2
    0x33,                    // baload
    0x11, ...intTo2Bytes(n), // sipush n
    0x60,                    // iadd
    0x91,                    // i2b
    0x54                     // bastore
  ];
}

Cada increment gera 10 bytes de bytecode.

move_head(h)

Essa é simples - só carrega o valor absoluto e guarda no slot 2:

function move_head(h) {
  return [
    0x11, ...intTo2Bytes(h), // sipush h
    0x3d                     // istore_2
  ];
}

4 bytes. Por isso a decisão de usar posição absoluta no parser (parte 1) simplifica as coisas aqui.

output

Pra imprimir um caractere, a gente precisa chamar System.out.print(char). Em bytecode:

function output({ fieldRefIndex, methodRefIndex }) {
  return [
    0xb2, ...intTo2Bytes(fieldRefIndex),   // getstatic System.out
    0x2b,                                   // aload_1 (array)
    0x1c,                                   // iload_2 (ponteiro)
    0x33,                                   // baload (carrega cells[head])
    0x92,                                   // i2c (converte int pra char)
    0xb6, ...intTo2Bytes(methodRefIndex)   // invokevirtual print(char)
  ];
}

O fieldRefIndex e methodRefIndex são índices no constant pool que referenciam System.out e PrintStream.print(C)V. Esses índices vêm do gerador de ClassFile que a gente construiu na parte 2.

O i2c (int to char) é necessário porque baload retorna um int e o método print espera um char. Eu originalmente tentei com (I)V no descritor (print recebendo int), mas o output saía como número em vez de caractere. O descritor correto é (C)V.

input

Ler de System.in.read() e guardar na célula:

function input({ fieldRefIndex, methodRefIndex }) {
  return [
    0xb2, ...intTo2Bytes(fieldRefIndex),   // getstatic System.in
    0xb6, ...intTo2Bytes(methodRefIndex),  // invokevirtual read()
    0x2b,                                   // aload_1 (array)
    0x5f,                                   // swap
    0x1c,                                   // iload_2 (ponteiro)
    0x5f,                                   // swap
    0x54                                    // bastore
  ];
}

Os dois swap são necessários por causa da ordem da stack. O bastore espera arrayref, index, value nessa ordem, de baixo pra cima. Mas depois do invokevirtual read(), o valor lido tá no topo. A gente precisa reorganizar.

Segue o estado da stack passo a passo:

Depois do read():     [valor_lido]
Depois do aload_1:    [valor_lido, array]
Depois do swap:       [array, valor_lido]
Depois do iload_2:    [array, valor_lido, ponteiro]
Depois do swap:       [array, ponteiro, valor_lido]
bastore consome tudo: []

jump_eqz e jump_neqz

Os saltos condicionais. O Brainfuck [ vira jump_eqz (pula se zero) e ] vira jump_neqz (pula se não-zero):

function jump_eqz(offset) {
  return [
    0x2b,                        // aload_1
    0x1c,                        // iload_2
    0x33,                        // baload (carrega cells[head])
    0x99, ...intTo2Bytes(offset) // ifeq offset
  ];
}

function jump_neqz(offset) {
  return [
    0x2b,
    0x1c,
    0x33,
    0x9a, ...intTo2Bytes(offset) // ifne offset
  ];
}

Cada jump gera 6 bytes. Mas tem um problema: na hora de gerar o bytecode, a gente ainda não sabe o offset do salto. Os offsets dependem do tamanho total do bytecode entre o [ e o ], e a gente só vai saber isso depois de gerar todas as instruções entre eles.

O sistema de patches

Pra resolver o problema dos offsets desconhecidos, a gente usa um sistema de dois passos.

Passo 1: gera todo o bytecode com offsets zerados (placeholder) e registra onde cada salto tá:

const patches = [];
const labelPC = {};

for (let i = 0; i < irInstructions.length; i++) {
  const instruction = irInstructions[i];
  labelPC[i] = jvmPc; // mapeia índice da IR pro PC do bytecode

  if (instruction.type === 'jump_eqz') {
    const bytes = jump_eqz(0); // offset 0 = placeholder
    patches.push({
      at: jvmPc + 4,           // posição dos 2 bytes de offset
      targetIr: instruction.jmp,
      branchPc: jvmPc + 3      // posição do opcode ifeq
    });
    code.push(...bytes);
    jvmPc += bytes.length;
  }
  // ... mesmo pra jump_neqz
}

Passo 2: depois de gerar todo o bytecode, percorre os patches e calcula os offsets reais:

for (const patch of patches) {
  const targetPc = labelPC[patch.targetIr];
  const offset = targetPc - patch.branchPc;
  const [hi, lo] = intTo2Bytes(offset);
  code[patch.at] = hi;
  code[patch.at + 1] = lo;
}

O offset é relativo à posição do opcode de salto, não ao início do bytecode. Se o ifeq tá na posição 35 e o destino tá na posição 70, o offset é 70 - 35 = 35. Se é um salto pra trás (como o ] voltando pro [), o offset é negativo.

Esse foi um dos bugs que mais demorou pra achar. No começo eu tava usando offsets absolutos e a JVM reclamava de “bytecode offset out of range”. Só depois de ler a spec com mais cuidado eu entendi que os offsets de ifeq e ifne são relativos ao próprio opcode.

A StackMapTable

Esse é o chefe de fase do projeto.

A JVM a partir da versão 50 (Java 6) exige uma StackMapTable em todo método que tem saltos. Essa tabela descreve o estado das variáveis locais e da stack em cada ponto de destino de um salto. O verificador da JVM usa isso pra garantir type safety sem precisar executar o código.

Se você não gerar a StackMapTable, a JVM se recusa a carregar o .class:

Error: Expecting a stackmap frame at branch target 107

Dá pra contornar com java -noverify, mas isso desabilita a verificação inteira. É tipo desligar o alarme de incêndio porque tá apitando.

Como a StackMapTable funciona

A tabela é uma sequência de “frames”, cada um descrevendo o estado num ponto específico do bytecode. Existem vários tipos de frame, mas pro Brainfuck a gente só precisa de dois:

append_frame (tipo 253): usado no primeiro frame. Indica que foram adicionadas variáveis locais em relação ao frame inicial do método. No nosso caso, adicionamos byte[] (slot 1) e int (slot 2).

same_frame (tipo 0-63): os locais não mudaram desde o frame anterior. O tipo do frame É o offset delta (se cabe em 0-63).

same_frame_extended (tipo 251): mesmo que same_frame, mas pra offsets maiores que 63. O offset delta vem nos 2 bytes seguintes.

Calculando os offset deltas

O offset delta entre frames não é simplesmente a posição do destino. A fórmula:

primeiro frame:   offset_delta = targetPc
demais frames:    offset_delta = targetPc - previousTargetPc - 1

O -1 existe porque o frame anterior já “consome” uma posição. Eu demorei pra entender isso e o resultado era que os frames ficavam sempre 1 byte deslocados.

Gerando a StackMapTable

Durante a geração de bytecode, a gente registra os destinos de saltos. Depois, ordena eles por posição e calcula os frames:

function computeStackMapTable(entries, stackMapTableConstantIndex) {
  const buf = [];

  for (let i = 0; i < entries.length; i++) {
    const entry = entries[i];

    if (i === 0) {
      // primeiro frame: append_frame com 2 locais
      buf.push(253);                              // frame type
      buf.push(...intTo2Bytes(entry.offsetDelta)); // offset delta
      buf.push(7);                                 // verification: Object
      buf.push(...intTo2Bytes(byteArrayCPIndex));  // index de [B no constant pool
      buf.push(1);                                 // verification: Integer
    } else if (entry.offsetDelta <= 63) {
      // same_frame: o tipo É o offset
      buf.push(entry.offsetDelta);
    } else {
      // same_frame_extended
      buf.push(251);
      buf.push(...intTo2Bytes(entry.offsetDelta));
    }
  }

  // monta o atributo completo
  const result = [];
  result.push(...intTo2Bytes(stackMapTableConstantIndex)); // nome
  result.push(...intTo4Bytes(2 + buf.length));             // tamanho
  result.push(...intTo2Bytes(entries.length));              // num entries
  result.push(...buf);                                      // frames

  return result;
}

O tamanho do atributo é 2 + buf.length - 2 bytes pro número de entries, mais o conteúdo dos frames. Eu errei esse cálculo e demorei horas pra achar o bug. O .class passava no javap mas a JVM dava erro de verificação. O problema era que eu tava somando entries.length ao invés de 2 como os bytes fixos do campo de contagem.

Quando funciona sem -noverify

Quando eu finalmente acertei a StackMapTable, o programa rodou sem a flag -noverify pela primeira vez. O commit 44ff6c2 marca esse momento. Eu atualizei o README pra remover a instrução de usar -noverify e foi uma das melhores sensações do projeto inteiro.

Juntando tudo

O fluxo completo de compilação:

1. Lê o arquivo .bf
2. Tokeniza (extrai os 8 comandos válidos)
3. Parse pra IR (com otimizações)
4. Gera bytecode JVM a partir da IR
   - Emite preâmbulo (alocação de memória)
   - Traduz cada instrução
   - Registra patches pra saltos
5. Resolve patches (calcula offsets)
6. Computa StackMapTable
7. Monta o ClassFile (constant pool + métodos + atributos)
8. Escreve o .class

O CLI do BrainJuck faz tudo isso em poucas linhas:

#!/usr/bin/env node
import { readFileSync, writeFileSync } from 'node:fs';
import { parseBrainfuck, brainfuckIRToJVM } from './index.js';
import { ClassFileGenerator } from './class_generator.js';

const [,, sourceFile, className = 'CompiledBrainfuck'] = process.argv;
const source = readFileSync(sourceFile, 'utf-8');
const ir = parseBrainfuck(source);

const generator = new ClassFileGenerator();
const classBytes = generator.generateHelloWorldClass(
  className,
  ({ symbolicConstantPool }) => {
    return brainfuckIRToJVM(ir, {
      input: {
        fieldRefIndex: symbolicConstantPool.input.fieldRef,
        methodRefIndex: symbolicConstantPool.input.readMethodrefIndex
      },
      output: {
        fieldRefIndex: symbolicConstantPool.output.fieldRef,
        methodRefIndex: symbolicConstantPool.output.printlnMethodrefIndex
      }
    });
  }
);

writeFileSync(`${className}.class`, new Uint8Array(classBytes));
console.log(`${className}.class generated`);

Compila e roda:

./brainjuck samples/helloworld.bf HelloWorld
java HelloWorld
# Hello, World!

Testando

O projeto tem testes unitários pro tokenizer, parser e geração de bytecode, e um teste de integração que compila o Hello World e roda com java:

import { describe, it } from 'node:test';
import { execSync } from 'node:child_process';

describe('integration', () => {
  it('compila e executa helloworld.bf', () => {
    execSync('./brainjuck samples/helloworld.bf CompiledHelloWorld');
    const output = execSync('java CompiledHelloWorld').toString();
    assert(output.includes('Hello, World'));
  });
});

Se esse teste passa, o compilador gera bytecode JVM válido que a JVM aceita, verifica, e executa corretamente.

Recapitulando a série

Em três posts, a gente construiu um compilador de ~700 linhas de JavaScript que transforma Brainfuck em bytecode JVM executável. Interpretador, parser com otimizações, gerador de ClassFile, tradução de IR pra bytecode, sistema de patches pra saltos, e StackMapTable. Sem dependências externas. Cada byte do .class escrito manualmente.

O código completo tá em geeksilva97/brainjuck. Clona, lê, modifica, quebra. Se você quiser ir mais fundo, a spec da JVM é a referência definitiva. E se quiser ver outra abordagem, o Tsoding fez um JIT compiler pra Brainfuck compilando direto pra x86-64.

Por hoje é só. Abraços.

Eu não acho que todo mundo precisa saber JVM no nível de bytecode. Sério, não acho. Mas quando você se propõe a explicar - quando você senta na frente de uma câmera e fala como se fosse referência - é sua obrigação entender o que tá falando. Não precisa ser especialista, mas pelo menos saber o mínimo sobre o processo que você tá descrevendo.

Eu já estava curioso sobre máquinas virtuais fazia um tempo. Não o Java - a máquina virtual em si. O bytecode, o constant pool, o formato .class. Aquele nível que a maioria dos devs nunca precisa tocar. E eu já tinha brincado com Brainfuck antes. Daí eu vi um vídeo do Tsoding Daily onde ele implementa um JIT compiler pra Brainfuck - traduzindo direto pra código de máquina x86-64, em tempo de execução. Ver alguém construindo algo assim na raça, sem framework, sem abstração - aquilo juntou tudo na minha cabeça.

E se eu pegasse a linguagem mais simples que existe e compilasse ela pra rodar na JVM? Entender a JVM por dentro e fazer algo com Brainfuck, tudo no mesmo projeto.

Brainfuck tem 8 comandos. Oito. +, -, >, <, [, ], ., ,. É isso. Uma linguagem que cabe num guardanapo. Mas pra compilar ela pra bytecode JVM? Aí a coisa fica interessante.

O resultado? Um compilador de Brainfuck pra JVM escrito em Node.js. Zero dependências externas. Código escrito na mão. E o projeto mais divertido que eu já fiz.

A jornada

O primeiro passo foi construir um interpretador. Isso foi rápido - em um dia eu tinha um interpretador funcional em JavaScript. Brainfuck é simples de interpretar. Você tem um array de memória, um ponteiro, e vai executando os comandos. Que nem um caixa de supermercado - você processa um item de cada vez, na ordem.

O problema começou quando eu quis gerar bytecode.

Eu precisava entender o formato .class da JVM. E quando eu digo entender, eu digo byte por byte. O magic number CAFE BABE, o constant pool, os descritores de método, os atributos de código. Tudo em binário.

Minha primeira abordagem foi pegar um .class compilado pelo javac e dissecar ele com xxd:

xxd -s 270 -l 4 BrainfuckProgram.class

Fiquei semanas lendo hex dump. Parece loucura, mas foi assim que eu comecei a entender como a JVM realmente funciona. Eu escrevia um programa Java simples, compilava, e ficava comparando o binário com a spec. Byte por byte.

NOTA: Eu escrevi dois artigos detalhados sobre essa parte técnica no blog da Codeminer42: The Road To JVM: How To Create A Brainfuck Interpreter e The Road To JVM: The JVM Specification. Se você quer o detalhe técnico, vale a leitura.

Os bugs mais legais da minha vida

Eu não tô exagerando quando digo que os bugs desse projeto foram divertidos. Em qualquer outro projeto, um VerifyError da JVM seria frustrante. Aqui, eu ficava animado quando algo quebrava porque significava que eu ia aprender mais uma coisa.

Um dos primeiros: eu tentei guardar um int e um array de bytes no mesmo slot de variável local. A JVM não deixa. Faz sentido - ela precisa saber o tipo de cada slot pra verificação. Mas eu só descobri isso porque a JVM me mandou um erro detalhado dizendo exatamente o que estava errado:

Caused by: java.lang.VerifyError: Bad type on operand stack
Reason: Type integer is not assignable to reference type

Descobri que o slot 0 é reservado pros argumentos do método. Meu array de memória tinha que ir pro slot 1 e o ponteiro pro slot 2. Parece óbvio agora, mas na hora eu passei um bom tempo compilando programas Java com javac -g:vars pra ver a LocalVariableTable e confirmar minhas suspeitas.

Outro bug legal: os offsets de jump. No Brainfuck, [ e ] são instruções de loop. No bytecode JVM, isso vira ifeq e ifne com offsets em bytes. Eu estava calculando errado e a JVM reclamava de “bytecode offset out of range”. A solução foi um sistema de dois passos - primeiro calcula as posições, depois gera o bytecode com os offsets corretos.

E o boss final: a StackMapTable.

O chefe de fase: StackMapTable

A JVM moderna (versão 50+) exige que todo .class tenha uma StackMapTable nos métodos que fazem jumps. É uma estrutura que descreve o estado da stack e das variáveis locais em cada ponto de salto. Se você não gerar isso corretamente, a JVM se recusa a rodar seu código.

Por um bom tempo eu contornei isso rodando com java -noverify. Funcionava, mas era trapaça. Que nem usar // @ts-ignore - resolve na hora, mas você sabe que tá errado.

O problema é que a spec da StackMapTable é confusa. Existem vários tipos de frame (same_frame, append_frame, same_frame_extended), cada um com regras diferentes pra calcular o offset_delta. O primeiro frame é um append_frame (tipo 253) porque adiciona duas variáveis locais (o array de memória e o ponteiro). Os frames seguintes são same_frame (tipo 0-63) porque os locais não mudam.

A fórmula do delta: target_pc - 1 - previous_target_pc.

Quando eu achei que estava tudo certo, funcionou pro caso trivial mas quebrava com mais de dois jumps. Passei horas debugando hex dumps até perceber que o cálculo do tamanho do atributo estava errado - eu somava o número de entries ao tamanho do buffer, mas o correto era 2 + buffer.length. Dois bytes pro número de entries, o resto pro conteúdo.

Quando finalmente funcionou sem -noverify, eu fiquei uns bons minutos olhando pro terminal sem acreditar. Meses de hex dump, de ler spec, de errar e tentar de novo. E agora o verificador da JVM aceitou meu .class como válido.

O que a IA não conseguiu fazer

Uma coisa interessante aconteceu durante o projeto. Quando eu já tinha a ideia de como o bytecode deveria ser gerado, eu pedi pro ChatGPT e pro Claude implementarem. Na época eu estava usando os dois no chat, sem nenhuma ferramenta de coding. Eu tinha o design mental, só queria ver se eles conseguiam traduzir isso em código.

Não funcionou.

O código que eles geraram não rodava. Mas - e isso é importante - serviu de referência. Especialmente o sistema de patches pra lidar com instruções de jump. Eu peguei a ideia, entendi, e reescrevi do zero.

Isso pra mim é o uso correto de IA. Você usa pra pesquisar, pra ter uma ideia de direção, mas o trabalho de verdade ainda é seu. Que nem o Pragmatic Programmer fala sobre protótipos - você constrói pra aprender, não pra usar diretamente.

Hoje em dia, com Claude Code ou OpenCode rodando Opus, eu acredito que a IA daria conta. Mas mesmo que desse - e esse é o ponto - eu não teria aprendido nada. Se a IA escreve o código por você, o código funciona mas a sua cabeça continua vazia.

Por que isso foi tão divertido

Eu trabalho com software há anos. Já fiz feature, já fiz bugfix, já fiz refactoring em código legado. Tudo isso é importante e eu gosto do que faço. Mas tem algo diferente em construir algo completamente do zero, sem framework, sem biblioteca, sem dependência externa.

O BrainJuck é Node.js puro. Usa node:fs pra ler arquivos, node:test pra testes, e mais nada. Cada byte do .class gerado é escrito manualmente. O constant pool, os descritores de método, as instruções - tudo.

A arquitetura é um pipeline de três estágios:

Brainfuck Source -> Tokenizer -> Parser -> IR -> JVM Bytecode -> ClassFile

Não tinha deadline, não tinha sprint, não tinha ticket no Jira. Era só eu, a spec da JVM, e um editor de texto. Quando um .class gerado rodava de primeira, eu comemorava sozinho. Quando quebrava, eu abria o xxd e ia caçar o byte errado. As duas coisas eram igualmente boas.

O que eu aprendi

Além de JVM bytecode (que, sinceramente, eu duvido que vá usar no dia a dia), eu aprendi coisas que vão além do técnico:

1. Ler specs é uma habilidade. A spec da JVM é densa, mas precisa. Cada byte tem um significado definido. Aprender a ler specs te torna um programador melhor - você para de depender de tutoriais e vai direto na fonte.

2. Projetos pessoais não precisam ser úteis. O BrainJuck não resolve nenhum problema real. Ninguém precisa compilar Brainfuck pra JVM. E tá tudo bem. O valor tá no aprendizado. Que nem a Barbara Oakley fala em A Mind for Numbers - aprender coisas aparentemente desconectadas fortalece sua capacidade de resolver problemas em geral.

3. Se a IA escreve por você, você não aprende. A IA me deu ideias que aceleraram meu entendimento. Mas se eu tivesse deixado ela escrever o compilador, eu não teria entendido nada do que foi feito. O valor estava no processo, não no resultado.

4. Debug de baixo nível é meditativo. Tem algo zen em olhar hex dump e entender o que cada byte significa. É o oposto do desenvolvimento web moderno onde tudo é abstração sobre abstração.

5. Raiva é um combustível válido. Às vezes ver alguém falar besteira sobre algo te motiva a ir mais fundo do que a curiosidade sozinha levaria. Não é o combustível mais nobre, mas funciona.

Recomendações

Se você ficou com vontade de explorar compiladores e máquinas virtuais:

• A spec da JVM é gratuita e online: The Java Virtual Machine Specification
• Crafting Interpreters do Robert Nystrom - excelente livro sobre como construir linguagens de programação, do zero
• O vídeo do Tsoding implementando um JIT pra Brainfuck - pura inspiração ver alguém construindo na raça
• O próprio Brainfuck como linguagem de estudo - é simples o suficiente pra você focar na mecânica do compilador sem se perder na complexidade da linguagem fonte

Se você quer aprender a construir o seu próprio, eu escrevi uma série de três posts que ensina passo a passo: parte 1 (interpretador), parte 2 (formato .class), parte 3 (gerando bytecode).

E o BrainJuck tá no GitHub. Zero dependências. Leia o código, brinque, quebre. É pra isso que ele existe.

Por hoje é só. Abraços.

Não exige. E pra te convencer disso, fui olhar o código-fonte do OpenCode pra ver o que realmente acontece por baixo dos panos.

Mas antes, preciso te explicar como LLMs funcionam de verdade. Sem isso, skill não faz sentido.

LLMs não fazem nada

Um LLM é uma função. Entra texto, sai texto. Ele não acessa a internet, não lê arquivos, não executa código. Ele prevê o próximo token baseado no que recebeu.

Isso é literalmente tudo.

Quando você manda uma mensagem pro Claude ou pro GPT e ele “lê um arquivo” ou “busca na web”, não é o modelo fazendo isso. É o sistema ao redor dele. O modelo só gera texto. Quem age é o programa que orquestra a conversa.

Tools: dando mãos ao modelo

Pra que um LLM interaja com o mundo real, usamos tools (ou function calling). O fluxo é:

1. Você envia uma mensagem junto com uma lista de tools disponíveis - cada uma com nome, descrição e parâmetros
2. O modelo analisa a mensagem e decide se precisa usar alguma tool
3. Se sim, ele responde pedindo a execução: { "tool": "read_file", "args": { "path": "src/main.ts" } }
4. O sistema host (não o modelo) executa a tool e devolve o resultado
5. O modelo recebe o resultado e continua gerando a resposta

O modelo nunca executa nada. Ele apenas pede pra executar. Quem roda é o agente.

Agentes: o loop que conecta tudo

Um agente é esse loop. Simplificando ao máximo:

enquanto não terminou:
    resposta = llm.gerar(mensagens, tools)
    se resposta tem tool_call:
        resultado = executar(tool_call)
        mensagens.append(resultado)
    senão:
        retornar resposta

O agente mantém o histórico, injeta as definições de tools, executa as chamadas e alimenta o modelo com os resultados. O OpenCode faz exatamente isso em packages/opencode/src/session/prompt.ts.

Se você quer entender agentes de verdade, estuda esse loop. Todo o resto é detalhe de implementação.

Como o OpenCode registra tools

No OpenCode, toda tool implementa uma interface Tool.Info definida em packages/opencode/src/tool/tool.ts:

export interface Info<Parameters, M> {
  id: string
  init: (ctx?) => Promise<{
    description: string
    parameters: Parameters
    execute(args, ctx): Promise<{ title, metadata, output }>
  }>
}

Toda tool tem um id, uma description, os parameters que aceita e uma função execute. O ToolRegistry em packages/opencode/src/tool/registry.ts junta todas - built-in, custom e de plugins - e entrega pro modelo a cada interação.

As tools built-in são registradas assim:

return [
  ReadTool, GlobTool, GrepTool, EditTool, WriteTool,
  BashTool, TaskTool, WebFetchTool, SkillTool,
  // ...
]

Repara nesse SkillTool ali no meio. Guarda esse nome.

Agora sim: o que é uma skill?

Uma skill no OpenCode é um arquivo markdown chamado SKILL.md com um frontmatter YAML:

---
name: agents-sdk
description: Build AI agents on Cloudflare Workers using the Agents SDK
---

# Cloudflare Agents SDK

Aqui vão instruções detalhadas, exemplos de código,
referências, boas práticas...

Isso. Um arquivo .md com nome e descrição.

O código que descobre esses arquivos está em packages/opencode/src/skill/skill.ts. Ele varre SKILL.md em diretórios globais (~/.claude/skills/, ~/.agents/skills/), diretórios do projeto (.opencode/skills/), caminhos custom e até URLs remotas.

O truque: SkillTool é só uma tool

O SkillTool em packages/opencode/src/tool/skill.ts é uma tool como qualquer outra. Na sua função init(), ele:

1. Escaneia todos os SKILL.md disponíveis
2. Monta sua própria descrição listando o que encontrou:

<available_skills>
  <skill>
    <name>agents-sdk</name>
    <description>Build AI agents on Cloudflare Workers...</description>
  </skill>
</available_skills>

Essa descrição vai pro modelo junto com as outras tools. Quando o modelo decide que precisa de uma skill, faz uma chamada de tool normal:

{ "tool": "skill", "args": { "name": "agents-sdk" } }

O SkillTool recebe essa chamada, lê o SKILL.md correspondente e devolve o conteúdo. O modelo usa essas instruções pra continuar o trabalho.

Releia. É o mesmo fluxo de qualquer tool. O modelo pede, o sistema lê um arquivo, o conteúdo volta pro contexto.

Pensa assim: se o modelo pode chamar read_file pra ler um arquivo de código, por que não pode chamar uma tool pra ler um arquivo de instruções? É exatamente isso que a SkillTool faz. A diferença é só a convenção - um lugar padronizado pra colocar instruções reutilizáveis que o modelo puxa sob demanda.

Como criar uma skill, de verdade

1. Cria uma pasta dentro de .opencode/skills/ (ou .claude/skills/, dependendo do agente)
2. Coloca um SKILL.md dentro com frontmatter name e description
3. Escreve as instruções em markdown

Pronto. Não tem passo 4.

O modelo vai ver a descrição curta da sua skill na lista de tools disponíveis. Se ele achar relevante pro que está fazendo, vai chamar a tool e ler o conteúdo completo. Se não achar, ignora. Você não força nada.

O conteúdo completo só entra no contexto quando o modelo pede. As descrições são leves, o markdown pesado fica de fora até ser necessário.

Uma dica sobre o que colocar numa skill: o Sean Goedecke escreveu sobre gerar skills depois de resolver o problema, não antes. A ideia é que a LLM escreve skills melhores depois que ela já iterou na solução, porque daí ela destila o que aprendeu. Faz sentido - você não escreve documentação boa antes de entender o problema.

Conclusão

Skill é um arquivo markdown que uma tool lê quando o modelo pede. O mesmo tool calling que permite o modelo ler arquivos ou executar comandos é o que permite ele carregar uma skill. Não tem framework, não tem runtime, não tem mágica.

Se você sabe escrever markdown, você sabe criar skills.

Por hoje é só.

O primeiro grupo está escolhendo a obsolescência. O segundo está fazendo vibecoding: jogando prompts num agente, torcendo pro melhor, e entregando o que volta.

Existe um jeito melhor de trabalhar com agentes e ele tem nome: Agentic Engineering.

Não caia na armadilha anti-IA

Era legal ser anti-IA. Você ficava no seu canto, tirando sarro de como os modelos eram ruins, de como isso era só hype, e de como você ia conseguir emprego corrigindo o código quebrado dos modelos.

Esse tempo passou.

O código gerado pelos modelos de ponta (Claude, GPT, até os open source como Kimi K2.5 e GLM 5) é bom. Com review adequado, você tem código pronto pra produção. Não é perfeito, mas funciona e faz sentido.

Ficando anti-IA você está ativamente perdendo a chance de aprender habilidades que estão em demanda, de ganhos reais de produtividade, e de participar de uma mudança tecnológica que não acontece com frequência. As últimas disrupções desse tamanho? Talvez Agile. Talvez a web em si. Talvez open source nos anos 90.

Como o antirez colocou: pra maioria dos projetos, escrever o código você mesmo não faz mais sentido, a não ser pra se divertir. E ele é o cara que escreveu o Redis na mão em C.

Você TEM QUE usar IA pra codar

Isso não é opcional.

A gente sempre soube que nosso trabalho não é digitar código. É pensar sobre problemas, tomar decisões, projetar soluções. Bom, agora a gente também não precisa digitar a maior parte.

Seu papel mudou pra decidir e revisar, cada um no seu escopo de tomada de decisão.

Se você não está usando IA, alguém com o mesmo nível que você mais um agente está te superando. É assim que é.

“You can’t review what you don’t understand, and you can’t understand what you haven’t done yourself.”

– Matteo Collina, Yes, Learning to Code Is Still Valuable

O que me leva a uma distinção que importa.

Vibecoding vs. Agentic Engineering

Vibecoding é o que a maioria faz quando começa com IA. Você abre um chat, descreve o que quer em termos vagos, o agente gera código, você cola em algum lugar, meio que funciona, segue a vida.

Tudo bem pra explorar. Tudo bem pra scripts descartáveis. Não é engenharia.

Agentic Engineering é a versão deliberada. Agentic porque o agente gera o código. Engineering porque você ainda pensa, planeja, itera e revisa.

Pensa em pair programming. O agente é o driver. Você é o navigator. O navigator não escreve código, mas é ele quem mantém o projeto no trilho.

Como começar

Antes das dicas, um check de realidade.

Você não vai integrar agentes no seu fluxo de trabalho da noite pro dia. Force-se a usar. Não estou falando de tentar por 20 minutos e desistir. Estou falando de semanas de uso consistente.

Você não vai ter resultados ótimos no começo. Tudo bem. Mesma curva de aprendizado que você enfrentou com toda ferramenta que já pegou.

O que funcionou pra mim:

1. Separe tempo pra experimentar

Você precisa forçar isso. Assim como qualquer habilidade, precisa de tempo dedicado. 30 minutos por dia, uma hora dia sim dia não, o que funcionar. O ponto é consistência.

2. Todo side project usa IA

Aquele PoC que você precisa fazer, a demo pra sua próxima talk, o projeto que você nunca começou. Todos são candidatos perfeitos. Você não precisa do projeto perfeito. Comece com o que tem.

3. Ache tarefas no trabalho

Documentação, parsing de arquivos, traduções, scripts repetitivos. Baixo risco, bom aprendizado.

Quer evoluir mais rápido? Refaça tarefas que você já resolveu, mas dessa vez com um agente. Como você já sabe a solução, pode focar inteiramente em guiar o agente. Uma das formas mais rápidas de melhorar nisso.

4. Construa projetos inteiros com IA

Eu fiz: 61 commits, 507 testes, 12 mil linhas de código, em produção em 5 dias. Não escrevi uma linha de código manualmente. Mas tomei cada decisão.

Dicas de Agentic Engineering

É aqui que vibecoding e agentic engineering se separam.

Tenha um plano antes de dar o prompt

Antes de pedir qualquer coisa pro agente, saiba o que você quer. Um objetivo e uma sequência aproximada de passos. Não precisa ser detalhado, mas precisa existir.

Use plan mode se seu agente suporta. Deixe o agente propor uma abordagem, revise, ajuste, daí execute.

Trabalhe passo a passo

Não peça pro agente construir uma feature inteira de uma vez. Quebre em pedaços. Valide cada mudança pequena. Mude a rota se precisar. Interfira. Peça pra refazer.

Depois de cada passo validado: atualize docs, rode o linter, rode os testes, commite e dê push.

Mudanças pequenas são fáceis de reverter. Grandes são um pesadelo.

Isso não é ideia nova. Isso é o que todo desenvolvedor competente deveria fazer. Agile, extreme programming, tudo converge pro mesmo ponto: passos pequenos, validados, incrementais.

Monte guardrails pro agente

Agentes funcionam melhor quando têm restrições. Eu não esperava que isso importasse tanto, mas muda tudo.

Dê ao agente arquivos de contexto (CLAUDE.md, AGENTS.md, skills files) pra ele conhecer as convenções do seu codebase. Configure linters e formatters pra que o agente leia a saída e corrija as próprias violações. Escreva testes e rode depois de cada mudança pra que você e o agente saibam se algo quebrou. Adicione git hooks (pre-commit, pre-push) como portões automáticos. Mantenha seu pipeline de CI/CD como checkpoint final.

Nenhuma dessas ferramentas é nova. Elas existiam antes de IA e sempre foram boas práticas. Mas agora são a infraestrutura que impede o desenvolvimento assistido por IA de sair dos trilhos. Linters mais testes mais hooks é basicamente um parceiro automatizado de code review em cima do agente.

O que falta aprender?

Muita coisa. Mais do que nunca, na verdade.

Eu tive uma PM na GoDaddy que estimava pontos de tarefas. Mas como você estima algo se não entende o processo de construir?

Você não consegue revisar o que não conhece.

Pra guiar um agente por uma feature, do frontend ao backend, você precisa entender UX, modelagem de dados, design de API, segurança, arquitetura. Precisa saber como sistemas se conectam, como quebram, como escalam.

Sistemas distribuídos, algoritmos, redes: são mais valiosos agora, não menos. O caminho de bootcamp de “aprenda React em 12 semanas” está se fechando. O caminho de fundamentos profundos está escancarado.

No lado de produto: aprenda sobre o produto do seu cliente. Entenda como os projetos se integram. Esse tipo de conhecimento contextual torna um desenvolvedor insubstituível, com ou sem agente.

O agente te amplifica

IA amplifica o que você já é. Se você é um bom dev que planeja antes de codar, escreve testes e entende o problema antes de resolver, o agente vai te tornar muito melhor.

Se você pula o pensamento, se não se importa em entender, se só faz vibecoding… vai acabar com uma bagunça. Uma bagunça rápida, mas uma bagunça.

Velocidade não é a mesma coisa que produtividade.

O agente é um multiplicador. E multiplicador só funciona se o que ele está multiplicando vale alguma coisa.

Por hoje é só.

Referências:

• antirez - Don’t fall into the anti-AI hype
• Matteo Collina - Yes, Learning to Code Is Still Valuable
• Writing a Good CLAUDE.md
• Claude Code Skills Explained
• Akita on Rails - Vibe Code do Zero à Produção

Eu construí o Kanario, um gerador de thumbnails pra blog que puxa um rascunho do WordPress, passa por uma LLM pra gerar prompts de imagem, e gera capas. Tem CLI, bot no Discord, dois backends de LLM, dois backends de geração de imagem, criptografia de credenciais por usuário, deploy no Cloud Run e pipeline completo de CI/CD. Com desenvolvimento assistido por IA, levou quatro dias. Uma estimativa tradicional colocaria entre 7 e 11 semanas pra um dev senior sozinho.

Isso é um ganho de 4-6x. Mas aconteceu num lugar bem específico.

Geração de código ficou rápida. O resto ficou igual.

Todo boilerplate: hierarquias de classes de erro, mocks de teste, parsing de argumentos CLI, handling de interações do Discord, Dockerfile, YAML do GitHub Actions. Foi de horas pra minutos. São coisas onde você sabe exatamente o que quer, mas digitar é tedioso. A IA remove essa fricção.

APIs desconhecidas foram outro grande ganho. Ao invés de gastar uma hora lendo a doc de async polling do RunPod ou tentando entender a verificação de assinatura Ed25519 do Discord, eu descrevia a intenção e iterava no resultado. O ciclo de exploração que costumava ser “lê doc, tenta algo, lê mais doc, conserta” comprimiu pra “descreve o que preciso, ajusta a saída.”

Escrever testes ficou muito mais rápido também. Uma vez que os padrões estavam estabelecidos (mock de HttpClient, mocks a nível de módulo com variáveis substituíveis, Fastify inject pra rotas HTTP), eu descrevia um novo caso de teste e recebia um teste funcionando em segundos.

Mas arquitetura? Toda decisão sobre como o sistema deveria ser estruturado exigiu pensar. Injeção de dependência do HttpClient. O schema compartilhado do gerador de prompts entre Gemini e Claude. A camada de workflow que permite CLI e Discord usarem a mesma lógica. A hierarquia de erros com hints acionáveis por código de erro do WordPress.

A IA não acelerou essas decisões porque o gargalo nunca foi digitar o código. Era descobrir a abstração certa.

Os bugs que a IA não enxerga sozinha

Prompt engineering foi todo manual. Quando o Qwen começou a renderizar a palavra “robot” como uma cópia do personagem mascote, nenhuma ferramenta de IA poderia ter me avisado. Eu tive que olhar as imagens geradas, notar o problema, levantar a hipótese de que a palavra “robot” estava conflitando com a imagem de referência, testar com “bot buddy” no lugar, e verificar a correção em múltiplas gerações.

Claro, IAs conseguem “ver” imagens hoje. Depois de identificar o problema, eu montei um smoke test onde o Claude analisava as imagens geradas e comparava com o que era esperado. Funcionou. Mas alguém precisou notar o problema primeiro, formular a hipótese, e montar a validação. A IA executou o teste. Eu defini o que testar.

Mesma coisa com o bug de balanceamento de quota da LLM. O gerador de prompts produzia exatamente 3 cenas com mascote e 1 diorama sem mascote, sempre. Estava balanceando internamente, tentando me dar uma “mistura legal.”

Corrigir exigiu entender que a formulação do system prompt estava incentivando isso sem eu perceber, e reescrever pra dizer “decida independentemente por cena.” A IA não pegou isso. Eu peguei porque a saída parecia errada.

Onde isso nos deixa

O multiplicador é real. 4-6x nesse projeto. Mas vem de eliminar as partes mecânicas do desenvolvimento: traduzir decisões em sintaxe, escrever padrões repetitivos, conectar APIs que você entende conceitualmente mas não decorou.

As decisões em si, o que construir, como estruturar, quando algo parece errado, continuam sendo suas. E se você tenta pular elas, se deixa a IA tomar decisões de arquitetura por você, acaba com uma codebase que funciona inicialmente mas briga com você toda vez que precisa mudar algo. A IA não conhece suas restrições nem seus usuários. Ela conhece sintaxe.

O pensamento continua sendo o trabalho. A digitação é que ficou mais barata.

Por hoje é só.