codex-workflows

English | 简体中文 | 日本語 | Español | 한국어 | Português (Brasil)

En trabajos de producto grandes, Codex puede perseguir una coherencia técnica que va más allá de lo que el usuario necesita. Cubrir hasta el último caso límite y forzar un resultado determinista en cada camino puede acabar cambiando lo que ve el usuario, aunque el resultado acordado no lo requiera.

codex-workflows mantiene el trabajo dentro del resultado mínimo aprobado. Primero deja claro qué comportamiento visible puede cambiar y qué debe permanecer intacto; después exige pruebas antes de dar el trabajo por terminado. Dentro de esos límites, Codex elige detalles de implementación reversibles a partir de lo que ya existe en el repositorio.

Los flujos se instalan como Agent Skills y agentes personalizados para OpenAI Codex CLI. La sesión principal de Codex confirma el alcance y el coste aproximado antes de diseñar, se hace cargo del avance y de las decisiones de revisión, y lleva el trabajo aprobado desde la implementación hasta una verificación independiente.

¿Por qué no usar Codex directamente?

Codex por sí solo es la mejor opción para una corrección bien acotada, un experimento desechable o un script puntual. Cuando el resultado esperado y el límite seguro de implementación ya están claros, es más rápido y económico.

Usa codex-workflows cuando una decisión técnica pueda ampliar el producto, alterar el comportamiento visible o deba conservarse al cambiar de contexto.

Por ejemplo, una petición para ampliar un flujo de autenticación existente puede desembocar en un segundo mecanismo técnicamente más limpio, más validaciones y un contrato de respuesta nuevo. El frontend puede adaptarse y todas las pruebas pueden pasar, pero el usuario termina recibiendo un comportamiento que nunca se aprobó.

codex-workflows evita que el alcance crezca sin control durante toda la ejecución:

Este flujo requiere más llamadas a agentes y más tokens que una ejecución directa. Úsalo cuando proteger el resultado acordado compense ese coste. Cuando un cambio no necesita todos los controles, el modo ligero ejecuta menos.

Un caso límite no exige trabajo solo porque Codex sepa resolverlo. Añadir validaciones, hacer determinista un comportamiento o crear otra abstracción debe servir para proteger un requisito aprobado o un contrato observable, o para corregir un fallo demostrado. Y funciona en ambos sentidos: si una decisión de diseño acaba abarcando más de lo que el resultado necesita, el flujo la retira en vez de defenderla porque ya figure en un documento.

Un caso real

La integración del proveedor BytePlus Seedream en mcp-image añadió un tercer proveedor externo de imágenes en 18 archivos. Ocho tareas planificadas permitieron evolucionar la implementación específica del proveedor sin modificar los contratos públicos de solicitud MCP, cliente, guardado de archivos ni URI de archivo.

Antes del merge, una evaluación contra el servicio real fijó el enrutamiento final de modelos, los límites del prompt, el timeout y el tratamiento de respuestas. Las revisiones independientes también detectaron una lectura de archivos sin límite, una vía para saltarse la validación, una ruta FIFO bloqueante y una normalización incoherente de claves API. Se corrigieron los cuatro problemas y el PR superó 303 pruebas repartidas en 19 archivos, además de una llamada real al proveedor sin reintentos. Los contratos públicos aprobados se mantuvieron intactos durante las ocho tareas y las cuatro correcciones.

Inicio rápido

Necesitas Node.js 22 o posterior y la última versión de Codex CLI.

Instalar y ejecutar

cd your-project
npx codex-workflows install

Después, invoca un flujo desde Codex CLI:

$recipe-implement Añade autenticación de usuarios con JWT

El prefijo $ invoca una skill de forma explícita. Escribe $recipe- para ver los flujos disponibles.

Elige el punto de entrada

En tareas largas, $recipe-outcome-watch revisa el trabajo de forma independiente mientras Codex avanza y avisa si empieza a añadir funciones innecesarias o a alejarse del resultado que pediste. Puedes activarlo mientras trabajas:

$recipe-outcome-watch Comprueba el trabajo con respecto a docs/design/export.md cada 60 minutos durante 4 horas

Indica un documento de diseño, un plan o una descripción de la tarea, o explica el objetivo directamente. Los avisos llegan a la sesión de trabajo; si todo va bien, no envía notificaciones. La supervisión termina al cumplirse el plazo, o antes si le pides a Codex que la detenga.

Cómo funciona

flowchart LR
    A[Petición] --> B[Acordar el resultado mínimo útil]
    B --> C{¿Hay una vía de implementación clara?}
    C -->|Sí| S[Ciclo directo de tareas y revisión de seguridad]
    S --> L[Finalizado]
    C -->|No| D[Inspección, diseño y revisión]
    D --> E[Planificar el trabajo dependiente]
    E --> F[Autorizar la implementación]
    F --> H[Por tarea: implementar, verificar, comprobar calidad y hacer commit]
    H --> K[Revisión independiente de código y seguridad]
    K -->|Corrección| H
    K -->|Cambian los requisitos o el diseño principal| B
    K -->|Aprobado| L[Finalizado]

La ruta depende del número de decisiones independientes de producto y diseño, no de cuántos archivos cambien ni de cuántos casos límite sea capaz de encontrar Codex.

Un cambio con un solo resultado que sigue un patrón existente en una parte del sistema pasa directamente a una tarea confirmada y después a la implementación, con controles de calidad y seguridad. Un cambio que exige coordinar varias partes del sistema o tomar una decisión de diseño duradera recibe primero un Design Doc y un Work Plan revisados, más una UI Spec o un ADR cuando alguna de sus decisiones lo requiera. Si el cambio tiene varios resultados que requieren decisiones de diseño independientes, también se crea un PRD, salvo que decidas omitirlo. Solo se escribe un ADR cuando una decisión duradera tiene al menos dos opciones sustancialmente distintas. El comportamiento se demuestra con pruebas de integración y E2E donde lo observan los usuarios y los sistemas que lo llaman, y solo se añade una prueba unitaria para lógica, como un cálculo o un parser, cuyos casos no puede cubrir una sola de esas pruebas.

Una vez autorizada la implementación, la sesión principal ejecuta las tareas, sus verificaciones específicas, los controles aplicables del repositorio y un commit de implementación por tarea. Primero resuelve los problemas a partir de los documentos aprobados y de la evidencia del repositorio. El comportamiento visible sigue siendo una frontera de producto: la implementación no puede ajustarlo por su cuenta para lograr coherencia interna. La sesión principal solo te consulta cuando avanzar exige un requisito de producto nuevo, cambiar algo que pediste o descartaste, usar una autorización que solo tú tienes o realizar una acción irreversible que no autorizaste. Encontrar una forma más acotada de llegar al mismo resultado no entra ahí, ni tampoco volver a pedir un permiso que ya diste. El flujo no añade la aprobación de terceros, el acceso a producción ni la ejecución de una release como condiciones para dar por terminada la implementación.

Modo ligero

$recipe-implement Modo ligero. Añade una tabla ordenable a la página de informes

Pide el modo ligero en la petición de cualquier flujo. Las fases y los puntos de aprobación no cambian, pero Codex ejecuta menos controles: los Design Docs no se contrastan con el repositorio ni entre sí, y se omite la revisión de seguridad. Los controles del repositorio se ejecutan una sola vez después de la última tarea, en lugar de antes de cada commit, y la revisión final del código se mantiene. El modo ligero sigue activo durante el resto de la sesión hasta que le pidas a Codex que lo desactive.

Instalación

Instalar

Instala los flujos en el proyecto actual:

cd your-project
npx codex-workflows install

Se copiarán estos elementos al proyecto:

• .agents/skills/: skills de Codex (fundamentos y flujos)
• .codex/agents/: definiciones TOML de subagentes
• Un manifiesto para controlar los archivos gestionados

Para que los flujos estén disponibles en todos tus proyectos, instálalos en el CODEX_HOME del usuario:

npx codex-workflows install --user

Las skills se instalan en $CODEX_HOME/skills/ y los agentes en $CODEX_HOME/agents/. Si CODEX_HOME no está definido, se usa ~/.codex.

Personalizar agentes

Las definiciones de los agentes son archivos TOML normales. En una instalación de proyecto, edita los archivos de .codex/agents/; en una instalación de usuario, edita los de $CODEX_HOME/agents/. Puedes cambiar model, sandbox_mode o developer_instructions. Los archivos que edites se conservan durante las actualizaciones, como se explica a continuación.

Actualizar

# Previsualizar los cambios
npx codex-workflows update --dry-run

# Aplicar la actualización
npx codex-workflows update

# Actualizar una instalación de usuario
npx codex-workflows update --user

El actualizador conserva los archivos que hayas modificado localmente. Compara cada archivo con su hash en el momento de la instalación y omite los que hayan cambiado. Si una actualización traslada un archivo, tus cambios locales lo acompañan a la nueva ruta. Los archivos modificados que se retiran sin sustituto se mueven a .codex-workflows-preserved/<version>/. Los archivos nuevos se añaden automáticamente.

# Consultar la versión instalada
npx codex-workflows status

# Consultar una instalación de usuario
npx codex-workflows status --user

Para desinstalar, ejecuta npx codex-workflows uninstall (con --user si es una instalación de usuario). Los archivos que hayas modificado localmente no se borran.

Referencia de flujos

Invoca un flujo con $recipe-name en Codex. Escribe $recipe- y usa el autocompletado con Tab para ver todas las opciones.

Estado de trabajo

Los flujos usan docs/plans/ como estado temporal para Work Plans, Task Files de implementación y Task Files provisionales de corrección o ampliación de pruebas. Añade el directorio al .gitignore del proyecto, salvo que el equipo quiera revisar expresamente esos archivos transitorios:

docs/plans/

Los PRD, ADR, UI Spec y Design Docs son documentación permanente del proyecto y sí deben incluirse en los commits.

Orientaciones incluidas

No hace falta invocar un flujo para aprovechar estas skills. Codex también las carga en una conversación normal, así que una corrección pequeña sigue los mismos criterios de causa raíz, alcance y verificación que un flujo completo.

Ecosistema

Nautilus valida ideas de producto y convierte los resultados en un PRD, mientras que linear-prism convierte requisitos aprobados en incidencias de Linear listas para implementar. claude-code-workflows aplica el mismo enfoque a Claude Code y puede instalarse junto con codex-workflows. outcome-doctor usa Jev para comprobar si el enfoque de implementación de Codex se queda corto o se pasa respecto al objetivo, y necesita una clave de API de TypeSafe.

¿Quieres usar Astra aquí?

Ejecutar un flujo completo con Astra agota el límite de uso enseguida. codex-subagent-playbook es un plugin de Codex que elige el modelo de cada subagente, así que solo usa Astra donde realmente cambia el resultado.

codex plugin marketplace add shinpr/codex-subagent-playbook

[[skills.config]]
path = "/Users/you/.codex/skills/subagent-delegation/SKILL.md"
enabled = false

[[skills.config]]
path = "/absolute/path/to/your-project/.agents/skills/subagent-delegation/SKILL.md"
enabled = false

Motivos de diseño

Licencia

Licencia MIT. Puedes usar, modificar y distribuir el proyecto libremente.

Creado y mantenido por @shinpr.