Lições que impedem o Claude de repetir um erro

Exemplo

Uma consulta falha por causa de uma permissão expirada, e o painel mostra “0 vendas” para a região. Ninguém questiona: um zero parece um dado.

O que fazer

Se a leitura falhar, mostre o erro no próprio cartão, e não uma lacuna nem um zero. E um contador que diz “0 problemas” só é confiável se antes encontrou um problema que você plantou de propósito.

Exemplo

“Data” pode ser a data do evento, a data de carga ou a data da partição. Ou “o chefe”: o chefe atual da pessoa, ou o chefe que ela tinha na época em que aconteceu o que você está medindo.

Outro exemplo

Uma tabela de campanhas tinha o gasto da empresa inteira, mas a receita vinha de uma amostra de uma compra em cada cem. As duas colunas estavam rotuladas como “reais”, e o retorno saiu negativo para todas as campanhas.

O que fazer

Dê um nome diferente para cada variante no código e na tela, mesmo que fique feio. E antes de dividir ou subtrair dois números de fontes diferentes, anote de onde vem cada um: se um resultado sai igual em todos os casos (todos perdem, todos ganham), suspeite da escala antes do negócio.

Exemplo

A curva de vendas “cai” no último ponto, que é o mês que só está na metade.

O que fazer

Corte os indicadores no último período fechado, ou marque na tela o período parcial. E mantenha os dois relógios separados: números de grupo usam meses fechados; pessoas nomeadas usam o dia atual.

Exemplo

O sistema guarda apenas o chefe atual de cada pessoa. Para quem já saiu, esse chefe fica congelado, então “rotatividade da equipe de cada chefe” acaba medindo “esta equipe não existe mais”.

O que fazer

Pergunte à origem se os dados são uma foto do momento ou um histórico antes de usá-los para olhar para trás.

Exemplo

Um modelo de repente fica muito melhor. Descobre-se que uma variável vale 1 para todos que saíram e 0 para todos que ficaram, porque a origem preenche cada grupo de um jeito. Outra variante: o modelo aprende em que ano algo aconteceu, e não com quem aconteceu.

O que fazer

Teste para frente: treine com o passado e avalie num período posterior. E antes de ajustar por algo, pergunte se esse algo é o que decide o resultado que você quer prever.

Exemplo

Um validador tinha a contagem de itens de referência digitada à mão como 43. Quando o documento cresceu para 47, ele rejeitou os quatro novos como inexistentes. Agora conta os itens do próprio documento.

O que fazer

Coloque a definição num único ponto por onde passa toda consulta, e faça todas lerem dali. Um número digitado à mão que copia um valor de outro lugar também é uma definição repetida.

Não confundir com

Repetir uma explicação de propósito, em material didático, não é copiar uma definição. O que não se deve copiar é a regra que calcula o valor.

Exemplo

Uma tela montava seus controles a partir da lista de variáveis que o modelo iria usar. O treinamento descartou uma delas, e durante dias houve um controle que não fazia nada.

O que fazer

Derive a partir do resultado publicado. E o que não puder ser derivado deve falhar em voz alta, em vez de sumir em silêncio.

Exemplo

Os rótulos de três telas foram atualizados depois que um modelo mudou. A quarta, que ninguém lembrou, continuou oferecendo opções do modelo anterior.

Outro exemplo

Ao escrever um capítulo, afirmou-se de memória que o leitor já conhecia três funções de um capítulo anterior. Uma busca mostrou que o capítulo ensinava só uma, e que outro capítulo já tinha explicado o tema apresentado como novo.

Mais um exemplo

Uma mudança foi salva com a lista de arquivos escrita de memória, e um ficou de fora: justamente o que fazia a coisa nova funcionar. A lista de mudanças pendentes, revisada depois, mostrou isso.

O que fazer

Mantenha um mapa escrito de impactos por tipo de mudança. Percorra-o inteiro, dizendo “muda” ou “não se aplica porque…”, e se a mudança cria um novo consumidor, adicione-o na mesma mudança. Antes de citar uma fonte, copie a frase que você está afirmando dela: o que alguém diz que outra pessoa fez ou viu também precisa ser conferido.

Exemplo

Uma pendência foi marcada como fechada na lista, mas o teste que a vigiava ainda estava marcado como “esperado que falhe”, e o documento ainda a descrevia como aberta. Três lugares, três versões.

O que fazer

A unidade de trabalho é o conjunto completo, na mesma mudança.

Exemplo

A versão de desktop ganhou um filtro de data. A versão para celular, que as pessoas veem como “a mesma tela”, ficou sem ele por um mês.

O que fazer

Não feche a mudança antes de conferir o gêmeo e escrever “igual” ou “não se aplica porque…”.

Exemplo

Um gráfico não confiável foi retirado, mas um cartão de “principais conclusões” e um plano de ação ainda recomendavam o que o gráfico dizia.

Outro exemplo

Um plano de capítulos foi renumerado do 7 para o 15. Duas listas em outro documento ainda apontavam para “7.4” e “7.7” do plano antigo, que agora eram outros temas. Quando você substitui um plano, os números antigos também são afirmações.

O que fazer

Busque por assunto, não por identificador. Ecos não têm nome de variável.

Exemplo

Uma questão de múltipla escolha afirmava que comparar um número com um texto entre aspas gera erro. Em alguns outros motores gera; no que as pessoas de fato usavam, a consulta rodou e devolveu linhas.

Outro exemplo

Um texto explicava corretamente que um bloco nomeado só vive dentro da própria consulta, mas o próprio exemplo supunha que três consultas separadas o compartilhavam. Ao rodar, a segunda consulta gerou erro: a tabela não existia.

Mais um exemplo

Todos os exemplos de uma página foram executados, e ainda assim três frases se revelaram falsas: a explicação de uma opção, escrita no fim, descrevia o que uma linha faz sem que ninguém tivesse executado; uma regra para ler erros (“se disser isto, então falta aquilo”) era contradita por outro passo da mesma página; e a introdução dizia que uma função “devolve um resultado” quando não devolve.

O que fazer

Reconcilie com um número conhecido, com o sistema de origem ou com o período anterior. Teste no ambiente real: com as suas permissões, as suas bibliotecas e a cópia do código que de fato roda. Toda afirmação sobre como o sistema se comporta é executada uma vez antes de ser escrita, inclusive a que aparece de passagem num exemplo ou é escrita por último. Se a afirmação é uma regra geral (“só”, “sempre”, “nunca”), encontre o caso que a quebraria e execute também: “converter para inteiro só lê inteiros” foi checado com um texto que tinha decimais, e se revelou falso para um número com decimais. Ao afirmar uma fração (“cinco em seis”), diga de qual todo ela é fração; e um cenário inventado também é checado: o tamanho, a diferença e o valor-p precisam ser coerentes entre si.

Exemplo

Um teste que proibia uma palavra só procurava a versão em minúsculas; com letra maiúscula ou acento, passava.

Outro exemplo

Foram semeados 37 registros duplicados para um exercício, e a contagem voltou 92: os dados já tinham correspondências naturais. Uma verificação que comparava a contagem com o que foi semeado, antes de salvar, pegou isso.

Mais um exemplo

Uma regra que detectava código indentado sinalizou uma linha que começava com um texto: o caso que deveria passar não tinha essa forma. E um teste de que a comparação de texto funcionava passou mesmo com a comparação quebrada, porque outra revisão rejeitou o erro antes.

O que fazer

Calibre com dois casos: um em que ele precisa encontrar algo e outro em que não pode encontrar nada, e rode de verdade no dia em que nasce. O caso bom importa tanto quanto o ruim: um verificador que rejeita o que está correto também está quebrado, e isso é mais difícil de notar porque parece rigoroso. O caso bom inclui as formas reais do que está certo, inclusive as que você não escreveu: outra ordem, outro nome. Cada verificação se calibra sozinha: se outra pega o erro antes, a sua nunca foi testada. E uma revisão que repete o que já leu não consegue falhar (uma “segunda passada” que relê o mesmo arquivo): substitua por uma reconciliação que falha se algo estiver errado.

Exemplo

Procuravam um problema de acento enviando consultas com acento pela mesma rota que os estava danificando.

O que fazer

Monte o teste numa forma que o dano não consiga tocar.

Exemplo

Um teste localizava uma tabela pelo título e, se não a encontrava, pulava. O título mudou, e o teste passou por semanas sem verificar nada.

Variante

Uma verificação que cai no primeiro arquivo quebrado deixa sem vigilância todos os arquivos seguintes. Um validador que quebra, em vez de informar “esta página não pode ser lida, linha 12”, desliga a revisão inteira.

O que fazer

Se o que falta é uma ferramenta, pular é honesto. Se o que falta é o dado que está sendo vigiado, o teste precisa falhar. E um arquivo que não pode ser lido é um achado com a sua linha, não o fim da revisão.

Exemplo

Um auditor de design revisava só elementos sem filhos. Os rótulos que precisavam de revisão tinham um ícone de ajuda dentro, então ele nunca os viu.

Outro exemplo

Um teste percorria todas as páginas marcando sempre a primeira opção e executando cada consulta conforme aparecia. Sempre passava, e nunca verificava se a resposta correta era aceita.

Mais um exemplo

Para decidir se alguém alterou um texto, os espaços eram ignorados. Isso deixava de fora exatamente o caso da página que explicava como dispor aquele texto com espaços e quebras de linha. Normalizar também é filtrar.

O que fazer

Anote o que o filtro deixa de fora e confira à mão uma amostra dos itens excluídos. E quando descobrir que um filtro te deixou cego, procure os outros filtros parecidos que você já escreveu: uma revisão que tirava todos os espaços do código juntava duas palavras numa só e rejeitava código correto, logo depois de a mesma lição ter sido aprendida com outra normalização.

Exemplo

Uma página passou na verificação de sintaxe e na de tipos. Ao ser aberta, ficou em branco: usava uma variável que só existe no servidor.

O que fazer

Tenha pelo menos um teste que rode a página ou o programa completo.

Exemplo

Verificou-se que cada resultado publicado estava correto, mas uma versão gerada a partir deles chegou à tela, e usava outra regra para dados ausentes.

Outro exemplo

Um revisor leu o arquivo-fonte de cada página e aprovou. Uma tabela que se empilhava em cartões no celular, e deixava de poder ser comparada, só apareceu quando a página foi vista.

O que fazer

Verifique no ponto em que chega à pessoa: a página como é vista, o arquivo que ela baixa, a mensagem que ela recebe (ver também a lição 41).

Exemplo

O design de duas telas foi feito para bater ao longo de quatro rodadas: primeiro o tamanho, depois a tipografia, depois as cores, depois a cor do rótulo. Cada entrega dizia “está pronto”.

Outro exemplo

As ilustrações de um material foram revisadas quanto ao conteúdo e ao tamanho, mas não quanto ao contraste: duas cores de texto ficaram abaixo do mínimo legível em quatro imagens.

O que fazer

Liste todas as diferenças antes de corrigir a primeira. E nas suas anotações, o verbo denuncia: “está corrigido” e “vai ficar” são intenções; “diz” e “mostra” são medições.

Exemplo

Uma legenda com as faixas de uma classificação foi inserida uma vez. As faixas mudaram, e a legenda continuou mostrando as antigas.

O que fazer

Substitua: remova a versão antiga, injete de novo e confira que sobrou só uma cópia.

Exemplo

Um ícone de ajuda foi adicionado ao lado de vários títulos, e as atualizações que se localizavam pelos títulos pararam de funcionar.

Outro exemplo

Uma revisão procurava o texto “int(” para ver se alguém converteu um número, e ele casava dentro de “print(”: qualquer linha que imprimisse algo parecia passar. O que você procura tem que ser uma palavra inteira, e não um pedaço de outra.

Mais um exemplo

Uma revisão tomava a última linha impressa pelo código como resposta. Com uma função que imprime o número lá dentro e não o devolve, aquela linha existia por outro motivo: a resposta aparecia na tela, mesmo que o código nunca a entregasse.

O que fazer

Use marcas próprias, como um ID ou um comentário de seção. E quando uma mudança toca muitos blocos de uma vez, confira todos, e não só o primeiro.

Exemplo

Para verificar que um script não mudou nada na segunda execução, comparou-se o checksum da mesma execução duas vezes, e depois dois checksums tirados de listas de arquivos diferentes. As duas comparações diziam “igual” ou “diferente” sem provar nada. A comparação que funciona tira o checksum, roda o script e tira o checksum de novo, dos mesmos arquivos e num único comando.

O que fazer

Rode duas vezes a partir do mesmo ponto de partida e compare os arquivos: a segunda execução não pode mudar nada.

Exemplo

Um script inseriu uma célula de título antes da célula 9 de um notebook, e depois editou a “célula 9”: editou justamente a célula que tinha acabado de inserir.

O que fazer

Localize o ponto de novo depois de cada inserção, e confira o resultado revisando a estrutura completa.

Exemplo

Um script abriu o arquivo de configuração para reescrevê-lo, falhou ao calcular um dos valores e deixou o arquivo vazio. O servidor nunca mais subiu.

O que fazer

Prepare tudo na memória, escreva num arquivo temporário e, no fim, substitua o original num único passo.

Exemplo

Uma tarefa agendada aparecia como “ativa”, mas não rodava havia dois meses por causa de uma credencial expirada. O painel mostrava o último dado como se fosse de hoje.

O que fazer

Mostre na tela quando os dados foram atualizados pela última vez. Confira quais períodos estão faltando. E faça os processos poderem ser rodados de novo sem duplicar linhas.

Exemplo

Um relatório publicado continuava filtrando por uma coluna que a origem tinha parado de preencher. Mostrava zero, e como estava “já validado”, ninguém perguntou de novo.

O que fazer

Submeta o que já está em uso aos mesmos testes do candidato novo, em toda revisão.

Exemplo

Uma tabela “perdeu metade das colunas”. Alguns minutos depois estava completa: você a olhava enquanto outro processo a reconstruía.

Outro exemplo

Uma imagem nova “não carregava” na página. O arquivo estava bem: o servidor de teste não enxergava pastas criadas depois que ele tinha subido.

Mais um exemplo

Um script “calculava errado um padrão de texto”. O script estava bem: o console pelo qual o código era passado transformava cada \n numa quebra de linha de verdade antes de o script lê-lo. E num notebook em que as células compartilham memória, um erro que deveria aparecer não apareceu: a variável ainda estava guardada de uma célula anterior.

O que fazer

Tire uma segunda foto alguns minutos depois, antes de declarar um desastre. Se um instrumento já te enganou do mesmo jeito, troque-o em vez de continuar olhando por ele: um erro repetido não é azar, é a ferramenta errada. Um console que transforma \n ou \\ pelo caminho não serve para passar código a ele: o código vai num arquivo, escrito com uma ferramenta que não o toca, e roda a partir dali. E qualquer coisa mecânica (um comando que já falhou três vezes) é bloqueada por uma proteção, e não lembrada.

Exemplo

Quem escreveu cada página também tirou as capturas de tela da revisão, e só das etapas que achava arriscadas. O revisor leu o arquivo-fonte. As etapas sem captura não foram vistas por ninguém.

O que fazer

Um roda e o outro verifica lendo o resultado. “Eu já fiz” é o sinal de que agora pode ser verificado, não a verificação. E quem verifica não olha pelo mesmo canal que quem fez (ver a lição 14): se os dois leem só a fonte, nenhum dos dois vê a tela.

Exemplo

Um comando de deploy tinha um nome de branch digitado de memória. A branch tinha outro nome, e quem rodou perdeu meia hora antes de perguntar.

O que fazer

Rode você mesmo antes de passar adiante, e copie cada nome (script, caminho, branch) do sistema, não da memória.

Exemplo

A estrutura de pastas de um projeto inteiro foi reorganizada sem aviso. A mudança estava correta em si, e foi desfeita por completo, porque outra pessoa já tinha decidido aquela estrutura por motivos que não estavam no código.

O que fazer

Antes de cada bloco grande de trabalho, explique em linguagem simples o que vai fazer e por quê, e espere a confirmação.

Exemplo

Uma tela de vendas mostrava, na primeira linha, o ID interno de cada pedido e a hora do último cálculo. Ninguém decidia nada com aquilo, e ocupava o espaço dos dados que importavam.

O que fazer

Antes de pôr algo na tela, anote qual decisão isso muda. Se não muda nenhuma, vai para o registro técnico ou para o código, e não para a tela.

Exemplo

Um filtro filtrava uma tabela, mas a tabela ficava duas telas abaixo. Foi relatado como “não faz nada”.

Variante

Esconder um contêiner esconde tudo o que está dentro dele, mesmo o que não tinha nada a ver com ele. Por exemplo, um link útil que morava dentro de um controle aposentado.

O que fazer

Cada controle diz o que mudou e leva o usuário até lá. E antes de esconder algo, confira o que mais vive dentro dele.

Exemplo

Duas pessoas diferentes leram 98 ÷ 441 como 98 + 441 num cartão em letra pequena, e as duas disseram que a conta estava errada.

Outro exemplo

A fonte de código de um material juntava >= num símbolo só, ⩾. Quem está aprendendo copia o que vê, e esse símbolo não existe no teclado nem no idioma.

O que fazer

Quando um símbolo se presta a confusão, troque-o por uma palavra: “98 sobre 441” em vez de “98 ÷ 441”.

Exemplo

Um relatório pedia para corrigir um gráfico que somava errado, mas esse gráfico não existia na tela: os dados passavam sem nada que os desenhasse.

O que fazer

Meça antes e depois da correção. Uma correção que melhora só em parte o sintoma ainda não está fechada.

Exemplo

Uma nota dizia “remover o filtro de data”. Quando finalmente foi trabalhada, o filtro já era uma decisão escrita da equipe, e removê-lo quebrou um relatório.

O que fazer

Antes de trabalhar numa pendência, verifique-a hoje e procure uma decisão escrita dizendo que ela foi deixada assim de propósito.

Exemplo

Uma explicação dizia que um bug fazia perder “quase um em cada cinco” chamados. Medido, eram mais de um em cada cinco: a frase veio de conta de cabeça, e não dos dados.

Outro exemplo

Um texto dizia que um grupo de coortes “estava acima de 50 %”; cinco das doze estavam abaixo. Em outro, a ilustração mostrava um cálculo feito à mão que não batia: a porcentagem vezes o total não dava o número desenhado.

O que fazer

Antes de escrever um número, meça de novo e anote ao lado de que dados e de que data ele veio. Palavras de quantidade (“quase”, “mais de”, “a maioria”) são números disfarçados: meça-as do mesmo jeito. E se uma imagem tem contas dentro, faça o mesmo script que a desenha fazer a conta.

Exemplo

Um manual dizia que os dados sincronizavam sozinhos. O sistema só sincronizava quando o app era aberto. A revisão “corrigiu” o manual para prometer que logo seria automático, em vez de declarar o limite como ele era.

O que fazer

Separe os achados sobre o documento (“está mal escrito”) dos achados sobre o sistema (“funciona diferente do ideal”). O segundo tipo é declarado como limitação.

Exemplo

Um procedimento tinha um tempo de resposta de 24 horas que ninguém tinha combinado. Foi escrito porque soava razoável, e depois de publicado virou um compromisso.

O que fazer

Marque o que falta de forma visível, como “Pendente” em vermelho, e pergunte a quem sabe. Redação neutra é melhor que redação falsa.

Não confundir com

A marca serve para quem decide, não para o leitor final. Um “aguardando confirmação” dentro de um texto publicado é mais um dado que não deveria estar lá. Se o documento sair antes de ser confirmado, use uma redação neutra que não afirme o que falta, e deixe o item pendente no relatório ou no registro do projeto.

Exemplo

Duas cópias de um manual circulavam por e-mail. A antiga dizia que a ferramenta “abre com um duplo clique”, o que já não era verdade, e ninguém conseguia saber qual das duas era a boa.

O que fazer

Atualize o número da versão e escreva a linha do histórico na mesma mudança que altera o documento.

Exemplo

Um histórico dizia “A foi tentado e falhou; B foi tentado e falhou; C ficou”. Quem lesse meses depois só precisava de C e do motivo, e tinha de ler três parágrafos para achá-lo.

O que fazer

Escreva o estado final e o motivo. O que foi tentado e falhou só entra se ensina algo que alguém precisa para não repetir.

Exemplo

Três passos numerados saíram como marcadores vazios. A verificação automática passou porque aquelas palavras apareciam em outro lugar do documento.

Outro exemplo

Um aviso de “há mais colunas à direita” foi adicionado e dado como pronto porque o código estava lá. Ele nunca apareceu: um estilo geral de tabela removeu a condição que o ativava. Outra pessoa viu numa captura de tela.

Mais um exemplo

Uma opção de resposta dizia “Total: {2 * 78}” no arquivo. Quando a página foi desenhada, o sistema calculou o que estava entre as chaves e mostrou “Total: 156”: duas opções idênticas. Só quem olhou a tela viu.

Variante

As capturas de tela que um revisor julga podem mostrar uma tela que ninguém alcança. A ferramenta de captura de um curso respondia cada exercício de código com uma linha de preenchimento só para seguir em frente, então a captura “depois” mostrava essa linha e a mensagem “resultado não esperado”: os revisores nunca viram o que o estudante vê ao acertar. No desktop, as capturas também pegavam o cabeçalho e o menu lateral, e a lição saía como uma faixa ilegível. Ao capturar para revisão, responda cada passo como um usuário bem-sucedido responderia, e capture apenas a parte em revisão.

O que fazer

Confira o elemento exato, como “estes três passos, como marcadores”, e veja a página como o leitor vai vê-la pelo menos uma vez. Uma correção pequena também é conferida: é onde outra regra menos se espera que a sobrescreva. E na primeira vez que usar um recurso novo na página (um bloco de código, um cabeçalho fixo), veja também no celular.

Exemplo

Uma reorganização do manual foi feita sobre uma versão de semanas antes. Ela voltou a dizer que a ferramenta “abre com um duplo clique”, o que já não era verdade.

O que fazer

Pegue a estrutura que a revisão propõe e despeje nela o conteúdo mais recente, e não o contrário.

Exemplo

Uma seção dizia que nada era salvo sem conexão. O FAQ ainda dizia que tudo o que é capturado fica guardado no aparelho.

O que fazer

Ao terminar cada rodada, busque por assunto tudo o que o documento diz sobre o que você corrigiu.

Exemplo

Uma página foi marcada como revisada porque o teste dela “terminou sem erros”. O resultado passou por um comando que mostrava só o fim, e o aviso de que o teste tinha falhado se perdeu no caminho.

Outro exemplo

Uma suíte de testes repetia automaticamente cada teste que falhava. Os testes que passavam na segunda tentativa não contavam como falhas, só como “instáveis”, e a causa ficava escondida: cada mudança de etapa pedia ao servidor a página de novo. Sem as novas tentativas, a falha aparecia e podia ser medida.

O que fazer

Encontre a linha do veredito antes de mudar um status. Se você encadeia comandos, garanta que a falha do primeiro chegue até o fim. Se a saída não tem veredito, isso significa “não sei”, e não “passou” (ver a lição 1). E salve a saída completa num arquivo e procure o veredito ali: assim você não precisa decidir de antemão quanto ler.

Exemplo

Uma célula de consulta contava uma tentativa só quando a consulta rodava. Com um erro de digitação, o botão para avançar nunca era ativado, e a pessoa ficava presa. Os testes passavam, porque sempre rodavam a consulta inicial, que não tinha erros.

O que fazer

Para cada controle, teste três caminhos: o bom, o erro mais comum e o vazio. Os três dizem o que aconteceu e deixam o usuário continuar.

Exemplo

Toda página de um site lia e processava todo o conteúdo para montar o sumário. Sozinha, uma página levava 0.4 s. Mas a barra lateral pedia cerca de 40 de uma vez, e juntas levavam 16 s. Meses depois, os testes começaram a falhar ao trocar de página, e a falha parecia um problema do próprio teste.

O que fazer

Meça no servidor compilado e no jeito como as pessoas o usam, com todas as requisições juntas, e não uma página isolada. Guarde em cache o que não muda enquanto o servidor roda, e deixe um teste que meça isso com o caso que de fato deixou tudo lento.

Exemplo

Quatro pessoas escreviam cada uma uma peça ao mesmo tempo e deixavam as partes compartilhadas como entrega. Na integração, duas entregas usaram um nome que já existia no teste compartilhado, e o teste parou de rodar. Outro teste guardava uma cópia do que verificava; a peça mudou e a cópia não. Uma rodada de testes falhou por causa de uma imagem que outra pessoa ainda estava desenhando. E no fim, cada peça não podia ser salva separadamente: os arquivos compartilhados já carregavam mudanças de todos.

O que fazer

Tenha uma pessoa integrando o que é compartilhado, com uma etapa que pare se um nome colidir. Faça os testes lerem o original, e não uma cópia. Rode a suíte de testes completa uma vez, quando todos terminarem, ou sem as peças que ainda estão mudando, e diga quais ficaram de fora. E salve juntas as peças que compartilham arquivos, para que cada versão salva funcione por inteiro.

Exemplo

Uma nota foi montada a partir das seções que cada pessoa entregou. Três linhas foram corrigidas direto na nota, e quando ela foi reconstruída a partir das entregas, as três linhas antigas voltaram. Em outra peça, um revisor corrigiu à mão o texto alternativo de uma página que vinha de um template; o autor regenerou a página, e a correção desapareceu.

O que fazer

Antes de corrigir um arquivo, descubra de onde ele vem. Corrija a fonte (o template, o script, a entrega) e regenere; se for preciso corrigir a saída, corrija a fonte também no mesmo passo. Quem revisa uma saída gerada diz o que mudou para que a mudança seja levada para a fonte. E antes de reconstruir um arquivo a partir das suas fontes, compare-o com o que vai sair: tudo o que for diferente é uma correção que se perderia.

Exemplo

O estilo de foco do teclado, escrito para o site inteiro, vinha com seu próprio raio de borda. Como ficava acima dos estilos de cada componente, um botão em formato de pílula mudava de forma ao receber foco pelo teclado. Ninguém notou, porque com o mouse o foco não aparece.

O que fazer

Deixe a regra geral mexer só no que é dela (o contorno do foco, e não a forma). Se ela deve vencer de propósito, escreva isso ao lado. E teste na peça mais diferente, e não só na comum.

Exemplo

Uma lição comparou subir em cinco pontos o primeiro passo de um funil com subir o último. O primeiro venceu, e o texto dizia: “eles valem mais onde há mais visitas”. Mas o primeiro passo também era o que menos convertia, e essa era a causa: em um funil em que o primeiro passo converte melhor, o último vence apesar de ter menos visitas. Em outro projeto, uma página foi culpada por carregar em 2.7 s; um teste que requisitava as páginas uma por uma passava mesmo sem a correção, porque a causa real eram quarenta requisições ao mesmo tempo.

O que fazer

Antes de ensinar ou reportar por que algo acontece, escreva a explicação rival e monte um caso em que as duas prevejam coisas diferentes. Compare partes de mesmo tamanho, teste outro tamanho de exemplo e meça uma afirmação geral em dados simulados antes de escrevê-la. Se você não consegue separá-las, diga que o exemplo é compatível com as duas.

Exemplo

Um curso de programação para iniciantes abriu com uma célula que tinha seis coisas novas ao mesmo tempo, e o plano nunca ensinava o que é um tipo de dado nem que o = guarda e lê da direita para a esquerda. O responsável pelo curso resumiu em uma frase: “você presume muito sobre os estudantes”. Depois, três lições diziam “como arrastar uma fórmula”; nenhuma tinha ensinado a arrastar, só “copiar a fórmula para baixo”.

O que fazer

Antes de escrever, liste o que o seu exemplo dá por certo (símbolos, palavras, cliques, coisas que o estudante já deveria ter construído) e ensine essas coisas primeiro: uma ideia nova por vez, cada símbolo explicado na primeira vez em que aparece. Procure cada palavra igual ao nome de um botão, e cada ação que você pede, do mesmo jeito que procura um símbolo. Se possível, deixe uma verificação automática comparar o que cada exemplo usa com o que já foi ensinado.

Exemplo

Um plano para um módulo de “análise com IA” começou com “a IA não consegue ver seus dados, então descreva sua tabela em vez de colá-la”. O responsável pelo curso observou que agentes agora se conectam ao banco de dados, executam as consultas sozinhos e devolvem o número. Uma pesquisa com fontes e datas confirmou: copiar código de um chat era a forma de fazer dois anos antes. Várias lições foram reescritas em torno do que ainda vale: definir a pergunta, supervisionar o agente e conferir o número.

O que fazer

Antes de escrever sobre uma ferramenta que muda rápido, pesquise a prática atual com fontes e datas: o que a ferramenta faz agora, o que é gratuito, o que as pessoas de fato usam. Construa o texto em torno da habilidade que sobrevive à próxima versão (enquadrar, supervisionar, verificar) e mantenha os passos específicos da ferramenta em um só lugar, que possa ser atualizado. Marque o que você não conseguiu verificar e teste à mão antes de publicar.

Exemplo

Duas edições numa mesma sessão, ambas no Windows PowerShell 5.1. Um ler-substituir-gravar de um script (Get-Content, -replace, Set-Content -Encoding utf8) leu o arquivo na página de código ANSI do sistema e o gravou de volta em UTF-8: cada ✓ e · nele virou ✓ e ·, e a autoverificação do script imprimiu a marca estragada. Depois, uma lista de substituições escrita como `@('old', 'new' + "n" + 'more')` perdeu linhas: no PowerShell a vírgula tem precedência maior que +`, então cada par virou quatro itens e só o primeiro pedaço do texto novo foi gravado.

O que fazer

Mude o código com as ferramentas de editar e gravar do próprio editor. Quando a mudança precisar ser feita por script, escreva o script num arquivo e rode-o com um interpretador que lê e grava UTF-8 e tem literais de string simples (node fix.mjs, python -I fix.py). Depois, olhe o diff: uma mudança que tocou mais linhas do que você queria, ou caracteres que você não tocou, é culpa do shell.

Exemplo

Um exercício pedia a maior compra do verão, usando um filtro de datas. A maior compra de toda a tabela também tinha sido no verão: sem o filtro, o número era o mesmo, e o exercício aceitou. Outro exigia que o código tivesse um =; passou com o resultado digitado à mão, total = 1945. A verificação olhava a letra, não a habilidade.

O que fazer

Resolva cada exercício três vezes: sem mexer, com o erro mais provável, e corretamente. Só a terceira pode passar. Depois, rode a mesma lista de atalhos em todos os exercícios: o número digitado à mão, o código inicial com a resposta acrescentada no fim, o sintoma corrigido à mão em vez da causa, a palavra exigida usada vazia, e uma execução com estado deixado por uma tentativa anterior. Mantenha qualquer margem de tolerância menor que a distância entre a resposta e o erro mais provável, e escreva três formas corretas que um estudante usaria, para que a verificação não rejeite o que está certo.

Exemplo

Uma ilustração com a figura certa ficou acima da prática que pedia essa figura. Uma lição perguntava o que acontece quando você guarda um novo valor em uma variável, em um passo intitulado “Guardar de novo substitui”. Um resumo colocado abaixo do questionário final era lido antes de responder ao questionário. Uma caixa de feedback que aparece depois da primeira tentativa, mesmo quando errada, já dava a direção da resposta.

O que fazer

Procure cada resposta em tudo que é mostrado antes da pergunta, inclusive o que aparece depois de uma primeira tentativa errada, o que o código inicial imprime ao rodar, os arquivos para baixar e o que pode ser contado em um desenho. Escreva por último o título do passo e os objetivos de aprendizagem, e leia-os ao lado do resultado de cada previsão. Uma verificação automática encontra números exatos; aproximações e paráfrases só são encontradas por alguém que leia com a resposta em mente.

Exemplo

Uma questão perguntava o que fazer com um desconto vazio “quando a venda não teve desconto”. A lição tinha ensinado que um campo em branco que é um fato continua em branco, então “deixar como está” era defensável; a resposta esperada, preencher com zero, dependia de algo que o enunciado nunca disse: que o objetivo era a média de todas as vendas. Em outra, “a métrica principal é a proporção que paga o segundo mês” não dizia proporção de quem, e as duas versões empatavam ou davam resultados diferentes, conforme a leitura.

O que fazer

Para cada opção errada, escreva uma linha dizendo por que ela está errada, usando apenas o enunciado e a lição. Se descartá-la exige um fato que não está escrito, acrescente-o ao enunciado: a finalidade do cálculo, a regra do sistema, o denominador de uma proporção, o que se sabe sobre os dados. Em um exercício de classificação, teste cada item contra todas as categorias, e não só contra a sua.

Exemplo

No quiz final de um módulo, a resposta certa era a segunda opção em seis de sete perguntas. Em um curso inteiro, a opção certa era a mais longa em 55 % das perguntas, quando o acaso, com três opções, dá uma em três. Depois que o tamanho foi equilibrado à mão, a opção certa acabou sendo a mais curta em seis de sete perguntas de uma lição, e a do meio em todas as perguntas de três lições seguidas.

O que fazer

Embaralhe as opções na hora de mostrá-las, com uma ordem que não venha de onde a certa foi escrita. Meça a mais longa, a mais curta e a do meio em cada arquivo, e agrupe arquivos pequenos por módulo, para que poucas perguntas não escondam o padrão. Compare a contagem com o que você pediu: uma passagem de balanceamento pode deslocar a pista em vez de eliminá-la.

Exemplo

Uma revisão das 277 práticas verificadas de um curso mudou 82 dicas em 49 arquivos. Algumas davam a linha que resolve (“o segundo é o…”). Algumas ditavam a ordem que separa a solução do erro comum. Em exercícios de “confira com um resultado anterior”, a dica dizia “deve bater com o que você obteve na lição 2.2”: quem lembrasse o número anterior podia digitá-lo sem fazer o passo.

O que fazer

Escreva a dica sobre a causa do erro provável (“as posições começam em 0, não em 1”), e cite apenas o que já foi ensinado. Guarde o “deve bater com o número anterior” para a explicação mostrada depois de responder, onde ensina que dois métodos que dão o mesmo número são uma verificação. Revise as dicas contra o erro mais provável do exercício, e não isoladamente.

Exemplo

Nas duas execuções da primeira simulação Web, o formulário salvava cada mensagem como uma linha JSON, e o painel administrativo pulava qualquer linha que não conseguia ler. Com uma linha cortada no fim do arquivo, a mensagem seguinte recebeu a resposta “Obrigado!”, foi salva e nunca apareceu no painel. Uma das duas versões tinha um comentário que dizia “linha danificada: pulada”.

Outro exemplo

Nas duas execuções da repetição, cada mensagem ficava num único arquivo JSON, gravado num arquivo temporário e depois renomeado, então uma queda no meio da escrita já não atrapalhava. Mas com o arquivo danificado de outra forma (uma edição feita à mão, um disco cheio, uma restauração malfeita), todo visitante novo recebia “Erro interno”, a página administrativa não mostrava nada, e o único sinal era um rastro de erro no console do servidor.

O que fazer

Faça um registro novo não depender dos antigos: acrescente a um arquivo que termina com quebra de linha (comece o registro com uma, se ele não terminar), ou salve cada registro num arquivo próprio, em vez de reescrever um arquivo que contém todos. Na leitura, conte o que não pôde ser lido e mostre essa contagem onde o dono vai vê-la. Teste danificando o armazenamento à mão (corte a última linha, trunque o arquivo) e depois envie um registro.

Exemplo

Nas duas execuções da simulação Web, o formulário de contato aceitou 650 mensagens de um script em poucos segundos, todas dizendo “obrigado”. O administrador não tinha páginas nem botão de apagar: a página de administração cresceu entre um e seis milhões de pixels de altura, e no celular o texto da mensagem saía da tela. Nas duas vezes, quem construiu anotou como pendência.

O que fazer

Desde o início, um freio barato: um campo oculto que as pessoas não preenchem, e um limite de envios por endereço por minuto. E um administrador com páginas, as mais recentes primeiro, e uma forma de apagar ou marcar como lixo. Teste enviando centenas de mensagens com um script e abrindo a administração no celular.

Exemplo

Nas duas execuções da simulação Web, o formulário enviava com JavaScript e declarava method="post". Sem JavaScript, numa versão o servidor rejeitava o envio com uma linha de JSON e a mensagem se perdia; na outra salvava a mensagem e mostrava só {"ok":true} numa página em branco. O resumo desta segunda versão dizia que ela não enviaria sem JavaScript.

O que fazer

Decida por uma de duas opções e teste: ou o servidor aceita o envio normal e responde com uma página (ou redireciona para uma página de agradecimento), ou o formulário não declara um fallback que não tem. Envie uma vez com JavaScript desligado.

Exemplo

Nas duas execuções da simulação Web, o envio desabilitava o botão. Com um e-mail que o servidor rejeitou, o aviso apareceu abaixo do botão, o foco caiu no documento, e o próximo Tab levou o usuário ao primeiro link da página, longe do campo que precisava de correção.

O que fazer

Quando o envio terminar, coloque o foco onde a pessoa precisa continuar: no campo com erro (marcado com aria-invalid e a mensagem ao lado) ou no aviso de sucesso. Ou evite o duplo envio sem desabilitar, usando aria-disabled e uma flag. Percorra o erro usando só o teclado.

Exemplo

Nas duas execuções da repetição da simulação Web, a página administrativa pedia uma senha e nunca limitava as tentativas erradas: 200 senhas erradas seguidas receberam 200 recusas em menos de um segundo, nenhuma bloqueada. A senha padrão era longa e aleatória, mas o resumo de quem construiu o site explicava ao dono como definir uma nova, e nada exigia que ela fosse longa.

O que fazer

Desacelere ou bloqueie as falhas repetidas, por endereço e por conta, com uma espera que cresce a cada falha. Exija um tamanho mínimo quando o dono definir uma senha. Teste: envie vinte senhas erradas seguidas e confira que as últimas são recusadas.