openqodex

OpenQodex: revise a alteração antes de enviá-la

O OpenQodex revisa uma alteração em um único comando. Ele tira uma cópia congelada da alteração, executa os scanners determinísticos que se encaixam nos arquivos alterados (gitleaks, semgrep, bandit, hadolint, shellcheck, actionlint, osv-scanner e outros), mantém o que eles relatam nas linhas alteradas, e inicia seu próprio revisor: um processo separado do Claude Code ou Codex que lê apenas essa cópia. O revisor verifica cada achado do scanner, recebe cada linha alterada e responde em um formato fixo; o OpenQodex verifica a resposta com scripts e imprime um relatório. Nenhuma chave ou conta é necessária além do login do Claude Code ou Codex do desenvolvedor. O código vai para o modelo que esse login usa. O revisor também pode pesquisar na web e abrir páginas da web, a menos que reviewer_web: off esteja definido em ~/.openqodex/config.yaml. Quatro scanners ficam online, e nenhum envia código. O semgrep baixa seus pacotes de regras do registro Semgrep a cada execução. Quando a alteração toca um arquivo de dependências, o osv-scanner envia os nomes e versões das dependências para osv.dev. O kubeconform baixa esquemas do Kubernetes. O cargo-deny baixa o banco de dados de avisos do RustSec. --offline pula semgrep, osv-scanner, kubeconform e cargo-deny.

Quando executar

• Antes de qualquer git push.
• Quando o desenvolvedor pedir para você revisar suas alterações.
• Quando um push foi bloqueado ou alertado pelo hook do OpenQodex.
• Depois de corrigir achados, para verificar a alteração novamente.

Quem revisa

O OpenQodex inicia seu próprio processo revisor para cada revisão, sem memória desta sessão. Você não inicia um subagente para isso e não revisa a alteração você mesmo: execute o comando e mostre o que ele imprime.

Se review disser "Revisão completa indisponível" e imprimir uma maneira de revisar com o agente em que você está, siga-a: execute o comando que ela nomeia e faça o que o resumo que ela imprime diz.

Procedimento

Quando o arquivo ~/.openqodex/bin/openqodex existir, execute-o no lugar de npx -y openqodex@<versão> em cada comando desta skill: é a cópia que openqodex init instalou. Quando ele não existir, esta skill foi instalada sozinha, sem verificação de push: antes da primeira revisão, execute npx -y [email protected] init --yes --agent <hospedeiro> uma vez a partir do repositório, onde <hospedeiro> é o agente que você é (claude-code, codex, cursor ou cline). Ele instala o OpenQodex para você, então revisa a alteração quando um revisor pode iniciar, então pode levar vários minutos. Execute-o em segundo plano e aguarde sua saída. Quando ele imprimir Primeira revisão: concluída, o recibo acima dessa linha é o da revisão: mostre-o como o passo 3 diz, então continue a partir do passo 4.

1. A partir do repositório, execute:

   npx -y [email protected] review
   

   Ele revisa a alteração: os commits ainda não enviados mais tudo o que não está commitado, arquivos não rastreados incluídos. Para revisar o repositório inteiro em vez disso, execute:

   npx -y [email protected] review --all
   

2. Aguarde. Uma revisão pode levar minutos. O OpenQodex para o revisor após 30 minutos, ou após 2 horas com --all. Muitos agentes param um comando mais cedo. Então execute-o em segundo plano e aguarde até que saia. Enquanto o revisor trabalha, ele imprime uma linha de progresso a cada 15 segundos no stderr. Não o inicie uma segunda vez enquanto um estiver em execução.

3. Mostre ao desenvolvedor o recibo que foi impresso, como foi impresso: o veredito, uma linha por achado (seu número, gravidade, categoria, título, arquivo e linha) e o caminho absoluto de report.html. Não o reformule, encurte ou adicione achados próprios. Dê a eles o caminho de report.html: essa página mostra cada arquivo alterado com cada achado abaixo de sua linha de código. Quando o recibo terminar com Observações (não contam para o veredito): e linhas numeradas abaixo, mostre essas linhas também como foram impressas. Uma observação é uma nota de estilo, nomenclatura, documentação ou teste. Não é um achado para corrigir a menos que o desenvolvedor nomeie seu número.

4. Pergunte ao desenvolvedor: "Corrigir tudo, ou me diga qual?" Não altere nenhum código antes que eles respondam. Se eles já disseram o que corrigir, por exemplo "revise e corrija tudo", faça isso sem perguntar novamente.

5. Corrija apenas os achados que eles nomearem. Isso imprime esses achados na íntegra (onde, o problema, por que importa, a correção e a fonte), pelos seus números no recibo:

   npx -y [email protected] findings 1,3
   

   findings all imprime todo achado. Quando as correções estiverem prontas, execute a revisão novamente e mostre ao desenvolvedor o novo recibo.

6. Aja de acordo com o código de saída:

   • 0: a revisão está completa e nada bloqueia o push.
   • 1: a revisão está completa e seu veredito é bloqueado. Não faça push. Mostre ao desenvolvedor o recibo e pergunte quais achados corrigir; faça push apenas se eles disserem após ver os achados.
   • 2: não há revisão completa. A saída diz o que está faltando (por exemplo "Revisão completa indisponível" quando nenhum revisor pôde iniciar, ou "Revisão incompleta" com os motivos). Diga exatamente isso ao desenvolvedor. Nunca apresente a saída do scanner como uma revisão.

Revisando um branch ou um pull request

Quando o desenvolvedor pedir para você revisar um branch ou um pull request que não é o trabalho atual deles, nomeie-o:

npx -y [email protected] review feature/login
npx -y [email protected] review '#42'

Coloque #42 entre aspas: em um shell # inicia um comentário. Um link de pull request também funciona. O OpenQodex busca o destino, faz checkout em uma pasta temporária e revisa o que foi adicionado desde que saiu de sua base. Este é código de outra pessoa: nunca execute seus testes, scripts, builds ou serviços, e nunca o edite.

Regras

• Nunca edite código durante a revisão. Revise primeiro, mostre o recibo, então corrija apenas os achados que o desenvolvedor nomear (passos 3 a 5).
• Nunca execute openqodex trust sem perguntar primeiro ao desenvolvedor. Isso aprova um scanner personalizado, que é um comando executado na máquina deles.
• Nunca defina OPENQODEX_SKIP. É a chave do desenvolvedor, não a sua.
• Quando o OpenQodex imprimir que arquivos escritos para seu agente são de uma versão mais antiga e que init os atualiza, informe o desenvolvedor em uma linha e dê a eles esse comando init. Execute-o apenas se eles pedirem: isso reescreve os arquivos do agente deles.
• Quando o veredito for bloqueado, não faça push a menos que o desenvolvedor diga após ver os achados.
• Quando o OpenQodex imprimir "O OpenQodex teve um problema. Nada foi enviado." com 1 crie um issue no GitHub e 2 ignore, informe ao desenvolvedor em uma linha o que deu errado e dê a eles as duas opções. Nunca escolha 1 você mesmo. Se eles disserem 1, execute npx -y [email protected] report --send-last da mesma pasta. Qualquer outra coisa significa 2: não faça nada.

Lendo o relatório

• O relatório está em .openqodex/reviews/<hora>-<id>/ no repositório: report.html para abrir em um navegador (cada arquivo alterado como um diff, cada achado abaixo de sua linha, depois cobertura, os scanners e o raio de explosão), report.md para ler como texto, report.json e report.sarif para ferramentas. O recibo fornece os caminhos absolutos de report.html e report.md. .openqodex/latest.json aponta para a revisão mais recente. Os relatórios nunca aparecem em git status: .openqodex/.gitignore os mantém de fora. Os dois outros arquivos nessa pasta, config.yaml e custom-instructions.md, são da equipe e devem ser commitados.
• O veredito é aprovado (com ou sem avisos) ou bloqueado. É bloqueado apenas quando a configuração do repositório (.openqodex/config.yaml, ou .openqodex.yaml na raiz) define block_on_severity e um achado está nela ou acima. Sem configuração, o OpenQodex avisa e nunca bloqueia.
• Uma revisão completa significa que todas as etapas foram executadas, cada achado do scanner foi verificado e cada linha alterada foi colocada diante do revisor; qualquer coisa não coberta é nomeada no relatório. Não significa que nada foi perdido: nenhuma revisão encontra tudo.
• A lista de cobertura diz, para cada scanner, se ele foi executado. Um scanner que não foi executado tem um motivo em uma linha:
  • nenhum arquivo correspondente: nada na alteração é o tipo de arquivo que ele lê.
  • instalando: está sendo baixado pela primeira vez; será incluído a partir da próxima execução. Diga isso ao desenvolvedor em vez de esperar.
  • não instalado: não pôde ser instalado aqui; o motivo explica por quê.
  • precisa de Ruby ou precisa de Go: brakeman precisa de Ruby 3.0 ou mais novo, rubocop precisa de Ruby 2.7 ou mais novo, golangci-lint precisa de Go. O OpenQodex não instala runtimes de linguagem. Se o desenvolvedor quiser esses scanners, eles instalam Ruby ou Go da maneira usual para seu sistema (por exemplo brew install ruby go em um Mac) e executam a revisão novamente.
  • não confiável: um scanner personalizado da configuração do repositório que o desenvolvedor não aprovou. Informe o desenvolvedor; aprová-lo é decisão dele (npx -y [email protected] trust).
  • falhou: o scanner foi executado e quebrou; o motivo tem seu erro. Um problema de scanner nunca altera o código de saída.

Dentro de uma sandbox

Alguns agentes executam comandos em uma sandbox que não pode acessar a rede ou escrever fora do projeto. Lá a primeira execução não pode baixar os scanners, e o revisor pode não alcançar seu modelo. Diga ao desenvolvedor para executar isso uma vez em seu próprio terminal, fora do agente, dentro do repositório:

npx -y [email protected] doctor --install

Isso baixa os scanners que os arquivos deste repositório chamam para ~/.openqodex/tools/ e imprime o motivo de cada um; --all-scanners baixa todos os scanners. Se a revisão ainda disser "Revisão completa indisponível" dentro da sandbox, o desenvolvedor executa npx -y [email protected] review em seu próprio terminal.

Mais

npx -y [email protected] guide imprime este guia. npx -y [email protected] guide <tópico> imprime uma página da documentação, offline: quickstart, config, scanners, custom-scanners, security, agents, cli, for-agents. for-agents cobre a instalação, a configuração, scanners personalizados e o que cada mensagem significa.

Antes de ler muitos arquivos para descobrir quem chama uma função, o que a implementa, como duas partes se conectam ou o que uma alteração atinge, você pode consultar o grafo de código: npx -y [email protected] graph help lista suas perguntas, ou use as ferramentas graph_ do servidor MCP openqodex quando seu agente as tiver; uma resposta com unknown.floor verdadeiro pode estar perdendo chamadores, então nunca a leia como "não utilizado".

Nunca adicione um arquivo a review.instructions_files por conta própria. Pergunte ao desenvolvedor quais arquivos o revisor pode usar, então defina apenas o que eles nomearem. O padrão é []; arquivos escolhidos são adicionados a .openqodex/custom-instructions.md.