O Que Pode Quebrar

Visão Geral

Listar chamadores não é o trabalho. grep faz isso em um segundo. Esta habilidade encontra a quebra que o grep não mostrará, e produz uma prova de que a mudança é segura.

Execute antes do design, não apenas antes do merge. Sempre que uma tarefa afirma algo sobre código existente ("X já lida com Y", "apenas torne X público"), essa afirmação é uma hipótese, e o censo de consumidores reais decide o design.

Quando Usar

• Use antes de qualquer edição em múltiplos arquivos, ou uma edição em um caminho compartilhado: payload de API, configuração, dados armazenados, um cliente que outros aplicativos leem, um prompt ou arquivo de política.
• Use quando o usuário perguntar "o que isso pode quebrar" ou "raio de explosão de X".
• Use para um diff pequeno em que você não confia.
• Use quando uma breve afirmação sobre código existente, antes de você projetar com base nessa afirmação.

Como Funciona

Passo 1: Não confie na sua própria descrição

Uma análise de risco que parece correta é inútil: ela soa convincente, quer seja verdade ou não. Encontre os um ou dois fatos dos quais toda a mudança depende, e leve cada um o mais longe possível nesta escada, enquanto for barato. Diga onde parou.

1. Você disse. Não vale nada por si só.
2. Você apontou para isso. Um file:line real, ou o próprio código-fonte da biblioteca na versão fixada.
3. Você percorreu. Você rastreou o caso ruim passo a passo e ele não alcança.
4. Você executou. Um script ou teste chama o código real e falha alto se você estiver errado.
5. Você viu ao vivo. Reproduzido no aplicativo, serviço ou dispositivo em execução.

O degrau 4 geralmente é um pequeno script que importa o mesmo módulo que a produção executa e chama a função exata sobre a qual você está preocupado, com a entrada sobre a qual você está preocupado.

Passo 2: Leia a mudança

O diff, os símbolos que ele adiciona, altera e exclui, e o que ele agora faz de diferente, incluindo o que o diff não explicita. git log -S '<symbol>' e git log -L :<function>:<file> mostram por que a forma antiga existe; uma proteção que parece desnecessária muitas vezes tem um commit explicando o incidente que ela impediu.

Passo 3: Encontre o único fato pelo qual é seguro

A maioria das mudanças de aparência arriscada é segura por causa de um fato ("isso apenas descarta entradas de cache que já expiraram", "nenhum cliente lê este campo"). Se isso se mantiver, a maioria dos riscos desaparece de uma vez. Se você não conseguir encontrar um, a mudança ainda não foi compreendida.

Passo 4: Olhe onde o grep para

Procure pelo valor literal, o nome do campo, o texto do erro e o comportamento antigo, não apenas o símbolo que você renomeou. Em seguida, verifique cada um deles manualmente:

• A mesma regra vivendo duas vezes. Um segundo arquivo de configuração, um caminho de fallback que codifica o padrão antigo, uma cópia sincronizada em outro repositório, uma constante duplicada em uma migração ou fixture de teste, um valor padrão de flag de recurso.
• Prompts e arquivos de agente que reafirmam a regra. Prompts do sistema, arquivos de agente e habilidades, AGENTS.md, CLAUDE.md, runbooks. Um agente obedece à frase desatualizada, não ao seu código.
• Todos os outros clientes. Web, iOS, Android, desktop, CLI, extensões, integrações de parceiros. Clientes móveis nas mãos dos usuários permanecem na versão antiga por semanas: o que um cliente antigo faz com a nova forma, e um cliente novo com o servidor antigo?
• Formatos de comunicação. Nomes e tipos de campos JSON, valores de enumeração, null versus ausente, formatos de data, forma de paginação, códigos de erro, payloads de webhook, esquemas de fila, contratos GraphQL e protobuf.
• Estado armazenado. Colunas e seus padrões, linhas escritas sob a forma antiga, entradas de cache, arquivos em disco, logs de append-only, conteúdo de sessão e cookie, índices de busca. Dados antigos sobrevivem ao deploy.
• Ambiente e segredos. Uma variável de ambiente renomeada no código, mas não na configuração de deploy, CI, a imagem, ou o segundo serviço que a lê.
• Processos que reiniciam separadamente. Servidor web, workers, jobs cron, funções serverless, o aplicativo móvel, um sidecar. Durante um rollout, um executa código novo enquanto outro executa código antigo contra os mesmos dados. Ambos podem coexistir por uma hora?
• Tempo e concorrência. Dois escritores na mesma linha ou chave, uma nova tentativa que agora dispara duas vezes, ordenação que só se manteve porque um passo era lento.
• Código-fonte da biblioteca em sua versão fixada. Leia o código da dependência na versão do lockfile, não sua memória da documentação.
• Código gerado e fornecido. Clientes gerados a partir de um esquema, cópias fornecidas, artefatos de build commitados, bundles cuja chave de cache-busting não mudou.
• Testes e fixtures que codificam o comportamento antigo. Um teste que passa porque sua fixture ainda tem a forma antiga não prova nada sobre a nova.

…