De código para intenção

Antes de tudo, um vocabulário comum. Um chatbot responde e espera. Um agente roda o próprio loop: você dá o objetivo, ele decide o próximo passo.

A escalada: do autocomplete à autonomia

O loop do agente — clique em cada etapa

As 5 peças de todo agente

Em fev/2025, Andrej Karpathy descreveu o vibe coding: "entregue-se ao vibes, esqueça que o código existe". O termo viralizou — e virou guarda-chuva confuso. Em 2026, o próprio Karpathy propôs engenharia agêntica para a ponta disciplinada. Não é binário: é um espectro. O diferencial não é se você usa IA — é quanta estrutura, verificação e julgamento humano cerca o output.

A qualidade do código gerado depende menos da esperteza do prompt e mais da qualidade do contexto fornecido. A pergunta não é "como engano a IA?" — é: "o que um novo membro do time precisaria saber para contribuir bem, e como codifico isso?"

Os 6 tipos de contexto que todo agente precisa

Estático × Dinâmico: o trade-off de arquitetura

O que é estático e o que é dinâmico é uma decisão de arquitetura de primeira classe — revisada e versionada como qualquer configuração. Estático demais desperdiça tokens; de menos e o agente esquece regras críticas.

Agent Skills — o padrão vencedor (clique nas abas)

skills_disponiveis:
  - deploy-agent:    "deploy de agentes ADK no Agent Runtime"
  - eval-runner:     "roda evalsets e reporta regressões"
  - db-migration:    "migrações seguras de schema"
  - legacy-refactor: "refatoração de código legado"
  ... (dezenas de outras)

carregando skill: deploy-agent
  ✓ checklist de pré-deploy (env vars, permissões)
  ✓ passos de publicação no Agent Runtime
  ✓ regras de rollback automático

referência profunda: deploy-agent/reference.md
  ✓ catálogo completo de flags do agents-cli
  ✓ matriz de permissões por ambiente
  ✓ runbook de incidentes de deploy

Skills resolvem 4 problemas clássicos: context rot (prompts sobrecarregados), falta de memória procedural dos LLMs, overhead de arquiteturas multi-agente e a necessidade de portabilidade entre ferramentas e vendors.

A IA comprime o ciclo de forma desigual: implementação que levava semanas agora leva horas, enquanto requisitos, arquitetura e verificação seguem em ritmo humano. O resultado não é um SDLC antigo mais rápido — é um fluxo diferente, com fases que se misturam e iterações de minutos.

A compressão (animada)

Fase por fase — explore

O modelo mental que amarra tudo: a produção principal do desenvolvedor não é o código — é o sistema que produz código. Um gerente de fábrica não monta cada peça à mão: desenha a linha de montagem e garante o controle de qualidade.

As 5 peças da sua fábrica

É tentador tratar o modelo como o sistema: "saiu modelo novo, o agente ficou mais esperto". Essa intuição está errada. O modelo é uma entrada. Todo o resto — prompts, ferramentas, políticas de contexto, hooks, sandboxes, sub-agentes, observabilidade — é o harness: o andaime que deixa o modelo terminar as coisas.

O harness em cada fase do SDLC

Dois modos de trabalho entre os quais você vai alternar fluidamente. Nenhum é "melhor" — cada um serve a um tipo de tarefa.

O problema dos 80% — clique na barra

Três lugares no seu dia — e a maioria dos devs usa os três no mesmo dia. O ponto de partida certo depende da tarefa, não de qual categoria está mais acima na escada de autonomia.

E quando o produto é um agente?

Um bot de suporte, um assistente de pesquisa, um monitor de compliance — esses não são tarefas para um agente de codificação resolver: são produtos que precisam de memória persistente, permissões com escopo, cobertura de evals e observabilidade próprios. O mesmo fluxo de terminal que produz scripts de protótipo agora alcança esses agentes de produção — o ciclo construir → avaliar → deploy → observar → refinar mora num lugar só:

A conversa costuma começar e terminar em "quão rápido escrevemos código?". Para líderes, a métrica crítica é o TCO — e na era da IA, o OpEx é ditado pela economia dos tokens.

Contexto como alavanca financeira + roteamento inteligente

8 perguntas cobrindo todo o guia. Sem pressa — a explicação de cada resposta faz parte do estudo.

Três artefatos que você pode usar hoje. Clique em copiar e cole no seu projeto.

# AGENTS.md

## Stack
TypeScript 5.x · Next.js 15 · Postgres (Drizzle ORM) · Vitest

## Convenções
- Funções puras sempre que possível; erros via Result<T, E>, nunca throw solto
- Nomes em inglês, comentários explicando "por quê", não "o quê"
- Todo handler de API valida input com zod antes de tocar no banco

## Regras rígidas (inquebráveis)
- NUNCA commitar segredos; usar env vars via .env.local
- NUNCA instalar dependência sem confirmar comigo
- NUNCA modificar migrations já aplicadas em produção

## Workflow
1. Leia docs/ antes de implementar  2. Escreva o teste primeiro
3. Rode `pnpm test` até verde       4. Descreva o diff antes do commit

# REVIEW DE CÓDIGO GERADO POR IA

[ ] Importações reais      — cada pacote existe? versão compatível?
                              (alucinação de dependência é o erro nº 1)
[ ] Nada "esperto demais"   — se parece clever demais, desconfie;
                              código que o time não entende = dívida
[ ] Error handling real     — cobre modos de falha realistas, não só
                              o happy path que passa no teste
[ ] Edge cases do negócio   — a IA não conhece sua regra de estorno;
                              verifique pressupostos da lógica de negócio
[ ] Trajetória, não só output — o agente RODOU os testes ou só disse
                              que rodou? confira logs / hooks de CI
[ ] Segredos e permissões   — nada hardcoded; escopo mínimo de acesso
[ ] Você explicaria este diff — se não consegue explicar, não embarque

# O NOVO SDLC — MAPA MENTAL

mudança     : sintaxe → intenção (você diz O QUÊ, a máquina o COMO)
espectro    : vibe coding ──────── ia-assistido ──────── eng. agêntica
divisor     : verificação (testes = determinístico · evals = não-determ.)
habilidade  : engenharia de contexto (6 tipos: instrução, conhecimento,
              memória, exemplos, ferramentas, guardrails)
trade-off   : contexto estático (sempre pago) × dinâmico (pago sob demanda)
padrão-chave: Agent Skills — generalista leve vira especialista sob demanda
fábrica     : seu output é o SISTEMA que produz código, não o código
harness     : AGENTE = MODELO + HARNESS · falhas de agente ≈ falhas de config
papéis      : maestro (tempo real) ⇄ orquestrador (assíncrono, multi-agente)
80/20       : IA faz 80% rápido; seu valor está nos 20% (edge, integração, sutileza)
economia    : vibe = CapEx↓ OpEx↑↑ · agêntico = CapEx↑ OpEx↓ + roteamento de modelos
lema        : "Geração está resolvida. Verificação, julgamento e direção são o novo ofício."

Marque as caixas conforme avança. O progresso fica salvo no seu navegador.

Este guia é o Dia 1 de uma série. O paper aponta explicitamente dois companions que aprofundam os temas introduzidos aqui — anote para onde ir depois.

As fontes originais que fundamentam este guia, para quando você quiser ir além do resumo.

As notas de rodapé numeradas do paper original, para você rastrear cada afirmação até a fonte.