como funciona: loop, tools, skills • MCP, ACP, subagents, reasoning • context, compact, hardening • Claude Code, Codex, OpenCode, Cursor • agile + agente: técnicas para controlar alucinação Prática • setup do agente • planejar antes de codar • TDD guiando o agente • persistência e MCP runtime • subagents em paralelo • quando o agente erra: freio e rollback
tools e Agents SDK viram produto mai 2025 Claude 4 pensa entre tool calls; Claude Code vira GA nov 2025 GPT-5.1 + Codex CLI; Opus 4.5 + Claude Code maduro jan 2026 Agentes em workflow real: CLI, skills, MCP, subagents Não foi um dia mágico. Foi o ano inteiro fechando modelo, thinking, tool support e operação.
qualquer ferramenta, o ganho depende mais de quem usa do que da ferramenta em si. Bom engenheiro com IA vai mais longe. Programador ruim com IA produz lixo mais rápido. IA é espelho — te acelera no que você já é.
acessa ferramentas, executa ações no seu sistema e itera até o objetivo. LLM o cérebro probabilístico Tools ler, escrever, rodar, buscar Loop age, observa, ajusta, repete Contexto memória da sessão
pedido → 2 Investiga lê arquivos, pesquisa → 3 Age edita, roda comandos → 4 Observa lê saída, testes, erros → 5 Ajusta corrige curso ou conclui O pulo do gato não é QI mágico — é ter ferramenta, execução e feedback DENTRO do loop, em segundos.
no sistema Skills conhecimento empacotado MCP protocolo de ferramentas ACP protocolo de editor Subagents delegação Reasoning quanto pensa antes Compact gestão do contexto Veremos cada um a seguir →
próxima linha • você aceita ou rejeita • não sabe o estado do projeto • não executa nada • não testa, não busca, não lê arquivos • trabalho ainda é 100% manual Code Agent (2026) • recebe uma tarefa em linguagem natural • lê seu repositório inteiro • edita múltiplos arquivos • roda testes, lint, build, git • ajusta curso sozinho quando algo quebra • itera até entregar
o modelo "vê" na hora de responder: system prompt, histórico da conversa, arquivos abertos e saída de ferramentas. Pensa como a RAM do agente: limitada, cara, compartilhada. • system prompt (instruções permanentes) • mensagens da sessão • arquivos que o agente leu • saída de cada tool call • skills carregadas sob demanda CONTEXT WINDOW ~200k tokens (Claude) • ~400k (Codex GPT-5.4) • 1M+ (Gemini) system prompt ~8% AGENTS.md / CLAUDE.md ~6% arquivos lidos ~22% saída de tools ~18% conversa ~14% livre ~32%
que ele "vê" Cada mensagem no contexto tem um "role" — um rótulo que diz de onde veio. Entender os roles é entender quem manda no quê. ROLE QUEM ESCREVE O QUE CONTÉM system a ferramenta (Anthropic, OpenAI) identidade, capacidades, guardrails. Você raramente modifica. project você — persistente por repo AGENTS.md / CLAUDE.md / .cursorrules. Injetado a cada sessão. user você — por mensagem a tarefa, a pergunta, o feedback. Cada coisa que você digita. assistant o modelo a resposta anterior. Vira contexto pro próximo turno. tool as tools (bash, read, MCP) saída de tool call. O modelo lê como mensagem especial. Quanto mais alto na pilha, mais fixo. Quanto mais baixo, mais efêmero e frequente.
contexto enche. Quando enche, o agente ou perde memória recente ou compacta o que já passou. Como funciona O agente resume a conversa passada num "sumário" compacto e descarta mensagens antigas, preservando intenção e decisões. O que se perde Detalhes exatos de código, stack traces, conteúdo de arquivos antigos. A cola fica, os rabiscos vão embora. Compact preventivo No Claude Code: /compact. No OpenCode: Ctrl+R. Use antes de tarefas grandes, não depois do estouro. Dica: termine a tarefa atual antes de compactar. /compact no meio confunde o agente.
passa por uma tool. O modelo decide qual chamar, com quais argumentos, e lê o resultado no próximo turno. Read ler arquivos Edit / Write modificar e criar arquivos Bash executar comandos Grep buscar por padrão Glob listar arquivos por pattern WebFetch ler páginas da web MCP tools ferramentas externas TodoWrite gerir sua própria to-do
SKILL.md e arquivos auxiliares. Descreve uma capacidade específica: "criar PPTX", "rodar TDD", "revisar PR". A mágica: o agente só carrega a skill quando o description bate com a tarefa. Contexto fica limpo. • carregamento sob demanda • reutilizáveis entre projetos • versionadas em git • podem ter código, templates, exemplos skills/tdd-cycle/ ├── SKILL.md │ name: tdd-cycle │ description: Use when │ writing new features. │ Enforces red-green- │ refactor. │ ├── templates/ │ ├── rspec-example.rb │ └── exunit-example.exs │ └── scripts/ └── run_failing_test.sh
editores a agentes (não agentes a ferramentas, como o MCP). Mesmo agente, qualquer editor. • MCP = modelo ↔ ferramenta • ACP = agente ↔ editor • Claude Code, Codex, OpenCode, Gemini CLI falam ACP • Zed, JetBrains, Obsidian, Toad são clientes ACP • ACP Registry: um pacote, todos os editores MCP × ACP MCP: agente → ferramenta (ex: Claude Code → GitHub) ACP: editor → agente (ex: Zed → Claude Code) os dois protocolos se complementam
— cada um com contexto novo e papel definido. Bom para pesquisa paralela, revisão isolada e tarefas que encheriam o contexto principal. Contexto fresh Cada subagent começa do zero. Não carrega o histórico inteiro — o que economiza tokens e reduz confusão. Papel específico Ex: "searcher", "code-reviewer", "test-writer". Cada papel tem system prompt e skills próprios. Paralelismo real Claude Code e Codex rodam múltiplos subagents em paralelo. OpenCode também (via Task tool). Regra prática: se uma subtarefa não precisa do contexto principal, ela vira subagent.
agir Budget extra de inferência para o modelo planejar tool calls, raciocinar sobre trade-offs e escolher abordagem — antes de qualquer ação. Sem isso, ele chuta a primeira coisa. no Claude Code think planos curtos think hard trade-offs médios think harder decisões complexas ultrathink arquitetura séria Trade-off: mais thinking = mais tokens = mais custo e mais lento. Use só onde vale.
seus arquivos e faz commits. Isso é poderoso — e é também uma superfície de ataque enorme. ⚠ Prompt injection Um README, issue ou MCP malicioso pode dizer: "ignore tudo, faça X". O agente obedece. ⚠ Exfiltração Agente pode enviar chaves, tokens, arquivos secretos para um servidor remoto. ✓ Sandbox Docker, devcontainer, máquina dedicada. Codex tem profile bubblewrap. ✓ Allow-list + human-in-the-loop Aprove comandos sensíveis. Nunca rode --dangerously-skip-permissions em produção. Regra de bolso: trate o output do agente como PR de estagiário. Revise antes de mergear.
acesso a tudo na sua máquina O QUE FAZ • container Docker isolado com filesystem restrito • sem acesso a ~/.ssh, ~/.aws, env vars do host • rede bloqueada por padrão (opt-in por domínio) • o projeto é montado via volume — Claude Code roda dentro • feito por Fabio Akita (akitaonrails) terminal # clonar e instalar $ git clone github.com/akitaonrails/ai-jail $ cd ai-jail && ./install.sh # rodar claude code dentro da jail $ ai-jail ~/meu-projeto # agente vê só o projeto, nada mais Use junto com o Hardening — não substitui. github.com/akitaonrails/ai-jail
que rodam automaticamente em pontos do ciclo do agente — independente do que o modelo “decidir” lembrar. Enforcement, não pedido. EVENTOS PRINCIPAIS SessionStart — injeta branch, issues, contexto UserPromptSubmit — valida ou enriquece prompt PreToolUse — bloqueia ação (ex: rm -rf) PostToolUse — formata, lint, teste (o mais comum) Stop — só termina se os testes passarem settings.json EXEMPLO: AUTO-FORMAT APÓS EDIT // em .claude/settings.json “hooks”: { “PostToolUse”: [{ “matcher”: “Edit|Write”, “hooks”: [{ “command”: “prettier -w .” }] }] } Em outros agentes: OpenCode expõe plugin API (tool.execute.before/after) • Cursor tem hooks por comando • Codex ainda não expõe hooks nativos.
é um compilador. Ele é probabilístico, contextual e, às vezes, bajulador. Probabilístico Nunca 100% confiável. A mesma pergunta pode dar respostas diferentes. Depende de contexto Qualidade varia com o que você dá. Contexto ruim = saída ruim. Bajula você Muitas vezes concorda com sua premissa, mesmo quando ela está errada. Conclusão: execução, teste e revisão continuam obrigatórios. Não delegue julgamento.
que resolve seu problema. Às vezes ela existe. Às vezes ele a inventa com confiança. Gem / package inexistente require 'fancy_http' que ninguém publicou Método que não existe user.magic_authenticate! que só existe na cabeça dele Endpoint inventado "segundo a API da OpenAI"... não é bem assim Path errado app/services/email_sender.rb (você tem mailers/) Assinatura trocada args na ordem errada, tipos errados Versão incompatível código de Rails 8 num projeto Rails 6 Antídoto: fazer o agente EXECUTAR o código. Teste passando > afirmação confiante.
você quer… o melhor pra código agent hoje → Claude Code ecossistema OpenAI / ChatGPT Pro → Codex CLI trocar de provider (local, Groq, etc) → OpenCode IDE completa com tab completion → Cursor
— pensa antes de agir • thinking: think / think hard / ultrathink • Subagents nativos (Task tool) • Skills (sob demanda, via descrição) • /compact, /clear, /resume • MCP nativo (claude mcp add) • hooks e background tasks • CLAUDE.md: contexto persistente do projeto Modelo Claude Opus 4.7 + Sonnet 4.6 e Haiku 4.5 Planos Pro $20/mês Max 5x $100 / 20x $200 API por token Plataforma macOS • Linux • Windows (WSL)
(Bubble Tea / Go) • funciona com qualquer provider: Anthropic, OpenAI, Google, Groq, Bedrock, OpenRouter, local… • Build mode + Plan mode (Tab para alternar) • arquitetura cliente/servidor (TUI remoto!) • MCP nativo + fala ACP (opencode acp) • AGENTS.md + subagents • LSP integrado (diagnostics p/ o agente) Modelo qualquer um (você escolhe o provider) Custo tool: grátis paga só os tokens do provider escolhido Plataforma macOS • Linux • Windows
Tab completion (o melhor do mercado) • Composer 2 — edição multi-arquivo • Agent mode (local e cloud agents) • Cursor 3: workspace de agentes multi-repo • plugins com MCPs, skills, subagents • compatível com extensões VS Code • .cursorrules — contexto persistente • bring your own model (ou usa Composer) Modelo Composer 2 (próprio) + Claude, GPT-5, Gemini Planos Hobby (grátis) Pro $20/mês Business (por seat) Plataforma macOS • Linux • Windows
/ Linux $ curl -fsSL https://claude.ai/install.sh | bash # Windows (PowerShell) $ irm https://claude.ai/install.ps1 | iex Alternativas • primeiro uso alternativas # Homebrew $ brew install --cask claude-code # npm (legado) $ npm install -g @anthropic-ai/claude-code primeiro uso # navega pro projeto e roda $ cd ~/meu-projeto $ claude # autentica via browser (Pro/Max) Requer conta paga: Claude Pro $20/mês, Max $100/$200, ou API key.
(recomendado) $ npm install -g @openai/codex # com Homebrew (macOS) $ brew install --cask codex Autenticação e primeiro uso primeiro uso $ cd ~/meu-projeto $ codex # escolha 'Sign in with ChatGPT' (ou API key) # modo headless pra scripts: $ codex exec "corrija o bug em user_service.ts" Requer ChatGPT Plus/Pro/Business ou OpenAI API key. Windows: WSL recomendado.
seu setup install # script oficial (simples) $ curl -fsSL https://opencode.ai/install | bash # ou via npm | ou via Homebrew $ npm i -g opencode-ai@latest $ brew install opencode Configure o provider e comece primeiro uso # login no provider $ opencode auth login # depois, no projeto $ cd ~/meu-projeto && opencode Custa só os tokens do provider. Pacman/Scoop/Nix/Mise também funcionam.
Apple Silicon) • Windows (x64 / ARM) • Linux (AppImage / .deb) Instalador ~150 MB • < 60 segundos • importa settings do VS Code em 1 clique Primeiros passos dentro do Cursor 1. Import VS Code Na primeira abertura: "Import All". 2. Sign in Login com email — ativa o plano Hobby grátis. 3. Tab + Cmd+K Tab = completion. Cmd+K = edita inline. 4. Composer 2 Cmd+I — edição multi-arquivo, plan mode incluso.
agente escrever uma linha 1 O que eu quero O objetivo descreva a feature ou comportamento esperado, sem jargão de impl. 2 Como Stack e restrições técnicas linguagem, framework, libs que já existem, padrões do projeto 3 O que não quero Guardrails e anti-patterns mocks, gems não aprovadas, mudar banco de dados, tocar arquivos fora do escopo 4 Validação Critérios de sucesso testes que devem passar, comportamento observável, condições de parada Os 4 blocos podem ser o Idea.md. Escreva uma vez, reutilize em todo prompt.
você já fez Extreme Programming, você já sabe trabalhar com agente. Os mesmos ciclos, as mesmas práticas — com um pair que digita mais rápido. TDD segura o erro do modelo antes de virar lama Review por commit pega drift e regressão cedo Refatoração contínua evita cirurgia cara depois Pair programming você julga, o agente executa A disciplina velha é o que torna o agente confiável. Sem ela, só sobra velocidade pra errar.
semântico. Sem ele, "implementa X" vira roleta. Com ele, o agente tem um oráculo pra saber se acertou. 🔴 Red Peça ao agente pra escrever o teste primeiro. Revise. Rode. Confirme que falha como esperado. 🟢 Green Agora sim peça a implementação. O agente sabe exatamente quando parar: quando o teste passa. 🔵 Refactor Com teste verde, peça pra simplificar. A malha de testes te protege da refatoração. prompt padrão $ Claude Code: "Escreva o teste primeiro, rode, mostre que falha. Só depois implemente até o teste passar."
de 8 horas. Dê quinze tarefas de 20 minutos. ❌ Big bang • "Construa o sistema de autenticação inteiro" • agente tenta fazer tudo de uma vez • contexto lota, começa a alucinar • se algo quebra, todo o diff quebra • git diff ilegível — não dá pra revisar ✓ Iterações pequenas • 1. modelo User com teste • 2. signup com validação + teste • 3. login + session + teste • 4. logout + teste • 5. recuperação de senha + teste git é seu freio de emergência. Commit a cada passo verde.
— código é só a saída Escreva um documento (Idea.md, RFC, SPEC.md) antes do código. O agente lê, pergunta, implementa. O time revisa a spec, não o diff. ✓ Vantagens • Clareza antes de implementação. Conflitos aparecem na review da spec, não no PR. • Contexto portátil. Qualquer agente (ou dev novo) começa do zero com a mesma base. • “Pronto” objetivo. Critérios de aceitação viram testes — sem ambiguidade. • Auditável. Você compara o construído contra o pedido — no texto, não no chat. • Recomeçar é barato. Chat poludo? Nova sessão. A spec continua lá. ⚠ Trade-offs • Custo upfront. Escrever spec dá trabalho — ruim para protótipo descartável. • Spec desatualiza. Se ninguém atualiza, vira folclore. Precisa disciplina. • Sobre-especificação. Decidir impl. demais na spec sufoca boas opções técnicas. • Obediência literal. O agente segue a spec mesmo quando a realidade mudou. • Ruim pra exploração. Pesquisa/spike não cabe num formato “spec → implementa”. Quando usar: features de médio/grande porte, trabalho em equipe, código que vai durar. Quando evitar: spikes, protótipos, scripts one-shot.
investiga, lê arquivos, propõe um plano — mas não escreve nada. Você revisa. Se aprovar, ele executa. Claude Code shift + Tab para alternar Plan ↔ Auto-accept OpenCode Tab alterna entre Build e Plan Codex CLI prefixe a tarefa: 'plan first, then execute' Cursor Composer em Chat mode = plan; Agent mode = execute Para tarefas > 30 min de trabalho: SEMPRE peça plano antes. O custo é zero e evita retrabalho.
qualidade do contexto. Curar contexto é tão importante quanto escrever código. AGENTS.md / CLAUDE.md instruções persistentes no root do projeto: stack, convenções, o que evitar @ menciona arquivo cite o arquivo exato em vez de deixar o agente procurar Skills sob demanda conhecimento empacotado por tarefa (TDD, refactor, debug) MCPs relevantes só os que a tarefa exige — MCP a mais polui o contexto Peça citação "mostre o arquivo:linha antes de modificar" — reduz invenção Não encha de lixo colar log de 10k linhas = enche contexto = agente perde foco
pra qualquer agente. 1. Execute, não invente rode o código. Teste passando > afirmação confiante. 2. Peça citação "mostre o arquivo:linha onde isso está definido" 3. Teste primeiro TDD faz o agente saber quando parou 4. Contexto curado AGENTS.md + skills + @ arquivo — reduz chute 5. Peça plano antes plan mode expõe suposições erradas antes de custar 6. Commits pequenos se algo errou, rollback é um git reset Se o agente tá travando, o problema quase sempre é contexto — não modelo.
• diretório de lojas e serviços de Guarapuava-PR • busca full-text ordenada por popularidade (likes) • página por loja: logo, fotos, mapa embutido, contato • seções: curated shops, novidades e promoções • cadastro de usuários + admin via Administrate • seed com ~100 estabelecimentos reais (Google Maps) A stack do projeto 🔴 Rails 8 SQLite · Tailwind · Hotwire · ActiveStorage · RSpec 📦 Gems principais devise · administrate · image_processing Convenções Rails puras: Scaffolds + Hotwire. Sem SPA. Sem API-only. O Idea.md é o spec — o agente lê antes de tudo. ↓ Idea.md do projeto
spec. O agente lê e cria a aplicação. setup # em um diretório vazio $ mkdir tem-em-guarapuava && cd tem-em-guarapuava $ cp ~/Idea.md . && git init && git add Idea.md $ git commit -m "docs: spec" # Tidewave (opcional): gem "tidewave", group: :development # adicione ao Gemfile e rode bundle install Adicione o AGENTS.md no mesmo diretório AGENTS.md Leia o Idea.md antes de qualquer ação. Crie toda a aplicação Rails seguindo o Idea.md. TDD: escreva o teste antes. Use FactoryBot, não mocks. Rode bin/rspec antes de considerar qualquer task pronta.
Descreva o objetivo. Deixe o agente perguntar. plan # prompt inicial (com Idea.md no root) > [shift+Tab → Plan Mode] > Leia o Idea.md no root. Não escreva código ainda. > > 1. Liste as models Rails que você vai criar > 2. Proponha o schema (tabelas, colunas, índices) > 3. Liste rotas RESTful e controllers necessários > 4. Mostre a ordem de implementação. Pare aqui. Revise o plano procurando por: Assunções erradas ele achou que já existia algo que não existe Falta de escopo tá querendo fazer tudo de uma vez? Suposições de stack usou gem que você não vai querer
feature por vez. O teste vem antes do código. prompt # primeira feature: home page (3 seções) > Implemente apenas a home page com as 3 seções. > Passo a passo (TDD): > > 1. Escreva spec/system/home_spec.rb verificando > curated shops, novidades e promoções > 2. Rode bin/rspec e me mostre o erro > 3. Crie models + seed mínimo + view para passar > 4. Rode novamente, confirme verde > 5. Commit: "feat: home page 3 seções" > NÃO implemente busca ainda. Seed com 3 lojas fake apenas.
contexto. Delegue. AGENTE PRINCIPAL Subagent #1 code-reviewer revisa os arquivos criados pelo passo 3; devolve bullet list de problemas Subagent #2 docs-writer gera README.md e API docs a partir dos controllers e specs Subagent #3 test-auditor varre specs em busca de testes frágeis ou sem asserção Claude Code: "rode 3 subagents em paralelo, um por tarefa". Codex: sub-agents v2 com endereços.
usa bem e quem não usa é como reage. 🛑 Pare. Não force. Se o agente entrou num loop de correção, INTERROMPA. Insistir com o mesmo contexto piora. 🔍 Olhe o git diff Antes de qualquer coisa: git diff e git status. O que ele realmente mudou? (spoiler: nem sempre é o que ele diz que mudou) ⏪ Reverta sem dó git reset --hard / git checkout -- <file>. Commits pequenos tornam isso barato. Você vai usar isso MUITO. 🔄 Novo chat > debug longo Às vezes o contexto já está poluído. Abra nova sessão, carregue só o essencial, recomece a subtarefa.
✓ Commits organizados mensagens claras, histório legível ✓ AGENTS.md atualizado reflete o estado real do projeto ✓ README gerado alguém novo consegue subir o projeto? ✓ Sem segredos no repo chaves, tokens, senhas — varra o diff ✓ CI configurado os testes rodam sozinhos a cada push
Igual engenheiro júnior. Disciplina > modelo TDD, CI, commits pequenos. O mesmo XP de sempre. Contexto é engenharia AGENTS.md + skills + MCPs certos > modelo maior Plan mode sempre pra tarefas > 30min, plano antes de código Execute, não acredite teste passando > afirmação confiante do modelo Git é seu freio comite a cada passo. Reverter deve ser barato. IA é espelho: se você é engenheiro, fica 5-10x mais rápido. Se não é, fica exposto 5-10x mais rápido.
adbatista
reverentgeek
tammyeverts
baasie
chriscoyier
kimpetersen
shlominoach
mayatellez
marcelosomers
caitiem20
codingconduct
inesmontani
