Agente /goal Loop

O que /goal é

/goal é um comando de barra que transforma um prompt de agente em um agente persistente em loop plan → act → test → review → iterate até que uma condição de parada seja atendida, o usuário pause ou o orçamento de tokens se esgote. Internamente chamado de "loop Ralph".

Agentes com o recurso /goal no momento: Codex, Claude Code e Hermes Agent.

Diferença chave de um prompt normal: quando um turno termina, mas o objetivo não é atingido, o agente continua automaticamente em vez de esperar por entrada.

Estados do ciclo de vida: pursuing, paused, achieved, unmet, budget-limited.

Ao monitorar um /goal em execução, cada verificação deve incluir uma atualização de uma linha para o usuário: o que o agente está fazendo e se está no caminho certo. Mantenha extremamente conciso.

Não é: um comando de orçamento, um limite de segurança, "executar para sempre" ou um substituto para /plan. É um aplicador de contrato com um loop de verificação.

Requisitos

• Um agente com o recurso /goal — no momento: Codex, Claude Code ou Hermes Agent
• O recurso de metas ativado na configuração do agente
• Autenticação de assinatura — a autenticação por chave de API não funciona. Um plano de nível profissional é o mínimo realista para execuções longas.

Quando Usar

Use apenas quando todas as três condições forem verdadeiras:

1. A tarefa é >30 minutos de trabalho mecânico.
2. Existe uma condição de parada verificável (testes passam, cobertura atingida, avaliação ≥ X, build verde).
3. O repositório está pronto para o agente (build funcionando, testes decentes, AGENTS.md presente).

Adequado para: migrações, aumentos de cobertura, construções de recursos TDD, refatorações com testes de contrato, otimização de prompt/avaliação, loops de retentativa de implantação, reprodução de bugs e correção.

Não adequado para: trabalho exploratório, "melhore isso" vago, qualquer coisa sem uma definição de "feito", credenciais de produção, operações destrutivas de infraestrutura compartilhada.

O contrato de 5 partes (cada meta precisa disso)

1. Objetivo — uma frase, um resultado concreto.
2. Restrições — o que NÃO deve mudar (API pública, arquivos, bibliotecas, convenções).
3. Comando de validação — o comando exato do shell que prova o progresso (pytest -q, pnpm test, etc.).
4. Condição de parada — verificável: "Parar quando X passar" OU "quando mudanças adicionais precisarem de entrada humana/de produto."
5. Documentação — uma frase instruindo o agente a escrever documentação concisa e direcionada para cada alteração, criando novos arquivos .md ou atualizando os existentes.

Além disso: diga ao agente o que ler primeiro, peça para ele trabalhar em pontos de verificação com um breve registro de progresso.

Escrevendo uma meta (o entregável principal)

Quando o usuário quiser uma instrução rápida de /goal, produza um bloco de markdown estruturado com uma linha por item do contrato (novas linhas adequadas, não prosa fluida). Não prefixe a saída com /goal — o usuário adiciona o comando de barra em si mesmo no compositor. Emita apenas o corpo do contrato. Modelo:

**Objective:** <one-sentence objective>
**Read first:** <files/PLAN.md/issue>
**Constraints:** <what not to change, libs, conventions>
**Validate:** `<exact command>` after each change
**Document:** Write concise, targeted documentation for all changes — create new `.md` files or update existing docs as needed.
**Checkpoints:** work in checkpoints and log progress briefly
**Stop when:** <verifiable condition>, OR when further changes require human/product input

Exemplo (migração)

**Objective:** Migrate this project from Pydantic v1 to v2.
**Read first:** pyproject.toml, src/, tests/
**Constraints:** no public API changes; keep imports backwards-compatible via shims if needed; no new dependencies
**Validate:** `pytest -q` after each change
**Checkpoints:** work in checkpoints; log progress briefly
**Stop when:** full suite passes with zero deprecation warnings, OR when a change requires architecture decisions

Exemplo (aumento de cobertura)

**Objective:** Raise coverage in src/auth/ from ~38% to ≥75%.
**Read first:** src/auth/, tests/auth/, AGENTS.md
**Constraints:** no new deps; mirror existing test style; do not modify production code unless strictly required for testability
**Validate:** `pytest --cov=src/auth --cov-report=term-missing`
**Checkpoints:** work in checkpoints; log coverage delta each one
**Stop when:** coverage ≥75% AND all tests pass, OR when uncovered code needs design changes

Regras de escrita

• Um objetivo, uma condição de parada. Não um backlog.
• Documentação é obrigatória. Cada prompt /goal deve incluir uma única frase comprometendo o agente a documentação concisa e direcionada — novos arquivos .md ou atualizações focadas na documentação existente.

…