ask-codex

O que ask-codex faz?

Skill para chamar o agente de codificação Codex da OpenAI no modo codex exec (não interativo) para consultas de design, implementação, investigação aprofundada e revisão de código.

O Codex tende a investigar persistentemente para aumentar a precisão, sendo ideal para segunda opinião e investigação aprofundada onde a exatidão é crítica.

O Codex inicia frio a cada chamada e não tem conhecimento da conversa atual, do plano ou dos resultados de investigações anteriores. Premissas, intenções, restrições e arquivos relevantes devem ser explicitamente fornecidos no prompt a cada chamada (veja "Como escrever uma tarefa" e exemplos abaixo).

Pré-requisitos

• O CLI codex deve estar instalado e autenticado (verifique com codex --version).
• Se a autenticação expirou, a configuração do Codex é necessária; informe o usuário.

Antes de executar

Antes de chamar o Codex, informe o usuário em uma frase sobre o que será consultado. Não é necessário aguardar aprovação; após informar, execute diretamente.

Padrão básico de chamada

Como o Codex atua como um revisor sênior somente leitura, use -s read-only como padrão. O prompt é passado via stdin (codex exec -) para evitar escapes do shell.

Existem duas práticas centrais:

1. Concluir a extração da resposta (cat) dentro do mesmo comando que chama o Codex. $OUT de OUT=$(mktemp …) desaparece em chamadas de shell subsequentes; fazer cat no mesmo comando garante que a resposta seja capturada sem suposições sobre o comportamento.
2. Não direcione stdout/stderr do Codex para o contexto. O Codex envia logs de progresso, cabeçalhos, avisos, hooks, eco final e tokens used para stderr, e apenas a mensagem final para stdout e o arquivo -o (tudo que "fez/pensou" vai para stderr). Como só queremos a conclusão, stdout é descartado e stderr é redirecionado para um arquivo temporário, exibido apenas em caso de falha. Assim, o resultado da ferramenta contém apenas a mensagem final de cat "$OUT", e erros como autenticação expirada ou flags inválidas são visíveis na falha.

Dividimos em duas receitas canônicas conforme o uso.

A. Consulta curta / revisão pequena (primeiro plano)

A resposta (apenas a mensagem final) é retornada no resultado da ferramenta de execução do shell. Nenhuma leitura adicional é necessária.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' "$PROMPT" | codex exec - -s read-only -C <DIR> -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
cat "$OUT"

B. Chamada longa (segundo plano)

codex exec pode levar vários minutos; a execução em primeiro plano pode ser interrompida dependendo do ambiente. Para investigações aprofundadas ou revisões de código (codex exec review) que podem ser longas, use o mecanismo de execução em segundo plano do seu harness (a forma de especificar fica a cargo do harness). O comando principal varia: codex exec - (consulta/investigação) ou codex exec review (revisão de diff, veja abaixo).

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' "$PROMPT" | codex exec - -s read-only -C <DIR> -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

Quando concluído, o harness emite uma notificação de conclusão, e a saída em segundo plano conterá a resposta a partir de === ANSWER ===. Leia essa saída (se longa, pode usar grep após === ANSWER ===). Não crie um loop de polling com sleep/pgrep (o harness notifica a conclusão).

Significado das flags

• codex exec -: Lê o prompt do stdin. Permite passar com segurança textos longos, blocos de código e caracteres especiais.
• -s read-only: Permite apenas leitura. Nesta skill, é padrão (atuamos como consultor/revisor, sem necessidade de escrita). Não é o padrão do CLI/config em si. É exclusivo do codex exec e não existe no codex exec review (causa erro se usado).
• -C <DIR>: Raiz de trabalho do codex exec. Aponta para o repositório alvo da investigação/revisão. Se omitido, usa o diretório atual. Não existe no codex exec review, então para review, faça cd <DIR> antes de chamar (veja abaixo).
• -o <FILE>: Escreve apenas a mensagem final do Codex neste arquivo. É escrito apenas na conclusão (vazio durante a execução); não leia antes. A receita canônica usa este arquivo como fonte da resposta.
• stdout: O Codex também envia a mensagem final para stdout, mas a receita canônica usa -o, então redirecionamos stdout para /dev/null para evitar duplicação e economizar contexto.
• stderr: Contém logs de progresso, cabeçalhos, avisos, hooks, eco final, tokens used e erros (autenticação expirada, flags inválidas, falha na verificação do repositório, etc.). Simplesmente descartar com 2>/dev/null esconderia a causa se cat "$OUT" estiver vazio; por isso, redirecionamos para um arquivo temporário ($ERR) e o exibimos apenas em caso de falha. Em caso de sucesso, não entra no contexto; em falha, a causa fica visível.
• mktemp /tmp/codex_answer.XXXXXX.txt: O sufixo XXXXXX é substituído aleatoriamente, gerando um caminho único sem colisões. Mesmo com múltiplas chamadas paralelas, cada mktemp gera um arquivo diferente.

Opções geralmente desnecessárias

• --skip-git-repo-check: Necessário apenas para execução fora de um repositório git. Não use se estiver dentro de um repositório.
• -s workspace-write: Apenas se quiser que o Codex edite arquivos. Foge do escopo desta skill (revisor somente leitura), portanto, não use em princípio.

Especificação de modelo

Para usar um modelo específico, use -m <MODEL> (ex: -m gpt-5.5). Se omitido, segue o padrão da configuração do Codex. Não especifique indiscriminadamente; adicione apenas quando solicitado pelo usuário.

Pesquisa na web

Se ~/.codex/config.toml tiver web_search = "live" configurado, o Codex pode usar pesquisa na web. A pesquisa na web é uma ferramenta nativa do Responses, portanto não é bloqueada por -s read-only (que restringe apenas execução de shell). Para verificar especificações de bibliotecas, APIs ou CLIs, peça explicitamente no prompt: "verifique na documentação oficial com pesquisa na web". Não há flag --search no codex exec; o controle é feito pelo web_search no config.

Exibição de ajuda

codex exec -h exibe a ajuda.

Como escrever uma tarefa

LLMs são bons em seguir exemplos; use o corpo do prompt nos exemplos abaixo como modelos de boas tarefas. Concentre uma consulta em uma única decisão/revisão/plano/investigação e inclua o seguinte no prompt:

• Intenção, contexto e restrições: Como o Codex inicia frio, sempre escreva o que quer fazer, por que e as premissas.
• Arquivos relevantes: Indique inline com @path/to/file. Se quiser que veja as alterações atuais, peça "verifique o diff com git diff".
• Pontos de atenção / alternativas para comparar / riscos a serem investigados: Seja específico.
• Formato da saída: Especifique (riscos classificados / tabela de tradeoffs / mudança de plano recomendada, etc.).
• O que ignorar: Para evitar scope creep (ex: nomenclatura, formatação).
• Verificação de especificações externas: Se necessário, peça "verifique na documentação oficial com pesquisa na web".
• Ordem da revisão: Peça para avaliar intenção → implementação (primeiro se faz sentido dado o contexto, depois a implementação).

O corpo do prompt deve ser envolvido em aspas simples (printf '%s' '…') para que $ e crases no texto não sejam interpretados pelo shell (apenas tome cuidado se o texto contiver aspas simples literais).

Exemplos de uso por finalidade

1. Segunda opinião / Comparação de múltiplas alternativas (Receita A)

Segunda opinião sobre decisões de design/implementação. Quanto mais específico sobre alternativas, restrições e formato de saída, melhor a qualidade.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' 'Intenção: Decidir a forma de refresh do token de autenticação. Atualmente,
verificamos a expiração em cada chamada de API e fazemos refresh síncrono
(@src/auth/client.ts), o que causa refresh duplicado em requisições concorrentes
de alta frequência.

Alternativas para comparar:
(1) Compartilhar a Promise do refresh em andamento para unificar
(2) Atualizar proativamente em segundo plano antes da expiração
(3) Após receber 401, fazer refresh uma única vez e retentar

Restrições: Deve funcionar tanto em SSR quanto CSR. Não queremos adicionar novas bibliotecas.
Saída: Tabela de tradeoffs com colunas de correção / complexidade / modos de falha,
recomendação de plano padrão e plano de fallback, e em quais condições mudar para outra
alternativa. Ignore nomenclatura e formatação.' \
  | codex exec - -s read-only -C /caminho/para/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
cat "$OUT"

2. Revisão de código

Restrição importante: As flags de escopo do codex exec review (--uncommitted / --base / --commit) não podem ser usadas junto com um PROMPT de instrução personalizada (seja via stdin - ou argumento posicional) (confirmado no codex 0.142.4; usar ambos causa erro imediato: error: the argument '--uncommitted' cannot be used with '[PROMPT]'). Portanto, dividimos em dois usos.

2a. Revisão com contexto e intenção (uso principal recomendado desta skill): Como não podemos usar flags de escopo e instruções personalizadas juntas, use codex exec - (Receita A/B) em vez de codex exec review, e especifique o escopo no prompt pedindo para verificar git diff, etc. -s read-only / -C / stdin funcionam normalmente, evitando escapes.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' 'Intenção: Esta alteração deve alterar o comportamento apenas ao suprimir o som
de notificação ociosa, sem afetar a reprodução do som de solicitação de entrada
do usuário. Verifique as alterações não commitadas com git diff (se necessário,
também git diff --cached e untracked). Primeiro avalie se faz sentido dada a
intenção, depois examine a implementação.
Pontos de atenção: Inversão de condições, mudanças de valores padrão, divergência
de significado entre cliente/servidor.
Saída: Recomendação → descobertas com evidências → suposições não verificadas,
nessa ordem. Ignore nomenclatura e formatação.' \
  | codex exec - -s read-only -C /caminho/para/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

2b. Revisão de diff pura sem especificação de pontos de atenção: Se não forem necessárias instruções personalizadas, use as flags de escopo do codex exec review diretamente (sem PROMPT, evitando a restrição). Ao contrário do codex exec, não há -C nem -s; chame-o dentro do repositório alvo com cd.

OUT=$(mktemp /tmp/codex_review.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
cd /caminho/para/repo || exit 1
codex exec review --uncommitted -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

Substituição da flag de escopo (substitua a linha codex exec review … acima; nenhuma delas usa PROMPT):

codex exec review --uncommitted -o "$OUT" >/dev/null 2>"$ERR"   # Não commitado (staged + unstaged + untracked)
codex exec review --base main   -o "$OUT" >/dev/null 2>"$ERR"   # Diff com a branch base
codex exec review --commit <SHA> -o "$OUT" >/dev/null 2>"$ERR"  # Commit específico

• Para revisão com pontos de atenção, use 2a (codex exec - + git diff). Flags de escopo + instruções personalizadas não podem ser usadas juntas.
• A revisão deve ser executada dentro do repositório alvo (não há -C, então use cd). Fora do repositório, --skip-git-repo-check pode ser usado, mas não faz sentido sem diffs para revisar.

3. Validação de plano/migração (Receita B)

Teste de estresse de planos e procedimentos de migração antes da implementação, identificando lacunas a serem resolvidas antes de começar. Use o modo somente leitura para verificar contratos do código atual.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' 'Revise o plano antes da implementação e aponte apenas as lacunas que precisam
ser resolvidas antes de codificar.
Plano: Quando a sincronização de eventos for rejeitada pelo servidor, definir
repair_required, enviar um snapshot compacto e, somente após o servidor confirmar
a sequência consistente, retomar eventos incrementais.
Relacionados: @src/sync/event-syncer.ts @src/db/sync-state.ts @api/types.ts.
Verifique os contratos atuais lendo o código existente antes de avaliar.
Pontos de atenção: Compatibilidade de esquema, limite de tamanho do snapshot,
condições de contorno da sequência de retomada, impacto de backfill/migration,
falta de testes.
Saída: Apenas as mudanças necessárias no plano antes de começar + um veredito de
"é seguro implementar como está".' \
  | codex exec - -s read-only -C /caminho/para/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

4. Investigação aprofundada (Receita B)

Investigação persistente de causas raiz de bugs, falhas de teste, race conditions, cache obsoleto, etc. Adicionar condições de sucesso verificáveis aproveita a capacidade de investigação aprofundada do Codex. Como é demorado, execute em segundo plano.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' 'O teste TestBar em foo_test.go falha raramente no CI. Investigue a causa raiz.
Condição de sucesso: Identificar a condição de reprodução e a localização do problema
(arquivo:linha) e apresentar uma sugestão de correção mínima.
Se houver suspeita de ser causado por uma biblioteca externa, verifique a documentação
oficial dessa biblioteca com pesquisa na web.' \
  | codex exec - -s read-only -C /caminho/para/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

Como lidar com os resultados

• Comunique os pontos principais ao usuário a partir da resposta (Receita A: resultado da ferramenta; Receita B: saída em segundo plano após notificação de conclusão). Se for longa, resuma, citando as descobertas importantes textualmente.
• O Codex pode fazer sugestões excessivamente defensivas (preocupação excessiva com compatibilidade reversa, etc.). Cabe a você decidir quais apontamentos adotar e quais rejeitar. Não aceite cegamente; incorpore apenas o que fizer sentido.