Escolher a superfície certa

Chat, coding agent e API podem usar modelos relacionados, mas entregam controles diferentes. ChatGPT favorece conversa, arquivos e artefatos. Codex e Claude Code operam sobre repositórios com ferramentas e instruções persistentes. Uma API coloca em seu software a responsabilidade por mensagens, estado, ferramentas, validação, telemetria — métricas e rastros técnicos — e custo. Escolha pela operação necessária, não por marca.

Use chat para explorar um conceito, revisar um documento e construir entendimento com uma pessoa presente. Use coding agent quando a tarefa exige ler o repositório, editar arquivos e executar verificações. Use API quando o comportamento precisa fazer parte de um produto repetível, com autenticação, políticas e observabilidade próprias.

Pergunta	Chat	Coding agent	API
Quem conduz?	pessoa	agente sob instruções do repo	aplicação/harness
Estado	conversa/produto	tarefa + arquivos	você projeta
Verificação	revisão humana/artefato	comandos e comparação das alterações (diff)	testes e avaliações automatizadas (evals)
Risco	dado enviado	alteração no workspace	efeito em usuários

Antes de escolher: o que significa “superfície”

Neste capítulo, superfície não quer dizer apenas a aparência da tela. É o conjunto de controles por onde uma pessoa ou um programa usa o modelo. A superfície determina quem fornece contexto, quem autoriza ações, onde o estado permanece, como uma falha aparece e quem precisa provar que o resultado está correto.

Uma analogia útil é comparar três maneiras de trabalhar com um especialista. No chat, você conversa com o especialista na mesma mesa e corrige o rumo continuamente. No coding agent, você entrega acesso controlado à oficina, indica o serviço e exige inspeções. Na API, você contrata o especialista para participar de uma linha de produção: agora sua aplicação precisa controlar entrada, ritmo, permissões, qualidade e parada. A analogia termina aí. Modelos não assumem responsabilidade, podem variar entre execuções e não devem receber autoridade apenas porque produziram uma frase convincente.

Alguns termos aparecerão ao longo da comparação. Um harness é a camada do seu sistema que monta contexto, chama o modelo, oferece ferramentas, limita a execução e registra resultados. Uma tool call é um pedido estruturado para executar uma ferramenta; o modelo propõe a chamada, mas o software decide se ela é válida e autorizada. Um schema descreve o formato aceito para dados. Uma sandbox é um ambiente com acesso limitado; uma worktree é uma área de trabalho Git separada, ligada ao mesmo repositório, para isolar alterações. Nenhum desses mecanismos substitui testes ou autorização.

O que acontece quando você usa ChatGPT

1. A pessoa escreve uma mensagem e, quando necessário, anexa arquivos.
2. O produto compõe instruções, histórico e recursos habilitados.
3. O modelo produz texto ou solicita uma ferramenta oferecida pelo produto.
4. A interface apresenta a resposta e mantém a conversa conforme as regras daquele produto.
5. A pessoa avalia, corrige e decide o que aproveitar.

O chat é adequado quando perguntas e critérios ainda estão mudando. Ele é especialmente útil para aprender, confrontar alternativas, redigir um documento e eliminar a “névoa” antes de transformar a intenção em especificação. O chat não é automaticamente um processo reproduzível: duas conversas podem conter contextos diferentes, e uma decisão importante pode ficar perdida no histórico. Quando uma decisão precisa sobreviver, registre-a no artefato correto — especificação, registro de decisão arquitetural (ADR), teste, documentação ou ticket.

O que muda em Codex ou Claude Code

Um coding agent recebe ferramentas para observar e modificar um ambiente de desenvolvimento. Ele pode procurar arquivos, ler instruções persistentes, alterar código e executar testes. Isso não o transforma em “programador sem supervisão”; transforma a tarefa em um sistema com mais capacidade e, portanto, com mais necessidade de limites.

O repositório é parte do contexto. Arquivos como AGENTS.md ou CLAUDE.md registram regras estáveis; uma skill carrega um procedimento especializado sob demanda; testes e integração contínua (CI) transformam expectativas determinísticas em verificações. O agente deve receber o menor escopo coerente: um ticket vertical — uma pequena capacidade ponta a ponta —, os caminhos relevantes, comandos de validação e uma condição de parada.

Entrada útil para um coding agent
├── objetivo verificável
├── arquivos e interfaces em escopo
├── regras persistentes do repositório
├── comandos de teste, typecheck e lint
├── ações proibidas ou que exigem confirmação
└── evidência que encerra o trabalho

Se você disser apenas “melhore o sistema”, o agente precisa adivinhar qual problema, quais usuários e qual evidência importam. Se disser “na rota de conclusão da OS, impeça duplicidade usando a chave já presente no contrato; preserve a API; execute os testes X e Y”, o espaço de decisão fica observável.

O que muda quando você usa uma API

Na API, o modelo passa a ser um componente do seu produto. Seu backend escolhe modelo e parâmetros, monta mensagens, oferece ferramentas, valida saída e registra telemetria. O provedor executa inferência; ele não conhece automaticamente suas regras empresariais, permissões ou fonte de verdade.

Observe a separação: o modelo pode propor concluir_ordem, mas a aplicação valida o schema e a identidade, verifica a unidade, consulta o estado atual e só então executa. A autorização sugerida pelo modelo nunca substitui a política do servidor.

Uma árvore de decisão prática

Comece pelo risco e pela repetibilidade:

1. A tarefa é exploratória e uma pessoa acompanhará cada passo? Comece no chat.
2. O resultado exige ler e alterar um repositório com testes? Use um coding agent em sandbox ou worktree.
3. O comportamento atenderá usuários ou outros sistemas repetidamente? Projete uma integração por API e um harness.
4. A ação produz efeito externo, financeiro, irreversível ou sobre dados pessoais? Adicione autorização fora do modelo, confirmação proporcional e auditoria.
5. Você ainda não consegue escrever o teste ou critério de aceite? Volte à descoberta; trocar de ferramenta não remove a ambiguidade.

Não existe hierarquia em que API seja sempre “mais avançada” e chat seja “menos profissional”. Para investigar um requisito raro, a conversa acompanhada pode ser mais segura e barata. Para classificar milhares de chamados segundo um contrato estável, uma API avaliada pode ser adequada. Para alterar 40 arquivos com testes, um coding agent tem ferramentas que o chat comum não oferece.

Mesmo pedido, três execuções

Para entender aprovação de OS, no chat envie requisitos e peça um mapa de dúvidas. No coding agent, aponte ticket/spec, autorize arquivos e forneça comandos de teste. Na API, implemente a ferramenta (tool) read_order, schema de saída, autenticação, tempo limite (timeout) e rastreamento (trace). Copiar a conversa do chat para as instruções de sistema da API não cria um produto confiável.

Uma instrução de coding agent pode ser:

Leia AGENTS.md e docs/specs/approval.md. Implemente T-014.
Não mude o provedor de identidade. Execute testes de domínio e contrato.
Pare se regra e código divergirem e mostre os caminhos conflitantes.

Já uma API precisa de controle fora do modelo:

const decision = DecisionSchema.parse(await callModel(input));
authorize(user, decision);
const result = await executeWithTimeout(decision);
audit.redacted({ userId: user.id, action: decision.kind });

Esse trecho é deliberadamente incompleto como aplicação, mas cada linha ensina uma fronteira:

• DecisionSchema.parse rejeita uma saída que não respeita o formato esperado;
• authorize usa a identidade e as regras do seu sistema, não a confiança do modelo;
• executeWithTimeout impede espera ilimitada e precisa de idempotência — repetir a operação sem duplicar seu efeito — quando houver nova tentativa (retry);
• audit.redacted registra o necessário sem despejar senha, token ou conteúdo sensível.

Uma implementação de produção também precisa tratar indisponibilidade do provedor, limite de taxa, cancelamento, custo, observabilidade, retenção e avaliação. O exemplo não deve ser copiado como se quatro linhas resolvessem toda essa operação.

Três pedidos bem formados para a mesma necessidade

No chat: aprender antes de decidir

Quero entender como aprovar uma ordem de serviço.
Faça uma pergunta por vez sobre atores, estados, permissões e consequências.
Quando houver mais de uma opção, compare riscos e recomende uma.
Ao final, produza um glossário e uma lista de decisões ainda abertas.
Não escreva código nesta etapa.

No coding agent: implementar uma fatia verificável

Implemente o ticket T-014 descrito em docs/specs/approval.md.
Leia as instruções do repositório e localize o contrato existente antes de editar.
Escopo: domínio, endpoint e teste ponta a ponta (**E2E**) da aprovação; não altere o provedor de identidade.
Negue aprovação quando usuário e OS pertencem a unidades diferentes.
Execute testes de domínio, contrato, checagem de tipos (*typecheck*) e análise estática (*lint*).
Pare se especificação e código divergirem e apresente os caminhos conflitantes.

Na API: contrato do comportamento repetível

{
  "operation": "suggest_work_order_priority",
  "input": {
    "description": "odor de queimado no quadro geral",
    "location": "subsolo B",
    "equipmentState": "operating"
  },
  "requiredOutput": {
    "priority": "immediate | high | normal | unknown",
    "reasons": ["string"],
    "missingInformation": ["string"]
  },
  "policy": "a sugestão nunca encerra nem aprova a OS"
}

Aqui o JSON representa dados e contrato; não é uma linguagem que “programa a IA”. TypeScript, Python ou Java implementam o backend que cria a requisição, chama o provedor, valida a resposta e aplica as regras.

Versões e portabilidade

Recursos, nomes de campos, modelos e limites mudam. Verifique a documentação da superfície e versão usadas. Preserve um contrato interno (ModelGateway) se troca de fornecedor for requisito real, mas não esconda diferenças relevantes atrás do “menor denominador comum”. Um coding agent também possui regras próprias de instruções, sandbox e confirmação; não suponha equivalência.

Falhas e segurança

Erros recorrentes: colocar chave de API no frontend; enviar dados sem base legal; conceder escrita quando leitura basta; assumir que o histórico é memória permanente; confiar em saída sem schema; e executar ferramenta usando apenas a autorização sugerida pelo modelo. Credenciais ficam no backend/secret manager. Autoridade é recalculada no momento da ação.

Diagnóstico por sintoma

Sintoma	Causa provável	Próxima verificação
A resposta ignora uma decisão antiga	decisão ficou apenas no histórico	procurar spec, ADR ou teste que deveria preservá-la
O agente altera arquivos fora do ticket	escopo e permissões amplos	revisar instruções, sandbox e caminhos autorizados
A API retorna JSON quase correto	ausência de saída estruturada ou validação	validar schema e registrar a resposta rejeitada sem dados sensíveis
O custo cresce a cada turno	histórico reenviado sem seleção	medir tokens de entrada, compactar e usar ponteiros
Uma tool executa ação proibida	modelo recebeu autoridade implícita	mover autorização para política determinística do backend
Usuário vê “erro de IA” para tudo	falhas distintas foram agrupadas	separar timeout, rate limit, recusa, schema e falha de dependência

Critérios de aceite para a escolha

Sua decisão está pronta quando registra:

• quem inicia e quem permanece responsável;
• quais dados entram e onde podem ser armazenados;
• que ferramentas ou arquivos ficam acessíveis;
• qual saída é esperada e como será validada;
• qual ação exige autorização ou confirmação;
• como timeout, indisponibilidade e resultado inválido aparecem;
• qual teste, avaliação ou revisão prova qualidade suficiente;
• qual condição encerra a execução.

Se esses itens não podem ser preenchidos, a lacuna não é “falta de prompt perfeito”; é uma decisão de produto ou engenharia ainda não realizada.

O menor sistema que resolve o problema

Escolher a superfície também significa recusar complexidade prematura. Se Cleiton ainda está descobrindo quais estados uma ordem de serviço pode assumir, uma conversa acompanhada permite formular perguntas e corrigir o vocabulário com baixo custo. Conectar uma API nesse momento apenas automatizaria uma regra ainda instável. Depois que a regra estiver documentada e possuir exemplos aceitos e rejeitados, um coding agent pode implementar uma fatia no repositório, porque agora existem arquivos, testes e uma condição objetiva de parada. A API só entra quando essa capacidade precisa atender usuários ou sistemas de forma repetível.

O mesmo princípio limita a chamada “Era Maestro”. Um fluxo com vários agentes não é o próximo passo obrigatório depois do chat. Primeiro demonstre que um único agente, com uma ferramenta estreita e uma avaliação clara, não atende ao caso. Só promova a solução para workflow, loop avaliado ou grafo orquestrado quando houver uma falha observável, uma hipótese de melhoria, uma métrica e um orçamento de custo e risco. Se o ganho não aparecer, remova a camada adicional.

Use esta sequência como verificação:

1. descreva o trabalho manual e a evidência de sucesso;
2. escolha a superfície mais simples que consegue produzir essa evidência;
3. limite dados, arquivos, ferramentas e duração;
4. provoque pelo menos uma falha esperada;
5. compare qualidade, tempo, custo e risco antes de aumentar autonomia.

Assim, “mais avançado” deixa de significar “mais agentes” e passa a significar “responsabilidade mais bem definida e resultado melhor demonstrado”.

Antes e agora

Antes, chat era tratado como interface única e automação significava colar respostas. Hoje existem superfícies próprias para repositório e APIs com tools, saídas estruturadas e traces. O chat continua superior quando o trabalho é exploratório e requer julgamento contínuo; API não é upgrade automático.

Exercício

Classifique dez tarefas reais entre chat, coding agent e API. Para três delas, escreva entrada, autoridade, saída, evidência e falha segura. O aceite exige justificativa ligada a repetibilidade, acesso e risco — “prefiro esta ferramenta” não basta.

Como referência de feedback, “resumir uma ata confidencial uma única vez” tende ao chat acompanhado se a política permitir o envio; “corrigir uma regra já especificada e protegida por testes” tende ao coding agent; “classificar chamados recebidos continuamente” pode justificar uma API. Mude a escolha se os dados, a autoridade ou a exigência de repetibilidade mudarem. Se sua resposta não nomeia essas condições, refaça a justificativa.

Conclusão

A superfície certa é a menor que oferece contexto, ferramentas e verificação suficientes para o trabalho. Chat favorece descoberta acompanhada; coding agents atuam em repositórios sob escopo e testes; APIs exigem que sua aplicação assuma estado, política, observabilidade e falha segura. Em todas elas, o modelo propõe resultados, mas pessoas e sistemas determinísticos preservam a responsabilidade e a autoridade.

Fontes

• OpenAI — visão geral do ChatGPT
• OpenAI — instruções persistentes com AGENTS.md
• OpenAI — sandbox do Codex
• OpenAI — worktrees no Codex
• OpenAI — Responses API
• OpenAI — saídas estruturadas
• Anthropic — Claude Code best practices
• OWASP — Authorization Cheat Sheet
• OWASP — Secrets Management Cheat Sheet