SpecGuard - Plugin CLI/Codex que revisa primero las especificaciones antes de programar con IA
(github.com/KoreaNirsa)Hola. Estoy creando una herramienta open source llamada SpecGuard.
Cuando usas herramientas de programación con IA como Codex o Claude Code, la velocidad de implementación sin duda mejora. Pero después de usarlas varias veces, el problema con el que yo realmente me topé con frecuencia estaba más cerca de “la IA no sabe programar” que de “la especificación que le pasé a la IA está incompleta”.
Si la especificación tiene defectos, la IA implementa rellenando esos huecos a su manera. Al principio parece razonable, pero conforme avanza el desarrollo, crecieron los siguientes problemas.
- La calidad y la estructura del código se van deteriorando.
- La especificación y el código cada vez dejan de coincidir más.
- Más adelante se vuelve difícil distinguir si el código está mal, si la especificación ya quedó obsoleta o si desde el inicio los requerimientos eran ambiguos.
Por eso pensé que no bastaba con hacer code review después de implementar. Antes de que una especificación defectuosa llegue tal cual al agente de implementación, hacía falta una etapa para revelar primero los huecos de la propia especificación.
SpecGuard es un plugin CLI/Codex creado para reducir este problema. No es una herramienta que inspecciona el resultado después de generar código, sino una herramienta que revisa primero la especificación antes de delegar la implementación a la IA.
Este es el flujo básico que tenía en mente.
- Una persona escribe la especificación del producto.
- Se revisa la especificación con SpecGuard.
- Si sale
NOT_READY, se refuerza la especificación. - Cuando queda en
READY, se entrega a un agente de implementación como Codex o Claude Code.
SpecGuard busca sobre todo este tipo de huecos.
- Límites de autenticación/autorización poco claros
- Falta el alcance de ownership de tenant/user
- No hay manejo de idempotency, replay o race condition
- Las reglas de expiración/revocación/transición de estado son ambiguas
- No hay política de reintentos para efectos externos, webhooks o background jobs
- Requerimientos que solo confían en la validación del cliente
Los resultados se agrupan en tres grandes estados.
READY: se puede entregar al agente de implementaciónREADY_WITH_WARNINGS: se puede entregar, pero hay puntos a tener en cuentaNOT_READY: hay problemas Critical/Major y hace falta reforzar la especificación
La ruta por defecto es la revisión heurística con --no-llm. Esto porque en CI o PR Review considero importante que el resultado sea rápido y reproducible. También se puede añadir una revisión detallada basada en OpenAI Platform o Codex, pero por ahora la dejo como una ruta auxiliar opcional para cuando se quiera revisar con más profundidad.
Lo agregado en v0.4.0
En esta v0.4.0 agregué el MVP del plugin para la app de Codex.
pip install spec-guard
specguard --help
codex plugin marketplace add KoreaNirsa/spec-guard --ref main
Si seleccionas la fuente SpecGuard Plugins en la app de Codex e instalas el plugin SpecGuard, puedes pedir que se ejecute SpecGuard dentro de Codex. Por ejemplo, después de crear una especificación de muestra:
specguard example copy specs/your-feature-name --force
En Codex puedes abrir esa carpeta y pedir algo así.
1. @SpecGuard ejecuta SpecGuard para specs/your-feature-name.
2. @SpecGuard ejecuta SpecGuard para el paquete de especificación specs/your-feature-name y resume el estado READY/NOT_READY y los hallazgos principales.
3. @SpecGuard ejecuta SpecGuard para specs/your-feature-name. Usa la revisión heurística por defecto y resume el estado resultante y lo siguiente que hay que hacer.
El plugin no reimplementa el motor de SpecGuard. Llama al CLI specguard existente, lee el resultado generado y resume el estado actual y la siguiente acción.
La idea es que, cuando SpecGuard deje todo en estado READY, se genere un documento de handoff para entregarlo al agente de implementación y luego Codex comience a implementar.
También soporta PR Review
También ofrece un workflow de SpecGuard PR Review basado en GitHub Actions.
El flujo consiste en ejecutar SpecGuard Review cuando cambia un paquete de especificación en un PR y dejar el resultado en el PR. Esta función se ejecuta llamando a OpenAI.
El objetivo no es “revisar código hecho por IA”, sino “revisar el insumo de especificación antes de entregarlo a la IA”.
Puede usarse cuando un equipo quiere definir reglas como estas.
- No pasar especificaciones
NOT_READYa implementación - Exponer primero los hallazgos Critical/Major en el PR
- Gestionar primero la calidad de entrada de los requerimientos, no el resultado de la implementación
La instalación puede hacerse desde el CLI con specguard actions install-pr-review, o pidiéndole a Codex @specguard configura el workflow de SpecGuard PR Review.
Sin embargo, como todavía es una función experimental, no se soporta configuración automática y hay que definirlo en GitHub Secret de la siguiente manera.
SPECGUARD_OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx
SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name
Estado actual y limitaciones
Todavía está en una versión inicial, así que no es una herramienta que pueda evaluar perfectamente todas las especificaciones.
Aun así, si al usar programación con IA han tenido el problema de que “la implementación se desvía porque la especificación es débil”, creo que puede servir como una barrera de seguridad para filtrar una vez antes de implementar.
Me gustaría recibir feedback. En particular, me interesa saber lo siguiente.
- En qué tipo de especificaciones encaja bien
- Qué hallazgos resultan excesivos o insuficientes
- Si el flujo del plugin de Codex realmente es útil en la práctica
- Si forzarlo mediante PR Review encaja con el workflow del equipo
Por ahora está en una etapa previa a beta, apenas comenzando su desarrollo, pero quiero convertirlo en un proyecto que realmente pueda usarse en trabajo real.
También son bienvenidos los issues/PR de quienes estén interesados. Actualmente los issues y PR del repositorio se gestionan principalmente en inglés, pero no pasa nada si los escriben en coreano.
1 comentarios
Pueden consultar más detalles sobre este proyecto en https://nirsa.tistory.com/487.