Prompt
Loops com Codex
No Prompt / yes Loops
Prompt completo
# Loops com Codex até concluir trabalho
Plano profissional, replicável em qualquer projeto: Codex altera, scripts validam, logs voltam ao Codex, e o ciclo pára apenas quando há prova objetiva.
`Codex CLI` `codex exec` `PowerShell` `Linux/macOS` `CI` `Testes`
## Diagnóstico
**O erro comum:** pedir “faz isto até ficar bom”. Isso é vago e caro. O Codex tem um loop interno de agente, mas a conclusão real tem de ser decidida por validação externa: testes, build, lint, checks de ficheiros, screenshots ou critérios automatizados.
O padrão profissional é um **repair loop**: planear → alterar → validar → devolver erro → reparar → repetir. O loop tem sempre limite máximo de iterações para evitar gastar créditos indefinidamente.
## Arquitetura do loop
- **1. Tarefa** — TASK.md com objetivo e critérios.
- **2. Codex** — codex exec altera dentro do workspace.
- **3. Validação** — npm test, pytest, build, lint, script próprio.
- **4. Feedback** — logs de erro voltam para a próxima iteração.
- **5. Stop** — pára só com exit code 0 ou limite atingido.
## Regra de ouro
| Fraco | Profissional |
| --- | --- |
| “Codex, faz o site até ficar perfeito.” | “Implementa a landing page descrita em TASK.md. O trabalho só termina quando `npm run build` e `npm test` passam.” |
| “Corrige todos os erros.” | “Executa a menor correção útil. Depois o runner executa `pytest`. Se falhar, recebe os logs e corrige a causa.” |
| “Continua sozinho.” | “Repete até 5 iterações. Se falhar, deixa logs, resumo e próximo bloqueio.” |
## Setup mínimo por projeto
```
meu-projeto/
├─ AGENTS.md # regras fixas para Codex
├─ TASK.md # tarefa atual e critérios
├─ .codex-loop/ # logs gerados pelo loop
├─ package.json / pyproject.toml / ...
└─ scripts/
├─ codex-loop.ps1
└─ codex-loop.sh
```
### AGENTS.md recomendado
```
# AGENTS.md
## Contrato de trabalho
- Antes de alterar, entende a estrutura do projeto.
- Faz alterações pequenas e verificáveis.
- Não declares a tarefa concluída sem indicar que comando de validação deve passar.
- Não apagues ficheiros sensíveis: .env, backups, uploads, bases de dados, migrations antigas, vendor, node_modules, dist/build.
## Qualidade
- Mantém o estilo existente.
- Não introduzas dependências novas sem necessidade.
- Corrige a causa do erro, não cales testes.
## Validação
- Node: npm test && npm run build
- Python: python -m pytest
- Docker: docker compose config
```
### TASK.md recomendado
```
# TASK.md
Objetivo:
Corrigir a funcionalidade X até os testes passarem.
Contexto:
- Projeto existente.
- Não mudar arquitetura se uma correção pequena resolver.
- Não apagar dados nem ficheiros sensíveis.
Critérios de conclusão:
- O comando de validação sai com código 0.
- A alteração é mínima.
- O Codex deixa resumo dos ficheiros alterados.
- Não há TODOs novos para partes essenciais da tarefa.
```
## Runner PowerShell — Windows
Uso:
```
cd C:caminhodoprojeto
# 1) Cria/edita TASK.md
notepad .TASK.md
# 2) Executa loop
.scriptscodex-loop.ps1 `
-Project . `
-TaskFile .TASK.md `
-Validate "npm test && npm run build" `
-MaxIterations 5
```
Modelo opcional:
```
.scriptscodex-loop.ps1 -Project . -TaskFile .TASK.md -Validate "pytest" -MaxIterations 5 -Model "gpt-5.5"
```
## Runner Linux/macOS
```
cd /caminho/do/projeto
chmod +x scripts/codex-loop.sh
./scripts/codex-loop.sh . ./TASK.md "npm test && npm run build"
# Com modelo explícito:
MODEL="gpt-5.5" MAX_ITER=5 ./scripts/codex-loop.sh . ./TASK.md "python -m pytest"
```
## Comandos Codex usados pelo padrão
| Comando/flag | Uso |
| --- | --- |
| `codex exec` | Modo não interativo. Serve para scripts, CI e loops automatizados. |
| `--cd ` | Define a pasta raiz do projeto antes de começar. |
| `--sandbox workspace-write` | Permite editar dentro do workspace sem abrir acesso total ao sistema. |
| `--ask-for-approval never` | Evita paragens em automação. Usa só quando o sandbox e os comandos são controlados. |
| `--output-last-message` | Guarda o resumo final do Codex num ficheiro. |
| `--output-schema` | Opcional. Obriga o Codex a responder num JSON com campos estáveis. |
| `--json` | Opcional. Emite eventos JSONL para pipelines/CI. |
**Não uses `--yolo` / `--dangerously-bypass-approvals-and-sandbox` no teu PC normal.** Só faz sentido dentro de VM/runner isolado. Para trabalho local usa `workspace-write`.
## Casos de uso contundentes
### 1. Corrigir bug até testes passarem
**Validação:** `npm test` ou `python -m pytest`.
**Tarefa:** “Corrige a causa dos testes falhados. Não removas testes.”
### 2. Refactor sem partir build
**Validação:** `npm run lint && npm run build && npm test`.
**Tarefa:** “Extrai módulo X, mantém API pública, não muda comportamento.”
### 3. Migração de API antiga
**Validação:** script que procura imports antigos + testes.
**Tarefa:** “Substitui chamadas antigas por cliente novo, mantendo compatibilidade.”
### 4. Docker Compose limpo
**Validação:** `docker compose config && docker compose up -d --build`.
**Tarefa:** “Corrige compose, envs e healthchecks sem destruir volumes.”
### 5. Documentação/SEO
**Validação:** `markdownlint .` + script que exige H1, metas, links.
**Tarefa:** “Melhora docs sem inventar comandos não testados.”
### 6. App pequena pronta a correr
**Validação:** `npm run build` + teste Playwright ou curl local.
**Tarefa:** “Implementa feature, cria teste mínimo, garante build.”
## Prompts prontos a copiar
### Bug fix
```
Corrige a causa dos testes falhados neste projeto.
Não removas testes.
Não faças refactor grande.
O trabalho só está terminado quando o comando abaixo sair com código 0:
npm test
Se precisares de alterar comportamento, documenta a razão no resumo final.
```
### Build web
```
Implementa a tarefa descrita em TASK.md.
Mantém o estilo existente.
Não instales dependências novas sem necessidade.
O trabalho só está terminado quando estes comandos passam:
npm run lint
npm run build
npm test
```
### Python
```
Corrige o pacote Python para que a suite passe.
Preserva a API pública.
Adiciona teste apenas se for necessário demonstrar a correção.
Critério de conclusão:
python -m pytest
```
### Docker/Proxmox/Home lab
```
Corrige a configuração sem destruir volumes, dados persistentes, .env ou backups.
Mostra claramente que ficheiros foram alterados e porquê.
Critério de conclusão:
docker compose config
```
## Versão avançada: resposta estruturada
Para pipelines sérias, força o Codex a devolver JSON em vez de texto solto.
```
{
"type": "object",
"properties": {
"status": { "type": "string", "enum": ["done", "blocked", "partial"] },
"files_changed": { "type": "array", "items": { "type": "string" } },
"validation_command": { "type": "string" },
"risks": { "type": "array", "items": { "type": "string" } },
"next_action": { "type": "string" }
},
"required": ["status", "files_changed", "validation_command", "risks", "next_action"],
"additionalProperties": false
}
```
```
codex exec `
--cd . `
--sandbox workspace-write `
--ask-for-approval never `
--output-schema .templatescompletion.schema.json `
--output-last-message ..codex-loopanswer.json `
"Implementa TASK.md e responde só no schema."
```
## Quando usar subagentes
Usa subagentes quando a tarefa é paralelizável: revisão de segurança, bugs, qualidade, testes, documentação. Não uses para uma correção simples: gasta mais tokens.
```
Revê este PR em paralelo.
Cria um subagente por ponto, espera por todos, e consolida o resultado:
1. Segurança
2. Bugs
3. Qualidade de código
4. Testes frágeis
5. Manutenibilidade
Não edites ainda. Primeiro devolve findings priorizados.
```
## Checklist antes de correr
| Item | Decisão recomendada |
| --- | --- |
| Projeto está em Git? | Sim. Faz commit limpo antes do loop. |
| Dados importantes? | Backup antes. Proibir apagamentos no AGENTS.md. |
| Validação existe? | Sim. Sem validação, o loop é teatro. |
| Quantas iterações? | 3 a 5. Mais que isso indica tarefa mal definida. |
| Permissões? | `workspace-write`. Evitar acesso total. |
| Rede? | Desligada por defeito. Só ativar se a tarefa precisar mesmo. |
## Falhas típicas e correção
| Sintoma | Causa provável | Correção |
| --- | --- | --- |
| Loop muda muita coisa | TASK.md vago | Adicionar limites: ficheiros permitidos, comportamento esperado, validação. |
| Loop nunca acaba | Validação instável ou tarefa grande demais | Dividir em subtarefas. Máximo 5 iterações. |
| Codex fica bloqueado | Precisa de aprovação/rede | Usar sandbox correto ou resolver dependências antes. |
| Passa testes mas feature errada | Validação fraca | Criar teste que representa o comportamento real. |
| Gasta créditos demais | Loop sem limites, logs enormes | Limitar logs, usar tarefas menores, validar localmente. |
## Aplicação direta a qualquer projeto
1. Faz commit ou backup.
2. Cria `AGENTS.md` com regras permanentes.
3. Cria `TASK.md` com objetivo, limites e critérios.
4. Escolhe um comando de validação com exit code objetivo.
5. Corre o script de loop com 3 a 5 iterações.
6. Se falhar, lê `.codex-loop/iter-XX/validate.stderr.log` e reduz a tarefa.
7. Se passar, revê `git diff` antes de aceitar.
## Fontes oficiais consultadas
- [OpenAI Developers — Codex CLI](https://developers.openai.com/codex/cli)
- [OpenAI Developers — Non-interactive mode](https://developers.openai.com/codex/noninteractive)
- [OpenAI Developers — Command line options](https://developers.openai.com/codex/cli/reference)
- [OpenAI — Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)
- [OpenAI Cookbook — Build iterative repair loops with Codex](https://developers.openai.com/cookbook/examples/codex/build_iterative_repair_loops_with_codex)
- [OpenAI Developers — AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
- [OpenAI Developers — Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security)
Documento gerado para uso local. Revê sempre diffs antes de aceitar alterações automáticas.