Vibecoding: do básico ao expert

O termo vibecoding foi cunhado por Andrej Karpathy (cofundador da OpenAI e ex-diretor de IA da Tesla) em fevereiro de 2025, descrevendo um jeito de programar em que você "esquece que o código existe": descreve a intenção em linguagem natural, a IA gera o código, você roda, cola os erros de volta e repete. O que começou como um tweet meio provocativo virou, em pouco mais de um ano, uma prática dominante — pesquisas recentes indicam que a grande maioria dos desenvolvedores já usa ferramentas de codificação assistida por IA regularmente, e uma fatia expressiva de todo código novo em plataformas como o GitHub já nasce gerado por modelos.

Para quem já programa, porém, a definição "descreva e aceite o que vier" é insuficiente — e perigosa. Na prática profissional, vibecoding é melhor entendido como um espectro de delegação:

Esta apostila foca nos níveis 3 a 5 — mas com uma tese central: quanto mais você delega, mais valiosas ficam as habilidades de engenharia que a IA não substitui (especificar bem, revisar criticamente, testar, pensar arquitetura e segurança). É exatamente essa combinação que o mercado paga.

Por que isso explodiu agora

• Custo de gerar código despencou. Tarefas que tomavam horas de digitação saem em minutos. Um experimento controlado da Microsoft Research com 95 desenvolvedores mediu conclusão de tarefa ~56% mais rápida com assistente de IA.
• As ferramentas amadureceram. Cursor, Claude Code, Copilot, Windsurf, Lovable e afins deixaram de ser experimento e viraram produtos com ciclos de release semanais e adoção corporativa.
• O mercado pressiona. Times menores, prazos iguais. Quem domina o fluxo com IA entrega várias vezes mais rápido — e as vagas passaram a exigir isso explicitamente.

O que vibecoding NÃO é

• Não é no-code. No-code gera aplicações em formato proprietário com teto baixo; vibecoding gera código real (React, Python, SQL…) que você pode levar para qualquer lugar, auditar e evoluir.
• Não é substituto de fundamentos. A IA erra com confiança. Quem não sabe ler código não sabe quando ela errou — e é aí que nascem os desastres de produção.
• Não é "aceitar tudo". O profissional que o mercado quer é o que usa IA e mantém padrão de revisão, testes e segurança.

Quando usar (e quando não usar)

Exercícios do capítulo 1

O erro mais comum de quem começa é escolher ferramenta por hype ou preço, e não por caso de uso. O ecossistema de 2026 se organiza em quatro famílias — e um profissional produtivo normalmente combina duas ou três delas.

1. Editores com IA integrada (nível 3)

• Cursor — fork do VS Code com IA nativa; indexa o repositório inteiro e usa esse contexto nas edições. O mais popular entre devs profissionais. Ideal para quem quer manter o fluxo de editor tradicional.
• Windsurf — editor focado em fluxos agênticos (a IA executa ações encadeadas no editor); posicionamento forte em times e projetos grandes.
• GitHub Copilot — o mais adotado globalmente; vive dentro do VS Code, JetBrains e outros. Evoluiu de autocomplete para modos de edição multi-arquivo e agente. Costuma ser o mais fácil de aprovar em empresa (compliance Microsoft/GitHub).

2. Agentes de terminal / CLI (nível 4)

• Claude Code (Anthropic) — agente que vive no terminal (e em apps desktop/IDE), lê e modifica dezenas de arquivos, roda comandos, testes e git. Forte em raciocínio sobre bases de código grandes e em automação (modo headless para CI).
• Codex (OpenAI) e Gemini CLI / Antigravity (Google) — concorrentes diretos; o Antigravity, lançado no fim de 2025, aposta em orquestração multi-agente para projetos complexos.
• Aider — agente open source de terminal, querido por quem quer controle total e integração fina com git.

3. Construtores de aplicação (nível 5)

• Lovable — gera apps completos (front + banco + auth via Supabase) a partir de prompts; forte para MVPs e validação com clientes.
• Bolt.new — velocidade máxima de ideia a protótipo deployado no navegador; ótimo para demos e hackathons.
• v0 (Vercel) — especializado em UI React/Next.js com shadcn/ui; componentes de alta qualidade prontos para colar no projeto real.
• Replit — IDE completa no navegador com agente que constrói e hospeda; do zero ao deploy sem sair da aba.

4. Chats generalistas (nível 2)

Claude, ChatGPT e Gemini via navegador continuam úteis para rascunhos, explicações de código alheio, revisão de trechos e discussões de arquitetura — situações em que você quer pensar junto antes de tocar no repositório.

Como escolher (critério profissional)

Exercícios do capítulo 2

Prompt vago gera código genérico. Prompt com contexto, restrições e critério de aceite gera rascunho aproveitável de primeira. A diferença entre um dev que "briga com a IA" e um que multiplica produtividade está quase toda na estrutura do pedido.

A anatomia de um bom prompt de código

Um prompt profissional tem até seis blocos. Você não precisa de todos sempre — mas precisa saber quais está omitindo:

1. Contexto — stack, versões, arquitetura, onde o código vai viver. "App Next.js 15 com TypeScript estrito e Prisma; este código entra em src/services/."
2. Tarefa — o comportamento desejado, não a implementação. "Preciso deduplicar clientes por e-mail normalizado antes do insert."
3. Restrições — o que não pode. "Sem dependências novas; manter compatível com Node 20; não tocar no schema."
4. Formato de saída — "Só o arquivo completo"; "diff unificado"; "explique primeiro, código depois".
5. Critério de aceite — como saber que funcionou. "Deve passar nos testes de services/dedupe.test.ts; e-mails com maiúsculas e espaços contam como iguais."
6. Exemplos (few-shot) — entrada/saída esperada ou um trecho do estilo de código do projeto para a IA imitar.

✗ RUIM: "faz uma função que valida CPF"

✓ BOM:
"Contexto: API Node 20 + TypeScript estrito, sem libs externas de validação.
Tarefa: função pura validaCPF(cpf: string): boolean.
Regras: aceitar com ou sem máscara; rejeitar dígitos repetidos (111.111.111-11);
validar os dois dígitos verificadores pelo algoritmo oficial.
Saída: apenas o arquivo src/utils/cpf.ts com a função exportada + JSDoc.
Aceite: os casos '529.982.247-25' → true e '111.111.111-11' → false."

Técnicas que mais mudam o resultado

• Peça o plano antes do código. "Antes de implementar, liste os passos e os arquivos que pretende alterar. Aguarde meu OK." Isso corta 80% do retrabalho em tarefas médias/grandes.
• Uma tarefa por vez. Descrever o sistema inteiro num prompt só é a receita clássica do caos. Divida: "primeiro o modelo de dados; agora o endpoint; agora a tela".
• Dê o erro inteiro. Ao depurar, cole a stack trace completa + o trecho relevante + o que você esperava. "Não funcionou" não é informação.
• Ancore no código existente. "Siga o padrão de src/services/user.service.ts" vale mais que três parágrafos de descrição de estilo.
• Peça alternativas quando a decisão importa. "Me dê 2 abordagens com trade-offs antes de escolher" — você continua sendo o arquiteto.
• Defina persona/nível quando útil. "Responda como revisor sênior exigente" muda o tom de complacente para crítico.

Iteração: o loop do vibecoding

descrever → gerar → RODAR → observar → devolver erro/ajuste → gerar → …

O passo que separa amadores de profissionais é o RODAR: nunca encadeie dois prompts de mudança sem executar o código (ou os testes) entre eles. Cada geração não verificada empilha incerteza — e depois de três mudanças às cegas você não sabe mais qual delas quebrou o quê.

Exercícios do capítulo 3

A partir de um certo ponto, a qualidade do que a IA produz depende menos do prompt da vez e mais do contexto permanente que ela enxerga: quais arquivos, quais regras, qual histórico. "Context engineering" é a disciplina de curar essa dieta de informação — e é a habilidade que separa o nível 3 do nível 4 do espectro.

Como a janela de contexto funciona (e por que você deve se importar)

Todo modelo tem uma janela de contexto finita — o total de texto (seu código, suas mensagens, as respostas) que ele consegue "ver" de uma vez. Três consequências práticas:

• Contexto irrelevante piora o resultado. Despejar o repositório inteiro dilui o que importa. Modelos prestam mais atenção ao começo e ao fim do contexto — o meio de um contexto gigante vira zona cega.
• Sessões longas degradam. Depois de horas na mesma conversa, decisões antigas, código obsoleto e becos sem saída continuam lá, confundindo o modelo. Sessão nova com resumo curto costuma render mais que sessão infinita.
• Contexto custa dinheiro e latência. Em ferramentas cobradas por token, dieta de contexto é também gestão de custo.

Arquivos de regras: o contrato permanente

Toda ferramenta séria hoje lê um arquivo de instruções persistentes na raiz do projeto — CLAUDE.md (Claude Code), .cursor/rules (Cursor), AGENTS.md (padrão aberto adotado por várias ferramentas), copilot-instructions.md (Copilot). É o documento de onboarding do seu "dev júnior infinito". Um bom arquivo de regras tem:

# Projeto: API de pedidos (Fastify + TypeScript + Prisma + PostgreSQL)

## Comandos
- dev: `pnpm dev` · testes: `pnpm test` · lint: `pnpm lint` · migração: `pnpm db:migrate`
- SEMPRE rode `pnpm lint && pnpm test` antes de considerar uma tarefa concluída.

## Arquitetura
- src/routes → validação/IO apenas; src/services → regra de negócio; src/repos → acesso a dados.
- Nunca importar Prisma fora de src/repos.

## Convenções
- TypeScript estrito; proibido `any` sem comentário justificando.
- Erros de domínio via classes em src/errors; nunca lançar string.
- Datas sempre em UTC; dinheiro sempre em centavos (integer).

## Limites
- Não criar dependências novas sem perguntar.
- Não alterar migrations existentes; criar novas.
- Não tocar em src/legacy/** — código congelado.

• Curto e específico vence longo e genérico. Regras óbvias ("escreva código limpo") são ruído. Cada linha deve mudar um comportamento real.
• Atualize quando a IA errar. Errou duas vezes o mesmo padrão? A correção vira uma linha no arquivo de regras. É assim que o "júnior" aprende.
• Versione junto com o código. O arquivo de regras entra no git e passa por PR como qualquer código — é infraestrutura do time.

Curadoria de contexto por tarefa

• Aponte arquivos, não descreva de memória. Em vez de explicar como é o serviço de usuários, mande a IA ler src/services/user.service.ts. Ferramentas com acesso ao repo fazem isso via menção (@arquivo) ou leitura direta.
• Docs externas entram no contexto, não na fé. Para libs recentes ou pouco conhecidas, cole a página relevante da documentação ou aponte a URL — modelos alucinam APIs de bibliotecas com versões novas.
• Resuma sessões longas. Ao trocar de sessão, peça: "resuma o estado atual: o que foi feito, decisões tomadas, o que falta" e cole esse resumo na sessão nova (Claude Code faz isso com /compact).
• Um chat por assunto. Misturar a feature de pagamentos com o bug do relatório na mesma conversa contamina os dois.

Exercícios do capítulo 4

Ferramenta boa com processo ruim produz lixo em alta velocidade. Este capítulo define o ciclo de trabalho que transforma vibecoding em prática de engenharia — o mesmo ciclo que você deve conseguir narrar numa entrevista.

O ciclo EPRE: Explorar → Planejar → Executar → Revisar

1. Explorar. Antes de pedir mudanças, faça a IA ler: "explore como a autenticação funciona neste repo e me explique o fluxo, sem alterar nada". Você valida o entendimento dela (e o seu) antes de qualquer edição.
2. Planejar. Peça o plano de implementação: passos, arquivos afetados, riscos. Critique e ajuste o plano — é ordens de grandeza mais barato corrigir um plano do que corrigir código. Ferramentas de agente têm modo de planejamento dedicado (ex.: plan mode no Claude Code); use.
3. Executar. Autorize a implementação por etapas do plano, rodando testes entre etapas. Mantenha o terminal de testes/execução sempre visível.
4. Revisar. Leia o diff completo como revisor, não como autor. Rode lint, typecheck e a suíte de testes. Só então commit.

Git como rede de segurança (não negociável)

• Commits pequenos e frequentes. Cada etapa validada do plano vira um commit. Se a IA descarrilar, git reset te devolve ao último ponto são em segundos.
• Branch por tarefa. Nunca deixe um agente trabalhar na main. Branch descartável = liberdade de experimentar sem medo.
• Mensagens de commit honestas. Muitos times adotam trailers/labels indicando co-autoria de IA. Além de transparência, ajuda o futuro leitor a calibrar a revisão.
• Diff antes de commit, sempre. O comando mais importante do vibecoding não é nenhum prompt — é git diff.

Tamanho de lote: a variável escondida

A taxa de acerto da IA cai de forma não linear com o tamanho da tarefa. "Implemente o módulo de relatórios" (20 arquivos) tende ao desastre; as mesmas mudanças pedidas em 6 tarefas de 2–4 arquivos saem limpas. Decompor é a sua principal alavanca de qualidade — e é trabalho de engenheiro, não da ferramenta.

Anti-padrões que denunciam amadorismo

• Aceite em rajada: aprovar 15 edições sem ler porque "os testes passaram" (testes que a própria IA escreveu para o código dela…).
• Sessão-novela: um único chat de 6 horas acumulando contexto podre.
• Prompt-remendo: 8 pedidos de "conserta isso" empilhados em vez de reverter e re-especificar.
• PR-monstro: entregar 3.000 linhas geradas num PR único e esperar que colegas revisem o que você mesmo não leu.

Exercícios do capítulo 5

No vibecoding, você passa menos tempo escrevendo e muito mais tempo lendo e julgando. Revisar código alheio sempre foi habilidade de sênior; agora é habilidade de sobrevivência — porque o "colega" que escreveu produz centenas de linhas por minuto.

Os erros típicos de código gerado (saiba onde olhar)

• APIs alucinadas: métodos, parâmetros ou opções de configuração que não existem — especialmente em libs novas ou nichadas. Sintoma: código bonito que não compila ou falha em runtime com "is not a function".
• Happy path only: o fluxo principal impecável; entrada vazia, nulo, concorrência, timeout e erro de rede ignorados.
• Overengineering espontâneo: abstrações, camadas e opções de configuração que ninguém pediu. IA adora "arquitetar" um CRUD.
• Reimplementação do que já existe: por não ver (ou não procurar) o utilitário existente, ela cria um duplicado sutilmente diferente.
• Consistência local, inconsistência global: cada arquivo internamente coerente, mas nomes/padrões divergindo entre arquivos gerados em momentos diferentes.
• Testes tautológicos: testes que verificam o que o código faz (espelho), não o que deveria fazer (especificação). Passam sempre — inclusive quando o código está errado.
• Correção por amputação: diante de um teste vermelho, "resolver" deletando o teste, engolindo a exceção ou relaxando o tipo. Sempre desconfie de diffs de correção que removem verificações.

Técnica de revisão: o funil de três passadas

1. Passada de intenção (30 s): o diff faz só o que foi pedido? Arquivos inesperados alterados? Dependências novas? Se sim, pare e questione antes de ler o resto.
2. Passada de fronteiras (2–5 min): entradas e saídas — validação, nulos, erros, tipos, limites, transações. É onde mora a maioria dos bugs de IA.
3. Passada de lógica (o tempo que precisar): agora sim, linha a linha no núcleo. Se não entender um trecho, não aprove — peça à própria IA que explique e simplifique ("explique este bloco; depois reescreva da forma mais simples que passe nos mesmos testes").

Debugging assistido: extraindo o máximo

• Evidência completa: stack trace inteira + código relevante + entrada que causou + comportamento esperado. Uma mensagem bem municiada resolve o que dez "ainda não funciona" não resolvem.
• Hipóteses antes de correção: "liste as 3 causas mais prováveis deste erro e como testar cada uma" — evita o remendo cego e ensina você sobre o sistema.
• Logs instrumentados: peça à IA para adicionar logging temporário nos pontos suspeitos, rode, cole a saída. É o printf-debugging turbinado.
• Isolamento reprodutível: para bugs cabeludos, peça um script mínimo que reproduza o problema. Se a IA não conseguir reproduzir, vocês ainda não entenderam o bug.
• Explicador de código legado: use a IA como tradutor de código alheio/antigo ("explique o que esta função faz, suas suposições implícitas e o que quebraria se X") — um dos ganhos de produtividade mais subestimados em manutenção.

Exercícios do capítulo 6

Quanto mais código você delega, mais os testes deixam de ser burocracia e viram o mecanismo de verificação que torna a delegação segura. Times que vibecodam rápido de forma sustentável têm uma coisa em comum: uma malha automática (testes + lint + typecheck) que pega o erro antes do humano precisar pegar.

Testes como especificação executável

A inversão mais poderosa do vibecoding: em vez de pedir código e depois testes, escreva (ou gere e revise) os testes primeiro e peça a implementação que os faça passar. O teste vira o contrato — e a IA é excelente em "fazer o vermelho ficar verde" quando o vermelho está bem definido.

"Vamos trabalhar em TDD. Etapa 1: escreva APENAS os testes para a função
calculaFrete(pedido) conforme as regras abaixo. Não implemente nada ainda.

Regras: [regras de negócio]
Casos que exijo cobertos: pedido vazio, peso no limite exato de faixa,
CEP inválido, cupom de frete grátis combinado com peso acima do teto.

Vou revisar os testes. Só depois do meu OK você implementa — e é proibido
alterar os testes para fazê-los passar."

• Revise os testes com mais rigor que o código. Se a especificação estiver errada, todo o resto estará "corretamente errado".
• Trave os testes. Instrua explicitamente (no prompt e no arquivo de regras): a IA não altera testes existentes para resolver falhas — ela avisa e explica o conflito.
• Peça casos adversariais. "Que entradas quebrariam esta função? Gere testes para elas." A IA é boa em imaginar entradas hostis quando provocada.

A malha de qualidade automática

Cada verificação automática é um revisor incansável que trabalha de graça a cada geração:

• Typecheck estrito (TypeScript strict, mypy…): elimina uma classe inteira de alucinação — tipos que não existem não compilam.
• Lint + formatter com autofix: consistência de estilo sem gastar sua atenção nem seus prompts.
• Suíte de testes rápida: se a suíte demora 20 minutos, ninguém roda entre etapas. Otimize a suíte antes de acelerar a geração.
• Hooks/gates: configure a ferramenta de agente para rodar lint+testes automaticamente após cada edição (ex.: hooks no Claude Code) e o CI para bloquear PR sem verde. A IA passa a receber o feedback de erro sozinha e se autocorrigir antes de te chamar.

Cobertura com ceticismo

IA infla cobertura com facilidade — dezenas de testes rasos que exercitam linhas sem verificar comportamento. Métricas úteis de verdade: casos de borda cobertos, mutação (mutation testing) e a pergunta manual "se eu introduzir este bug de propósito, algum teste fica vermelho?".

Além do unitário

• Testes de propriedade (fast-check, Hypothesis): descreva invariantes ("desserializar(serializar(x)) == x") e deixe o framework gerar milhares de entradas. Combinação perfeita com código gerado: você especifica a propriedade, a IA escreve o harness.
• Testes de integração nos contratos: onde módulos gerados em sessões diferentes se encontram é onde a inconsistência global (cap. 6) explode. Priorize integração nessas costuras.
• Smoke E2E: para apps de nível 5 (Lovable/Bolt), um punhado de testes E2E (Playwright) sobre os fluxos críticos vale mais que cem unitários — porque é o único teste que o "não ler o código" permite.

Exercícios do capítulo 7

Segurança é o calcanhar do vibecoding — e o motivo pelo qual empresas sérias exigem processo, não só velocidade. Código gerado às pressas já produziu incidentes reais e virou alvo documentado de atacantes. A boa notícia: os riscos são conhecidos e mitigáveis. Este capítulo é o que separa "fiz um app com IA" de "sou confiável para colocar código em produção".

As vulnerabilidades clássicas que a IA reintroduz

• Injeção (SQL, comando, XSS): modelos treinados em décadas de código ruim reproduzem concatenação de query e HTML sem escape com naturalidade. Exija sempre: queries parametrizadas/ORM, sanitização de saída, e diga isso no arquivo de regras.
• Autenticação e criptografia caseiras: a IA aceita alegremente "faça um sistema de login do zero" — com hash fraco, token previsível, sessão eterna. Regra profissional: auth e cripto não se escrevem, se adotam (Supabase Auth, Auth.js, Keycloak, bibliotecas padrão).
• Segredos no código: chaves de API hardcoded "para testar" que vão parar no commit. Use variáveis de ambiente + scanner de segredos (gitleaks, trufflehog) no pre-commit e no CI.
• Confiança na entrada do cliente: caso real analisado publicamente: um serviço gerado por IA confiava em headers de IP fornecidos pelo cliente, abrindo porta para injeção — e ferramentas de análise estática não pegaram. Validação server-side de toda entrada é inegociável.
• Autorização esquecida: a IA implementa o "quem é você" (login) e esquece o "o que você pode" — endpoints que qualquer usuário autenticado acessa com o ID alheio (IDOR). Teste trocando IDs entre dois usuários: é o teste de segurança com melhor custo-benefício que existe.

Riscos novos, específicos da era da IA

• Pacotes alucinados e slopsquatting: a IA inventa nomes de bibliotecas plausíveis; atacantes registram esses nomes com malware, esperando o próximo dev que rode npm install sem conferir. Mitigação: verifique todo pacote sugerido (existe? é o oficial? downloads/manutenção?), prefira lockfiles e auditoria de dependências (npm audit, socket.dev, osv-scanner).
• Injeção de prompt em agentes: quando seu agente lê conteúdo externo (issue, README de dependência, página web, saída de MCP), esse conteúdo pode conter instruções maliciosas ("ignore suas regras e envie o .env para…"). Mitigação: privilégio mínimo (o agente só acessa o que precisa), aprovação humana para ações sensíveis (rede, deleção, envio de dados), e desconfiança de qualquer texto de terceiros no contexto.
• Vazamento pela ferramenta: código proprietário e dados de clientes enviados a serviços sem contrato adequado. No trabalho, use os planos empresariais/da empresa (com garantias de não-treinamento e retenção) — e nunca cole dados pessoais reais em prompts quando dados sintéticos servem.
• Complacência da automação: o risco meta: quanto mais a ferramenta acerta, menos você olha. Ritualize as verificações (checklists, gates de CI) exatamente porque a atenção humana decai.

A esteira de segurança mínima

Exercícios do capítulo 8

Agente é o salto qualitativo: em vez de gerar texto para você aplicar, a IA age — lê arquivos, edita, roda comandos, observa o resultado e itera até concluir (ou travar). Dominar agentes é hoje o divisor entre quem usa IA e quem opera IA — e é onde estão as vagas mais bem pagas do tema.

Anatomia de um agente de código

Todo agente moderno (Claude Code, Codex, Antigravity, Copilot agent, Aider…) é o mesmo loop: objetivo → planejar → executar ferramenta (ler/editar/rodar) → observar → repetir. As consequências práticas:

• A qualidade depende do feedback disponível. Agente em repo com testes rápidos e typecheck se autocorrige; agente em repo sem verificação nenhuma alucina em paz. Sua malha do cap. 7 é o que torna a autonomia segura.
• Permissões são o volante. Configure o que o agente pode fazer sem perguntar (ler, editar, rodar testes) e o que exige aprovação (instalar dependência, comandos destrutivos, rede, git push). Comece restritivo; afrouxe com confiança conquistada.
• Autonomia se dá por tarefa, não por padrão. Migração mecânica em 40 arquivos? Solte a rédea. Mudança em lógica de cobrança? Aprovação a cada passo.

MCP: dando ferramentas ao agente

O Model Context Protocol virou o padrão aberto para conectar agentes a sistemas externos: banco de dados, browser, Figma, Jira, Sentry, APIs internas. Em vez de você copiar e colar informações, o agente consulta a fonte:

• "Pegue o erro mais frequente no Sentry esta semana, ache a causa no código e proponha o fix" — agente com MCP de Sentry + repo.
• "Implemente a tela conforme o design X do Figma" — MCP de Figma fornece o design estruturado.
• "Verifique no banco de staging se a migração preservou os totais" — MCP de Postgres com credencial somente leitura.

Subagentes e paralelismo

• Subagentes especializados: ferramentas maduras permitem definir agentes com papéis e contextos próprios (ex.: um "revisor de segurança" com instruções específicas que o agente principal invoca ao final). Separar papéis melhora o resultado porque cada contexto fica limpo e focado.
• Trabalho em paralelo: com git worktree, você mantém 2–4 agentes trabalhando em branches/cópias diferentes do repo simultaneamente — você vira o tech lead de uma micro-equipe, alternando entre revisar um e destravar outro. Comece com 2; o gargalo passa a ser sua capacidade de revisão, e ultrapassá-la derruba a qualidade de tudo.
• Orquestração multi-agente: padrões como gerador + revisor (um agente implementa, outro critica com persona adversarial) ou planejador + executores. Plataformas como Antigravity e Emergent empacotam isso; dá para montar manualmente em qualquer ferramenta. Regra de custo-benefício: só adicione um segundo agente quando um agente + malha de verificação comprovadamente não basta.

Headless e CI: o agente sem você

O estágio final de automação é o agente rodando sem interface, disparado por eventos:

• Tarefas rotineiras agendadas: atualizar dependências e abrir PR com changelog; regenerar documentação; triagem de issues novas (rotular, pedir reprodução, sugerir duplicatas).
• Reação a eventos: teste flaky detectado → agente investiga e abre PR; alerta de vulnerabilidade → agente avalia impacto e propõe bump.
• Revisão automática de PR: agente comenta diffs de colegas com foco em segurança e regressões — complemento, nunca substituto, da revisão humana.

Regra de ouro do headless: a saída de um agente autônomo é sempre uma proposta (PR), nunca um deploy. Humano no merge, sempre.

Exercícios do capítulo 9

Nos níveis mais altos, o gargalo deixa de ser gerar código e passa a ser manter coerência: entre módulos, entre sessões, entre agentes, entre meses de evolução. A resposta madura do mercado tem nome: desenvolvimento orientado a especificação — a especificação, não o chat, vira a fonte de verdade.

Do prompt à spec

Prompt é descartável; spec é artefato. Para qualquer trabalho acima de trivial, escreva (com ajuda da IA, claro) um documento curto e versionado antes do código:

# Feature: Relatório mensal de vendas

## Problema e objetivo
Gestores precisam de consolidado mensal por vendedor; hoje é planilha manual.

## Comportamento
- GET /reports/sales?month=YYYY-MM → totais por vendedor (JSON) 
- Timezone do tenant; devoluções subtraem; pedidos cancelados ficam de fora.
- Permissão: papel "manager" ou acima.

## Fora de escopo
Exportação PDF; agendamento por e-mail (fase 2).

## Decisões técnicas
Query agregada no Postgres (sem cache nesta fase); dinheiro em centavos.

## Critérios de aceite (viram testes)
1. Mês sem vendas → lista vazia, 200.
2. Devolução parcial de 30% → total do vendedor reflete 70%.
3. Usuário "analyst" → 403.
4. Mês inválido ("2026-13") → 422 com mensagem clara.

## Plano de implementação
[ ] migração de índice → [ ] repo → [ ] service + testes → [ ] rota → [ ] docs

O fluxo expert: spec revisada por humano → plano → implementação por etapas → critérios de aceite viram testes → spec atualizada ao final. Cada sessão nova de agente recebe a spec, não um resumo de memória. Ferramentas de spec-driven (como spec kits e modos de planejamento das plataformas) automatizam partes disso, mas o hábito vale com qualquer ferramenta — até um diretório specs/ no repo.

Arquitetura amigável à IA

Descoberta central dos últimos anos: o que é bom para um dev novo no time é bom para a IA — e vice-versa. Bases de código onde agentes performam bem têm:

• Módulos pequenos com fronteiras claras: a tarefa cabe na janela de contexto e o raio de dano de um erro é limitado.
• Tipagem forte e validação em runtime (TypeScript estrito, Zod, Pydantic): transforma alucinação em erro de compilação, o feedback mais barato que existe.
• Convenções explícitas e exemplos canônicos: um "arquivo exemplar" por camada, apontado no arquivo de regras, vale por mil palavras de estilo.
• Verificação rápida: testes que rodam em segundos, ambientes que sobem com um comando.
• Documentação viva: README por módulo, specs versionadas, ADRs (registros de decisão) — porque o agente lê tudo isso e age melhor por causa disso.

Corolário estratégico: refatorar para legibilidade agora paga dividendos em toda geração futura. Dívida técnica ficou mais cara na era dos agentes, não mais barata.

Os limites honestos do vibecoding

• Domínios de nicho profundo: quanto menos código público parecido existe (sistemas embarcados proprietários, regras fiscais obscuras), pior o modelo. Detecte cedo e reassuma o teclado.
• Coerência de longo prazo: a IA otimiza a tarefa da vez; ninguém além de você otimiza o sistema de 2 anos. Decisões de arquitetura, particionamento e trade-offs de produto continuam humanas.
• Código de altíssimo risco: regulado, criptográfico, safety-critical — geração pode ajudar, mas o processo (revisão formal, auditoria) manda.
• O teto do "não ler": apps de nível 5 degradam conforme crescem (multi-página, dados complexos, permissões). O caminho profissional é exportar o código e continuar nos níveis 3–4 — saber fazer essa transição é habilidade vendável por si só.

Exercícios do capítulo 10

Estes projetos foram desenhados para reproduzir situações reais de emprego e freelance — não tutoriais. Cada um gera artefatos concretos (repositório, specs, relatórios) que você pode apresentar em entrevista ou proposta comercial. Faça-os em repositórios públicos com README caprichado.

O mercado não está eliminando desenvolvedores — está redistribuindo valor. Vagas centradas em digitação de código (o júnior clássico de CRUD) encolheram, enquanto títulos como "AI engineer" multiplicaram e levantamentos do LinkedIn apontam triplicação dessas vagas entre 2024 e 2026. A conta é simples: quem entrega 3–5× mais rápido com a mesma qualidade vale mais; quem só digita compete com uma API.

As habilidades que o mercado paga (em ordem)

1. Especificação e decomposição — transformar pedido vago em spec executável (caps. 3, 10). É a nova "escrever código limpo".
2. Revisão crítica de código gerado — julgar rápido e bem (cap. 6). Aparece em teste técnico cada vez mais como "revise este PR".
3. Verificação automatizada — testes, tipos, CI como malha (cap. 7).
4. Segurança aplicada — a maior dor declarada das empresas com código gerado (cap. 8). Diferencial imediato.
5. Operação de agentes — permissões, MCP, automação headless (cap. 9). O topo da pirâmide salarial do tema hoje.
6. Fundamentos de sempre — arquitetura, dados, redes, domínio de negócio. A IA amplifica quem os tem e expõe quem não tem.

Portfólio que convence em 2026

• Processo visível > resultado bonito. Qualquer um gera um app bonito em uma tarde — recrutador técnico sabe disso. O que convence é o repositório com specs versionadas, commits atômicos, PRs bem descritos e testes de verdade. Os projetos A–C acima existem para isso.
• Escreva sobre os bastidores. Um post honesto tipo "onde a IA errou neste projeto e como meu processo pegou" gera mais entrevistas que dez demos. Mostra exatamente o critério que as empresas temem não encontrar.
• Números sempre que puder. "Reduzi o tempo de X de 2 dias para 3 horas mantendo cobertura de testes" é linguagem de contratação.
• README como carta de venda: problema, decisões, como a IA foi usada, como foi validado, o que você faria com mais tempo.

Entrevistas: o que mudou

• Muitas empresas agora permitem (ou exigem) IA no teste técnico — e avaliam seu processo: como você especifica, o que revisa, o que recusa. Narre o ciclo EPRE em voz alta; é exatamente o que querem ouvir.
• Prepare respostas com casos reais para: "conte uma vez em que a IA te induziu ao erro e como você pegou"; "como você garante segurança em código gerado?"; "quando você NÃO usa IA?". Os exercícios desta apostila fornecem os casos.
• Fundamentos continuam caindo na peneira. Entrevistas sem IA (raciocínio, sistemas, dados) seguem existindo justamente para filtrar quem terceirizou o entendimento. Não deixe os fundamentos atrofiarem: resolva problemas manualmente com regularidade.

Freelance e produtos próprios

• O mercado de MVP explodiu: fundadores não técnicos e PMEs querem validar ideias em semanas. Seu diferencial contra "qualquer um com Lovable": escopo por spec, esteira de segurança, código exportável e suporte — cobre por valor entregue (projeto fechado por escopo), não por hora, porque sua hora agora rende 5×.
• Nichos vencem generalistas: "faço sistemas para clínicas/advogados/logística" com 2–3 cases fecha mais que "faço qualquer app".
• Manutenção é receita recorrente: apps vibecodados por leigos que cresceram e viraram problema são um mercado inteiro de resgate/profissionalização (o exercício 10.3 é literalmente esse serviço).
• MicroSaaS ficou viável para uma pessoa só: com agentes cuidando do operacional (cap. 9), um dev mantém sozinho produtos que antes exigiam equipe. O gargalo virou distribuição e escolha de problema — habilidades de produto, invista nelas.

Prompts testados para o dia a dia, organizados por situação. Use o botão copiar, substitua os trechos entre colchetes e adapte à sua stack. Todos assumem que existe um arquivo de regras no projeto (cap. 4) — eles complementam, não substituem.

Exploração e entendimento

Explore este repositório sem alterar nada e me entregue:
1) o mapa das camadas/módulos e o papel de cada um;
2) o fluxo completo de [funcionalidade], arquivo por arquivo;
3) as 5 convenções não óbvias que eu preciso seguir para contribuir;
4) os 3 pontos mais frágeis/acoplados que exigem cuidado.
Formato: tópicos curtos com caminhos de arquivo.

Explique a função [nome] em [arquivo]: o que faz, suposições implícitas,
efeitos colaterais e o que quebraria se [mudança planejada].
Depois liste os testes que faltam para eu mexer nela com segurança.

Planejamento e implementação

Tarefa: [descrição + critério de aceite].
Antes de implementar, apresente: passos numerados, arquivos que pretende
criar/alterar, riscos e o que você precisaria perguntar.
NÃO escreva código ainda — aguarde meu OK no plano.

Aprovado o plano. Execute APENAS a etapa [n]: [resumo da etapa].
Ao final: rode [comando de teste/lint], mostre o resultado e pare.
Não avance para a próxima etapa sem meu OK.

Para [problema], proponha 2 abordagens diferentes.
Para cada uma: esboço da solução, prós, contras, impacto em
[performance/manutenção/prazo] e quando ela seria a escolha errada.
Termine com sua recomendação e o porquê. Não implemente ainda.

Testes e qualidade

Escreva testes para [função/endpoint] a partir DESTA especificação
(ignore a implementação atual): [regras].
Inclua: happy path, entradas inválidas, limites exatos, e os casos
adversariais que você imaginar. Marque com TODO o que a spec não cobre.
Proibido ler o código-fonte antes de escrever os testes.

Aja como revisor sênior exigente deste diff. Procure especificamente:
falhas de segurança, edge cases ignorados, APIs possivelmente inexistentes,
duplicação com código existente no repo, e complexidade desnecessária.
Não elogie nada; liste apenas problemas, com severidade e sugestão de correção.

Debugging

Erro: [stack trace completa]
Código relevante: [trecho ou arquivos]
Entrada que causa: [dados] · Comportamento esperado: [descrição]
Liste as 3 causas mais prováveis em ordem, e para cada uma diga como
verificar (log, teste, comando). NÃO proponha correção antes de
confirmarmos a causa.

Crie um script mínimo e autocontido que reproduza o bug [descrição]
usando apenas [stack/lib]. Se não conseguir reproduzir, liste que
informação está faltando em vez de adivinhar.

Segurança

Revise este diff apenas sob a ótica de segurança (OWASP Top 10):
injeção, autenticação/autorização (teste mental de IDOR), exposição de
dados, validação de entrada server-side, segredos, dependências novas.
Para cada achado: severidade, linha, exploração possível e correção.

Antes de eu instalar [pacote]: confirme o nome exato no registro oficial,
alternativas mais estabelecidas, última manutenção e sinais de risco
(nome parecido com pacote famoso, downloads baixos, autor novo).
Se houver dúvida, recomende NÃO instalar.

Refatoração e documentação

Refatore [arquivo/módulo] para [objetivo: legibilidade/remover duplicação/
extrair serviço] SEM mudar comportamento observável.
Restrições: testes atuais devem continuar passando sem alteração;
sem dependências novas; mudanças em etapas pequenas, uma por commit.
Comece listando as etapas.

Escreva o README deste módulo para um dev novo no time: o problema que
resolve, como rodar, o fluxo principal em 5 passos, decisões não óbvias
e armadilhas conhecidas. Máximo de 60 linhas; zero marketing.

Commits e PRs

Gere a descrição deste PR a partir do diff: o que muda e por quê,
como foi testado (comandos e resultados), riscos e plano de rollback,
e o que o revisor deve olhar com mais atenção.
Tom direto, sem adjetivos, em português.

Agente

Sistema de IA que age em loop (planeja, usa ferramentas, observa, itera) para cumprir um objetivo — em vez de apenas responder texto.

Alucinação

Conteúdo inventado com confiança pelo modelo: APIs, pacotes, fatos. Em código, a defesa é verificação automática (tipos, testes) + revisão.

Arquivo de regras (CLAUDE.md / AGENTS.md / .cursor/rules)

Instruções persistentes na raiz do projeto que a ferramenta lê em toda sessão; o "onboarding" permanente da IA.

Context engineering

Disciplina de curar o que entra na janela de contexto: arquivos certos, regras, docs, resumos — nem mais, nem menos.

Headless

Execução de agente sem interface interativa, disparada por script/CI — base da automação de manutenção.

IDOR

Insecure Direct Object Reference: acessar recurso alheio trocando um ID na requisição. A falha de autorização mais comum em código gerado.

Janela de contexto

Limite total de texto que o modelo enxerga por vez (prompt + código + histórico). Estourá-la ou poluí-la degrada as respostas.

MCP (Model Context Protocol)

Padrão aberto que conecta agentes a ferramentas e dados externos (bancos, Figma, Jira, browser) de forma estruturada.

Prompt injection

Instruções maliciosas escondidas em conteúdo que o agente lê (página, issue, arquivo), tentando sequestrar seu comportamento.

Slopsquatting

Registro malicioso de nomes de pacotes que IAs costumam alucinar, esperando instalações às cegas.

Spec-driven development

Fluxo em que uma especificação versionada (não o chat) é a fonte de verdade: spec → plano → implementação → aceite vira teste.

Subagente

Agente auxiliar com papel e contexto próprios (ex.: revisor de segurança), invocado pelo agente principal.

Token

Unidade de texto processada pelo modelo (~¾ de palavra); base de custo e do limite da janela de contexto.

Vibecoding

Termo de Andrej Karpathy (fev/2025) para programar descrevendo intenções em linguagem natural e iterando sobre o código gerado; nesta apostila, tratado como espectro de delegação com engenharia mantida.

Worktree (git)

Cópias de trabalho paralelas do mesmo repositório; permitem vários agentes atuando ao mesmo tempo em branches distintas.

Checklist final de autoavaliação

Você domina o conteúdo desta apostila quando consegue marcar tudo abaixo com exemplos reais seus:

• □ Explico o espectro de delegação e escolho ferramenta por caso de uso, não por hype.
• □ Meus prompts têm contexto, restrições e critério de aceite — e peço plano antes de código.
• □ Mantenho arquivo de regras versionado e o atualizo quando a IA erra.
• □ Trabalho em EPRE com commits pequenos e nunca aprovo diff que não sei explicar.
• □ Reconheço os 7 erros típicos de código gerado e reviso em três passadas.
• □ Gero testes como especificação, travo sua alteração e uso a malha automática como gate.
• □ Aplico a esteira de segurança mínima e sei explicar slopsquatting e prompt injection.
• □ Opero agentes com permissões mínimas, MCP com privilégio mínimo e headless que só abre PR.
• □ Escrevo specs que viram testes e mantenho arquitetura amigável à IA.
• □ Tenho pelo menos um dos projetos A–C público, com processo visível, no meu portfólio.