Una metodología portable, versionada y agnóstica de agentes para mantener el control del proceso de ingeniería cuando trabajamos con Claude Code, Codex, OpenSpec u otras herramientas.
Durante los últimos meses —y especialmente en las últimas semanas— he ido incorporando cada vez más agentes de IA a mi forma de desarrollar software.
Claude Code y Codex forman parte habitual de ese trabajo. OpenSpec me ayuda a estructurar cambios antes de implementarlos. Y constantemente aparecen nuevas herramientas, modelos e integraciones que ofrecen capacidades interesantes.
Pero mientras más herramientas incorporaba, más evidente se hacía un problema que no tenía que ver directamente con la capacidad de los modelos.
¿Dónde vive realmente el estado de un proyecto?
Si una sesión de Claude Code contiene decisiones importantes, ¿qué ocurre cuando se termina el contexto o el límite de uso?
Si quiero continuar con Codex, ¿tengo que explicarle nuevamente todo?
Si mañana aparece un agente mejor, ¿mi metodología depende de las particularidades de Claude, Codex o de algún plugin?
Y hay una pregunta todavía más importante:
cuando un agente dice que terminó y que todo funciona, ¿qué significa realmente que funciona?
De esas preguntas nació engineering-workflow.
La idea
La premisa central es bastante sencilla:
El estado durable del proyecto debe vivir en el repositorio, no en la memoria del agente.
Un agente puede razonar, implementar, revisar y proponer.
Pero la autoridad sobre el estado del proyecto debería estar en artefactos que puedan sobrevivir al agente:
SPEC + GIT + TESTS + DOCS + HANDOFF
>
AGENT MEMORYEsto cambia bastante la forma de pensar el desarrollo asistido por IA.
Claude Code deja de ser el entorno donde vive el proyecto y pasa a ser una herramienta capaz de trabajar sobre él.
Lo mismo ocurre con Codex.
Y debería ocurrir lo mismo con cualquier agente futuro.
El workflow
La primera versión de la metodología utiliza este ciclo:
DISCOVER
↓
SHAPE
↓
SPEC
↓
IMPLEMENT
↓
VERIFY
↓
REVIEW
↓
DOCUMENT
↓
HANDOFF / COMMITCada etapa intenta responder una pregunta diferente.
DISCOVER busca entender el sistema existente antes de modificarlo.
SHAPE define el problema, el alcance, las restricciones y aquello que deliberadamente no vamos a resolver.
SPEC establece qué vamos a construir y, especialmente, qué significa que el trabajo esté terminado.
IMPLEMENT es donde finalmente modificamos el software.
Y aquí aparece una distinción que terminó siendo una de las ideas centrales del proyecto.
VERIFY no es REVIEW
Cuando comenzamos a trabajar con agentes resulta muy fácil aceptar algo como:
“La implementación está completa y todos los tests pasan.”
Eso es importante, pero no es suficiente.
En engineering-workflow intento separar explícitamente tres preguntas:
VERIFY
¿Podemos demostrar que la implementación funciona?
REVIEW
¿Qué defectos podrían seguir existiendo?
ADVERSARIAL REVIEW
¿La solución y sus supuestos son realmente correctos?VERIFY debe apoyarse en evidencia determinística siempre que sea posible:
tests
linters
builds
exit codes
checksUn agente diciendo PASS no constituye verificación.
Pero incluso una suite completa de tests pasando sólo demuestra algo acerca del comportamiento que efectivamente estamos probando.
No demuestra necesariamente que hayamos considerado todos los casos importantes.
Durante el desarrollo de la propia herramienta ocurrió exactamente eso.
La suite estaba completamente en verde y un review independiente con Codex encontró un caso que los tests no estaban cubriendo.
Eso produjo otro principio operativo:
REVIEW
↓
FINDING ACCEPTED
↓
IMPLEMENT
↓
VERIFY
↓
RE-REVIEWEl finding no se resuelve porque el agente diga que lo corrigió.
Se vuelve a verificar.
Dogfooding
Aquí apareció una oportunidad particularmente interesante.
Decidí desarrollar engineering-workflow utilizando engineering-workflow.
Es decir, hacer dogfooding de la propia metodología.
La herramienta comenzó a encontrarse con los mismos problemas que pretende resolver:
- decisiones de diseño;
- cambios de alcance;
- verificación;
- reviews;
- findings;
- documentación;
- handoffs;
- conflictos;
- seguridad;
- continuidad entre agentes.
Los reviews y adversarial reviews encontraron problemas reales en la propia implementación y esos problemas fueron incorporados nuevamente al ciclo.
Eso permitió que la metodología dejara de ser solamente un diagrama atractivo y comenzara a enfrentarse a su propio uso.
El riesgo también importa
Otra conclusión fue que no tiene sentido aplicar la misma ceremonia a todo.
Corregir un typo no debería requerir el mismo proceso que modificar persistencia, infraestructura o producción.
Por eso el workflow considera distintos niveles:
LOW
→ verify
MEDIUM
→ verify + review
HIGH
→ verify + independent/deeper review
CRITICAL
→ verify + adversarial review + explicit human approvalLa intención no es agregar burocracia.
Es aplicar rigor proporcional al riesgo.
De hecho, una de las reglas que quiero preservar a medida que evolucione el proyecto es:
Si operar la metodología cuesta más que el riesgo que intenta controlar, probablemente estamos usando mal la metodología.
¿Y OpenSpec?
OpenSpec encaja naturalmente dentro del proceso, pero tampoco constituye la metodología.
Lo estoy utilizando principalmente alrededor de SHAPE y SPEC, donde necesitamos transformar una idea en requisitos y criterios verificables antes de comenzar a implementar.
De la misma forma, Claude Code y Codex son capacidades opcionales.
La arquitectura conceptual es más cercana a esto:
engineering-workflow
│
┌────────────────┼────────────────┐
▼ ▼ ▼
OpenSpec Git / Tests Documentation
│ │
└──────────────┬──────────────────┘
▼
AGENTS
┌─────┴─────┐
▼ ▼
Claude Code CodexSi mañana reemplazo uno de ellos, el proyecto debería seguir siendo comprensible y operable.
¿Qué pasa cuando se termina un agente?
Éste era uno de los problemas originales.
La solución no consiste simplemente en transferir la conversación completa al siguiente modelo.
El proyecto mantiene un HANDOFF que permite reconstruir operacionalmente:
- objetivo;
- estado actual;
- trabajo completado;
- verificación;
- findings abiertos;
- decisiones;
- siguiente acción.
El siguiente agente debería poder recuperar el contexto relevante leyendo el repositorio.
Una integración específica puede hacer esa transferencia más cómoda, pero es un acelerador.
No debería ser la fuente de verdad.
v0.1.0
La primera versión ya está disponible.
v0.1.0 implementa deliberadamente un core pequeño:
install
↓
doctor
↓
init-project
↓
operate
↓
handoff
↓
uninstallNo quiero convertirlo rápidamente en otro framework gigantesco.
Todavía faltan cosas.
Y algunas son deliberadamente importantes.
La primera versión ha sido probada empíricamente en macOS. Ubuntu Desktop y Ubuntu Server forman parte de los objetivos de diseño, pero todavía quiero validar físicamente la misma versión en ambos entornos antes de afirmar que esa portabilidad está demostrada.
Después vendrán proyectos reales.
Y, espero, pruebas realizadas por otras personas.
El proyecto está disponible
He decidido publicar el repositorio porque probablemente esta misma problemática la estén encontrando otras personas que trabajan diariamente con coding agents.
No espero que mi metodología sea necesariamente la correcta.
De hecho, me interesa especialmente descubrir dónde no funciona.
Si trabajas con Claude Code, Codex, OpenSpec u otros agentes y quieres probarla, cuestionarla, romperla o mejorarla, cualquier experiencia puede ser útil.
engineering-workflow en GitHub
La v0.1.0 es un punto de partida.
No un producto terminado.
Nota sobre el idioma
Aunque este artículo está escrito en español, engineering-workflow está desarrollado y documentado principalmente en inglés de forma intencional.
Buena parte de la terminología utilizada en ingeniería de software, desarrollo asistido por IA y coding agents no tiene una traducción ampliamente aceptada al español o pierde precisión al traducirse.
Conceptos como dogfooding, handoff, rollback, review gate, runtime, tooling o workflow son buenos ejemplos.
El proyecto nace desde un contexto hispanohablante, pero conserva la terminología técnica en inglés cuando hacerlo mejora la precisión, la compatibilidad con las herramientas y la consistencia con el ecosistema de ingeniería.
Las conversaciones, issues y contribuciones pueden realizarse tanto en español como en inglés.