Reglas de conformidad (Guardrails)

Las reglas de conformidad son verificaciones deterministas que validan los cambios de código contra tus decisiones de arquitectura. Imponen convenciones de nombres, restricciones tecnológicas, límites entre capas y patrones de seguridad, sin ninguna IA de por medio.

Ve a Hub de Agentes en la barra lateral para gestionar tus reglas de conformidad.

¿Por qué reglas de conformidad?

Cuando los agentes de codificación de IA (Claude Code, Cursor, Copilot) generan código, no conocen tus decisiones de arquitectura. Las reglas de conformidad codifican esas decisiones como restricciones ejecutables:

• El agente no puede usar MongoDB si tu radar tecnológico dice PostgreSQL
• El agente no puede poner llamadas a la base de datos en los handlers HTTP si tu arquitectura exige una capa de servicio
• El agente no puede añadir fmt.Println si tu equipo usa logging estructurado

Las reglas se evalúan de forma determinista: sin LLM, sin resultados probabilísticos. El mismo código produce siempre el mismo resultado.

Tipos de reglas

Archyl admite siete tipos de reglas de conformidad:

Patrón obligatorio

Comprueba patrones que deben existir o que no deben existir en tu código.

Configuración:

• File glob — Comprueba solo los archivos que coinciden con un patrón (p. ej., *.go, *.{ts,tsx})
• Forbidden patterns — Patrones regex que generan una infracción cuando aparecen
• Required patterns — Patrones regex que generan una infracción cuando faltan

Los globs de archivos admiten expansión de llaves: *.{js,jsx,ts,tsx} coincide con todos los archivos JavaScript y TypeScript.

Convención de nombres

Valida los patrones de nombres de archivos, tipos y funciones.

Configuración:

• Patterns — Lista de ámbito (archivo/tipo/función) + regex + descripción

Restricción tecnológica

Restringe qué lenguajes y bibliotecas se permiten en un contenedor.

Configuración:

• Allowed languages — Lista separada por comas (p. ej., go, typescript)
• Forbidden imports — Un import por línea

Límite de capa

Aplica las reglas de imports entre capas de Clean Architecture, arquitectura hexagonal o DDD.

Configuración:

• Layers — Define cada capa con un nombre, un patrón de ruta (glob) y los orígenes de import permitidos
• Haz clic en los nombres de las capas para activar o desactivar los permisos de import

Cumplimiento de contratos

Valida que los archivos de handlers de endpoints contengan la documentación de contrato de API adecuada.

Configuración:

• Contract type — HTTP (OpenAPI), gRPC, GraphQL o AsyncAPI
• Endpoint file patterns — Globs para los archivos que contienen definiciones de endpoints
• Strict mode — Si está activado, cualquier archivo coincidente sin documentación de contrato genera una infracción

Regla de dependencias

Impone rutas de import prohibidas entre límites de arquitectura.

Configuración:

• Scope — Nivel de contenedor o de componente
• Forbidden pairs — Patrones de ruta de origen y destino que nunca deben depender entre sí (p. ej., **/service/** -> **/handler/**)

Cumplimiento de canales de eventos

Valida que los patrones de productores y consumidores de eventos sigan las convenciones de nombres.

Configuración:

• Producer patterns — Patrones regex que identifican el código que produce eventos (p. ej., kafka\.Send)
• Consumer patterns — Patrones regex que identifican el código que consume eventos
• Topic regex — Patrón con el que deben coincidir los nombres de topics válidos (p. ej., ^[a-z]+\.[a-z]+\.[a-z]+$)

Packs de reglas

Los packs son colecciones curadas de reglas que puedes instalar con un clic. En lugar de añadir reglas una a una, instala un pack y obtén un conjunto completo de reglas para tu stack.

Haz clic en Packs en la barra de herramientas para explorar los packs disponibles.

Packs de arquitectura

Packs de lenguaje

Packs de dominio

Catálogo de reglas

Archyl incluye un catálogo de 169 reglas predefinidas para 23 tecnologías. Explora el catálogo haciendo clic en Explorar catálogo en el Hub de Agentes.

Tecnologías cubiertas

Go, TypeScript, JavaScript, Python, Java, Kotlin, Rust, C#, C/C++, Ruby, PHP, Swift, React, Vue, Angular, Next.js, Docker, Kubernetes, Terraform, SQL, Shell, YAML, GitHub Actions

Categorías

Haz clic en cualquier regla del catálogo para añadirla: el formulario de configuración se rellena automáticamente.

Niveles de severidad

Cada regla tiene una severidad que determina su impacto:

Una verificación de conformidad falla si encuentra alguna infracción crítica o alta. Las infracciones medias y bajas se reportan, pero no hacen fallar la verificación.

Panel de conformidad

La pestaña Panel del Hub de Agentes ofrece una vista en tiempo real de todas las verificaciones de conformidad de tus proyectos.

Qué muestra

• Tarjetas de estadísticas — Total de verificaciones, tasa de aprobación (con código de colores), número de aprobadas y de fallidas
• Ratio aprobado / fallido — Barra visual que muestra la proporción de un vistazo
• Banner de la última verificación — Estado de la verificación más reciente con un enlace al reporte completo
• Lista de verificaciones recientes — Todas las verificaciones con su estado, tipo de disparador, nombre del proyecto, número de archivos, número de infracciones y hace cuánto se ejecutaron

Filtrado

Usa el selector de proyecto de la parte superior para filtrar las verificaciones por proyecto, o elige "Todos los proyectos" para verlo todo.

Reportes de verificación

Haz clic en cualquier verificación para abrir su reporte completo:

• Barra de desglose por severidad — Visualización proporcional de las infracciones críticas, altas, medias y bajas
• Infracciones agrupadas por archivo — Secciones plegables con la severidad, el título, la descripción y la sugerencia de cada infracción
• Metadatos de la verificación — Tipo de disparador, SHA del commit, hora de inicio, duración

Cada reporte de verificación tiene su propia URL para compartir (p. ej., /agent/dashboard/:checkId).

Eliminar verificaciones

Usa la selección múltiple para eliminar verificaciones en bloque:

1. Marca las casillas junto a las verificaciones que quieras, o usa "Seleccionar todo"
2. Haz clic en el botón rojo Delete que aparece
3. Las verificaciones y sus infracciones se eliminan de forma permanente

Integración con CI/CD

Las reglas de conformidad pueden ejecutarse automáticamente en cada pull request. Consulta Integración con GitHub Actions para ver cómo configurarlo.

Cómo funciona

1. Se abre o se actualiza una PR en GitHub
2. La GitHub Action de Archyl obtiene los archivos modificados
3. Los archivos se envían a la API de Archyl para su evaluación
4. Los resultados aparecen como comentario en la PR y como status check del commit
5. El workflow falla si se encuentran infracciones críticas o altas

Comentario en la PR

Cuando encuentra infracciones, Archyl publica un comentario detallado en la PR:

• Tabla resumen con el número de infracciones por severidad
• Infracciones por archivo con descripciones y sugerencias
• El comentario se actualiza (no se duplica) en los pushes posteriores

Gestión de reglas

Crear reglas

1. Haz clic en Packs para instalar un conjunto de reglas curado para tu stack, o
2. Haz clic en Explorar catálogo para explorar y añadir reglas de entre las 169 predefinidas, o
3. Haz clic en Regla personalizada para crear una regla nueva a mano

Activar/desactivar reglas

Usa el interruptor junto a cualquier regla para activarla o desactivarla. Las reglas desactivadas no se evalúan.

Editar reglas

Haz clic en el icono de edición (lápiz) de cualquier regla para modificar su nombre, descripción, severidad o configuración.

Eliminar reglas

Haz clic en el icono de eliminar (papelera) y confirma. Esta acción no se puede deshacer.

Filtrar reglas

• Búsqueda — Filtra por nombre o descripción de la regla
• Filtro por tipo — Haz clic en las etiquetas de tipo para mostrar solo las reglas de un tipo concreto

Integración con MCP

Las reglas de conformidad están disponibles para los agentes de IA a través del servidor MCP:

Herramientas MCP disponibles

Ejecutar verificaciones desde un agente

La herramienta run_conformance_check permite a los agentes de IA validar el código antes de hacer commit. El agente envía los archivos en los que está trabajando:

{
  "projectId": "your-project-uuid",
  "changedFiles": [
    { "path": "internal/handler/user.go", "status": "modified" }
  ],
  "fileContents": {
    "internal/handler/user.go": "package handler\nimport..."
  }
}

La respuesta incluye:

• passed — Si la verificación se ha superado (sin infracciones críticas ni altas)
• violations — Lista de infracciones con severidad, ruta del archivo, título y sugerencia
• rulesEvaluated — Qué reglas se han evaluado
• filesAnalyzed — Cuántos archivos se han analizado
• checkId — El ID de la verificación (visible en el panel)

El agente puede usar esta información para corregir las infracciones antes de hacer commit del código.

Contexto del agente

La herramienta MCP get_agent_context devuelve todas las reglas de conformidad activas como parte del briefing de arquitectura. Los agentes de IA que llaman a esta herramienta antes de empezar a trabajar sabrán qué guardrails deben respetar.

REST API

# Rules
GET    /api/v1/conformance/rules              # List rules
POST   /api/v1/conformance/rules              # Create rule
POST   /api/v1/conformance/rules/bulk         # Create multiple rules (used by packs)
GET    /api/v1/conformance/rules/:id          # Get rule
PUT    /api/v1/conformance/rules/:id          # Update rule
DELETE /api/v1/conformance/rules/:id          # Delete rule
POST   /api/v1/conformance/rules/:id/toggle   # Enable/disable

# Checks
POST   /api/v1/projects/:id/conformance/check # Trigger check with changed files
GET    /api/v1/conformance/checks             # List all checks (org-wide, ?projectId= filter)
GET    /api/v1/conformance/checks/:id/report  # Get check report with violations
POST   /api/v1/conformance/checks/delete      # Bulk delete checks { ids: [...] }

# Stats
GET    /api/v1/conformance/stats              # Org-wide statistics
GET    /api/v1/projects/:id/conformance/stats  # Project statistics

Todos los endpoints requieren autenticación (JWT o una clave de API con scope de escritura para las mutaciones).