
A regra que o guard cobrava e ninguém tinha escrito
O guard que aprovava tudo
Todo plano de trabalho passa por um guard em Python que não olha mérito: olha procedência. Para cada fonte citada, exige quatro coisas — URL ou caminho, data de acesso, trecho usado e nível de confiança (alta, média ou baixa). Sem isso, a fonte não conta como pesquisa feita, porque o que se perde não é o texto, é a capacidade de refazer o caminho depois.
Rodei o guard contra um plano qualquer: código de saída zero. Silêncio. Aprovado. Repeti em três planos sem nenhum dos quatro campos: os três passaram. Guard que aprova o que deveria reprovar não é rigor, é decoração com saída bonita.
As ferramentas que uso neste projeto ficam na loja de skills — a primeira é grátis.
O que a medição mostrou
Antes de acusar o guard, medi o acervo. No mês de novembro havia 909 planos escritos. O campo de data de acesso aparecia em 4 deles — 0,4%. Uma seção formal de pesquisa ou fontes aparecia em 144 — 15,8%. E 750 planos, ou 82,5%, não tinham nenhum dos três sinais que eu procurava: nem data, nem confiança, nem seção de pesquisa. O recorte mais estreito, feito quando o guard nasceu, era pior: 1 de 500 planos cumpria o mínimo. 0,2%.
A explicação tinha duas camadas. A primeira era estrutural e correta: ele tem um baseline. Na primeira execução grava o instante em que a exigência passou a valer e passa a ignorar tudo que foi escrito antes — regra nova não retroage. Certo na intenção, e desastroso na primeira semana: sem plano posterior ao baseline não há o que medir, e o guard devolve zero. Silêncio por conformidade e por inércia são indistinguíveis.
A segunda camada era o motivo real do 0,2%: a regra não estava escrita em lugar nenhum. O guard cobrava quatro campos que nenhum documento de contrato exigia — ela vivia num commit de branch que nunca foi mergeado. O auditor estava certo, o acervo estava certo, e o único lugar que poderia tornar o hábito exigível não dizia nada. Guard que cobra regra inexistente só produz duas coisas: falso furo, quando mede o passado, ou inércia, quando respeita o baseline.
Como foi resolvido
A correção teve duas frentes, e a primeira não foi código.
Primeiro a regra entrou no contrato, com teto proporcional ao tamanho do plano. A exigência de quatro campos por fonte é razoável num plano de 20 KB e vira formulário num plano de 2 KB. Então o teto passou a ser explícito: plano pequeno registra os campos completos nas duas fontes que sustentam a decisão; plano grande, em todas as fontes que influenciaram o resultado. A pergunta que decide se uma fonte entra é literal: essa fonte mudou alguma coisa no plano? Se li e não mudou nada, ela não entra.
Segundo, o guard passou a usar a mesma régua que a regra:
def minimo_de_campos(bytes_do_plano: int) -> int:
# plano pequeno não é formulário: 3 de 4 campos já provam que houve pesquisa
# plano grande sustenta o rigor completo
return 3 if bytes_do_plano <= 4096 else 4
E o baseline, que era a fonte do silêncio, virou uma função explícita em vez de um comportamento implícito:
def dentro_da_janela(caminho: str, instante_do_baseline: float) -> bool:
return os.path.getmtime(caminho) >= instante_do_baseline
Com isso o guard deixou de misturar duas perguntas: existe plano novo para medir, e o plano novo cumpre a regra. Se não há plano novo, ele diz isso quando chamado com detalhe, em vez de devolver zero mudo. Se há e o plano fura, ele imprime o que falta campo por campo e sai com código 1.
O terceiro ajuste foi sobre a repetição do alerta. A primeira versão guardava a lista de planos já avisados de forma permanente: gritava uma vez e emudecia para sempre, mesmo com todos os furos abertos. Alerta que fala uma única vez não é alerta, é desabafo. Agora o aviso reincide a cada três dias enquanto o furo existir, e o plano sai sozinho da lista quando é corrigido.
O que isso muda
Medi de novo hoje: 48 planos escritos depois do baseline, 7 conformes, 15%. Cinco vezes o 0,2% de antes, e ainda ruim — 85% furam. A diferença é que agora o número existe. Antes havia uma regra bonita num documento que ninguém consultava e um guard que dormia; a aderência real era invisível. Agora a distância entre o que eu digo que faço e o que de fato registro aparece como número, e número que aparece é número que cobra.
A lição de engenharia vale além deste caso. Regra escrita não é regra executada, e a única forma de saber a diferença é medir a aderência antes de escrever mais regra. Se eu tivesse começado pelo guard, sem medir o acervo, teria concluído que o problema era disciplina de quem escreve os planos — e teria escrito um alerta mais agressivo sobre um contrato que não exigia nada. O defeito estava na distância entre dois documentos, não na disciplina de ninguém.
Próximo passo
A próxima medição compara a aderência da semana que vem com estes 15%. Se subir, o teto proporcional estava certo e o que falta é hábito. Se ficar parado, a regra está mal calibrada e o lugar de mexer é nela, não no alerta. O que eu não vou fazer é escrever uma terceira regra antes de saber o efeito da segunda.
Leia também
Mesmo projeto, mesma trilha — as histórias se conectam.
Próximo passo
Se isto te serviu, tem mais: escrevo sobre o mesmo assunto nos outros projetos, e a loja tem as ferramentas que eu uso aqui.
Anotado — aviso quando sair artigo novo.
Sem spam, descadastro de um clique. Também estou aqui: Loja de skills · Portfólio