Templates para Refatoração Cirúrgica e Correção Rápida de Bugs

Templates para Refatoração Cirúrgica e Correção Rápida de Bugs — aula do módulo Templates de Prompt & OpenCRO, na trilha Governança Ágil com Método OKAM da…

Leitura de aproximadamente 4 minutos.

Módulo: Templates de Prompt & OpenCRO · Curso: Governança Ágil com Método OKAM · Formação: Formação Nível Zero: Ferramentas Essenciais e Gratuitas de IA e Código

Templates para Refatoração Cirúrgica e Correção Rápida de Bugs

O que você vai aprender

O perigo de enviar pedidos vagos de correção como "não está funcionando, arrume para mim".
O formato canônico de um Bug Report Cirúrgico: Comportamento Observado, Comportamento Esperado, Evidência Técnica e Escopo Bloqueado.
Como exigir edições pontuais (Surgical Edits) para proteger o código que já está estável.
Como executar testes de regressão para garantir que o conserto de hoje não quebrou nada construído ontem.

1. Por Que a IA Quebra Códigos Funcionais ao Corrigir Bugs?

Todo profissional que utiliza inteligência artificial já vivenciou o seguinte pesadelo: Você passa duas horas construindo uma página com cabeçalho, formulário, galeria de imagens e rodapé. No teste final, percebe que um botão específico não executa o clique.

Apressado, você digita no chat:

"O botão de enviar não funciona. Conserte isso agora."

A IA lê o pedido e, em vez de alterar apenas as duas linhas do botão, devolve uma reescrita completa do arquivo de quinhentas linhas. Quando você cola o código novo, o botão até passa a funcionar, mas a galeria de imagens sumiu, as cores do cabeçalho foram resetadas e o rodapé quebrou.

Esse desastre ocorre porque a IA não sabe quais partes eram intencionais e quais estavam quebradas. Sem fronteiras, ela refaz tudo a partir do zero.

2. A Anatomia do Bug Report Cirúrgico

Para consertar defeitos sem gerar danos colaterais, utilizamos o Template de Correção Cirúrgica:


+-------------------------------------------------------------------------------+
|                       ESTRUTURA DO BUG REPORT CIRÚRGICO                       |
+-------------------------------------------------------------------------------+
|                                                                               |
|   1. COMPORTAMENTO OBSERVADO (O ERRO REAL)                                    |
|      └─ "Ao clicar no botão 'Salvar', a página recarrega e nada acontece."    |
|                                                                               |
|   2. COMPORTAMENTO ESPERADO                                                   |
|      └─ "Deveria exibir o alerta 'Dados salvos' sem recarregar a página."     |
|                                                                               |
|   3. EVIDÊNCIA TÉCNICA (LOG / ERRO EXATO)                                     |
|      └─ "Console do navegador exibe: Uncaught TypeError: Cannot read null."   |
|                                                                               |
|   4. ESCOPO CIRÚRGICO E RESTRIÇÕES                                            |
|      └─ "Edite APENAS a função handleFormSubmit() no arquivo src/app.js."     |
|                                                                               |
+-------------------------------------------------------------------------------+

3. O Template Pronto para Copiar e Usar

Sempre que encontrar um erro no seu aplicativo, preencha o formulário estruturado abaixo antes de chamar o assistente:


# Relatório de Correção Cirúrgica de Bug

## 1. Comportamento Observado
Explique exatamente o que aconteceu de errado no momento do teste.

## 2. Comportamento Esperado
Explique o que deveria ter acontecido.

## 3. Evidência Técnica
Cole aqui a mensagem de erro literal do terminal ou do console do navegador (F12):

[Cole o log de erro aqui]



## 4. Instruções e Restrições de Escopo
- Arquivo alvo: `src/[nome-do-arquivo]`
- Função específica: `[nomeDaFuncao]`
- Proibição: NÃO altere estilos CSS, NÃO modifique a estrutura de outras funções e NÃO instale bibliotecas adicionais.
- Formato da resposta: Entregue apenas as linhas modificadas com a explicação breve da causa raiz.

4. Comparativo de Abordagens de Correção

| Critério | Pedido Vago ("Não funciona") | Bug Report Cirúrgico OKAM | |---|---|---| | Ação da IA | Reescrita de 100% do arquivo | Modificação de 3 a 5 linhas | | Risco de Quebra Colateral | Altíssimo (perda de estilos e funções) | Zero (escopo isolado) | | Tempo de Diagnóstico | IA tenta adivinhar o erro | IA vai direto na linha causadora | | Testabilidade | Impossível saber o que mudou | Verificação imediata via git diff |

5. Armadilhas Comuns e Como Evitar

[!WARNING]

Omitir a Mensagem de Erro do Console: O erro mais grave ao reportar um defeito para a IA é dizer que "deu erro" sem colar o texto exato da mensagem. O console de desenvolvedor do navegador (aberto com a tecla F12) ou as linhas vermelhas do terminal contêm o número exato da linha e o motivo da falha. Sem essa evidência, a IA precisará adivinhar, aumentando exponencialmente o risco de alucinação.

Exercício Prático

Vamos praticar a montagem de um Bug Report Cirúrgico:

1. Cenário de teste: Imagine que você tem uma página com um formulário de login e, ao clicar no botão "Entrar", a tela pisca e o console do navegador exibe:


   Uncaught ReferenceError: validateEmail is not defined at login.js:14

2. Preencha o template:

Comportamento Observado: O formulário recarrega a página e o login não avança.
Comportamento Esperado: O formulário deve validar o e-mail e autenticar o usuário.
Evidência: Uncaught ReferenceError: validateEmail is not defined at login.js:14.
Escopo: Editar apenas o arquivo src/login.js nas proximidades da linha 14.

3. Envie para a IA: Entregue essa especificação estruturada ao seu assistente e confira como a resposta vem focada exclusivamente em definir ou importar a função faltante, preservando todo o restante do seu código intacto.

Templates para Refatoração Cirúrgica e Correção Rápida de Bugs