Crear reglas para tu agente

Una regla es una instrucción corta y permanente que tu agente de IA lee en cada sesión y que moldea cómo se comporta en todas las tareas. Si notás que el agente comete siempre el mismo error y vos lo corregís a mano una y otra vez, no necesitás más paciencia: necesitás una regla. La escribís una vez, queda guardada, y el problema deja de volver.

Qué es una regla (y por qué te sirve para poner la IA a trabajar)

Pensá en una regla como una "orden permanente" para tu asistente. No es una sugerencia que tirás en el chat y se olvida al cerrar la ventana: vive en un archivo del proyecto y se carga sola cada vez que arrancás. Eso significa que el agente arranca cada tarea ya sabiendo tus convenciones, tus límites y tu forma de trabajar.

Las reglas te dan cuatro cosas concretas:

1. Límites de comportamiento — qué hacer y, sobre todo, qué NO hacer.
2. Estándares — formato, patrones, decisiones de arquitectura que querés que respete siempre.
3. Controles de calidad — condiciones que se tienen que cumplir antes de avanzar.
4. Convenciones del proyecto — la terminología y las prácticas propias de lo que estás armando.

El principio central es simple: una regla efectiva no solo te dice qué hacer, te muestra el ejemplo incorrecto al lado del correcto. Esa comparación elimina la ambigüedad. El agente ve exactamente dónde está el límite entre lo aceptable y lo que no va.

Cuándo usás una regla y cuándo te conviene una skill

No todo va en una regla. Las reglas se cargan SIEMPRE, en cada sesión, así que ocupan contexto todo el tiempo. Si la metés con cosas que solo importan a veces, le estás metiendo ruido al agente.

Usá una regla cuando:

• El comportamiento tiene que aplicarse a TODAS las sesiones, no a una tarea puntual.
• El agente repite el mismo error a pesar de que ya lo corregiste.
• Hay un patrón con un correcto y un incorrecto claros (se puede mostrar con ejemplos).

NO uses una regla (y armá una skill o ponelo en otro lado) cuando:

• Es un flujo de trabajo de varios pasos ("primero esto, después esto, después esto"). Eso es una skill.
• Es una instrucción de una sola vez. Eso va directo en el prompt.
• Es contexto general del proyecto. Eso va en el archivo CLAUDE.md.

La diferencia rápida: las reglas son límites cortos y enfocados que están siempre presentes. Las skills son procedimientos completos que se cargan solo cuando hacen falta. Si tu instrucción tiene una lista numerada de pasos, casi seguro es una skill, no una regla.

Dónde viven las reglas

Las reglas son archivos markdown que van en la carpeta .claude/rules/ de tu proyecto. Un archivo, un tema. El nombre describe la preocupación, no la solución.

tu-proyecto/
├── .claude/
│   ├── CLAUDE.md            # contexto general del proyecto
│   └── rules/
│       ├── manejo-errores.md
│       ├── estilo-codigo.md
│       └── seguridad.md

Convenciones de nombre que conviene seguir:

• Minúsculas con guiones: manejo-errores.md, no ManejoErrores.md.
• Nombrá por el tema, no por la técnica: manejo-errores.md, no patrones-try-catch.md.
• Un tema por archivo. Si tenés que juntar dos cosas distintas, son dos archivos.

La estructura: descripción, incorrecto, correcto

Toda regla buena sigue el mismo molde: una descripción breve, un ejemplo de lo que está mal, y un ejemplo de lo que está bien. Este es el esqueleto que podés copiar y rellenar:

---
title: Nombre corto de la regla
paths:                    # opcional: si podés acotar a ciertos archivos, hacelo
  - "src/**/*.ts"
---

# Nombre de la regla

[1 o 2 frases que digan QUÉ obliga la regla y POR QUÉ importa.]

## Incorrecto

[Qué tiene de malo este patrón.]

\`\`\`lenguaje
// código o comportamiento que NO querés
\`\`\`

## Correcto

[Por qué este patrón es mejor.]

\`\`\`lenguaje
// código o comportamiento recomendado
\`\`\`

## Referencia

[Opcional: links a documentación o reglas relacionadas.]

¿Por qué funciona tan bien mostrar el incorrecto y el correcto juntos? Por tres razones:

1. Elimina la ambigüedad — el agente ve el límite exacto entre lo que sirve y lo que no.
2. Corta las excusas — es más difícil que justifique "bueno, casi" cuando el patrón malo está explícito.
3. Permite que se autocorrija — el agente puede comparar su propio resultado contra los dos patrones.

Cómo escribir directivas claras

Una regla vaga no sirve. "Mantené las funciones cortas" no le dice nada útil al agente, porque "corta" significa cosas distintas para cada uno. Estos son los principios que separan una regla útil de una inútil:

• Sé específico, no vago. "Las funciones no deben superar las 50 líneas", no "mantené las funciones cortas".
• Decí el POR QUÉ. "Usá returns tempranos para reducir anidamiento — el código muy anidado cuesta más de leer." El motivo ayuda al agente a aplicar bien la regla.
• Usá la forma imperativa. "Usá returns tempranos", no "deberías usar returns tempranos".
• El ejemplo incorrecto tiene que ser realista. Mostrá el error que el agente DE VERDAD comete, no algo absurdo que nunca produciría. Un ejemplo malo inventado no enseña nada.
• El ejemplo correcto es el cambio mínimo. Arreglá solo lo que importa. Si reescribís todo, se pierde la lección.

Reglas acotadas a ciertos archivos

A veces una regla solo tiene sentido para cierto tipo de archivos: por ejemplo, validar la entrada solo en los endpoints de la API. Para eso usás el campo paths en el frontmatter, con patrones glob. La regla se carga únicamente cuando el agente toca archivos que coinciden, así no le metés ruido al resto del trabajo.

---
paths:
  - "src/api/**/*.ts"
  - "src/routes/**/*.ts"
---

# Los endpoints de la API deben validar la entrada

Todo endpoint tiene que validar el cuerpo del request antes de procesarlo. La entrada sin validar genera errores en runtime, agujeros de seguridad y datos corruptos.

Algunos patrones útiles:

• **/*.ts — todos los archivos TypeScript, en cualquier carpeta.
• src/**/* — todo lo que esté bajo src/.
• src/components/*.tsx — componentes en una carpeta puntual.

Si tu regla aplica a TODO el proyecto, no pongas paths: dejala global y listo. Acotar a **/* es lo mismo que no acotar, pero con más vueltas.

Un ejemplo completo y listo para copiar

Esta es una regla real, entera, que podés pegar tal cual y adaptar. Fijate cómo el incorrecto y el correcto muestran exactamente el mismo escenario, y la única diferencia es lo que importa:

---
title: Usá returns tempranos para reducir el anidamiento
paths:
  - "**/*.ts"
---

# Usá returns tempranos para reducir el anidamiento

Manejá los errores y los casos borde arriba de todo con returns tempranos. El código muy anidado cuesta más de leer y esconde el camino feliz.

## Incorrecto

Las validaciones quedan enterradas en condicionales anidados y el caso principal queda 3 niveles adentro.

\`\`\`typescript
function procesarPedido(pedido: Pedido) {
  if (pedido) {
    if (pedido.items.length > 0) {
      if (pedido.estado === 'pendiente') {
        const total = calcularTotal(pedido.items)
        return enviarPedido(pedido, total)
      } else {
        throw new Error('Pedido no pendiente')
      }
    } else {
      throw new Error('Sin items')
    }
  } else {
    throw new Error('Sin pedido')
  }
}
\`\`\`

## Correcto

Los errores se manejan primero con returns tempranos y el caso principal queda arriba, a la vista.

\`\`\`typescript
function procesarPedido(pedido: Pedido) {
  if (!pedido)
    throw new Error('Sin pedido')
  if (pedido.items.length === 0)
    throw new Error('Sin items')
  if (pedido.estado !== 'pendiente')
    throw new Error('Pedido no pendiente')

  const total = calcularTotal(pedido.items)
  return enviarPedido(pedido, total)
}
\`\`\`

Errores comunes que conviene evitar

• Reglas vagas sin ejemplos. "Usá nombres de variables con sentido" no calibra nada. Sin un incorrecto y un correcto, el agente no sabe dónde está el límite.
• Meter un flujo de trabajo en una regla. Si tenés una lista de pasos para desplegar a producción, eso es una skill, no una regla. Las reglas son límites, no procedimientos.
• Reglas duplicadas. Si la misma indicación está en CLAUDE.md y también en una regla, el agente no sabe cuál manda. Cada indicación va en un solo lado.
• Reglas largas. Como se cargan en cada sesión, cada palabra cuenta. Apuntá a 50–200 palabras de texto por regla (sin contar el código) y un solo tema por archivo.

Cómo escribir tu primera regla en 5 pasos

1. Identificá el problema. Escribilo concreto: "el agente hace X, pero debería hacer Y".
2. Decidí el alcance. ¿Aplica a todo el proyecto (global), solo a ciertos archivos (paths), o es una preferencia tuya para todos tus proyectos (~/.claude/rules/)?
3. Escribí primero los ejemplos. Empezá por el incorrecto (el error real del agente), después el correcto (el arreglo mínimo). La diferencia tiene que entenderse en menos de 5 segundos.
4. Escribí la descripción. Una o dos frases: qué obliga la regla y por qué importa.
5. Guardá el archivo. En .claude/rules/ con un nombre descriptivo y con guiones.

Próximo paso

Elegí UN error que tu agente repite siempre, abrí un archivo en .claude/rules/, y escribí tu primera regla con un ejemplo incorrecto y uno correcto. Probala en la próxima sesión y fijate si el error desaparece. Si querés que armemos juntos tu set de reglas y dejes a tu IA trabajando como vos querés, reservá una llamada en /agenda.