AI Coding Workflow 101 — o loop de 6 estágios que separa dev que reclama de IA de dev que entrega 3x mais

Felipe Vieira 23 de maio de 2026 🇧🇷 Português 9 min read

AI Coding Workflow 101 — o loop de 6 estágios que separa dev que reclama de IA de dev que entrega 3x mais — cover

Todo mundo fala em usar AI pra escrever código como se fosse máquina automática:

"Cola o problema, recebe a solução pronta."

Na primeira vez que tentei, aprendi do jeito difícil que não é assim que funciona em projeto real. O modelo sugeria, com confiança, código que chamava funções que não existiam, assumia libs que não estávamos usando, ignorava constraints óbvios. O output parecia polido. No momento que eu rodava… caía aos pedaços.

Depois de bastante tentativa e erro, parei de tentar "prompt melhor" e comecei a trabalhar diferente. O que finalmente fez AI ser útil não foi ferramenta mágica nem prompt esperto. Foi um loop simples que mantém o modelo com coleira curta e mantém você no controle.

Este post junta o que aprendi construindo o Dev Team Kit e operando agents em produção — o loop, os patterns e os anti-patterns que de fato fazem AI coding render em projeto real.

O modelo mental — o que AI é e o que não é

AI coding assistants são fantásticos quando o problema é bem-escopado e está diante deles. São não-confiáveis no momento que você assume que eles "sabem" o que você não forneceu explicitamente. O workflow é basicamente como ficar na primeira zona e evitar a segunda.

Quando você dá requisitos claros, AI é ótimo pra:

Mas tem um limite duro: só sabe o que vê no context atual. Não lembra do último chat, não conhece sua arquitetura ou convenções, e não vai te avisar quando está chutando. Continua confiante.

Eu já vi AI chamar funções de lib que não existem, usar sintaxe da versão errada, ignorar constraints que eu achava óbvios. O padrão é sempre o mesmo: AI não sabia o que eu não tinha dito, então preenche as lacunas inventando algo plausível.

3 princípios que mudaram tudo

  1. Dê mais context do que acha que precisa. Igual briefar colega que acabou de entrar no projeto, briefe a AI toda vez. Se não compartilha detalhes, ela inventa.
  2. Guie com steps específicos. AI sofre com "construa um app web", mas vai bem com "adicione validação de input pra estes campos, retorne erro claro, escreva teste que prova que input inválido é rejeitado". Quanto mais específico o request, melhor o output.
  3. Se importa, verifica. Logic sensitive de segurança, migration de banco, algoritmo que tem que estar correto — eu reviso pessoalmente e adiciono testes que provam o comportamento.

Forma boa de manter isso na cabeça: AI é um colega esperto que entrou no seu projeto 5 minutos atrás. Escreve rápido, mas não conhece sua arquitetura, convenções, constraints — a não ser que você diga.

O loop — 6 estágios que se repetem

Diagrama hexagonal do loop com 6 estágios — Context, Plan, Code, Review, Test, Iterate — conectados em ciclo com ícones

O loop é o mesmo seja consertando bug, adicionando feature, ou limpando módulo bagunçado:

  1. Context: compartilho background do projeto, constraints, código relevante. AI não fica chutando.
  2. Plan: peço estratégia antes de qualquer código.
  3. Code: gera ou edita código um step de cada vez. Mudanças ficam pequenas e revisáveis.
  4. Review: checa output cuidadosamente, frequentemente uso AI-assisted PR review como segundo par de olhos.
  5. Test: roda testes, e frequentemente peço pra AI gerar novos que travam o comportamento.
  6. Iterate: debuga falhas, refina o pedido, repete até a mudança estar sólida.

Step 1: Context — o que mata 80% dos problemas

Comparativo lado a lado — desenvolvedor com fix this minimalista e AI gerando solução errada, vs desenvolvedor com README, AGENTS.md e logs anexados e AI gerando solução correta

Maioria dos erros de AI em código tem a mesma causa-raiz: o modelo está chutando no vácuo. Pessoa cola função, digita "fix this", e se surpreende quando a sugestão ignora metade do sistema.

"Fix this" é a forma mais rápida de fazer o modelo halucinar. Sem background do projeto e constraints, ele tem que preencher lacunas com o que soa certo: funções que não existem, sintaxe da versão errada, soluções que quebram convenções de outras partes do repo.

Pra qualquer tarefa não-trivial, eu carrego 3 tipos de context:

1. Project background

Mantenho README atualizado em cada projeto e começo a maioria das sessões com:

Read the README below to understand the project.
Then I will give you a specific task.

Se a mudança toca algo sensível (pagamentos, auth), incluo os arquivos-chave na primeira mensagem também. Quando descrevo a mudança, o assistente já viu a vizinhança.

2. Rules e constraints (AGENTS.md / CLAUDE.md)

Mantenho arquivo de regras (AGENTS.md é padrão emergente, ou CLAUDE.md específico do Claude Code) que junta:

Tools como Cursor, Claude Code, Cline, Continue suportam "rules" ou "custom instructions" que evitam repetição em cada sessão.

3. Relevant source e signals

Pra bugs ou features, colo a função/arquivo envolvidos junto com stack traces ou logs. Uma única linha de erro é como screenshot de um pixel. O assistente precisa de mais que isso pra raciocínio real em vez de chute otimista.

Pattern de prompt reutilizável

Read @README to understand the project scope, architecture, constraints.
Read @AGENTS.md for coding style, rules, constraints of this codebase.

Then read @main.py, @business_logic_1.py, @business_logic_2.py carefully.

Your task is to update @business_logic_2.py to implement:

1. <mudança 1>
2. <mudança 2>
3. <mudança 3>

Follow the conventions in README and AGENTS file.
Do not modify other files unless strictly necessary, and explain any extra changes.

A estrutura fica igual: context, rules, tarefa precisa. Mudo só os filenames e a lista de mudanças.

Aprendido na marra: mais texto não é sempre melhor. Os melhores briefings são curtos e focados. Se notar que estou colando mais do que humano leria razoavelmente antes de começar, eu corto. Context deve ser curado, não dumpado.

Step 2: Plan Before You Code

Context responde "onde estou?". Não responde "o que devo construir?". Esse é o ponto que descarrila.

Se você deixa AI escrever código direto, ela frequentemente escolhe abordagem estranha, otimiza a coisa errada, ignora silenciosamente constraints. Força o processo em duas etapas: plan first, then code.

Primeiro: peça plano só

Pra qualquer mudança não-trivial, descrevo a feature ou bug em linguagem natural:

Here is the feature I want to build and some context.
Help me design it.
- What needs to change?
- Which modules are involved?
- What are the main steps?

Do not write any code until I say "approved".

O "Do not write any code" explícito é crucial. Sem ele, modelos modernos pulam direto pra implementação.

Depois: aprove e implemente em small steps

Plano aprovado, peço pra implementar uma etapa de cada vez. Pra cada step, peço pra ele explicar o que vai mudar e propor o código só daquele step.

Small steps são mais fáceis de revisar e desfazer se algo der errado.

Verifique APIs sugeridas

Se a AI recomendar lib ou função que você nunca viu, verifique se de fato existe usando search assistant (Perplexity, ChatGPT search) ou docs oficiais. Modelos frequentemente halucinam APIs que soam plausíveis mas não existem.

Step 3-6: Code, Review, Test, Iterate

Code em incrementos

Cada step deveria ser pequeno o suficiente pra você revisar em 5-10 minutos. Função única, mudança contida. Se a AI propor diff de 200 linhas tocando 5 arquivos, peça pra quebrar.

Use sempre o git: git status antes de cada step pra ver o que mudou. Se algo desviou, git diff mostra. Se quebrou tudo, git checkout reverte.

Review como se fosse PR humano

Trate código gerado por AI igual código de júnior:

Ferramentas como CodeRabbit, Greptile, e Diamond automatizam parte do review — vale especialmente pra PRs grandes.

Test prova comportamento (não cobertura)

Peça pra AI escrever testes que comprovem o caso de uso específico. Não 50 testes triviais — 5-10 testes que cobrem o caminho feliz e os 2-3 edge cases principais.

Padrão útil: "Write tests first, then implementation". Não TDD puro, mas garante que você (e a AI) pensaram nos comportamentos antes do código.

Iterate quando bugs aparecem

Bugs durante iteração não são fracasso — são o loop fazendo o trabalho. Não tente "consertar pelo prompt" mais de 2 vezes. Se na terceira tentativa ainda não passou, é sinal que falta context ou plan está errado. Volte ao Step 1.

Stack de ferramentas — qual usar quando

Ecossistema de ferramentas — Cursor, Claude Code, GitHub Copilot, ChatGPT, Perplexity, CodeRabbit — cada uma com sua especialidade

Diferentes tools são boas em coisas diferentes:

AI Editors (Cursor, VS Code + Copilot, Claude Code)

Bom pra trabalho dentro do repo. Vê arquivos, faz refactor multi-file, mantém context do projeto. Cursor é o padrão de mercado em 2026; Claude Code é o líder em CLI/agent autônomo.

Chat models (Claude, ChatGPT, Gemini)

Bom pra pensar em linguagem natural. Brainstorm de approach, explicar erro, comparar trade-offs, sanity-check de design antes de escrever código. Use chat antes de abrir o editor.

Search assistants (Perplexity, ChatGPT search)

Bom pra verificar fatos. API existe na versão que você usa? Comportamento dessa lib mudou no release X? Esse pattern ainda é recomendado?

AI code review (CodeRabbit, Greptile, Diamond)

Bom como segundo par de olhos. Rode em PR antes do reviewer humano. Pega coisas óbvias (typos, error handling missing, security smell) e libera o reviewer humano pra arquitetura.

Specialized agents (Devin, Sweep, Tessl)

Bom pra tarefas autônomas long-running (refactor grande, bug triage, doc generation). Ainda não substituem dev em features complexas, mas crescem rapidamente.

Anti-patterns que vejo todo dia

  1. One-shot prompt mega-detailed: 2.000 palavras descrevendo a feature inteira. AI esmaece, gera 500 linhas mediocres. Quebra em planos + steps.
  2. Aceitar a primeira sugestão: AI propôs solução? Pergunte 2 alternativas antes de aceitar. Frequentemente a 2ª ou 3ª é melhor.
  3. Skip review porque "passou nos testes": testes passam, mas código é horrível, viola conventions, ou tem race condition que só aparece em prod. Leia.
  4. Não usar git stash / branches: AI quebrou tudo, você não sabe o que mudou. Trabalhe em branches separadas pra cada experiment.
  5. Esquecer AGENTS.md/CLAUDE.md: cada sessão você re-explica as mesmas coisas. Capture em arquivo, deixa AI carregar.
  6. Confiar em URLs/imports que a AI inventou: GitHub URL inexistente, pacote npm que não existe, função do framework removida há 2 versões. Verifique.

Stack que recomendo pra começar amanhã

Conclusão

AI não substitui dev — multiplica dev que sabe operar. A diferença entre os 90% que reclamam de "AI gera código ruim" e os 10% que entregam 2-3× mais features é o workflow. Context → Plan → Code → Review → Test → Iterate.

Não é mágica. É disciplina aplicada. Faça uma vez, sente o ganho, repita. Em 30 dias você não consegue mais voltar pro fluxo antigo.