🪜 Identifique as três fases da IA no código
A evolução do uso de IA no desenvolvimento passou por três fases. Elas não se substituem: convivem no seu dia. O que muda em cada uma é quanto da execução sai da sua mão — e, por consequência, que tipo de controle você precisa colocar no lugar.
🆕 Novo aqui?
LLM é o modelo de IA que gera texto — o mesmo tipo que roda atrás do ChatGPT ou do Claude. Ferramentas ("tools") são ações que esse modelo pode disparar sozinho: ler um arquivo, rodar um comando no terminal, buscar na web. Agente é o modelo mais essas ferramentas mais um ciclo que o faz repetir até achar que terminou. Guarde esses três: o curso inteiro usa.
Autocomplete
A IA sugere linhas, funções ou pequenos trechos enquanto você digita.
O humano continua responsável por praticamente todas as decisões. O erro possível é local: uma sugestão ruim que você aceita sem ler. O custo de revisar é baixo porque o diff é pequeno.
Assistente
A IA responde perguntas, explica código, cria funções, gera arquivos.
Ela já participa da implementação, mas ainda depende de instruções frequentes. Aqui aparece o primeiro risco de escala: você aceita blocos inteiros que não leu linha a linha, porque "parecia certo".
Agente
Recebe uma tarefa e executa: explora o repositório, lê documentação, modifica arquivos, roda comandos e testes, analisa o erro e tenta corrigir a própria implementação.
Esta fase exige um novo tipo de engenharia. O agente não deve ser tratado como um chatbot esperto, e sim como um componente operacional dentro de um sistema controlado — com permissões, limites, verificação e registro.
Sugestão
Fase 1: risco local
Resposta
Fase 2: risco de bloco
Execução
Fase 3: risco sistêmico
Controle
Muda de linha para sistema
🧩 Liste o que um agente precisa para funcionar
Quando um agente "não funciona", a causa quase nunca é o modelo. É um item ausente desta lista. Use-a como diagnóstico: percorra os treze pontos e marque o que falta no seu setup atual.
Como ler: a caixa central é a única coisa que muitos times configuram — e é a menor parte do problema. Tudo em ciano ao redor é o que você monta. Se uma dessas caixas está vazia, o agente falha exatamente ali: sem "critério de fim" ele não para; sem "registro" você não descobre o que ele fez.
✓ Setup que funciona
- ✓Acesso ao repositório com escopo declarado (o que pode ler, o que pode escrever)
- ✓Comando de teste que roda em segundos e falha alto
- ✓Critério de conclusão explícito e verificável
- ✓Log de todas as ações executadas
✗ Setup que vira acidente
- ✗Acesso total à máquina "para facilitar"
- ✗Nenhum teste — a verificação é você olhando o diff
- ✗"Termine quando estiver bom" como critério
- ✗Sem registro: ninguém sabe quais comandos rodaram
Contexto
O que ele consegue ver
Permissão
O que ele pode fazer
Verificação
Como saber se deu certo
Registro
O que ficou de prova
🎛️ Assuma o novo papel do engenheiro
O trabalho não diminuiu — ele mudou de lugar. Menos tempo digitando a implementação, mais tempo definindo o que é certo, montando o contexto, fixando limites e julgando o resultado. Quem faz isso bem multiplica o time inteiro.
🎯 O deslocamento em uma frase
Antes, seu produto era o código. Agora, seu produto é o sistema que produz código confiável — a spec, o harness, o loop, os gates. O código é a saída desse sistema.
- •Você escreve menos linhas e revisa mais mudanças.
- •Você transforma conhecimento tácito do time em documento e teste.
- •Você decide onde a autonomia para e o humano assina embaixo.
💡 Dica prática
Na próxima tarefa que você fosse delegar à IA, gaste 10 minutos escrevendo a spec antes de abrir o agente. Meça: quantas idas e vindas você economizou? Esse número é o argumento que convence seu time — não o discurso.
Especificar
Definir o que é certo
Contextualizar
Escolher o que ele vê
Limitar
Definir onde para
Julgar
Aceitar ou rejeitar
🏗️ Entenda por que os fundamentos voltaram a importar
A IA gera código rapidamente, mas não substitui conhecimento de engenharia. Quanto mais código ela produz, mais valiosa fica a sua capacidade de avaliar o resultado — e essa capacidade vem de fundamentos, não de conhecer a ferramenta da vez.
🔍 O que passa despercebido sem fundamentos
Todos esses defeitos passam nos testes de caminho feliz. É exatamente por isso que eles chegam à produção.
O conhecimento durável
Arquitetura, testes, sistemas operacionais, redes, APIs, segurança, bancos de dados e infraestrutura. Nada disso envelhece na velocidade das ferramentas.
O conhecimento durável não está em decorar uma ferramenta.
Está em compreender como sistemas funcionam.
Checagem rápida (não bloqueia nada): um agente entregou uma correção e todos os testes passaram. Qual é a conclusão correta?
Avaliar > produzir
O gargalo virou julgamento
Caminho triste
É onde mora o defeito
Durável
Sistemas, não produtos
Escala
Mais código, mais revisão
🚧 Reconheça os limites atuais das ferramentas
Saber onde a ferramenta falha não é pessimismo — é o que define quais tarefas você delega hoje e quais ainda exigem aprovação humana. Estes quatro limites explicam a maioria dos resultados ruins.
1. Só existe o contexto que você deu
O agente não sabe da conversa no corredor, da regra que só o Paulo conhece, nem do sistema vizinho que consome sua API de um jeito não documentado. O que não entrou no contexto, ele preenche com suposição plausível.
2. "Teste passou" não é "intenção atendida"
Ele otimiza para o verificador que você deu. Se o verificador é fraco, a solução será fraca do jeito exato que o verificador não detecta.
3. Confiança constante, acerto variável
O tom da resposta não varia com a qualidade dela. Você não consegue usar "ele pareceu seguro" como sinal.
4. Efeitos colaterais fora do repositório
Banco, infraestrutura, permissões e integrações externas não voltam com um git revert. É por isso que essas ações pedem aprovação, não autonomia.
⚠️ Atenção
Mudanças em produção, banco de dados, infraestrutura, permissões e segurança precisam de controles adicionais — sempre. Nenhuma economia de tempo compensa uma migração irreversível aplicada por um loop automático às 3h da manhã.
Contexto ausente
Vira suposição
Verificador fraco
Solução fraca
Tom ≠ acerto
Confiança não é sinal
Irreversível
Exige humano
⚠️ Fuja do desenvolvimento baseado só em prompts
Desenvolvimento só por prompt é aquele em que a única entrada é a frase do momento: sem especificação, sem testes, sem limites, sem revisão independente. Parece produtivo por uma semana e cobra o preço no mês seguinte.
🧪 Exercício copiável — o mesmo pedido, dois níveis
Objetivo: sentir na prática a diferença que o contexto faz. Rode os dois no seu agente (Claude Code, Codex, Cursor — tanto faz), num repositório de teste.
Prompt A (só prompt):
Adicione cache no endpoint de listagem de produtos.
Prompt B (mesma tarefa, com engenharia em volta):
Tarefa: adicionar cache na listagem de produtos em <caminho/do/arquivo>. Fora do escopo: não alterar o contrato da resposta, não tocar em outros endpoints, não adicionar dependências novas sem me perguntar antes. Critérios de aceitação: - resposta idêntica à atual para os mesmos parâmetros (byte a byte); - invalidação do cache quando um produto é criado, alterado ou removido; - TTL configurável por variável de ambiente, com default de 60s; - teste automatizado cobrindo hit, miss e invalidação. Antes de implementar: me mostre o plano em até 10 linhas e espere aprovação. Ao terminar: rode <comando de teste do seu projeto> e cole a saída real.
Como verificar: compare os dois diffs. Conte arquivos alterados, dependências adicionadas e testes criados. O prompt A costuma inventar camada de cache genérica e mexer em arquivos não pedidos; o B entrega uma mudança revisável em minutos. Guarde os dois diffs — eles são o seu argumento no time.
✓ Sinal de que você saiu do "só prompt"
- ✓Existe um artefato escrito que define "certo" antes da execução
- ✓Existe um comando que responde "deu certo?" sem opinião humana
- ✓Existe uma fronteira do que não pode ser tocado
- ✓Existe um segundo par de olhos (humano ou agente revisor)
✗ Sintomas da dívida por prompt
- ✗Duas soluções para o mesmo problema em módulos diferentes
- ✗PRs grandes demais para revisar de verdade
- ✗Testes que só cobrem o caminho feliz
- ✗Dependências que ninguém sabe explicar por que entraram
Velocidade dupla
De entrega e de erro
Fronteira
Escopo negativo escrito
Verificador
Comando, não opinião
Sistema
O diferencial real
📌 Resumo do Módulo
Próximo Módulo:
1.2 - Spec-Driven Development: transformar intenção em critério verificável.