Reglas del Agente IA - CreaRack Pro

Documento de referencia obligatoria para agentes IA (Claude, Gemini, etc.) Contiene las reglas detalladas de comportamiento y configuraciones fijas.

Nota histórica (2026-07): varias secciones de abajo citan rutas Documentation/… del repo CreaRack-Pro. La carpeta Documentation/ fue archivada y eliminada en abril de 2026; la documentación técnica canónica vive ahora en la wiki del workspace y, para contexto de agente, en CreaRack-Pro/context/. Trata esas rutas Documentation/… como referencias históricas.

Reglas de Oro

1. Idioma

Responde SIEMPRE en Español.

2. Duplicidad de Código

EVITA A TODA COSTA LA DUPLICIDAD DE CÓDIGO. Antes de crear nuevo código, analiza exhaustivamente si ya existe una función o utilidad centralizada.

Servicios Centralizados Frontend

OBLIGATORIO: Consultar Documentation/frontend/CENTRALIZED_SERVICES.md antes de crear nuevos servicios.

Servicios existentes que NO debes duplicar:

• ApiService.js - HTTP requests con CSRF (NUNCA usar fetch() directo)
• TabHelper.js - “New Tab” standalone mode (Terminal, Observatory)
• EChartsService.js - Factory para gráficas Apache ECharts
• ToastService.js - Notificaciones toast
• StateManager.js - Undo/Redo global
• PersistenceManager.js - LocalStorage wrapper
• IpValidator.js - Validación de IPs RFC 1918
• Logger.js - Sistema de logging con niveles

Checklist antes de crear nuevo servicio:

1. ¿Consulté CENTRALIZED_SERVICES.md?
2. ¿Busqué en static/js/services/ y static/js/utils/?
3. ¿Será usado en más de 2 lugares?
4. ¿Es específico de un módulo o reutilizable?

Si es reutilizable → añadir a services/ o utils/ y documentar en CENTRALIZED_SERVICES.md.

3. Documentación Incremental

Actualizar en CADA commit los siguientes archivos cuando corresponda:

Estado vivo de tareas: TASK.md fue jubilado (s185, 02-07-2026). El estado vivo de tareas ya NO vive en un archivo del repo, sino en el Supercontexto (CreaRackSL-workspace/public/supercontext/STATE.md + briefings/NEXT.md) y en el Gestor de tareas del workspace. Los docs vivos del repo Pro son: CLAUDE.md, CHANGELOG.md, RELEASE_NOTES.md, README.md y context/.

Principio: Pequeñas actualizaciones en cada commit son menos laboriosas que regularizar múltiples versiones acumuladas.

4. GitHub — Equipo plano de 3 (Edu + Dani + Txell)

Equipo plano de confianza total: los 3 (Edu, Dani, Txell) commitean, pushean y mergean por igual, sin aprobación de nadie más. Quien conduce la sesión es quien sube. El “consenso” se refiere al plan/diseño (Regla 6), NUNCA a un permiso por persona.

• Rama principal: main (protegida — todo se mergea aquí)
• Feature branches: edu/<feature> · dani/<feature> para trabajo concurrente (cortas, 1-2 días)
• Antes de push: git pull --rebase origin main SIEMPRE
• Commits: Nunca incluir “Co-authored-by: CLAUDE/GEMINI”
• Conflictos docs: rerere activo + CHANGELOG.md/RELEASE_NOTES.md con merge=union; si conflicta, el último en push resuelve
• Push vs PR: flujo híbrido (Regla 20). Merge al verde MANUAL (gh pr merge <N> --squash; el auto-merge está OFF en el repo)
• Repositorio: https://github.com/CreaRackSL/CreaRack-Pro

Si trabajáis en módulos distintos: push directo a main sin branch es aceptable (hacer git pull --rebase antes)

4b. Directriz de Push — siempre inmediato

Política vigente desde 30-04-2026: tras cada commit, push inmediato a main. Sin [skip ci]. Da igual si el cambio es código, docs o mixto. Reformulada con el upgrade a GitHub Pro (3000 min/mes) y al detectar que [skip ci] saltaba CF Pages Deploy (los cambios de docs no llegaban a workspace.crearack.com) y Bibliotecario-Ingest (el grafo no recibía cambios de docs).

Clasificación de commits:

Reglas:

1. Commits locales siguen siendo incrementales — la Regla 3 no cambia, se commitea docs con cada cambio.
2. Push tras cada commit — git pull --rebase origin main + git push. Sin diferir, sin acumular.
3. Tras push, verificar CI (comprobar TODOS los workflows del commit — gh run list --json conclusion,name, NO --limit 1, Regla 14). Si rojo, arreglar antes de cerrar tarea.
4. Si la cuota Actions algún mes se queda corta: optimizar workflows individuales (frecuencia de crons, concurrency, paths filters), NO reintroducir [skip ci] manual.
5. Excepción única: emergencia explícita autorizada por Edu/Dani con motivo documentado en el commit message. Avisar al equipo de que el deploy también se salta.

Histórico: la política previa “docs-only con [skip ci]” estuvo activa varios meses con GitHub Free (2000 min/mes apretados). Eliminada cuando Edu subió a Pro y se evidenció el coste oculto.

5. Modularización desde el Diseño

Diseña modular desde el punto cero. Todo código nuevo debe nacer ya modularizado:

• Límite por archivo: Máximo 500 líneas de lógica por módulo (excluye datos estáticos, migraciones, vendor files).
• Separación de responsabilidades: Un módulo = una responsabilidad. Si un archivo necesita más de 3 secciones con headers # ──, probablemente debe ser un package con sub-módulos.
• Patrones de modularización:
  • Python: Package con __init__.py que re-exporta la API pública (ver network/services/device_discovery/).
  • JavaScript: Named exports en sub-módulos, coordinador que importa y delega (ver static/js/pages/observatory/).
• Datos vs lógica: Los datos estáticos voluminosos (OIDs, configuraciones, constantes) van en archivos separados de la lógica que los consume.
• Detección reactiva: Si detectas archivos existentes con más de 1000 líneas de código, informa inmediatamente con un plan de refactorización.

Principio: Modularizar después cuesta 10x más que modularizar desde el inicio. El código nuevo NUNCA debe nacer monolítico.

6. Confirmación de Trabajos

Tras una petición compleja, presenta el plan (Implementation Plan) y no inicies la ejecución sin la aprobación previa del usuario.

7. No Fakes

NUNCA implementar configuraciones falsas, fakes, mocks ocultos ni datos hardcoded que simulen funcionalidad real sin informar explícitamente al usuario. Si un dato no se puede obtener en tiempo real, mostrar “No disponible” o “Sin monitorizar” — nunca inventar un estado ficticio. Los mocks son aceptables solo cuando están claramente marcados como tales (ej: badge “Datos de ejemplo”).

Razón: Un indicador falso en verde puede ocultar un problema real en producción y generar falsa confianza.

No falsear la verificación (gaming del verificador): la misma prohibición aplica al propio sistema de tests. Nunca debilitar, borrar o editar tests — ni relajar asserts o meter skip/xfail — para forzar el verde de CI. Un test que falla legítimamente se arregla en el CÓDIGO o se documenta el fallo con su plan; jamás se toca el verificador para simular éxito. Aplica igual a los subagentes y agentes de commit (Vigía/Estibador) que empujan a CI. Un CI en verde amañado es la forma más peligrosa del indicador falso: da confianza de que “pasa” mientras el defecto sigue vivo. (Origen: cruce del catálogo de 17 modos de fallo de loop-maker contra las Reglas de Oro, s209 · 09-07-2026 — único hueco no cubierto por una regla previa.)

Entorno de Desarrollo

Nota Windows: OneDrive puede interferir con bind mounts. Si los cambios no se reflejan, usar rebuild.

Acceso SSH a Producción (Hetzner)

El agente tiene acceso SSH directo al servidor de producción:

Contenedores: crearack-pro-zcmvsl-{web,worker,cache,db,victoriametrics}-1

VictoriaMetrics (solo desde dentro del Docker network, via docker exec + Python urllib).

Usar este acceso para: verificar deploys, inspeccionar logs, consultar métricas, diagnosticar problemas en producción.

Configuraciones Fijas (NO MODIFICAR)

Auto-Plan AI

DIRECTRIZ PERMANENTE: modelo primario único, centralizado en config/settings/base.py (Regla 8). Cambiarlo = 1 env var.

PROHIBIDO: cambiar el modelo sin autorización explícita del usuario (Regla 8 — modelo primario único, sin OpenRouter/DeepSeek).

Razón: Gemma 4 es el modelo primario único del producto (CNS / Tutor / Explain / Auto-Plan), con el mejor balance validado velocidad/precisión para análisis de planos.

Directrices de Diseño UI

Documento completo: Documentation/frontend/DESIGN_GUIDELINES.md

Regla Principal: Botones Solo Texto

PROHIBIDO añadir iconos dentro de botones.

<!-- INCORRECTO -->
<button><i class="fas fa-save"></i> Save</button>

<!-- CORRECTO -->
<button>Save</button>

JavaScript Dinámico

// INCORRECTO
btn.innerHTML = '<i class="fas fa-spinner"></i> Loading...';

// CORRECTO
btn.textContent = 'Loading...';

Títulos de Modales

Sin iconos en <h3>, <h4>.

Tooltips Obligatorios

OBLIGATORIO: Todo botón debe incluir title con descripción de su función.

<!-- CORRECTO -->
<button class="btn btn-action" title="Save changes">Save</button>

Clases Semánticas de Botones (OBLIGATORIO)

Fuente de verdad: static/css/components.css → sección SEMANTIC BUTTON ALIASES Documentación completa: Documentation/frontend/DESIGN_GUIDELINES.md → Sección 6

PROHIBIDO crear estilos de botón custom en CSS de páginas. Usar SIEMPRE:

Tamaños: btn-sm (28px), btn-xs (22px). Patrón: class="btn btn-sm btn-action".

Rendimiento Frontend

Documento completo: Documentation/frontend/PERFORMANCE_GUIDELINES.md

• Scripts pesados (>50KB): usar defer
• CSS no crítico: cargar async
• Google Fonts: requieren preconnect
• PROHIBIDO: backdrop-filter: blur() en modales con inputs
• Auto-save: usar debounce (mín. 500ms)

Nuevas Dependencias (OBLIGATORIO)

Documento completo: Documentation/reports/SECURITY_AUDIT.md

Antes de instalar cualquier dependencia:

1. Verificar seguridad:

   • ¿Tiene vulnerabilidades conocidas? (Snyk, Safety)
   • ¿Última actualización < 1 año?
   • ¿Código fuente auditable?

2. Verificar licencia:

   Licencia	Permitida
   MIT, BSD, Apache, ISC	✅ Sí
   LGPL	⚠️ Solo como librería
   GPL, AGPL	❌ No

3. Actualizar documentación:

   • Añadir a Documentation/reports/SECURITY_AUDIT.md (sección 3)
   • Actualizar requirements.txt o package.json
   • Añadir entrada en core/licenses.py (página pública /licenses)
   • Registrar en CHANGELOG.md

Ejemplo de registro:

| paquete | versión | Licencia | Uso Comercial |
|---------|---------|----------|---------------|
| nueva-lib | 1.0.0 | MIT | ✅ Permitido |

Sistema de Versiones

Aplicación Principal

Fuente de verdad: config/settings/base.py → APP_VERSION

Mantener sincronizado en:

1. config/settings/base.py → APP_VERSION = "X.Y.Z"
2. CLAUDE.md (header) y README.md

Sistema dinámico:

• core/context_processors.py pasa APP_VERSION a templates
• Templates usan {{ APP_VERSION }}

Local Agent (CreaRackAgent.exe)

Fuente de verdad: terminal/agent/version.py → AGENT_VERSION

OBLIGATORIO al recompilar el agente:

1. Actualizar AGENT_VERSION en terminal/agent/version.py
2. Actualizar versión en build_agent.bat (comentarios y mensajes)
3. Documentar cambios en Documentation/backend/LOCAL_AGENT_GUIDE.md
4. Registrar en CHANGELOG.md

Cuándo incrementar versión:

• Nuevas dependencias (ej: icmplib, scrapli)
• Cambios en endpoints API del agente
• Modificaciones en módulos bundled (assets, agent_modules)
• Fixes de seguridad o bugs críticos

Sistemas Centralizados (Frontend Legacy)

Herramientas de Desarrollo

Última actualización: 09-07-2026

Véase también

• [[ia-tech—metodo—claude-method-guide]] — guía del método Claude
• [[crearack-tech—method—harness-guide]] — guía maestra del Harness (sustituye a ia-tech--metodo--harness-engineering archivada)
• [[ia-tech—metodo—glossary]] — glosario del método
• [[crearack-tech—guides—biblioteca-guide]] — guía de uso de la Biblioteca
• [[crearack-tech—backend—biblioteca]] — arquitectura interna de la Biblioteca
• [[concept—biblioteca—supercontexto]] — modelo Supercontexto aplicado a la wiki