Framework de Trabajo Cirange

Cuando una parte del trabajo la hacen agentes de IA, el contexto se vuelve frágil. Una conversación se cierra y se lleva consigo lo que se decidió. Un agente nuevo entra sin saber qué está desplegado. Alguien aprueba algo de palabra y nadie puede reconstruir quién autorizó qué.

El síntoma habitual no es un error de código: es que nadie puede responder con certeza qué hay en producción ahora mismo y cómo lo volvemos atrás.

El framework ataca eso con una idea simple: el estado vive en texto versionado, no en la memoria de nadie. Si el archivo y la realidad se contradicen, gana la realidad verificable, y eso abre una tarea.

Nació observando el desarrollo de Gustiin, un producto real del ecosistema Cirange. Pero no es un manual de Gustiin: todo lo que publicamos acá es genérico y aplicable a un SaaS, un ecommerce, una plataforma educativa o cualquier otro producto digital.

SDD (Spec-Driven Development) es una forma de trabajar donde la especificación —el documento que describe qué debe hacer el sistema— es la fuente de verdad, y el código se deriva de ella. Herramientas como Spec Kit u OpenSpec la implementan con un flujo de constitución → spec → plan → tareas → implementación.

SDD responde qué construir. Cirange responde cómo se construye, se verifica y se opera.

El hueco que Cirange llena

Las herramientas SDD definen muy bien la intención, pero casi no traen un ciclo de verificación real. Generan la spec, generan las tareas, generan el código — y el ciclo termina ahí.

Cirange exige verificar contra el sistema real. «Corrió sin error» no es evidencia. La pregunta es si el campo crítico del dominio quedó con el valor correcto, comprobado contra producción, no si el proceso terminó sin lanzar una excepción.

Cómo se enganchan

El ciclo completo

Cada etapa está del lado de quien la aporta: a la izquierda SDD, a la derecha Cirange. Mirá dónde se termina el carril de SDD y qué pasa cuando algo falla.

Estados ampliados

El modelo de estados de Cirange, extendido con los dos primeros que aporta SDD:

idea → especificada → planificada → lista → en_curso → en_revision → aceptada → despliegue_autorizado → desplegada → verificada_en_vivo → activada

Tres reglas que sostienen el conjunto:

Gate de Spec. La spec la aprueba alguien distinto de quien la escribió. Es la misma regla de separación que se aplica al código, movida un paso antes.

Anti-deriva. Si cambia un requisito, primero se actualiza la spec y después el código. Nunca al revés, o la spec deja de servir para algo.

Dos fuentes de verdad que no chocan. La spec es la verdad de la intención. Producción es la verdad del estado. Si difieren, no se discute cuál manda: se abre una tarea.

Agnóstico de herramienta

Todo esto es Markdown y Git. No hace falta instalar nada. Como sugerencia: OpenSpec encaja mejor en proyectos que ya existen, Spec Kit en proyectos nuevos.

Antes de la lista, tres palabras que vas a ver repetirse. Vienen del vocabulario de las especificaciones técnicas:

• MUST — obligatorio. Incumplirlo no es una variante aceptable, es una desviación.
• SHOULD — recomendación fuerte. Podés no seguirla, pero tenés que entender y documentar por qué.
• MAY — realmente opcional.

Los once principios del núcleo, uno por línea:

1. Existe una única fuente de verdad del estado, y cuando el archivo y la realidad se contradicen, manda la realidad verificable.
2. Todo cambio está versionado, no como aspiración sino como criterio de aceptación.
3. Todo despliegue se asocia a un commit o artefacto identificable.
4. Ningún agente asume permisos que no tiene, y una autorización no se extiende sola a la acción siguiente.
5. Quien implementa no es quien aprueba.
6. Toda tarea tiene responsable, alcance, criterios de aceptación y estado.
7. Todo cambio se puede revertir, con un identificador concreto.
8. Las credenciales no aparecen en código, logs, prompts ni documentación.
9. Los datos reales se distinguen siempre de fixtures, mocks y ejemplos.
10. Los bloqueos se documentan, nunca se ocultan.
11. Las autorizaciones humanas quedan por escrito, nunca verbales.

Y uno más, como recomendación: toda estimación no verificada se marca como punto de partida a validar, no como diseño final.

De todos ellos, el quinto es el que no admite excepción por tamaño de equipo. Podés combinar funciones todo lo que necesites —en un equipo de una persona es inevitable—, pero implementar y aprobar la misma entrega no pueden recaer en el mismo agente. Si trabajás solo, el mínimo es releer tu propio trabajo contra una checklist de aceptación antes de darlo por bueno.

Un gate es un punto de control: algo que se verifica antes de dejar avanzar una entrega. No es burocracia, es la respuesta a «¿qué tuvo que ser cierto para que esto llegara a producción?».

Lo que nunca decide un agente

Un agente puede preparar todo lo necesario para decidir —el script, el diff, el plan de rollback, la consulta de verificación—. Pero la decisión es humana, siempre:

• Cualquier cambio en producción.
• Escritura directa en la base de datos productiva.
• Activación pública de una funcionalidad o producto.
• Manejo de secretos: crear, rotar, compartir acceso.
• Pagos: procesar, reembolsar, cambiar montos.
• Cambios de dominio: DNS, certificados, transferencias.
• Cambios destructivos: borrado masivo, desactivación en masa.
• Cambios legales o de privacidad.
• Publicación pública de la marca.
• Rollback de alto impacto.

El criterio detrás de la lista: son acciones que no se deshacen, o cuyo daño ya está hecho para cuando te enterás.

Lo que sí se automatiza

Una vez que el canal ya fue autorizado en general: correr tests, generar builds, correr smoke tests contra un ambiente que no sea producción, crear una tarea desde plantilla, avisar de un bloqueo, generar un resumen de estado, y desplegar a un preview descartable.

Adoptar el framework no significa adoptarlo entero de una vez. Son cuatro niveles, acumulativos.

Una señal práctica de que te quedó corto el perfil: si aparecen pagos reales o datos personales, la capacidad de seguridad tiene que separarse de quien implementa, aunque hasta ayer fueran la misma persona.

Adoptar esto en un proyecto que ya existe no requiere reescribir código ni cambiar de stack. Es una capa de proceso sobre lo que ya tenés.

Día 1

1. Un único archivo de estado: qué existe hoy, qué falta.
2. La primera tarea real, con responsable, alcance y criterios de aceptación.
3. Decidir dónde va a vivir todo esto.
4. Mover a un gestor de credenciales cualquier secreto que hoy esté en un chat o en un archivo versionado.
5. Si sos perfil C o D: escribir en una línea quién dirige el producto y quién coordina, aunque sea la misma persona.

Semana 1

1. Completar la primera plantilla de Entrega al cerrar la primera tarea.
2. Aplicar al menos una vez la regla «quien implementa no aprueba».
3. Crear el registro de despliegues antes del primer despliegue real.
4. Asignar explícitamente las primeras capacidades operativas.
5. Escribir el primer handoff al terminar una sesión de trabajo de un agente.

Mes 1

1. Un ciclo completo de tarea documentado de punta a punta.
2. Un despliegue real registrado, con su rollback probado al menos una vez.
3. Revisar la tabla de gates y marcar cuáles ya cumplís.
4. Decidir si tu proyecto necesita reglas propias de dominio, y documentarlas aparte del núcleo.

Qué no hacer el primer mes

No construyas una herramienta propia todavía. No armes reglas de dominio especulativamente antes del primer caso real. Y no intentes cumplir el perfil D si tu proyecto hoy es A o B.

Es la pieza que más rinde cuando hay agentes involucrados. Al cerrar una sesión de trabajo, dejás escrito:

• Qué está realmente desplegado ahora mismo.
• Qué se probó y qué no, con el resultado concreto.
• Qué sigue bloqueado y por qué.
• El rollback exacto si algo falla.
• Qué no se debe hacer todavía.

Y antes de actuar, el que llega reconstruye el estado contrastando cuatro capas, en este orden de autoridad cuando se contradicen: producción, luego el workspace, luego la entrega, luego la tarea. Lo que dice la tarea es lo que alguien declaró; lo que dice producción es lo que hay.

Versión 0.3 del núcleo, con fecha de verificación 2026-08-31. La integración con SDD descrita más arriba es una propuesta de la v0.4, en validación.

Esto es un método en evolución, no un estándar cerrado. Se publica con sus supuestos a la vista: hay puntos marcados como pendientes, y la portabilidad entre herramientas es un objetivo de diseño que todavía no se probó con una migración real.

El framework se entrega tal cual, sin garantía de ningún tipo. Quien lo adopte evalúa por su cuenta si le sirve para su proyecto, su industria y su marco regulatorio.

Licencia

El contenido publicado del Framework de Trabajo Cirange se ofrece bajo Creative Commons Atribución 4.0 Internacional (CC BY 4.0).

Podés copiarlo, redistribuirlo, adaptarlo y usarlo, incluso comercialmente, siempre que des crédito razonable a la fuente e indiques si hiciste cambios.

Framework de Trabajo Cirange — https://cirange.com/framework — CC BY 4.0

El caso de estudio interno que dio origen al método no forma parte de esta publicación y no se distribuye bajo esta licencia.