AI coding: exploração/refactor/debug
Um assistente de programação pode explorar arquivos, sugerir mudanças e executar ferramentas. O ganho não vem apenas de completar linhas: vem de conectar uma tarefa ao comportamento real do repositório. Nesta semana aprenderemos a usar essa capacidade para compreender, refatorar e diagnosticar código com evidência.
O caso é um cálculo de frete que falha no limite de valor para entrega gratuita. Você começará pelo comportamento esperado e pelos arquivos que o implementam. O agente ajudará a localizar relações, mas o resultado será julgado pelo contrato e por verificações do projeto, não pela confiança da explicação.
JavaScriptIA & MLProgramaçãoAo terminar esta aula
- Explore o fluxo por perguntas concretas.
- Debugging precisa de hipótese refutável.
- Código gerado é uma proposta que exige evidência.
Antes de continuar: Laboratório: Context Engineering
Superfícies e capacidades de coding assistants
ProgramaçãoCodex, Claude Code, Copilot, Cursor e OpenCode oferecem diferentes superfícies para assistência de desenvolvimento. Algumas trabalham dentro do editor, outras no terminal ou no fluxo de repositório remoto. A disponibilidade de edição, execução, revisão e subagentes depende do produto, versão, configuração e permissões. Não suponha que um recurso observado em uma ferramenta existe em todas. Consulte a documentação do ambiente utilizado e registre quais capacidades realmente foram concedidas.
↗ Common workflows↗ GitHub Copilot on GitHub.com↗ Cursor Agent overview↗ OpenCode Agents↗ Custom instructions with AGENTS.md
A fronteira prática é o efeito possível. Sugerir um trecho não modifica o projeto; editar modifica arquivos; executar um comando pode instalar dependências, alterar banco ou publicar artefatos. Um agente com ferramentas precisa de uma tarefa delimitada e de critérios de conclusão. Para o frete, autorize inspeção e alteração do módulo relevante, definindo a verificação esperada. Não amplie o pedido para reestruturar todo o checkout sem necessidade. O contexto de instruções do repositório também influencia comportamento, mas não substitui permissões efetivas.
↗ Common workflows↗ GitHub Copilot on GitHub.com↗ Cursor Agent overview↗ OpenCode Agents↗ Custom instructions with AGENTS.md
Exploração de codebase parte de perguntas
FundamentosExplorar o código é construir um mapa orientado pela tarefa. Procure ponto de entrada, fluxo de dados, regras de negócio, testes e dependências. Para frete, uma busca pelo texto da opção exibida pode levar à interface; a função de cálculo pode estar em outro módulo. Siga importações e chamadas até entender quem fornece subtotal, moeda e endereço. Ler um arquivo isolado pode produzir uma correção local que quebra outro caminho.
Use perguntas verificáveis: onde a elegibilidade é calculada? O subtotal inclui descontos? Existe contrato para moeda? Qual teste cobre o limite? Peça ao assistente que apresente caminhos e evidências, distinguindo inferência de constatação. Um nome como totalFinal não comprova que inclui impostos. A leitura do fluxo mostra isso. Registre apenas o mapa necessário à tarefa e confirme hipóteses com execução ou inspeção adicional. Uma exploração ampla sem objetivo consome contexto e pode gerar uma narrativa detalhada, porém desconectada do bug.
Refatoração preserva comportamento definido
FundamentosRefatorar altera a estrutura interna mantendo o comportamento que o contrato exige. Extrair uma função pode facilitar testes e reduzir duplicação, mas também mudar ordem de operações ou tratamento de valores. O agente precisa conhecer invariantes antes de editar. Para frete, preserve arredondamento, tratamento de subtotal zero e o limite exato. Uma mudança “mais limpa” que passa a conceder frete a um valor inferior não é uma refatoração correta.
Separe refatoração e alteração funcional quando isso ajuda a revisar. Primeiro estabeleça testes que descrevam o comportamento vigente desejado; depois reorganize o código; por fim faça a mudança funcional autorizada se houver. Não preserve por acidente um comportamento que o requisito identifica como bug. A diferença deve ser explícita. Revise o diff procurando alterações fora da tarefa e dependências adicionadas sem justificativa. O tamanho do código reduzido não é a medida principal; legibilidade, verificabilidade e manutenção precisam ser avaliadas no contexto do projeto.
Debugging exige hipótese e reprodução
ProgramaçãoDebugging começa com uma discrepância observável entre esperado e ocorrido. Crie uma entrada mínima que reproduza a falha, capture a saída e localize a condição relevante. Para um limite inclusivo de 100, valores abaixo, no limite e acima distinguem >= de >. Pedir “corrija o frete” sem especificar isso permite ao agente escolher uma regra plausível, mas não necessariamente a regra do produto.
Formule uma hipótese: a comparação exclui o limite. Inspecione o código e execute o caso que a refuta ou confirma. Depois aplique a menor alteração coerente e rode verificações pertinentes. Se a falha persiste, atualize a hipótese; não acumule ajustes até alguma combinação parecer funcionar. Logs e stack traces devem ser tratados como evidência parcial. Uma linha apontada no stack pode ser o local em que a falha aparece, enquanto a origem está no dado produzido antes. O assistente pode acelerar investigação, mas precisa mostrar esse encadeamento.
Critério de conclusão e limites da assistência
FundamentosUma tarefa concluída tem comportamento demonstrado, verificação executada e limitações declaradas. A frase “corrigido” é insuficiente sem saber quais casos passaram. Para o frete, confirme casos de fronteira e um cenário de integração que mostre o total exibido. Testes locais não provam funcionamento em produção, mas oferecem evidência sobre o escopo executado. Se uma verificação requer um serviço indisponível, registre a lacuna sem inventar resultado.
↗ Cursor Agent overview↗ GitHub Copilot on GitHub.com↗ OpenCode Agents
Checkpoints do editor podem ajudar a recuperar alterações, mas não são automaticamente commits Git nem substituem revisão do diff. Preserve o estado inicial e não sobrescreva trabalho alheio. Ao receber código sugerido, confira tipos, contratos, efeitos e dependências. Explicações podem soar convincentes mesmo quando um símbolo citado não existe. O uso responsável consiste em aproveitar a velocidade de exploração e manter uma cadeia clara de evidência até o resultado aceito.
↗ Cursor Agent overview↗ GitHub Copilot on GitHub.com↗ OpenCode Agents
Exemplo comentado e limites
FundamentosO exemplo explicita uma fronteira inclusiva e valida valores inválidos. A implementação é deliberadamente pequena para que a regra seja inspecionada. Uma versão com > falharia em 100, embora passasse em entradas distantes do limite. Isso mostra por que casos normais não bastam para diagnosticar comparações.
function frete(subtotal) {
if (!Number.isFinite(subtotal) || subtotal < 0) throw new Error("Subtotal inválido");
return subtotal >= 100 ? 0 : 12;
}
for (const [entrada, esperado] of [[99.99,12],[100,0],[100.01,0]]) {
const obtido = frete(entrada);
if (obtido !== esperado) throw new Error("Falhou em "+entrada);
console.log({entrada,esperado,obtido});
}Não copie automaticamente o número 12 ou a política de 100 para um checkout real: são dados fictícios do exercício. No projeto, identifique a origem da configuração e preserve regras de moeda e desconto. O agente deve encontrar esse contexto antes de transformar uma reprodução mínima em uma alteração integrada.
Exercício aplicado
O requisito diz frete grátis a partir de 100, mas o sistema cobra em 100. Reproduza e corrija sem alterar regras de desconto.
- Localize módulo, chamadas e testes.
- Demonstre falha no limite antes da mudança.
- Aplique condição inclusiva e verifique fronteiras.
- Revise diff e documente escopo de integração.
Abrir resolução comentada
A resolução começa demonstrando a falha do limite, depois troca a condição para >= e mantém os casos abaixo e acima. Verifica também subtotal inválido. O relatório cita o módulo alterado e explica por que a mudança não altera a ordem de aplicação de desconto.
Uma refatoração pode extrair a política para configuração, mas isso é uma decisão separada. A tarefa atual não exige nova biblioteca nem reorganização global. O critério final é que a regra inclusiva apareça no comportamento e que as verificações existentes pertinentes continuem passando.
Uma entrega satisfatória inclui a saída do caso que falhava e sua aprovação após a mudança, com o requisito que justifica >=. A alteração deve preservar a representação de moeda e a ordem de desconto do projeto.
A resolução reproduz a discrepância com a função antiga, verifica a condição inclusiva e inclui inválidos, subtotal zero e desconto. A unidade monetária é centavos e a política fictícia considera o subtotal depois do desconto. O mapa e o diff correspondem ao arquivo de prática, sem fingir inspeção de um checkout externo. No repositório real, o estudante confirma unidade, política e fluxo antes de aplicar a alteração e registra as verificações de integração realmente executadas.
import assert from "node:assert/strict";
// Política fictícia: subtotal após desconto, centavos internos, limite inclusivo de R$100.
function antigo(centavos){return centavos>10000?0:1200;}
function frete(centavos){
if(!Number.isSafeInteger(centavos)||centavos<0)throw new Error("SUBTOTAL_INVALIDO");
return centavos>=10000?0:1200;
}
const casos=[[9999,1200],[10000,0],[10001,0],[0,1200]];
assert.notEqual(antigo(10000),0); // Reprodução antes da correção.
for(const [entrada,esperado] of casos)assert.equal(frete(entrada),esperado);
assert.throws(()=>frete(-1),/SUBTOTAL_INVALIDO/);
assert.throws(()=>frete(99.99),/SUBTOTAL_INVALIDO/);
const subtotal=10500,desconto=1000;
assert.equal(frete(subtotal-desconto),1200);
const mapa={modulo:"função frete deste arquivo",chamadas:"loop de casos e caso com desconto",
testes:"asserts explícitos",contrato:"centavos depois do desconto"};
const diff={antes:"centavos > 10000",depois:"centavos >= 10000",
representacao:"normalização em centavos preservada",alteracoesForaDaTarefa:[]};
assert.equal(diff.alteracoesForaDaTarefa.length,0);
console.log({status:"aprovado",mapa,diff,casos:casos.length,
integracaoCheckout:"não executada; localizar o fluxo real antes de aplicar a política fictícia"});Como conferir seu resultado
- O teste distingue > de >=.
- Alterações fora da tarefa foram revisadas.
- Não há afirmação de verificação que não ocorreu.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Encontrar regra/chamadores/testes.
- Preservar unidade monetária.
Desconto vale subtotal>=200; código usa>200. Planeje investigação e testes 199,99/200/200,01.
Conferir raciocínio e critérios de domínio
Caso 200 revela falha inclusiva; corrigir operador.
Preservar unidade e ordem de desconto dos chamadores.
Diff deve justificar mudança; não reestruturar checkout sem necessidade.
Evidências para autoavaliação ou revisão por pares
- Reprodução: Caso 200 revela falha inclusiva; corrigir operador.
- Contrato: Preservar unidade e ordem de desconto dos chamadores.
- Escopo: Diff deve justificar mudança; não reestruturar checkout sem necessidade.
Um erro frequente
Explicação do assistente prova correção.
O contrato e os testes sustentam a correção.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. Um checkpoint é necessariamente um commit Git?
Não.
Mecanismos de recuperação do editor e histórico Git têm contratos diferentes.
2. Uma explicação convincente comprova o bug?
3. Refatoração pode alterar regra de frete silenciosamente?
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Common workflows
Anthropic • consulta: 2026-10-06
AutomaçãoExploração de codebase, debugging, refatoração, testes, review e análise assistida.
Limites: Resultados do agente devem ser verificados com testes, análise estática e review humano apropriado.
- GitHub Copilot on GitHub.com
GitHub • consulta: 2026-10-06
FundamentosSuperfície Copilot, agente de coding e fluxo de review no GitHub.
Limites: Disponibilidade e limites dependem de plano e organização; verificar antes do laboratório.
- Cursor Agent overview
Cursor • consulta: 2026-10-06
AgentesExploração, edição, terminal, ferramentas de agente e checkpoints.
Limites: Checkpoints locais do Cursor não são commits Git; recursos mudam por versão/plano.
- OpenCode Agents
OpenCode • consulta: 2026-10-06
AgentesAgentes primários, subagentes, configuração, tools e permissões.
Limites: Documentação dinâmica; fixar a versão usada no laboratório e conferir compatibilidade antes de executar.
- Custom instructions with AGENTS.md
OpenAI • consulta: 2026-10-06
OpenAIAgentesInstruções globais e de projeto, descoberta, AGENTS.override.md e precedência por diretório.
Limites: Precedência documentada para Codex; instruções são orientação, não garantia de cumprimento ou controle de acesso.