A regra que o guard cobrava e ninguém tinha escrito
Estudos·

A regra que o guard cobrava e ninguém tinha escrito

6 min de leitura← Voltar para timeline

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.

Sem spam, descadastro de um clique. Também estou aqui: Loja de skills · Portfólio