Saltar al contenido principal

Codex · Claude Code · Gemini CLI · agentes con terminal

Usa QZX para entender un proyecto antes de que tu agente de IA lo cambie

Instala QZX, comprueba que la CLI funciona con una operación de solo lectura y luego convierte un repositorio desconocido en evidencia estructurada para Codex, Claude Code, Gemini CLI u otro agente con acceso a terminal.

python -m pip install --upgrade qzx
qzx getCurrentDateTime --output-format iso --json
Ver QZX en acción

La primera comprobación no requiere cuenta ni modifica tu proyecto. Continúa abajo cuando quieras inspeccionar un código real.

Paso 1 · Instala e identifica

Verifica el paquete antes de delegar trabajo

Usa una compilación estándar de CPython que cumpla los metadatos del paquete. Estos comandos instalan la versión publicada actual, la identifican y completan el mismo primer éxito canónico que muestra la CLI.

python -m pip install --upgrade qzx
qzx version --json
qzx getCurrentDateTime --output-format iso --json

Usa el comando de instalación generado anterior cuando controles el entorno Python seleccionado. Para una CLI independiente y aislada también puedes usar pipx install qzx. Si pip muestra externally-managed-environment, prefiere pipx en lugar de forzar el Python del sistema. Elige la ruta de instalación adecuada. Si falta un comando, actualiza QZX y comprueba qzx version --json antes de continuar.

Por qué este comando: Confirma QZX con una marca de tiempo ISO rápida y de solo lectura. El sitio puede documentar capacidades de desarrollo más nuevas que el wheel, así que considera el catálogo instalado —no un artículo ni un prompt— como la fuente de verdad sobre lo que puede ejecutar este equipo. Revisa la compatibilidad de Python y plataformas. Los resultados para máquinas siguen el QZX Result Contract v1 abierto.

Paso 2 · Tu primer flujo útil

Convierte un repositorio desconocido en un diagnóstico de proyecto

Después de completar el paso 1, abre una terminal dentro del proyecto que deseas inspeccionar. El punto representa ese directorio, no todo tu disco. Ejecuta estos tres comandos por separado; inspeccionan el proyecto sin ejecutar sus pruebas, scripts de compilación ni instaladores.

qzx getProjectTree . 2 --max_entries 200 --json
qzx diagnoseProject . --json
qzx projectLanguages . --json

¿Necesitas ayuda o quieres contar cómo te fue?

1. Entiende la estructura

Lee tree_text para una vista rápida o tree_structure desde código. El ejemplo conserva como máximo 200 entradas hasta dos niveles de profundidad. Comprueba details.entry_limit_reached y details.scan_complete antes de considerar completa la vista.

2. Encuentra la siguiente acción útil

Inspecciona details.technologies, los manifiestos de dependencias y details.summary.issues. El diagnóstico descubre la configuración de validación; no la ejecuta ni certifica que las pruebas hayan pasado.

3. Conoce con qué estás trabajando

Lee summary.primary_language y languages. La documentación y la configuración quedan separadas en supporting_formats, en lugar de presentarse como código de la aplicación.

Qué pedirle después a tu agente

Usando estos resultados de QZX, resume el proyecto, identifica el problema observado más importante y propón un siguiente paso. Separa los hechos observados de las suposiciones. No afirmes que las pruebas pasaron y todavía no modifiques archivos ni ejecutes scripts del proyecto.

Comprueba localmente los comandos y parámetros disponibles:

qzx listCommands file
qzx help findFiles
qzx help diagnoseProject --json
Explora el catálogo instalado
Filtra el catálogo instalado para ver comandos relacionados con archivos.
Comprende antes de ejecutar
Revisa parámetros, ejemplos, madurez y seguridad antes de ejecutar.

¿Este flujo te ayudó?

Después de probarlo en tu terminal, cuéntale a Alejandro qué pasó o ve directamente a la ayuda. La respuesta opcional no exige cuenta ni explicación.

Opcional: la categoría elegida se envía con la sesión analítica existente del sitio. No leemos tu terminal, proyecto, destino ni portapapeles. Es tu valoración, no una comprobación automática. Cómo se usa esta respuesta

¿Encontraste un problema reproducible? Abre el formulario de errores existente, revisa sus campos y decide qué compartir. Los reportes son públicos y requieren iniciar sesión en GitHub.

Reportar a Alejandro un problema del flujo

Paso 3 · Añade instrucciones duraderas

Un bloque de instrucciones que los agentes pueden seguir

Coloca una versión revisada de este bloque en el mecanismo de instrucciones que admita tu agente. Codex puede usar AGENTS.md, Claude Code usa CLAUDE.md y Gemini CLI usa GEMINI.md. La herramienta de terminal debe seguir habilitada conforme al modelo de permisos del producto.

## Política de comandos QZX

- Usa QZX solo cuando un comando documentado coincida con la tarea.
- Antes del primer uso, ejecuta `qzx version --json`, `qzx getCurrentDateTime --output-format iso --json`, `qzx listCommands file` y `qzx help findFiles`.
- Añade `--json` cuando otro programa o agente consuma el resultado.
- Comprueba tanto el código de salida del proceso como el campo `success`.
- Lee `message` y los campos del comando; no deduzcas éxito solo porque falten errores.
- Comienza con comandos de solo lectura.
- Antes de una mutación, revisa la página del comando, el preview/dry-run, la aprobación y el respaldo.
- Si QZX no modela la operación, usa una API nativa mantenida o el shell.
- QZX no es un sandbox y se ejecuta con los permisos del usuario actual.
OpenAI: contexto persistente con AGENTS.md Anthropic: memoria de Claude Code Gemini CLI: contexto GEMINI.md

Paso 4 · Elige la interfaz correcta

QZX es una capa útil, no todas las capas

Usa QZX CLI

Para una operación local documentada de sistema, archivos, desarrollo o red donde ayuden un comando multiplataforma y una salida estructurada.

Usa MCP

Cuando un host compatible con MCP necesite herramientas, recursos o prompts descubribles desde un servidor local o remoto, con ciclo de vida y autorización de protocolo.

Usa una API directa

Cuando el código de una aplicación necesite un SDK tipado mantenido, control dentro del proceso, autenticación propia del servicio o el contrato de dominio más fuerte.

Estas opciones pueden combinarse: un servidor MCP puede llamar a una CLI y una CLI puede usar una API del sistema operativo. La pregunta correcta es qué frontera ofrece al host el contrato más claro con la menor complejidad innecesaria. Lee la guía práctica de MCP vs CLI vs API.

Listo para delegar

Elige un comando de solo lectura y revisa el resultado real

El catálogo documenta disponibilidad, parámetros, propiedades de seguridad, contrato de resultado y si la salida mostrada es registrada o representativa.