openqodex

OpenQodex: revisa el cambio antes de enviarlo

OpenQodex revisa un cambio con un solo comando. Toma una copia congelada del cambio, ejecuta los escáneres deterministas que se ajustan a los archivos modificados (gitleaks, semgrep, bandit, hadolint, shellcheck, actionlint, osv-scanner y otros), conserva lo que reportan sobre las líneas modificadas, e inicia su propio revisor: un proceso separado de Claude Code o Codex que lee solo esa copia. El revisor verifica cada hallazgo del escáner, recibe cada línea modificada y responde en un formato fijo; OpenQodex comprueba la respuesta con scripts e imprime un informe. No se necesita clave ni cuenta más allá del inicio de sesión de Claude Code o Codex del desarrollador. El código va al modelo que usa ese inicio de sesión. El revisor también puede buscar en la web y abrir páginas web a menos que reviewer_web: off esté configurado en ~/.openqodex/config.yaml. Cuatro escáneres se conectan en línea, y ninguno envía código. semgrep descarga sus paquetes de reglas del registro de Semgrep en cada ejecución. Cuando el cambio toca un archivo de dependencias, osv-scanner envía los nombres y versiones de las dependencias a osv.dev. kubeconform descarga esquemas de Kubernetes. cargo-deny descarga la base de datos de avisos de RustSec. --offline omite semgrep, osv-scanner, kubeconform y cargo-deny.

Cuándo ejecutarlo

• Antes de cualquier git push.
• Cuando el desarrollador te pida revisar sus cambios.
• Cuando un push fue bloqueado o advertido por el hook de OpenQodex.
• Después de corregir hallazgos, para verificar el cambio nuevamente.

Quién revisa

OpenQodex inicia su propio proceso revisor para cada revisión, sin memoria de esta sesión. Tú no inicias un subagente para ello y no revisas el cambio tú mismo: ejecuta el comando y muestra lo que imprime.

Si review dice "Full review unavailable" e imprime una forma de revisar con el agente en el que estás, síguela: ejecuta el comando que nombra y haz lo que dice la instrucción que imprime.

Procedimiento

Cuando el archivo ~/.openqodex/bin/openqodex existe, ejecútalo en lugar de npx -y openqodex@<version> en cada comando de esta skill: es la copia que instaló openqodex init. Cuando no existe, esta skill se instaló sola, sin verificación de push: antes de la primera revisión, ejecuta npx -y [email protected] init --yes --agent <host> una vez desde el repositorio, donde <host> es el agente que eres (claude-code, codex, cursor o cline). Instala OpenQodex para ti, luego revisa el cambio cuando un revisor pueda iniciar, por lo que puede tomar varios minutos. Ejecútalo en segundo plano y espera a que termine. Cuando imprima First review: finished, el recibo que está encima de esa línea es el de la revisión: muéstralo como dice el paso 3, luego continúa desde el paso 4.

1. Desde el repositorio, ejecuta:

   npx -y [email protected] review
   

   Revisa el cambio: los commits aún no enviados más todo lo no confirmado, incluidos los archivos no rastreados. Para revisar todo el repositorio en su lugar, ejecuta:

   npx -y [email protected] review --all
   

2. Espera. Una revisión puede tomar minutos. OpenQodex detiene al revisor después de 30 minutos, o después de 2 horas con --all. Muchos agentes detienen un comando antes. Así que ejecútalo en segundo plano y espera hasta que termine. Mientras el revisor trabaja, imprime una línea de progreso cada 15 segundos en stderr. No lo inicies una segunda vez mientras uno se ejecuta.

3. Muestra al desarrollador el recibo que imprimió, tal como se imprimió: el veredicto, una línea por hallazgo (su número, gravedad, categoría, título, archivo y línea) y la ruta absoluta de report.html. No lo reformules, acortes ni añadas hallazgos propios. Dale la ruta de report.html: esa página muestra cada archivo modificado con cada hallazgo debajo de su línea de código. Cuando el recibo termina con Observations (do not count toward the verdict): y líneas numeradas debajo, muestra esas líneas también tal como se imprimieron. Una observación es una nota de estilo, nomenclatura, documentación o pruebas. No es un hallazgo que corregir a menos que el desarrollador nombre su número.

4. Pregunta al desarrollador: "¿Corregir todo, o dime cuáles?" No cambies ningún código antes de que responda. Si ya te dijo qué corregir, por ejemplo "revisa y corrige todo", hazlo sin preguntar de nuevo.

5. Corrige solo los hallazgos que nombre. Esto imprime esos hallazgos completos (dónde, el problema, por qué importa, la corrección y la fuente), por sus números en el recibo:

   npx -y [email protected] findings 1,3
   

   findings all imprime cada hallazgo. Cuando las correcciones estén hechas, ejecuta la revisión nuevamente y muestra al desarrollador el nuevo recibo.

6. Actúa según el código de salida:

   • 0: la revisión está completa y nada bloquea el push.
   • 1: la revisión está completa y su veredicto es blocked. No hagas push. Muestra al desarrollador el recibo y pregunta qué hallazgos corregir; haz push solo si él lo dice después de ver los hallazgos.
   • 2: no hay una revisión completa. La salida dice qué falta (por ejemplo "Full review unavailable" cuando ningún revisor pudo iniciar, o "Review incomplete" con las razones). Dile exactamente eso al desarrollador. Nunca presentes la salida del escáner como una revisión.

Revisar una rama o una pull request

Cuando el desarrollador te pida revisar una rama o una pull request que no sea su trabajo actual, nómbrala:

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

Pon entre comillas #42: en un shell # inicia un comentario. Un enlace de pull request también funciona. OpenQodex obtiene el destino, lo revisa en una carpeta temporal y revisa lo que añadió desde que se separó de su base. Este es código de otra persona: nunca ejecutes sus pruebas, scripts, compilaciones o servicios, y nunca lo edites.

Reglas

• Nunca edites código durante la revisión. Revisa primero, muestra el recibo, luego corrige solo los hallazgos que el desarrollador nombre (pasos 3 a 5).
• Nunca ejecutes openqodex trust sin preguntar primero al desarrollador. Aprueba un escáner personalizado, que es un comando que se ejecuta en su máquina.
• Nunca establezcas OPENQODEX_SKIP. Es el interruptor del desarrollador, no el tuyo.
• Cuando OpenQodex imprima que los archivos que escribió para tu agente son de una versión anterior y que init los actualiza, díselo al desarrollador en una línea y dale ese comando init. Ejecútalo solo si te lo pide: reescribe los archivos de su agente.
• Cuando el veredicto sea blocked, no hagas push a menos que el desarrollador lo diga después de ver los hallazgos.
• Cuando OpenQodex imprima "OpenQodex had a problem. Nothing has been sent." con 1 create a GitHub issue y 2 ignore, dile al desarrollador en una línea qué salió mal y dale las dos opciones. Nunca elijas 1 tú mismo. Si dice 1, ejecuta npx -y [email protected] report --send-last desde la misma carpeta. Cualquier otra cosa significa 2: no hagas nada.

Leer el informe

• El informe está en .openqodex/reviews/<time>-<id>/ en el repositorio: report.html para abrir en un navegador (cada archivo modificado como un diff, cada hallazgo debajo de su línea, luego cobertura, los escáneres y el radio de explosión), report.md para leer como texto, report.json y report.sarif para herramientas. El recibo da las rutas absolutas de report.html y report.md. .openqodex/latest.json apunta a la revisión más reciente. Los informes nunca aparecen en git status: .openqodex/.gitignore los mantiene fuera. Los otros dos archivos en esa carpeta, config.yaml y custom-instructions.md, son del equipo y están destinados a ser confirmados.
• El veredicto es passed (con o sin advertencias) o blocked. Es blocked solo cuando la configuración del repositorio (.openqodex/config.yaml, o .openqodex.yaml en la raíz) establece block_on_severity y un hallazgo está en ese nivel o por encima. Sin configuración, OpenQodex advierte y nunca bloquea.
• Una revisión completa significa que cada etapa se ejecutó, cada hallazgo del escáner fue verificado y cada línea modificada se puso frente al revisor; cualquier cosa no cubierta se nombra en el informe. No significa que no se haya pasado nada por alto: ninguna revisión encuentra todo.
• La lista de cobertura dice, para cada escáner, si se ejecutó. Un escáner que no se ejecutó tiene una razón de una línea:
  • no matching files: nada en el cambio es el tipo de archivo que lee.
  • installing: se está descargando por primera vez; se incluirá a partir de la próxima ejecución. Dilo al desarrollador en lugar de esperar.
  • not installed: no se pudo instalar aquí; la razón dice por qué.
  • needs Ruby o needs Go: brakeman necesita Ruby 3.0 o más reciente, rubocop Ruby 2.7 o más reciente, golangci-lint necesita Go. OpenQodex no instala entornos de ejecución de lenguajes. Si el desarrollador quiere esos escáneres, instala Ruby o Go de la forma habitual para su sistema (por ejemplo brew install ruby go en un Mac) y ejecuta la revisión nuevamente.
  • untrusted: un escáner personalizado de la configuración del repositorio que el desarrollador no ha aprobado. Dilo al desarrollador; aprobarlo es su decisión (npx -y [email protected] trust).
  • failed: el escáner se ejecutó y falló; la razón tiene su error. Un problema del escáner nunca cambia el código de salida.

Dentro de un sandbox

Algunos agentes ejecutan comandos en un sandbox que no puede alcanzar la red ni escribir fuera del proyecto. Allí la primera ejecución no puede descargar los escáneres, y el revisor puede no alcanzar su modelo. Dile al desarrollador que ejecute esto una vez en su propia terminal, fuera del agente, dentro del repositorio:

npx -y [email protected] doctor --install

Descarga los escáneres que requieren los archivos de este repositorio en ~/.openqodex/tools/ e imprime por qué para cada uno; --all-scanners descarga todos los escáneres. Si la revisión aún dice "Full review unavailable" dentro del sandbox, el desarrollador ejecuta npx -y [email protected] review en su propia terminal.

Más

npx -y [email protected] guide imprime esta guía. npx -y [email protected] guide <topic> imprime una página de la documentación, sin conexión: quickstart, config, scanners, custom-scanners, security, agents, cli, for-agents. for-agents cubre la instalación, la configuración, los escáneres personalizados y lo que significa cada mensaje.

Antes de leer muchos archivos para encontrar quién llama a una función, qué la implementa, cómo se conectan dos partes o qué alcanza un cambio, puedes preguntar al grafo de código: npx -y [email protected] graph help lista sus preguntas, o usa las herramientas graph_ del servidor MCP openqodex cuando tu agente las tenga; una respuesta con unknown.floor true puede estar omitiendo llamantes, así que nunca la leas como "no usado".

Nunca añadas un archivo a review.instructions_files por tu cuenta. Pregunta al desarrollador qué archivos puede usar el revisor, luego establece solo los que nombre. El valor predeterminado es []; los archivos elegidos se añaden a .openqodex/custom-instructions.md.