trailofbits/goal-prompt

Goal Prompt

/goal mantém o agente trabalhando até que uma condição de conclusão seja atendida. Tanto o Claude Code quanto o Codex o aceitam em uma única linha, com no máximo 4.000 caracteres. No Claude Code, um modelo pequeno reavalia a condição a cada turno apenas com base na transcrição — ele não pode executar comandos.

Elabore uma condição que possa ser encerrada e, em seguida, formate-a. Um objetivo se encaixa em um trabalho maior que um único turno com uma linha de chegada verificável; encadeie objetivos pequenos com revisão entre eles em vez de escrever um único objetivo gigante.

Rascunho

Inclua, unidos por AND — nunca "ou", pois o loop pega o ramo mais barato:

1. Estado final, não atividade — "todos os locais de chamada legacyAuth() usam auth.verify()", não "migre o código de autenticação". Uma atividade pode ser reivindicada; um estado final é verdadeiro ou falso.
2. Escopo para leitura primeiro — os arquivos, issues, logs ou plano a serem lidos antes de agir.
3. Verificação declarada — o comando exato e seu resultado observável ("npm test sai com 0"), mais uma instrução para executá-lo e mostrar a saída; um resultado que nunca chega à transcrição não existe para o avaliador.
4. Invariantes — o que não deve mudar ("sem modificar vendor/"), sempre incluindo "não enfraqueça, pule ou edite as próprias verificações".
5. Limite de parada ou cláusula de bloqueio — "ou pare após 20 turnos", "se bloqueado, pare e relate o bloqueador". Sem um, uma condição mal declarada entra em loop infinito; o formatador avisa quando está faltando. (O Claude Code redefine o contador de turnos na retomada da sessão, então um limite de turno se estende silenciosamente entre retomadas.)

Mantenha pequeno. Cada restrição reduz o espaço de estado que o modelo pode explorar. Reduza a um único critério de encerramento quando possível, mova o escopo e as definições para um arquivo referenciado e elimine não-objetivos — uma restrição só merece seu lugar se fechar uma saída fácil real.

Para objetivos longos, também nomeie a evidência final (diff, relatório, artefato) e exija um arquivo de log de progresso — estado durável entre compactação e retomada. Se o resumo exceder 4.000 caracteres, coloque os detalhes em um arquivo GOAL.md e referencie esse arquivo a partir do objetivo.

Nunca invente elementos ausentes. Baseie cada elemento no pedido do usuário, na conversa ou no repositório — pesquise em vez de adivinhar. Se um elemento não puder ser preenchido com as informações disponíveis, ainda otimize e formate o que o usuário forneceu, deixe o elemento de fora e sinalize-o como ausente (veja Formatação). Um objetivo com uma condição de sucesso inventada termina no contrato errado.

Feche as saídas fáceis

Antes de formatar, releia a condição rascunhada como um modelo preguiçoso faria: qual é a maneira mais barata de fazer todas as verificações passarem sem fazer o trabalho pretendido? Feche as mais baratas — prefira emparelhar verificações que você já tem a adicionar restrições e não enumere todas as brechas concebíveis em uma lista de não-objetivos. As saídas recorrentes:

• Deletar ou substituir por stub em vez de corrigir — "a pesquisa não imprime nada" também é verdade quando os chamadores sumiram; emparelhe tais verificações com uma que prove que o recurso ainda funciona.
• Passar em um subconjunto — executar um único arquivo de teste, restringir o caminho de pesquisa, excluir diretórios da verificação.
• Jogar com o portão — pular/marcar testes como xfail, codificar resultados esperados, criar casos especiais para as entradas de teste, editar a verificação (a regra de invariantes).
• Afirmar sem executar — declarar concluído ou bloqueado sem nenhuma saída de verificação na transcrição (a regra de mostrar a saída).

Mesma disciplina acima: uma saída que você não pode fechar com as informações disponíveis vai para a lista Ausente: como um aviso — uma restrição inventada ou absurda é pior do que uma lacuna sinalizada.

Objetivos de pesquisa de segurança

Reduza objetivos de auditoria a um único critério de encerramento, como identificar, acionar e validar uma vulnerabilidade de alta gravidade válida sob um arquivo de modelo de ameaça referenciado. Esse arquivo, não o objetivo, carrega escopo, poderes do atacante, linha de base de gravidade e descobertas conhecidas a serem ignoradas. Use uma redação neutra ("acionar e validar", não "prove que isso é explorável"), exija pré-condições demonstradas — acesso de atacante assumido é o falso positivo mais comum — e pare para revisão humana após cada descoberta em vez de acumular relatórios não triados. Valide as descobertas com uma segunda passagem por um agente novo, nunca apenas o descobridor.

Formatação

Execute uv run --no-project {baseDir}/scripts/format_goal_prompt.py --fenced no rascunho (arquivo ou stdin). Ele colapsa espaços em branco em uma linha, remove prefixos /goal, aspas e fences, avisa sobre uma cláusula de parada ausente e rejeita saída com mais de 4.000 caracteres — encurte ou mova os detalhes para um arquivo e execute novamente.

Retorne exatamente um bloco text delimitado, uma linha:

/goal <objetivo normalizado único>

Não adicione prosa ao redor — exceto quando os elementos do checklist não puderem ser fundamentados: então siga o bloco com uma lista Ausente:, uma linha por lacuna, dizendo ao usuário o que fornecer.

Exemplo

Rascunho:

/goal Migrar o módulo de autenticação:
  - substituir legacyAuth() por auth.verify()
  - garantir que os testes ainda funcionem

Reformulado e formatado:

/goal Todos os locais de chamada legacyAuth() usam auth.verify(): `rg "legacyAuth\(" -t ts` não imprime nada AND `npm test` sai com 0 (execute ambos, mostre a saída), sem modificar vendor/ ou enfraquecer qualquer teste. Se bloqueado, pare e relate os caminhos tentados e o bloqueador, ou pare após 20 turnos.

Aqui npm test veio do package.json do repositório — não um palpite — e emparelhá-lo com a verificação de zero correspondências fecha a saída mais barata: deletar os locais de chamada em vez de migrá-los. Quando nada fundamenta um elemento, formate o que existe e sinalize as lacunas:

Rascunho: tornar o checkout mais rápido, sem métrica ou benchmark em qualquer lugar no contexto:

/goal Tornar o checkout mais rápido

Ausente:

• estado final mensurável — qual métrica e limite contam como "mais rápido"
• verificação — o benchmark ou comando que prova isso
• limite de parada — ex. "ou pare após 20 turnos"