Rules, Skills y Agentes: cómo organizamos el conocimiento cuando la IA escribe código

Cuando empiezas a usar IA para desarrollar en serio —no para generar un snippet suelto, sino para construir una aplicación entera— te das cuenta rápido de que el mayor problema no es la capacidad del modelo. Es la consistencia. La IA no recuerda lo que hizo ayer, no sabe cómo nombras tus columnas, no conoce tu guía de estilos ni por qué decidisteis usar UUID en unas tablas y BIGINT en otras.

Rules, Skills y Agentes son tres mecanismos distintos para resolver ese problema. No son intercambiables: cada uno actúa en un nivel diferente. Vamos por partes.

Rules: el contexto siempre activo

Las rules son instrucciones que se inyectan automáticamente en cada conversación, sin que tengas que pedirlo. Son el equivalente a pegar un post-it en el monitor del modelo: «oye, recuerda que aquí hacemos las cosas así».

En Cursor se definen en .cursor/rules/ (antes era un único .cursorrules). En Claude se configuran como System Prompt del proyecto o, en proyectos de equipo, como ficheros en .claude/.

¿Qué va en las rules? Lo que debe ser verdad siempre, en cualquier tarea:

• Stack tecnológico: «Este proyecto usa Angular 19 standalone, Bootstrap 5.3 y Python 3.12 con FastAPI.»
• Convenciones de nombrado: «Las tablas propias usan UUID como PK. Las tablas corporativas usan BIGINT y no declaran FK.»
• Restricciones globales: «Nunca usar any en TypeScript. Nunca DELETE físico, siempre soft delete con deleted_at.»
• Tono y formato: «Los comentarios en el código van en español. Los commits siguen Conventional Commits.»

La regla de oro de las rules: si tienes que repetirlo en cada sesión, ponlo en las rules. Si te encuentras escribiendo «recuerda que usamos signals de Angular, no observables para el estado local» por tercera vez, ese texto pertenece a las rules, no al chat.

El peligro de las rules es inflarse. Si metes demasiado contexto, el modelo se pierde en los detalles y los más importantes pierden peso. Las rules deben ser concisas y estables: cambian poco, y cuando cambian es porque hay una decisión de arquitectura real detrás.

Skills: conocimiento especializado bajo demanda

Una skill es un documento de referencia que el agente o el modelo lee antes de abordar una tarea específica. No está siempre activa como las rules: se carga cuando la tarea lo requiere.

En la práctica, una skill es un fichero Markdown estructurado que describe cómo hacer algo concreto: qué librerías usar, qué patrones seguir, qué errores evitar, ejemplos de código válido e inválido. En nuestro caso viven en .claude/skills/ y el agente correspondiente las lee explícitamente al inicio de su tarea.

Ejemplos del skills empleadas en un proyecto interno:

• database-conventions — cómo definir modelos SQLAlchemy: cuándo usar ForeignKey() real vs. columna sin FK, cómo declarar índices parciales, qué es el AuditMixin.
• angular-patterns — signals vs. observables, cómo estructurar un servicio dual-mode (mock/HTTP), cómo usar viewChild en lugar de @ViewChild.
• style-guide — tema appPersonasRrhh (#990066), clases Bootstrap propias, patrón de modal, reglas de tabla y badge.
• figma-to-angular — cómo inferir la estructura de un componente Angular a partir de una captura de pantalla o un diseño Figma.
• skill-creator — meta-skill: cómo crear y optimizar las propias skills (sí, hay una skill para hacer skills).

La diferencia clave con las rules es el alcance. Las rules aplican a todo. Una skill aplica solo cuando alguien la invoca. Esto permite tener mucho más detalle sin saturar el contexto: el agente que implementa un endpoint de backend carga backend-patterns y database-conventions. El que genera un componente Angular carga angular-patterns y style-guide. Nunca los dos a la vez si no hace falta.

En Cursor el equivalente son los docs (.cursor/docs/) o los propios ficheros de referencia que mencionas en el chat con @archivo. La idea es la misma: conocimiento especializado que se activa cuando la tarea lo necesita.

Agentes: roles con responsabilidad acotada

Un agente es un rol especializado con un proceso definido, herramientas específicas y unas fuentes de verdad concretas. No es simplemente «Claude con un prompt diferente»: es una unidad de trabajo con entradas, salidas y criterios de éxito propios.

Siguiendo con el ejemplo del proyecto interno citado anteriormente, en él tenemos 12 agentes definidos como ficheros Markdown en .claude/agents/, cada uno con un frontmatter YAML que declara su nombre, cuándo se activa y qué herramientas MCP necesita:

---
name: data-modeler
description: Se activa cuando hay que diseñar o modificar el modelo de datos
tools: [mcp-filesystem, mcp-postgres]
---
# System prompt del agente
Lee database-conventions/SKILL.md antes de actuar.
Tu output es /docs/phase2-data-model.md...

El pipeline completo del proyecto sigue este orden:

lovable-analyzer → architect → data-modeler + api-designer → schema-builder + auth-agent → endpoint-builder + component-builder → backend-qa + integration → doc-generator

Cada agente tiene responsabilidad sobre una fase y un artefacto concreto. El data-modeler produce el modelo de datos. El api-designer produce el OpenAPI. El backend-qa produce los tests. Ninguno se mete en el trabajo del otro.

¿Por qué importa esta separación? Porque el contexto de cada agente es diferente. El lovable-analyzer necesita Playwright para navegar prototipos. El schema-builder necesita acceso a PostgreSQL para verificar las migraciones. El doc-generator necesita acceso al sistema de archivos para leer todos los planes de fase. Si metieras todo en un solo agente, el contexto explotaría y la calidad bajaría.

En Cursor los agentes se implementan de forma más ligera: son conversaciones con un system prompt específico y un conjunto de @archivos o @docs cargados. No hay un fichero de definición formal, pero el concepto es el mismo: rol acotado, contexto relevante, output concreto.

Cómo se relacionan los tres

	¿Cuándo actúa?	¿Quién lo lee?	¿Qué contiene?
Rules	Siempre, en toda conversación	El modelo automáticamente	Restricciones y contexto global
Skills	Cuando la tarea lo requiere	El agente explícitamente	Conocimiento especializado con ejemplos
Agentes	Cuando la fase lo requiere	Se invoca manualmente	Rol + proceso + herramientas + skills

Una forma de pensarlo: las rules son la cultura del equipo (siempre presente), las skills son los manuales técnicos (se consultan cuando hace falta) y los agentes son los perfiles de los miembros del equipo (cada uno con su especialidad y sus herramientas).

Lo que aprendimos usándolos en producción

Las rules deben ser cortas y estables. Si las rules cambian cada semana, algo falla en el proceso de toma de decisiones, no en las rules.

Las skills se crean cuando te repites. La segunda vez que le explicas al modelo cómo nombrar una FK corporativa, eso es una skill. La tercera vez que corriges el mismo patrón de modal, eso es una skill.

Los agentes no son para todo. Las tareas con mucho contexto específico y mucho diálogo (refinamiento visual, decisiones de UX, debug complejo) son más eficientes en conversación directa. Los agentes brillan en tareas con entradas y salidas bien definidas.

Versionar todo en el repo cambia las reglas del juego. Rules, skills y agentes en .claude/ o .cursor/ significa que el conocimiento del proyecto viaja con el código, está disponible para todo el equipo y se puede revisar en un PR como cualquier otro cambio.