ponytail-audit

Audite todo o repositório como o desenvolvedor sênior que acabou de herdá-lo e será acionado quando ele quebrar. Ordem de importância: correto, seguro, aguenta sob carga, testado, rápido, enxuto. Enxuto ainda importa: cada linha extra precisa ser lida, testada e corrigida depois. Este é um relatório que o usuário solicitou, então entregue-o por completo.

1. Mapeie primeiro

• Audite o que o usuário nomeia: uma pasta, um pacote ou o repositório inteiro. Nada nomeado: o repositório inteiro.
• Leia o README, a configuração de deploy e build, a lista de dependências, os pontos de entrada (main, rotas, handlers, jobs, comandos CLI) e os testes.
• Descubra a carga esperada: uma pessoa executando um script, ou muitos usuários e processos ao mesmo tempo. Julgue a escala contra isso e diga qual carga você assumiu.
• Trace os fluxos principais de ponta a ponta: onde os dados entram, o que é armazenado, o que sai. Leia esses caminhos completamente: entrada de usuários, dinheiro, autenticação, escritas de dados, jobs em segundo plano, qualquer coisa compartilhada entre processos.
• Repositório grande: vá fundo onde um erro custa mais, não arquivo por arquivo. Diga quais partes você não leu.

2. Procure por

1. Bug: resultado incorreto, crash, caso de borda perdido (vazio, zero, último item, arredondamento, fusos horários), chamadores que discordam do que uma função retorna, a mesma regra aplicada de forma diferente em dois lugares.
2. Risco: falhas de segurança (injeção, aleatoriedade fraca, segredos no código, falta de verificações na entrada de usuários), perda de dados (erros ignorados, escritas na ordem errada, sem transação).
3. Escala: bom para um usuário, errado para muitos: corridas de check-then-write, o mesmo trabalho feito por cada processo, memória ou listas que só crescem, uma consulta por item, O(n^2) em entrada grande, estado por processo que precisa ser compartilhado.
4. Teste ausente: lógica arriscada (um branch, um parser, dinheiro, segurança, escritas de dados ) sem um teste que falhe quando quebrar. Um bom teste, não cobertura.
5. Velocidade: grandes lentidões são problemas. Pequenas vitórias (trabalho repetido em um loop quente) são sugestões; algum software conta cada milissegundo.
6. Enxuto: código que não deveria existir ou deveria ser menor.
   • deletar: código morto, opções não utilizadas, flags e configuração, recursos especulativos
   • reutilizar: dois helpers fazendo a mesma coisa (mantenha um, nomeie o caminho)
   • stdlib / nativo: a biblioteca padrão ou plataforma já faz isso; uma dependência fazendo o que algumas linhas ou a plataforma podem fazer
   • yagni: interface com uma implementação, fábrica com um produto, wrapper que apenas passa chamadas
   • mesclar: cópias próximas que precisam mudar juntas
   • dividir: uma função ou classe fazendo vários trabalhos não relacionados, tornando-a difícil de ler ou testar. Divida por trabalho, nunca por contagem de linhas, e nunca em helpers que existem apenas para tornar uma função menor.

3. Verifique antes de relatar

• Cada descoberta precisa de um caso concreto: "esta entrada ou situação leva a este resultado incorreto". Sem caso, sem descoberta.
• Antes de chamar código de não utilizado, use grep em toda a árvore, incluindo testes, fixtures, configuração e referências de string ou dinâmicas.
• Um atalho marcado com um comentário shortcut: (ou o mais antigo ponytail:) que nomeia seu limite é uma decisão, não uma descoberta, a menos que a carga esperada já o ultrapasse.
• Proponha a menor correção que funcione. Prefira correções que deletem código. Nunca adicione camadas, frameworks ou configuração que o problema não precise.
• Sem gosto de estilo, sem "considere", sem preocupações vagas.

4. Saída

Inglês muito simples: frases curtas, palavras do dia a dia. Explique um termo técnico na primeira vez que o usar. O leitor pode nunca ter visto este código.

Comece com What this repo does: em duas ou três frases, e a carga que você assumiu.

Em seguida, as descobertas em três grupos, mais importantes primeiro, pule grupos vazios:

• Precisa corrigir: bug, segurança, perda de dados, quebra na carga esperada.
• Deve corrigir: código arriscado sem teste, lentidão real, duplicação, uma função que mistura trabalhos, código que não deveria existir.
• Bom ter: pequenas melhorias de velocidade, formas mais curtas.

Numere as descobertas em todos os grupos, para que o usuário possa dizer "corrija 2 e 5". No máximo 20 descobertas; se você deixou de fora as menores, diga quantas. Cada descoberta tem todas as quatro partes, cada uma com uma ou duas frases curtas:

2. Pedidos chegam no dia errado (billing/close_day.py:L40-52)
   • O que é: À meia-noite, este job fecha o dia e fatura todos os pedidos desse dia.
   • Problema: Ele pega "hoje" do relógio do servidor, que roda em UTC. Um pedido feito às 00:30 em Berlim é faturado no dia anterior.
   • Correção: Calcule o dia uma vez no fuso horário da loja:

…