IA para desenvolvedores: agentes de programação, custos e delegação segura

Como fazer

1. 1Antes de entregar a tarefa, escreva ou indique a verificação: o teste que falha, ou o comando e a saída esperada.
2. 2Passe a tarefa com o prompt desta página, incluindo os arquivos que ele pode alterar e os que não pode.
3. 3Deixe que ele mesmo rode a verificação e cole a saída final.
4. 4Revise o diff como o pull request de um colega; uma verificação que passa começa a revisão, não a encerra.

Recurso nativo

• ChatGPT · Codex
• Claude · Claude Code

Prompt para copiar

Tarefa: [mudança].
Pronto significa: [teste ou comando] passa e imprime [saída esperada]. Rode antes de terminar e cole o resultado.
Você pode alterar: [caminhos]. Não altere: [caminhos], as dependências nem os testes.
Se não conseguir fazer passar, pare e explique por quê, em vez de contornar a verificação.

Onde dá errado

• Às vezes os agentes fazem um teste passar enfraquecendo-o. Proíba alterar testes e procure por isso no diff.
• Uma tarefa grande demais para uma verificação é grande demais para uma única delegação. Divida-a.

Como fazer

1. 1Escolha o que fica mais perto do seu código: Codex Cloud, o Copilot cloud agent no GitHub ou o Claude Code na web.
2. 2Garanta que o ambiente dele consiga instalar suas dependências e rodar seus testes; sem isso, o agente está chutando.
3. 3Envie tarefas pequenas e independentes, cada uma com sua própria verificação, como na tarefa acima.
4. 4Deixe um revisor automático ler cada pull request primeiro e depois revise você mesmo.

Recurso nativo

• Codex · Codex Cloud
• GitHub Copilot · Copilot cloud agent
• Claude Code · Claude Code on the web (cloud sessions)

Prompt para copiar

Neste repositório: [tarefa].
Contexto: [onde no código, issue relacionada].
Pronto quando: [teste ou comando] passar no seu ambiente; coloque a saída na descrição do pull request.
Mantenha o pull request com menos de [n] linhas alteradas. Se precisar de mais, pare e proponha como dividi-lo.

Onde dá errado

• Testes que precisam de segredos ou serviços que você não configurou são pulados ou falham. Uma execução verde sem eles prova pouco.
• Vários agentes trabalhando em código relacionado produzem pull requests em conflito. Mantenha as tarefas paralelas em áreas separadas.

Como fazer

1. 1Coloque seus comandos de build, teste e lint no arquivo de instruções que o agente lê no início de cada sessão; a documentação de cada agente diz qual é o arquivo.
2. 2No Claude Code, adicione hooks que rodam o formatador e os testes depois de cada edição, para que o agente veja as falhas e as corrija.
3. 3Faça um bot revisar cada pull request: ative “Automatic review” no Codex ou peça o Copilot como revisor.
4. 4Quando o agente cometer o mesmo erro duas vezes, transforme-o em um teste ou em uma regra no arquivo de instruções.

Recurso nativo

• Claude Code · Hooks
• Codex · Codex code review
• GitHub Copilot · Copilot code review

Prompt para copiar

Leia este repositório e escreva o arquivo de instruções para agentes de programação:
1. Os comandos exatos para instalar, fazer build, testar, rodar o lint e formatar.
2. A estrutura do projeto em 10 linhas ou menos.
3. Convenções que quem chega erra aqui, com um exemplo de cada.
4. O que um agente nunca deve fazer aqui, por exemplo alterar migrations ou editar arquivos gerados.
Liste só os comandos que você executou com sucesso; marque os demais como “não verificado”.

Onde dá errado

• Um arquivo de instruções com comandos que não funcionam mais ensina o agente a ignorá-lo. Rode-os de novo quando a configuração mudar.
• Bots de revisão também erram com segurança. Trate os comentários deles como sugestões.

Como fazer

1. 1Liste o que você mais cola nas conversas, como issues, logs de erro, documentação ou o schema. Conecte isso primeiro.
2. 2Adicione o servidor MCP oficial de cada um, com um token que só pode ler. No Gemini CLI, uma extensão pode reunir o servidor MCP e a configuração dele.
3. 3Dê ao agente uma tarefa que precise deles e confira se ele chamou o certo.
4. 4A cada poucas semanas, remova os servidores que você não usa mais.

Recurso nativo

• Gemini CLI · Extensions

Prompt para copiar

Antes de alterar qualquer coisa: leia a issue [id] no tracker, encontre o erro nos logs e consulte a documentação de [biblioteca].
Diga o que cada um mostrou e qual arquivo você acha que tem o problema.
Não escreva em nenhuma ferramenta conectada.

Onde dá errado

• Uma página da web, uma issue ou um documento podem conter texto escrito para manipular o agente. Não dê acesso de escrita a ferramentas que leem conteúdo de fora.
• Tokens em arquivos de configuração vazam. Use o armazenamento de segredos do cliente ou variáveis de ambiente, nunca o repositório.

Como fazer

1. 1Confira o que você já paga: os planos do ChatGPT incluem o Codex, e os planos pagos do Claude incluem o Claude Code.
2. 2Anote o uso de tokens de algumas sessões típicas, onde o seu agente mostrar isso.
3. 3Calcule o preço desse uso na nossa página de preços de API e compare com a assinatura.
4. 4Para automação e CI, use chaves de API com limite de gastos, para que um loop não gere uma conta alta.

Recurso nativo

• ChatGPT · Codex
• Claude · Claude Code

Prompt para copiar

Este é o meu uso em [n] sessões típicas: [tokens de entrada e de saída]. Trabalho cerca de [dias] dias por semana.
Estime meu custo mensal por token com estes preços: [cole da página de preços de API].
Compare com uma assinatura de [preço] por mês. Mostre as contas para que eu possa conferir.

Onde dá errado

• Assinaturas também têm limites de uso. Atingir um no meio de uma tarefa custa tempo; confira o limite, não só o preço.
• O modelo muda a conta mais do que qualquer outra coisa. Compare usando o modelo que você realmente usa.

Como fazer

1. 1Rode /init no repositório: ele analisa a base de código e escreve um CLAUDE.md inicial, ou sugere melhorias no que você já tem.
2. 2Mantenha as regras da equipe, como comandos de build e de teste e padrões de código, em ./CLAUDE.md e faça commit dele. Suas preferências pessoais vão em ~/.claude/CLAUDE.md, para todos os projetos, ou em CLAUDE.local.md, só para este.
3. 3Aponte para documentos mais longos em vez de colá-los: @path/to/file importa outro arquivo na inicialização.
4. 4Cada vez que o Claude errar a mesma coisa duas vezes, adicione a linha que teria evitado o erro.

Prompt para copiar

Leia este repositório e melhore o CLAUDE.md. Mantenha-o com menos de 60 linhas:
1. Os comandos exatos para fazer build, testar e rodar o lint.
2. A estrutura em poucas linhas.
3. Convenções que quem chega erra aqui.
4. Arquivos e pastas que nunca devem ser editados.
Remova tudo o que não for mais verdade. Marque os comandos que você não executou como “não verificado”.

Onde dá errado

• Tudo no CLAUDE.md é carregado em toda sessão e ocupa contexto. Mova os detalhes para arquivos que ele importa.
• Instruções que deixaram de ser verdade são piores do que nenhuma. Confira os comandos de novo quando a configuração mudar.

Da documentação oficial: Claude Code docs: How Claude remembers your project

Como fazer

1. 1Pressione Shift+Tab até a barra de status mostrar “plan mode on”, ou comece seu prompt com /plan.
2. 2Descreva a mudança e o que não pode mudar. O Claude ainda pode rodar comandos para explorar, mas não edita arquivos enquanto planeja.
3. 3Leia o plano como um documento de design: um arquivo errado, um caso esquecido, uma mudança grande demais. Peça ajustes até ficar certo e então aprove.
4. 4Antes da próxima tarefa, sem relação com esta, recomece do zero com /clear.

Prompt para copiar

/plan Altere [o quê] para que [objetivo]. Restrições: [o que não pode mudar].
Liste os arquivos em que você vai mexer, a ordem das mudanças, o teste que prova cada passo e tudo de que você não tem certeza. Não edite nada até eu aprovar.

Onde dá errado

• Um plano que mexe em mais arquivos do que você esperava é o sinal de alerta. Pergunte por quê antes de aprovar.
• O plan mode ainda roda comandos para explorar. Ele não torna seguro rodar um repositório desconhecido.

Da documentação oficial: Claude Code docs: Choose a permission mode · Claude Code docs: Commands · Claude Code docs: Best practices

Como fazer

1. 1Abra /permissions para ver todas as regras e de qual arquivo de configuração cada uma vem.
2. 2Coloque as regras da equipe em .claude/settings.json e faça commit. As regras pessoais vão em ~/.claude/settings.json ou .claude/settings.local.json.
3. 3As regras são verificadas nesta ordem: primeiro deny, depois ask, depois allow; por isso uma regra deny vence qualquer allow.
4. 4Troque de modo com Shift+Tab: acceptEdits aprova edições de arquivos no diretório de trabalho. bypassPermissions desativa as confirmações e as verificações de segurança; a documentação diz para usá-lo apenas em contêineres isolados ou VMs sem acesso à internet.

Prompt para copiar

Veja os comandos que você executou nesta sessão. Proponha regras de permissão para .claude/settings.json: permita os comandos somente de leitura e de teste que usamos todo dia, bloqueie tudo o que lê segredos ou apaga fora do projeto e deixe todo o resto pedindo confirmação. Explique cada regra em uma linha.

Onde dá errado

• Uma regra allow que vale para qualquer comando é o mesmo que não ter confirmações. Permita comandos exatos.
• As regras em .claude/settings.json valem para a equipe toda depois do commit. Revise-as como código.

Da documentação oficial: Claude Code docs: Configure permissions · Claude Code docs: Settings files and precedence · Claude Code docs: Choose a permission mode

Como fazer

1. 1Entre tarefas sem relação, /clear inicia uma nova conversa com o contexto vazio.
2. 2Numa tarefa longa, /compact com um foco, por exemplo “/compact mantenha o plano e o teste que falha”, resume o que veio antes.
3. 3Passe buscas amplas para um subagente: cada um roda na própria janela de contexto, então só a resposta dele volta para a sua sessão.
4. 4O Claude Code também compacta sozinho perto do limite; compactar você mesmo num bom momento preserva o que você escolher.

Recurso nativo

• Claude Code · Subagents

Prompt para copiar

/compact Mantenha: o objetivo, o plano, os arquivos alterados até agora e o teste que ainda falha. Descarte a exploração.

Onde dá errado

• /clear esquece a conversa. Tudo de que você vai precisar de novo deve ir antes para o CLAUDE.md.
• A resposta do subagente é tudo o que volta para você. Peça caminhos de arquivo e números de linha, não só conclusões.

Da documentação oficial: Claude Code docs: Commands · Claude Code docs: Best practices · Claude Code docs: Create custom subagents

Como fazer

1. 1Inicie cada sessão com claude --worktree <name> (ou -w). Ele cria um git worktree em .claude/worktrees/<name>/ na branch worktree-<name>.
2. 2Adicione .claude/worktrees/ ao .gitignore, como a documentação recomenda.
3. 3Dê a cada sessão uma tarefa com sua própria verificação, para poder revisá-las uma por uma.
4. 4Revise cada branch e faça merge dela como de qualquer outro pull request.

Prompt para copiar

Você está trabalhando em um worktree na branch worktree-[nome]. Tarefa: [uma mudança]. Pronto quando: [teste ou comando] passar. Faça commit só nesta branch; não faça merge nem rebase de outras branches.

Onde dá errado

• Cada worktree é uma pasta própria, então as dependências e a saída do build não são compartilhadas. Instale em cada um.
• Duas tarefas que mexem nos mesmos arquivos ainda entram em conflito no merge, com ou sem worktree.

Da documentação oficial: Claude Code docs: Run parallel sessions with worktrees

Como fazer

1. 1Pressione Esc duas vezes com o prompt vazio ou digite /rewind (/checkpoint e /undo também funcionam).
2. 2Escolha o ponto antes de as coisas darem errado e restaure a conversa, o código ou os dois.
3. 3Conheça os limites: arquivos alterados por comandos de shell como rm, mv ou cp não são restaurados, nem edições feitas fora do Claude Code ou em outra sessão.
4. 4Faça commit antes de passos arriscados. Checkpoints servem para uma recuperação rápida dentro de uma sessão, não substituem o git.

Prompt para copiar

Antes de começar, faça commit do estado atual com a mensagem “checkpoint antes de [tarefa]”. Depois, [tarefa]. Me pergunte antes de qualquer comando que apague ou mova arquivos.

Onde dá errado

• O rewind não traz de volta um arquivo que um comando apagou. Só o git faz isso.
• Edições que você fez à mão nesse meio-tempo também não são registradas. Faça commit delas antes de usar o rewind.

Da documentação oficial: Claude Code docs: Checkpointing · Claude Code docs: Commands

Como fazer

1. 1claude -p "..." roda sem interação. --output-format json ou stream-json gera uma saída que um script consegue interpretar.
2. 2Ele sai com 0 em caso de sucesso e com um valor diferente de zero em caso de falha, então o CI pode decidir o que fazer com base nisso.
3. 3Adicione --bare no CI para execuções que não dependem da configuração local.
4. 4Para pull requests, /install-github-app configura o Claude Code GitHub Actions (só repositórios no github.com); depois mencione @claude em um comentário de pull request ou de issue.

Prompt para copiar

claude -p "Leia o diff em relação à main. Liste toda mudança que adiciona uma dependência, mexe na autenticação ou altera uma migration do banco de dados, como JSON: {\"files\": [], \"reason\": \"\"}. Retorne uma lista vazia se não houver nenhuma." --output-format json

Onde dá errado

• Um script roda com as permissões que você dá a ele. Dê ao CI o mínimo de que ele precisa.
• /install-github-app só funciona com repositórios no github.com.

Da documentação oficial: Claude Code docs: Run Claude Code programmatically · Claude Code docs: GitHub Actions

Como fazer

1. 1Rode /init no CLI para escrever um AGENTS.md inicial na pasta atual.
2. 2Coloque orientações pessoais em ~/.codex/AGENTS.md e as regras do projeto no repositório. Uma subpasta pode ter o próprio arquivo; os arquivos mais próximos de onde o Codex trabalha prevalecem.
3. 3Mantenha os arquivos curtos: o tamanho somado deles tem um limite, 32 KiB por padrão.
4. 4Adicione uma seção “## Code Review Rules”: as revisões do Codex no GitHub seguem essa seção.

Prompt para copiar

Leia este repositório e escreva o AGENTS.md:
1. Os comandos exatos para instalar, fazer build, testar e rodar o lint.
2. A estrutura em poucas linhas.
3. Convenções que quem chega erra aqui.
4. Uma seção “## Code Review Rules” com o que um revisor deve sempre apontar.
Liste só os comandos que você executou com sucesso; marque os demais como “não verificado”.

Onde dá errado

• Arquivos longos jogam contra você: o tamanho somado tem limite de 32 KiB por padrão.
• Um arquivo de subpasta que contradiz o da raiz sem avisar confunde as pessoas tanto quanto o Codex. Diga o que ele substitui.

Da documentação oficial: Codex docs: AGENTS.md · Codex docs: CLI commands · Codex docs: GitHub integration

Como fazer

1. 1No CLI, /permissions troca o modo, e /status mostra a política de aprovação e as pastas graváveis em vigor.
2. 2“Ask for approval”, o padrão recomendado, edita e roda comandos dentro do espaço de trabalho e pausa antes de ir além dele.
3. 3“Approve for me” mantém o mesmo sandbox, mas envia os pedidos de aprovação para revisão automática em vez de para você.
4. 4“Full access” remove os limites de sistema de arquivos e de rede. A documentação faz um alerta; reserve esse modo para ambientes descartáveis.

Prompt para copiar

Antes de começar, rode /status e me diga a política de aprovação e as pastas graváveis. Depois, [tarefa]. Pergunte antes de qualquer comando que precise da rede ou escreva fora deste repositório.

Onde dá errado

• Com “Approve for me”, nenhuma pessoa lê cada pedido. Use onde uma ação errada é fácil de desfazer.
• “Full access” vale para a máquina inteira, não só para o repositório.

Da documentação oficial: Codex docs: Permission modes · Codex docs: Sandboxing · Codex docs: Approvals and security · Codex docs: CLI commands

Como fazer

1. 1codex exec "..." roda sem interação e usa por padrão um sandbox somente de leitura.
2. 2Adicione --sandbox workspace-write quando ele precisar editar arquivos; --full-auto está obsoleto.
3. 3--json emite um fluxo de eventos em JSON Lines para scripts que precisam de cada passo.
4. 4No GitHub Actions, openai/codex-action@v1 roda codex exec para você.

Prompt para copiar

codex exec "Leia as mudanças desde a tag [v1.2.0]. Escreva notas de versão agrupadas em Adicionado, Alterado e Corrigido: uma linha por mudança, em palavras que um usuário entenda, sem hashes de commit."

Onde dá errado

• Guias mais antigos ainda usam --full-auto. Ele está obsoleto; use --sandbox workspace-write.
• Um job que só lê deve continuar somente com leitura, também no CI.

Da documentação oficial: Codex docs: Non-interactive mode · Codex docs: GitHub Action

Como fazer

1. 1/review no CLI revisa sua working tree. codex review faz o mesmo sem o chat, em relação a uma branch base, a um commit ou a mudanças sem commit.
2. 2No GitHub, comente @codex review em um pull request.
3. 3Ative as revisões automáticas em “Personal preferences”, nas configurações do Codex; assim nenhum comentário é necessário.
4. 4Escreva as regras da sua equipe em uma seção “## Code Review Rules” do AGENTS.md.

Recurso nativo

• Codex · Codex code review

Prompt para copiar

## Code Review Rules
- Aponte qualquer mudança em autenticação ou permissões.
- Aponte migrations de banco de dados sem caminho de volta.
- Aponte novas dependências e diga se elas são necessárias.
- Ignore a formatação; o linter cuida disso.

Onde dá errado

• As revisões no GitHub apontam só problemas P0 e P1. Nenhum comentário não significa que o design está certo.
• Uma revisão é uma segunda opinião, não uma execução de testes. Mantenha os testes.

Da documentação oficial: Codex docs: CLI commands · Codex docs: GitHub integration

Como fazer

1. 1Crie um ambiente com os repositórios, dependências, ferramentas e configurações de acesso de que as tarefas precisam. Ambientes novos registram um script de instalação e uma skill de início.
2. 2Defina o acesso à internet por ambiente: só gerenciadores de pacotes, domínios escolhidos ou tudo.
3. 3Inicie tarefas pelo ChatGPT, pela extensão da IDE para jobs mais longos ou pelo terminal com codex cloud exec; --attempts 1-4 pede várias tentativas para comparar.
4. 4O Code Review e as integrações com GitHub e Linear ainda rodam no Codex Cloud antigo (Legacy), que a OpenAI planeja desativar.

Recurso nativo

• Codex · Codex Cloud

Prompt para copiar

codex cloud exec --attempts 3 "Tarefa: [mudança]. Contexto: [arquivos]. Pronto quando [teste] passar neste ambiente. Mantenha o diff com menos de [n] linhas."

Onde dá errado

• Internet sem restrição permite que uma tarefa acesse qualquer site, inclusive páginas escritas para manipulá-la. Libere só o que o job precisa.
• Se o script de instalação estiver faltando, os testes podem não ter rodado. Confira se a tarefa realmente os executou.

Da documentação oficial: Codex docs: Cloud environments · Codex docs: CLI commands · Codex docs: IDE extension

Como fazer

1. 1Defina o modelo padrão e o esforço de raciocínio em ~/.codex/config.toml (model e model_reasoning_effort). O CLI e a extensão da IDE compartilham esse arquivo.
2. 2Crie um perfil como arquivo próprio, ~/.codex/<name>.config.toml, e inicie com --profile <name>.
3. 3Adicione servidores MCP com codex mcp add <name> -- <command>; cada um vira uma tabela [mcp_servers.<name>], e /mcp lista os ativos.
4. 4/status mostra o que está em vigor, e codex resume --last retoma a sessão mais recente nesta pasta.

Prompt para copiar

Leia ~/.codex/config.toml e o .codex/config.toml deste projeto. Diga o modelo, o esforço de raciocínio, o sandbox e os servidores MCP em vigor, de qual arquivo vem cada um e tudo o que estiver em conflito.

Onde dá errado

• As configurações de projeto só são carregadas em projetos confiáveis. Se uma parecer ignorada, confira isso primeiro.
• Agora os perfis são arquivos separados. Guias que colocam [profiles.name] dentro do config.toml estão desatualizados.

Da documentação oficial: Codex docs: MCP · Codex docs: Config basics · Codex docs: Advanced config · Codex docs: CLI commands