2

O checklist que eu sigo antes de aceitar código que a IA escreveu

Faz uns meses que quase todo código que eu escrevo passa pela IA antes (Claude Code, Cursor). Ganhei muita velocidade, mas comecei a ver um tipo de bug que antes eu quase não tinha. O código compila, passa no lint, o diff parece ok, e mesmo assim alguma coisa quebra lá na frente, normalmente num lugar que eu nem pedi pra mexer.

Depois de levar umas pancadas, montei um checklist que sigo antes de aceitar qualquer mudança que a IA fez. Compartilho aqui porque talvez ajude alguém.

  1. Ler o diff inteiro. O resumo que a IA escreve no final conta o que ela queria fazer, e nem sempre bate com o que ela fez de fato.

  2. Desconfiar de teste escrito na mesma sessão. Ele costuma testar a implementação nova e não o comportamento que você esperava. E se a IA alterou um teste antigo pra ele passar, eu paro tudo e vou ver o porquê, porque muitas vezes o teste tava certo.

  3. Olhar os arquivos que ela mexeu sem eu pedir. Pedi pra ajustar um formulário e veio alteração no hook de auth? Quero entender antes de aceitar.

  4. Conferir dependência nova. Se o pacote existe mesmo, se é o certo, se a versão faz sentido. Já vi nome de pacote inventado.

  5. Testar fora do caminho feliz. Campo vazio, null, lista sem item, erro de rede. A IA escreve muito pensando no cenário em que tudo dá certo.

  6. Ver quem consome o que mudou. Esse é o que mais me pegou. Exemplo bem comum: a IA refatora a API de cadastro pra ler emailAddress, mas o form continua mandando email. O TypeScript não reclama, os testes unitários passam, e o usuário fica clicando num botão que não faz nada.

  7. Rodar os fluxos principais num navegador de verdade. Cadastro, login, checkout. O que não pode quebrar eu quero ver funcionando do jeito que o usuário usa, sem mock.

Esse último item virou um projeto open source que eu tô mantendo, o stillworks. Você descreve as jornadas como uma lista de passos e cada passo é Playwright normal:

// journeys.config.ts
import { defineConfig } from "stillworks";

export default defineConfig({
  baseURL: "http://localhost:3000",
  journeys: [
    {
      name: "signup",
      steps: [
        { name: "Open the signup page", run: ({ page }) => page.goto("/signup") },
        {
          name: "Fill in email and password",
          run: async ({ page }) => {
            await page.getByLabel("Email").fill(`test+${Date.now()}@example.com`);
            await page.getByLabel("Password").fill("correct-horse-battery-staple");
          },
        },
        { name: "Submit the form", run: ({ page }) => page.getByRole("button", { name: "Create account" }).click() },
        { name: "See the welcome screen", run: ({ page }) => page.getByText("Welcome").waitFor() },
      ],
    },
  ],
});

E pra rodar:

npx stillworks init
npx stillworks run --url http://localhost:3000

Quando alguma jornada quebra ele gera um REPORT.md com o passo que falhou, os erros do console, as requests que deram erro (com a resposta do servidor) e um print da tela. A ideia é você colar isso direto no Claude Code ou no Cursor. No caso do emailAddress ali de cima, o relatório já mostra o POST /api/signup voltando 500 com o TypeError, então o agente vai direto no ponto.

Tem integração pronta com Claude Code (--claude, que cria um comando /verify), Cursor (--cursor) e GitHub Actions rodando nos previews da Vercel (--github).

  1. Prestar atenção redobrada em segurança. Já peguei validação no servidor removida "pra simplificar", segredo hardcoded e query montada com concatenação de string.

  2. Pedir mudanças pequenas. Diff de 40 linhas eu revejo de verdade. Diff de 600 eu confesso que só passo o olho.

É isso. Vocês fazem algo diferente? Já tiveram bug em produção que veio de código da IA e passou batido pelos testes? Curioso pra saber o que adicionariam.

O repo tá aqui pra quem quiser testar ou contribuir: https://github.com/valmirjunior2109-spec/stillworks
Se tiver algum fluxo da sua stack que você queria ver como template (Next + Supabase, Clerk, Stripe...), abre uma issue lá.

Em paralelo tô construindo a Publishub, que vai ser a versão que roda sozinha em todo PR e compara com a última versão que funcionava. Ainda não tá pronta, mas quem quiser entrar na lista de acesso antecipado (é grátis): https://getpublishub.com/?utm_source=tabnews#early-access

Carregando publicação patrocinada...
1

Sobre o item 2, um teste rápido que eu uso: antes de aceitar, rodo o teste novo contra o código antigo. Se for correção de bug, o teste tem que falhar sem a correção. Na prática é guardar só a mudança do código com git stash push -- src/ (se o teste está fora de src/, ele continua no lugar), rodar a suíte e depois git stash pop. Se o teste passa nos dois casos, ele não está testando a mudança.

No item 4 já tem até nome: slopsquatting. Tem gente registrando no npm e no PyPI justamente os nomes de pacote que os modelos costumam inventar. Além de ver se o pacote existe, eu olho quando ele foi criado (npm view nome-do-pacote time.created) e quantos downloads tem. Pacote de poucas semanas, com poucos downloads e nome parecido com um conhecido, eu não instalo sem ler o código.

1

O ponto crítico é quando o modelo reescreve um teste existente para cobrir um comportamento errado. O TypeScript e o linting validam a sintaxe e a tipagem estática, mas não têm noção da intenção de negócio que o teste antigo protegia. O mecanismo de alucinação aqui é a otimização de recompensa local: o modelo vê o erro de compilação ou o teste falhando e "conserta" o sintoma (o teste) em vez da causa (a lógica), criando um falso positivo de qualidade.

A mutação silenciosa da camada de verificação é o que quebra a pipeline. Se o teste foi reescrito para validar o erro, o diff parece limpo e a pipeline passa, mas a regressão está embutida no próprio artefato de garantia. Para mitigar isso, você prefere manter os testes como "fatos imutáveis" que o modelo só pode ler, ou confia em um segundo modelo de revisão focado apenas em detectar mudanças de comportamento nos testes antigos?

1

Eu faço revisão adverária, usando modelos diferentes para código e revisão. E o modelo para revisão é mais novo/maior/caro... Mas como é só pra revisão, não onera muito. Também tenho uma skill que tem crescido aos poucos.

1

Gostei da ideia de usar modelo diferente pra revisar, faz sentido, já que o mesmo modelo tende a concordar com o que ele mesmo escreveu. E como a revisão gasta bem menos token que a geração, compensa pagar pelo maior.

Essa skill que você comentou é tipo um checklist que o revisor segue? Fiquei curioso pra saber que tipo de coisa você foi adicionando nela com o tempo, se foram erros que já passaram pra produção.

Uma coisa que eu sinto falta só com revisão (mesmo adversária) é quando o código tá certo olhando o diff, mas quebra rodando, tipo aquele caso do emailAddress. Por isso acabei juntando as duas coisas: revisão no código + rodar o fluxo no navegador depois.

1

Ela tem um workflow, com um checklist geral e outros específicos por tipo de projeto. Se algo passa, peço o agente pra revisar a skill e acrescentar a "lição aprendida". É solução caseira, não é algo no nível das skills de Matt Pocock, pstack ou superpowers. Mas acho que é importante fazer algo você mesmo pra aprender mais sobre IA.

1

Faz total sentido. Essa parte de pedir pro agente revisar a skill e acrescentar a “lição aprendida” é o que transforma erro em processo: o mesmo bug não passa duas vezes. Acho até que é aí que a solução caseira ganha das prontas, porque o checklist fica com a cara dos erros do seu projeto, não de um projeto genérico.

E concordo sobre fazer você mesmo. Foi montando o meu fluxo que eu percebi onde a revisão sozinha não alcança.

Curiosidade: os checklists por tipo de projeto você separa como? Tipo frontend / API / mobile, ou por stack? E quando o agente acrescenta uma lição, você revisa antes de entrar na skill ou deixa ele editar direto?