concava/skills

Guia do Skill Codex

Executando uma Tarefa

1. Para uma nova sessão (resumes herdam o modelo/esforço anterior — veja passo 5), pergunte ao usuário (via AskUserQuestion) qual modelo E qual esforço de raciocínio usar, em um único prompt com duas perguntas. Quando o usuário não expressar preferência, use o padrão gpt-6-astra com high.
   • Modelo — padrão gpt-6-astra:
     • GPT-6: gpt-6-astra (fronteira / mais capaz — padrão)
     • GPT-5.6: gpt-5.6-sol (cavalo de batalha confiável), gpt-5.6-terra (equilibrado, dia a dia), gpt-5.6-luna (rápido e acessível)
     • Legado (mantido para compatibilidade): gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark, gpt-5.3-codex
   • Esforço de raciocínio — padrão high: low, medium, high, xhigh, max, ultra.
     • max/ultra exigem um modelo GPT-6 ou GPT-5.6; ultra é apenas em astra/sol/terra (luna limita em max); modelos legados limitam em xhigh.
     • ultra = raciocínio máximo com delegação automática de tarefas (mais lento e mais caro — reserve para os trabalhos mais difíceis).
     • Se o esforço escolhido exceder o máximo do modelo escolhido, recue para o maior esforço suportado por aquele modelo e informe o usuário.
2. Selecione o modo de sandbox exigido pela tarefa; use --sandbox read-only como padrão, a menos que edições ou acesso à rede sejam necessários.
3. Monte o comando com as opções apropriadas:
   • -m, --model <MODEL>
   • --config model_reasoning_effort="<low|medium|high|xhigh|max|ultra>" (max/ultra apenas em modelos GPT-6 / GPT-5.6; ultra apenas em astra/sol/terra — veja passo 1)
   • --sandbox <read-only|workspace-write|danger-full-access>
   • --full-auto
   • -C, --cd <DIR>
   • --skip-git-repo-check
   • "seu prompt aqui" (como argumento posicional final)
4. Sempre use --skip-git-repo-check.
5. Ao continuar uma sessão anterior, use codex exec --skip-git-repo-check resume --last via stdin. Ao retomar, não use flags de configuração a menos que o usuário as solicite explicitamente (por exemplo, se ele especificar o modelo ou o esforço de raciocínio ao pedir para retomar). Sintaxe de retomada: echo "seu prompt aqui" | codex exec --skip-git-repo-check resume --last 2>/dev/null. Todas as flags devem ser inseridas entre exec e resume.
6. IMPORTANTE: Por padrão, anexe 2>/dev/null a todos os comandos codex exec para suprimir tokens de pensamento (stderr). Mostre stderr apenas se o usuário solicitar explicitamente ver os tokens de pensamento ou se for necessário depuração.
7. IMPORTANTE (stdin): codex exec sempre lê stdin e o concatena com o prompt posicional — mesmo quando o prompt é totalmente fornecido como argumento posicional. Se stdin não for fechado, codex bloqueia para sempre. Ao invocar de um harness (tarefas em segundo plano, hooks, scripts onde stdin não é um TTY mas também não está fechado), redirecione stdin explicitamente: anexe </dev/null ao comando, por exemplo: codex exec ... "prompt" </dev/null 2>/dev/null. Sintoma de errar isso: zero bytes de stdout, zero CPU acumulado, processo parece travado indefinidamente.
8. Execute o comando, capture stdout/stderr (filtrado conforme apropriado) e resuma o resultado para o usuário.
9. Após o Codex terminar, informe o usuário: "Você pode retomar esta sessão Codex a qualquer momento dizendo 'codex resume' ou pedindo que eu continue com análises ou alterações adicionais."

Referência Rápida

Caso de uso	Modo de sandbox	Flags principais
Revisão ou análise somente leitura	read-only	--sandbox read-only 2>/dev/null
Aplicar edições locais	workspace-write	--sandbox workspace-write --full-auto 2>/dev/null
Permitir acesso à rede ou amplo	danger-full-access	--sandbox danger-full-access --full-auto 2>/dev/null
Retomar sessão recente	Herdado da original	echo "prompt" | codex exec --skip-git-repo-check resume --last 2>/dev/null (nenhuma flag permitida)
Executar de outro diretório	Corresponder às necessidades da tarefa	-C <DIR> + outras flags 2>/dev/null

Timeouts de Execução

O Codex não produz saída intermediária — ele escreve o resultado apenas na conclusão. Se o processo for encerrado antes de terminar, o arquivo de saída fica silenciosamente vazio (sem erro).

Abordagem preferida: execute de forma síncrona — elimina completamente o risco de timeout e a conversa aguarda o resultado de qualquer forma.

Se executando em segundo plano, defina o timeout de execução com base no esforço de raciocínio:

Esforço de raciocínio	Timeout
low	150s
medium	300s
high	600s
xhigh	1200s
max	1800s
ultra	1800s

Acompanhamento

• Após cada comando codex, use imediatamente AskUserQuestion para confirmar os próximos passos, coletar esclarecimentos ou decidir se deve retomar com codex exec resume --last.
• Ao retomar, envie o novo prompt via stdin: echo "novo prompt" | codex exec resume --last 2>/dev/null. A sessão retomada usa automaticamente o mesmo modelo, esforço de raciocínio e modo de sandbox da sessão original.
• Reafirme o modelo, esforço de raciocínio e modo de sandbox escolhidos ao propor ações de acompanhamento.

Avaliação Crítica da Saída do Codex

O Codex é alimentado por modelos OpenAI com seus próprios cortes de conhecimento e limitações. Trate o Codex como um colega, não uma autoridade.

Diretrizes

• Confie em seu próprio conhecimento quando estiver confiante. Se o Codex afirmar algo que você sabe que é incorreto, conteste diretamente.
• Pesquise discordâncias usando WebSearch ou documentação antes de aceitar as afirmações do Codex. Compartilhe descobertas com o Codex via retomada, se necessário.
• Lembre-se dos cortes de conhecimento — o Codex pode não saber sobre lançamentos recentes, APIs ou mudanças que ocorreram após seus dados de treinamento.
• Não delegue cegamente — o Codex pode estar errado. Avalie suas sugestões criticamente, especialmente em relação a:
  • Nomes e capacidades de modelos
  • Versões recentes de bibliotecas ou mudanças de API
  • Melhores práticas que podem ter evoluído

Quando o Codex Estiver Errado

1. Declare sua discordância claramente ao usuário
2. Forneça evidências (seu próprio conhecimento, pesquisa web, documentação)
3. Opcionalmente, retome a sessão do Codex para discutir a discordância. Identifique-se como Claude para que o Codex saiba que é uma discussão entre AIs. Use seu nome de modelo real (por exemplo, o modelo que você está executando atualmente) em vez de um nome fixo:

   echo "Este é o Claude (<seu nome de modelo atual>) acompanhando. Discordo de [X] porque [evidência]. Qual é a sua opinião sobre isso?" | codex exec --skip-git-repo-check resume --last 2>/dev/null
   

4. Enquadre as discordâncias como discussões, não correções — qualquer AI pode estar errada
5. Deixe o usuário decidir como proceder se houver ambiguidade genuína

Tratamento de Erros

• Pare e relate falhas sempre que codex --version ou um comando codex exec sair com código diferente de zero; solicite orientação antes de tentar novamente.
• Antes de usar flags de alto impacto (--full-auto, --sandbox danger-full-access, --skip-git-repo-check), peça permissão ao usuário usando AskUserQuestion, a menos que já tenha sido concedida.
• Quando a saída incluir avisos ou resultados parciais, resuma-os e pergunte como ajustar usando AskUserQuestion.