Terturionsland
02Blog

A documentação que falta

Notas do que vamos aprendendo. Quase tudo sai de um problema concreto que nos custou mais do que esperávamos.

Todas
  1. ProductoLa web de un pintor solo tiene que hacer una cosa: que le llamenHice la web y la app de trabajo de Mamu, un pintor de Valencia, en cuatro días sueltos. Lo que más mejoró la web fue borrar las páginas de precios y de por qué elegirnos.
  2. IACómo construimos Zenbu, un buscador de anime que busca por lo que cuentasCatorce mil animes, un vector por serie y un LLM que reordena al final. Lo que más nos costó no fue la búsqueda semántica: fueron las secuelas con sinopsis de una línea.
  3. ArquiteturaJá migrei de provedor de auth quatro vezesQuatro provedores gerenciados em um ano e meio, e o mesmo destino em todos: middleware próprio. O que quebra em cada transição e o que eu olho agora antes de escrever uma linha de auth.
  4. OperaçãoO Stripe já quebrou meu build cinco vezes e eu já deixo isso na agendaSubir a versão da API do Stripe não é um incidente. É manutenção recorrente, com danos colaterais bem previsíveis, e convém orçá-la.
  5. ProdutoCréditos, saldo, limites de gastoEm cinco produtos montei a cobrança por uso do mesmo jeito: começo com créditos, acabo com saldo em centavos e limites por chave. Já sei em que etapa começar.
  6. Bancos de dadosPor que tirei o RLS do Postgres nas duas vezes em que o useiRow Level Security parece a prática correta por padrão. Com Drizzle, server actions e auth própria, a lógica de permissões já vive em outro lugar e manter as duas dói.
  7. CritérioNunca começo do zero: o que sempre levo e o que sempre cortoDez projetos sobre o mesmo boilerplate. O primeiro commit de cada um se parece mais com o último do anterior do que com um projeto novo, e o segundo commit quase sempre apaga algo.
  8. CritérioA primeira coisa que tiro de qualquer template é o StripeComeço quase todos os projetos apagando o checkout, o portal e o webhook. Não é descuido: é separar a infraestrutura de que sempre vou precisar daquela que ainda não é hora.
  9. ArquiteturaO mesmo bug de concorrência já apareceu em três projetos diferentesUm contador que soma sob carga perde incrementos, e um que subtrai pode cobrar duas vezes a mesma coisa. Quando o contador é dinheiro, isso não é um detalhe para consertar depois.
  10. IACada modelo novo quebra algo diferenteSeis migrações de modelo em um ano e meio. Nenhuma foi trocar uma string, embora todas começassem parecendo isso.
  11. Bancos de dadosReescrevi o mesmo modelo de contratos mais de dez vezesUm modelo de domínio complicado não sai certo de primeira. Converge-se até ele reescrevendo com os dados reais na frente, e isso inclui reverter decisões que pareciam corretas.
  12. Bancos de dadosMeus primeiros esquemas de dados quase nunca sobrevivem ao primeiro mêsO esquema do dia 1 é uma hipótese sobre um domínio que você ainda não entende. Assumir isso muda como você o escreve e quanto dói mudá-lo.
  13. SegurançaPor que faço os acessos de convidado com token de sessão e não com códigosUm código de seis dígitos parece a forma simples de deixar alguém entrar sem conta. É, até você ter que revogá-lo, e então descobre que não sabe quem está expulsando.
  14. OperaçãoPor que "funciona na minha máquina" já não me diz nadaAs diferenças entre a sua máquina e produção não são azar: são quatro categorias concretas que falham sempre e que o build verde não consegue enxergar.
  15. EngenhariaO teste que dizia verde e mentiaSeis SCRIPT ERROR dentro de um teste que imprimia TODOS LOS TESTS OK e saía com código 0. Como se descobre que um verde é falso e o que faço agora antes de confiar em um.
  16. DesempenhoAs listagens de admin são a primeira coisa que caiO painel interno é escrito sem limites porque no começo há quatro linhas. É justamente o lugar onde tudo explode quando o produto cresce.
  17. SegurançaO que aprendi auditando meu próprio código como se fosse de outra pessoaUma ACL vazia que devolvia o corpus inteiro, uma injeção de CSS sem uma linha de JavaScript e uma API key que continuava valendo depois de cancelar a conta do dono. Tudo num dia, tudo em código que eu tinha escrito.
  18. ArquiteturaPor que exijo login em apps que não precisam dissoSem identidade não há cota, nem limite de gasto, nem forma de cortar quem abusa. O atrito do cadastro é barato perto do que custa não ter.
  19. CritérioO que sempre acaba acontecendo quando começo algo na mãoConstruí editores na mão quatro vezes. Três acabaram reescritos com uma biblioteca. A quarta não chegou a dois dias.
  20. FrontendQuando um store global conquista seu lugarO estado global não se justifica por comodidade. Justifica-se quando um componente intermediário recebe props que não usa, só para passá-las adiante.
  21. CritérioCinco migrações de ESLint para Biome: a decisão já está tomadaQuando você faz a mesma migração em cinco projetos sem parar para pensar, aquilo deixa de ser preferência e vira critério. O que quebra pelo caminho e o que se perde.
  22. CritérioDocumentar antes de programar: minha regra para integrações que não controloNuma integração com uma API alheia, os quatro primeiros commits não tocam em código. Escrever o documento antes obriga a medir os limites que depois explodem em produção.