FactorIA v3.1

Planning Gate

Nunca escribir código antes de que la planificación esté aprobada. Sin excepción.

No Hardcoded Secrets

Usar los 3 niveles de credenciales. Ningún secreto directo en el código.

Security Audit Required

Checklist de seguridad después de cada tarea + auditoría holística final.

Admin Panel Mandatory

Siempre. Sin negociación.

Docker Deployment

El proyecto debe estar preparado para despliegue con Docker (EasyPanel).

Scope Control

No añadir cosas no pedidas. Si parece "útil" pero no está en el plan → parar y preguntar.

Journey Completeness

Una tarea no está "terminada" hasta que el usuario puede usarla end-to-end (backend + frontend + verificación).

Document as You Work

Actualizar task_tracker y work_log después de cada tarea. No al final.

Terminar la tarea actual antes de empezar otra

Nunca trabajar en dos tareas a la vez. Finaliza, documenta, luego avanza.

No releer ficheros ya leídos en esta sesión

Salvo que hayan cambiado. Releer consume contexto sin aportar nueva información.

Leer solo secciones relevantes de design docs

No leer data_model.md entero (300+ líneas) cuando solo necesitas 10 líneas sobre una entidad.

La IA no leía los docs de planificación antes de implementar

Causa: "Consider reading the planning docs" → la IA "consideraba" y decidía que no era necesario.
Consecuencia: Implementación basada en suposiciones, no en el plan.
Solución v2: Lenguaje imperativo + regla "Read planning docs. You may not implement from memory alone."

La documentación no se generaba o era superficial

Causa: "You should document your decisions" → sugerencia, no obligación.
Consecuencia: Sin memoria persistente, cada sesión empezaba de cero.
Solución v2: R8 en CLAUDE.md — actualizar task_tracker y work_log tras cada tarea. "This is not optional."

El checklist de seguridad se aplicaba aleatoriamente

Causa: "It would be good to apply a security checklist" → opcional.
Consecuencia: Módulos sin revisión de seguridad.
Solución v2: Checklist inline en CLAUDE.md (siempre visible) + R3 como regla crítica.

La IA añadía funcionalidades no pedidas

Causa: "Try to stay within scope" → intento sin consecuencia.
Consecuencia: Scope creep, tiempo gastado en features innecesarias.
Solución v2: R6 — "Build what the user requested. If adding something 'because it seems useful' → stop and ask."

La IA programaba sin esperar aprobación

Causa: No había Planning Gate formal.
Consecuencia: Código escrito antes de entender los requisitos.
Solución v2: R1 — "Never write code before planning is approved." + pre-flight check en /start-execution.

No había verificación de cumplimiento

Causa: Las reglas existían pero nadie comprobaba que se seguían.
Consecuencia: Violaciones invisibles e irrecuperables.
Solución v2: Subagentes de /review con contexto limpio que verifican independientemente.

Presión de contexto por exceso de ficheros

Causa: 92 ficheros, 7 de gobernanza, 11 roles, 3 skills, 10 docs por módulo. La ventana de contexto se llenaba antes de poder hacer trabajo real.
Consecuencia: La IA marcaba docs como "actualizados" sin leerlos. "Completitud aparente" — todo parecía hecho pero la calidad era baja.
Solución v2: Reducir a ~30 ficheros y 1 fichero de gobernanza. Criterio: si un fichero no se lee activamente durante la ejecución, no debe existir.

Módulos técnicos que no cruzan el stack

Causa: Módulos como "M05: Backend de fuentes" se marcaban como completos sin que existiera la página frontend.
Consecuencia: En SPAIDER (v1), varios backends marcados como terminados sin páginas frontend correspondientes.
Solución v2: User Journeys como unidad de trabajo. No está "done" hasta que el usuario puede usarlo end-to-end.

Gobernanza redundante con riesgo de divergencia

Causa: Las mismas reglas en CLAUDE.md, SYSTEM_RULES.md, FactorIA_SYSTEM_PROMPT.md, skills y prompts. A veces con variaciones sutiles.
Consecuencia: La IA no sabía cuál era la fuente de verdad y seguía la versión más fácil de interpretar.
Solución v2: Una sola fuente de verdad (CLAUDE.md). Los otros 6 ficheros de gobernanza no existen.

10 ficheros de documentación por módulo

Causa: execution_journal, change_log, task_tracker, decision_log, security_findings, issue_log, risk_log, remediation_log, iteration_log, phase_status.
Consecuencia: La IA hacía actualizaciones superficiales o se las saltaba — creando exactamente el problema que el sistema intentaba prevenir.
Solución v2: 2 ficheros por tarea (task_tracker + work_log) + 1 por sesión (project_memory). El work_log unifica 6 ficheros anteriores.

Fases de lifecycle como carpetas vacías

Causa: 8 phase_status.md — de las cuales solo 1 se actualizó durante la ejecución real de SPAIDER (v1).
Consecuencia: Las carpetas existían pero nadie las usaba. Peso muerto.
Solución v2: 3 carpetas funcionales (planning, design, implementation). Seguridad y validación integradas en el workflow, no en carpetas separadas.

Roles de agente como peso muerto

Causa: 11 ficheros en agents/ (architect.md, backend_engineer.md, etc.) que nunca fueron consultados durante la implementación.
Consecuencia: 11 ficheros bien escritos que nadie leía. Consumo de espacio sin valor operativo.
Solución v2: No existe la carpeta agents/. Un único agente principal + subagentes temporales de /review.

Skills base redundantes con CLAUDE.md

Causa: 3 skills de gobernanza (planning_gate_enforcement, traceable_execution, scope_control) con reglas ya presentes en CLAUDE.md.
Consecuencia: La IA debía leer CLAUDE.md Y las skills, encontrando las mismas instrucciones con palabras diferentes.
Solución v2: No hay skills base. Las reglas viven exclusivamente en CLAUDE.md.

Falta de iteración formalizada

Causa: v1 no tenía mecanismo formal para cambios post-entrega.
Consecuencia: Cuando el usuario pedía modificaciones, la IA trabajaba sin protocolo, sin clasificar el tipo de cambio, sin evaluar regresiones.
Solución v2: Comando /iterate con 4 categorías (bug fix, planning gap, enhancement, new feature) y workflows específicos para cada una.

No había gestión explícita del contexto

Causa: Ni Fase 1 ni v1 mencionaban la ventana de contexto. El recurso más escaso del sistema y nadie lo gestionaba.
Consecuencia: La IA llenaba el contexto hasta que no quedaba espacio para implementar.
Solución v2: Sección "Context Management" en CLAUDE.md con reglas explícitas + heurísticos concretos en v3.

Relectura masiva de design docs

Causa: Cada UJ leía data_model.md (~300 líneas), api_contracts.md (~400 líneas) y ui_wireframes.md completos. Tras cada compactación de contexto, los volvía a leer. El 80% era irrelevante para la tarea actual.
Consecuencia: Gran parte del contexto de cada sesión consumida releyendo docs ya leídos.
Solución v3: design/design_summary.md — documento compacto de ~50 líneas que condensa stack, módulos, entidades y patrones. Reduce relectura ~80%.

Reviews cada 3 ítems — arbitrario y disruptivo

Causa: El número 3 era una constante arbitraria. A veces los 3 ítems eran ITs triviales donde el review era excesivo. Otras veces, 3 UJs grandes se beneficiaban enormemente.
Consecuencia: Reviews sobre trabajo trivial donde el coste superaba el beneficio. Reviews sobre trabajo complejo que llegaban demasiado pronto o tarde.
Solución v3: Reviews por milestone semántico (conjuntos de 3-6 journeys que forman una unidad funcional). El review coincide con puntos naturales de verificación.

Sin verificación visual — páginas construidas pero nunca vistas con datos

Causa: v2 no tenía fase de verificación visual obligatoria. Todas las páginas mostraban estados vacíos al terminar.
Consecuencia: Al añadir datos reales aparecieron: un botón superpuesto ilegible, el campo metadata_ de SQLAlchemy no se mapeaba a Pydantic (errores 500 en 4 endpoints), varias páginas admin mostraban "No data" cuando los datos existían.
Solución v3: Fase obligatoria de verificación visual antes de la entrega: seed script con datos realistas + verificar cada página con datos + verificar empty states.

Skills y MCPs ignorados — la IA no exploraba lo disponible

Causa: El Step 6 usaba "evaluate" (sugerente, no imperativo). La IA "evaluaba mentalmente" y escribía "None selected" sin explorar nada.
Consecuencia: En SpAIder no se instaló ningún skill ni MCP. postgresql-table-design habría detectado el problema de metadata_. tailwind-design-system habría evitado el conflicto PostCSS (.mjs vs .js) que consumió una sesión de debugging.
Solución v3: Step 6 reescrito con lenguaje imperativo y 5 sub-pasos concretos. "Do not skip. Do not write 'None selected' without exploring first."

Gestión de contexto sin heurísticos — "context is getting large" es subjetivo

Causa: v2 tenía la regla pero "getting large" es subjetivo. La IA no tiene un indicador visible de cuánto contexto ha consumido.
Consecuencia: La sesión se compactaba varias veces sin previo aviso, perdiendo detalles de design docs ya leídos.
Solución v3: 4 heurísticos concretos y observables: 4+ tareas completadas, 8+ ficheros leídos, sesión compactada, confiando en memoria en vez de releer.

La tabla de Project Files Reference no distinguía prioridades

Causa: La tabla listaba todos los archivos sin distinguir entre "leer siempre" y "leer una vez". La IA releía style_guide (que ya había absorbido) en cada sesión de frontend.
Consecuencia: Consumo de contexto innecesario releyendo docs estáticos que no habían cambiado.
Solución v3: Tabla reorganizada en 3 niveles: Always load, Load per task, Load once (ver Sección 07).

Tokens de Tailwind en colisión con utilidades reservadas

Qué pasó: El style_guide definía tokens como text.primary y background.from que generaban clases Tailwind (text-text-primary, bg-background-from) colisionando con utilidades reservadas de Tailwind CSS v3.

Impacto: Hubo que renombrar todos los tokens a t-primary, bg-from, etc., con impacto en 12 archivos de frontend.

Lección: El style_guide debe documentar restricciones de naming específicas del framework CSS elegido.

APScheduler en entornos sin psycopg2

Qué pasó: El scheduler usaba SQLAlchemyDataStore que internamente requiere psycopg2 (driver sync). El proyecto usaba asyncpg (driver async). En entorno local solo con asyncpg, el scheduler fallaba al arrancar.

Solución aplicada: Scheduler no-bloqueante — si falla, logea un warning y el resto de la app arranca normalmente. Funciona correctamente en el entorno Docker de producción.

Lección: Verificar compatibilidad entre drivers sync y async al elegir librerías de scheduling.

CORS en desarrollo con puertos dinámicos

Qué pasó: La config original solo preveía localhost:3000 como origen CORS. Cuando el preview tool de Claude Code asignaba puertos dinámicos, las peticiones del frontend al backend fallaban con error CORS.

Solución aplicada: Implementar allow_origin_regex para aceptar cualquier localhost:* en desarrollo.

Lección: La configuración CORS en desarrollo debería usar regex por defecto para aceptar cualquier puerto localhost desde el inicio.

El cache de preflight CORS del browser es persistente

Qué pasó: Cuando un preflight CORS falla y el servidor devuelve un max-age, el browser cachea ese fallo. Cambiar la configuración del servidor no tiene efecto hasta que el cache expira o se reinicia el browser.

Consecuencia: Causó confusión durante el debugging porque los cambios en el servidor parecían no tener efecto.

Lección: Ante errores CORS persistentes después de cambiar la config: reiniciar el browser o limpiar el cache de preflight antes de asumir que el problema sigue en el servidor.

Leer antes de implementar

Antes de escribir cualquier código, la IA debe leer los documentos de planificación relevantes para la tarea. No puede implementar desde memoria de lo que "cree que estaba en el plan."

Documentar desviaciones

Si la implementación se desvía del plan (por una razón técnica válida), la IA debe documentar la desviación y su justificación en el work_log. No puede desviarse silenciosamente.

Nunca saltarse reglas silenciosamente

Si una regla de CLAUDE.md no puede cumplirse por algún motivo, la IA debe declararlo explícitamente al usuario. No puede ignorarla sin avisar. La transparencia es parte del rol.

Preguntar antes de asumir

Ante requisitos ambiguos o decisiones que afecten el alcance, la IA debe preguntar al usuario en lugar de asumir y proceder. Las decisiones de alcance pertenecen al usuario, no al agente.

planning/requirements.md

Los requisitos funcionales y no funcionales deben estar documentados y haber sido revisados por el usuario.

planning/user_journeys.md

Todos los User Journeys definidos con su backend, frontend, criterios de verificación y seguridad.

implementation/task_tracker.md

La tabla de tareas completa con todos los ITs y UJs listados, ordenados por dependencias y agrupados en milestones.

design/data_model.md

El modelo de datos diseñado. La implementación no puede empezar si no hay un esquema de base de datos definido.

design/design_summary.md

El resumen compacto del proyecto generado al final de la planificación. Sin él, la IA no tiene una referencia rápida y tendrá que releer los docs completos en cada sesión.

Los journeys funcionan end-to-end

Para cada UJ marcado como "done": ¿existe el backend (modelo + endpoints)? ¿existe el frontend (página + formulario + link en sidebar/nav)? ¿el usuario puede realizar la acción completa de principio a fin? ¿los estados vacíos y de error están manejados?

El checklist de seguridad se aplicó

Para cada IT y UJ completado: ¿hay una entrada en el work_log con "Security Check: pass"? Si hay entradas sin security check, el subagente los marca como gaps y el agente principal los completa antes de continuar.

No hay gaps entre lo planificado y lo implementado

Comparación directa entre user_journeys.md (lo que se planificó) y el código real (lo que se implementó). El subagente busca funcionalidades definidas en el plan que no tienen implementación correspondiente, y funcionalidades implementadas que no estaban en el plan (scope creep).

Import roto en el seed script

El seed script importaba async_session de app.database, pero esa variable no existía — solo existía async_session_factory. El seed habría fallado en cualquier entorno. Corregido antes de la entrega.

Healthcheck apuntando a URL inexistente

El docker-compose.prod.yml tenía un healthcheck que apuntaba a /api/v1/health pero el endpoint real era /health. El contenedor habría fallado el healthcheck en producción. Corregido antes de la entrega.

Header HSTS documentado pero ausente en nginx

El work_log afirmaba que nginx configuraba HSTS, pero el header Strict-Transport-Security no estaba en nginx.conf. Se añadió antes de la entrega. Un ejemplo de por qué el subagente lee el código real, no solo la documentación.