As decisões sem registro

Este repositório tem dois documentos que parecem registrar decisões, e nenhum dos dois registra.

O que o MEMORY.md tem

659 linhas de regras, declaradas com autoridade:

"Consultas precisam ser agnósticas de infraestrutura. Recebem page e per_page, usam .limit/.offset, e devolvem registros + total_count. Não devolva objetos Pagy."

Essa é uma regra boa e clara. Agora tente responder três perguntas sobre ela a partir do documento:

Quando isso foi decidido? Não está dito.

Qual era a alternativa? Não está dito, e havia uma, porque a documentação da própria Pagy mostra devolver os objetos dela, e a gem está neste Gemfile.

O que mudaria a resposta? Não está dito. Se a paginação fosse para outra gem amanhã, essa regra ainda valeria, ou ela protegia algo específico da Pagy?

Uma regra sem essas três é uma instrução, não um registro de decisão. Ela te diz o que fazer e não te dá como saber se ainda se aplica.

O que o git tem

A outra metade, e ela tem o problema oposto:

$ git log --diff-filter=A --format='%ad %h %s' --date=short -- app/queries | tail -1
2026-02-26 5bb5b08 feat(enrollment): namespace Enrollment domain — DashboardController and UserXpQuery

$ git log --diff-filter=A --format='%ad %h %s' --date=short -- app/services/execution/run_sandbox_service.rb | tail -1
2026-02-26 e0afeb7 feat: Implement Execution Sandbox with ruby.wasm and xterm.js

Datas e autoria, sem raciocínio. O e0afeb7 te diz que em 26 de fevereiro alguém decidiu rodar o código de quem estuda no navegador com ruby.wasm. Ele não te diz qual era a alternativa, por que ela perdeu, ou o que a decisão custa.

flowchart TB
  M["MEMORY.md: a regra"] --> M1["o que fazer"]
  M --> M2["sem data, sem alternativa, sem condição de validade"]
  G["git log: a mudança"] --> G1["quando, e por quem"]
  G --> G2["sem raciocínio, sem alternativa, sem consequências"]
  M2 --> A["nenhum dos dois é registro de decisão"]
  G2 --> A

Quatro decisões que merecem registro

Lendo o código e o histórico juntos, quatro decisões moldaram esta aplicação e nenhuma está escrita como decisão.

Rodar o código de quem estuda no navegador. e0afeb7, 26 de fevereiro. ruby.wasm e Xterm.js, sem nenhum sandbox no servidor na época. Todo desafio do catálogo foi escrito só com a biblioteca padrão por causa disso. A correção depois passou para o servidor; a aula 3 volta a esse ponto.

Nomeação por domínio desde o primeiro dia. 5bb5b08, no mesmo dia do esqueleto Rails. Não uma refatoração que chegou depois. O oitavo dos quarenta e sete commits feitos naquele dia, numa sequência de seis commits de nomeação por domínio que começou três commits depois do esqueleto do Rails, já tinha Enrollment::.

Dois caminhos de autenticação. O has_secure_password no esqueleto, e o OAuth do GitHub acrescentado em 7 de março no 9a38bf1. Os dois ainda existem, o que é uma decisão de manter dois, e nada diz por quê.

Pagy para configuração, não para objetos. A gem é usada (o Pagy::OPTIONS[:limit] aparece dentro de três objetos de consulta como fonte do tamanho de página padrão) enquanto o MEMORY.md proíbe devolver os objetos dela. Essa é uma linha sutil e deliberada, e um documento de regras a achata numa proibição que soa como antipatia pela gem.

Por que a quarta é o melhor exemplo

Porque a regra e o código aparentam se contradizer. Quem chega lê "não devolva objetos Pagy", busca por Pagy, encontra dentro de três consultas, e agora precisa descobrir se a regra está velha, o código está errado, ou existe uma distinção que ninguém escreveu.

Existe uma distinção, ela é boa, e reconstruí-la leva vinte minutos: ler três objetos de consulta e inferir o princípio. Um ADR teriam sido quatro frases.

Esses vinte minutos são pagos por toda pessoa que esbarra na pergunta, para sempre. O custo de um registro de decisão faltando é a rederivação, multiplicada por todo mundo que precisar dela, e não a escrita.

Pontos-chave

• O MEMORY.md declara regras sem data, sem alternativa e sem condição que as mudaria.
• O git tem datas e autoria sem raciocínio, alternativas ou consequências.
• Quatro decisões moldaram esta aplicação: sandbox no navegador (depois substituído), nomeação desde o dia um, dois caminhos de autenticação, Pagy de config e não de objetos.
• A regra da Pagy e o código da Pagy aparentam se contradizer; a distinção é real e não está escrita.
• O custo de um registro faltando é a rederivação, multiplicada por todo mundo que precisar dela.