Reglas y gobernanza de agentes
El framework no confía en que los agentes hagan lo correcto por defecto. Define límites explícitos, checkpoints humanos y reglas que protegen la integridad del sistema.
"No usamos IA para improvisar más rápido. Usamos IA dentro de un sistema de ingeniería gobernado por especificaciones."
Restricciones absolutas. Un agente que viole estas reglas debe pausar y escalar a un humano.
No código sin spec aprobada
Hard RuleTodo cambio de código debe tener un OpenSpec change con proposal.md revisado antes de que un agente empiece a implementar.
No modificar arquitectura sin design.md aprobado
Hard RuleCambios estructurales (nuevos servicios, módulos, patrones) requieren design.md completo y revisado por un senior.
No tocar base de datos sin plan de rollback
Hard RuleCualquier migración, schema change o seed debe incluir el script de rollback documentado en el change antes de ejecutarse.
No editar archivos generados automáticamente
Hard RuleArchivos marcados como generated no deben modificarse manualmente. Si el output no es el deseado, se modifica el template o el generador.
No hacer scope creep en un change
Hard RuleCada change resuelve exactamente lo que define su proposal.md. Si se detecta algo adicional, se crea un nuevo change.
Pausar ante ambigüedad y documentar
Hard RuleCuando la spec no es clara, el agente pausa, documenta la ambigüedad y espera resolución humana. No asume ni improvisa.
Momentos donde el flujo debe pausar para revisión humana antes de continuar.
Human checkpoint antes de cualquier operación destructiva
CheckpointEliminar datos, borrar columnas, desactivar servicios o deployar a producción requieren aprobación explícita de un humano.
Revisión de design.md antes de ejecutar Specification Layer
CheckpointEl diseño técnico debe ser revisado antes de que los agentes comiencen a generar código o specs detalladas.
Quality gates completos antes del PR
CheckpointNo se abre un PR sin que todos los quality gates del change estén documentados como pasados o con justificación de excepción.
Archive del change al cerrar
CheckpointAl mergear un change, se archiva la carpeta en openspec/archive/ con fecha y resultado. La trazabilidad es permanente.
Pautas que mejoran la calidad del trabajo aunque su violación no bloquea el flujo.
Preferir soluciones existentes sobre nuevas abstracciones
Best PracticeAntes de crear un nuevo patrón, verificar si ya existe uno en el sistema. La consistencia es más valiosa que la elegancia local.
Documentar decisiones técnicas en el change, no en comentarios
Best PracticeLas razones por las que se tomó una decisión viven en design.md, no como comentarios inline que desaparecen con refactors.
Tests antes de considerarse done
Best PracticeUna tarea del execution plan no se marca como completa si no tiene coverage mínimo acordado en el plan de pruebas.
Implementación
Estas reglas se materializan en el archivo CLAUDE.md o AGENTS.md del repositorio. Los agentes los leen como contexto antes de ejecutar cualquier tarea.