Reglas para agentes de IA en equipo: plantilla de CLAUDE.md y AGENTS.md

Para CTO, tech leads y desarrolladores cuyo equipo ya usa Claude Code, Codex, Cursor o Copilot. Cada uno a su manera. Esta plantilla lo convierte en una capa común.

Hoy la IA escribe todo nuestro código y un sénior responde del resultado. Desde 2023 hemos entregado más de 15 proyectos en producción. Este es el marco que usamos en ellos.

1. Por qué no bastan las reglas escritas

Le prohíbe al agente abrir un archivo. No lo abre. Escribe un script que lo imprime.

No es malicia. El agente recibió una tarea y busca un camino. Una frase en el prompt es para él un obstáculo, no un muro. Por eso cada regla de abajo tiene una columna que falta en la mayoría de las “políticas de IA”: qué la detiene de verdad.

Una regla que se ha incumplido dos veces deja de ser solo una frase. Súbala un nivel.

2. Ocho cosas que el agente no debe hacer

En el punto ocho escribimos con honestidad “solo una frase”. Hoy nada lo impone de forma mecánica. Una regla que admite su debilidad es mejor que una regla que finge ser fuerte.

¿Cuántas de sus reglas son solo una frase? Esos son los agujeros que tiene.

3. Dónde va cada regla

El agente carga su archivo de reglas en cada ejecución. Cuanto más texto, peor se ciñe a lo importante. Por eso, tres niveles:

1. Raíz del repositorio: un CLAUDE.md o AGENTS.md corto. Qué es este repositorio, cómo ejecutar los tests, qué no debe hacer el agente, cómo es un trabajo terminado.
2. Carpeta: las reglas de un módulo, en un archivo dentro de ella. Solo se cargan cuando el agente trabaja ahí.
3. Lint o test: las reglas más importantes. Nadie tiene que leerlas; detienen un cambio malo por sí solas.

¿Usa varias herramientas? Tenga las reglas en AGENTS.md y enlácelas desde CLAUDE.md con la línea @AGENTS.md. Dos copias se separan antes de que nadie lo note.

Estructura de archivos

CLAUDE.md  o  AGENTS.md       corto: repo, comandos, enlaces
.claude/
  settings.json               las prohibiciones en formato máquina
  hooks/push-gate.sh          lo que los ajustes no pueden expresar
  rules/
    00-nunca.md               8 prohibiciones + columna "qué lo impone"
    10-tarea.md               qué necesita una tarea antes de que empiece el agente
    20-controles.md           lint, typecheck, tests: bloquea sí/no
    30-revision.md            quién revisa y qué recibe
    90-responsable.md         quién es responsable de las reglas y cómo se añade una nueva

4. Patrones para su repositorio

Los ejemplos son para Claude Code. El principio (deny, hook, CI, lint) sirve también para otras herramientas; solo cambia la sintaxis.

Prohibiciones en los ajustes (puntos 1 a 5)

{
  "permissions": {
    "deny": [
      "Bash(psql:*)",
      "Bash(git push --force:*)",
      "Bash(git reset --hard:*)",
      "Read(.env.prod*)",
      "Read(**/*.pem)"
    ],
    "ask": [
      "Read(**/.env*)",
      "Bash(npx prisma migrate deploy:*)"
    ]
  }
}

Atención: una regla compara el texto del comando, no la intención. Si el agente puede ejecutar cat, cat .env se salta la prohibición de lectura. Por eso los secretos viven fuera del repositorio. Los scripts los cargan y nunca los imprimen.

Hook contra el push a main (punto 5)

#!/bin/bash
# .claude/hooks/push-gate.sh  (PreToolUse, Bash)
# exit 0 = permitir, exit 2 = detener
CMD=$(jq -r '.tool_input.command // empty')
[[ "$CMD" != *"git push"* ]] && exit 0
case "$CMD" in
  *" main"*|*" master"*)
    echo "No se permite hacer push a main. Abra un PR." >&2
    exit 2 ;;
esac
exit 0

Dos errores desactivan un hook en silencio. || true después del hook convierte el exit 2 en 0. Y 2>/dev/null tira el mensaje, así que el agente no sabe por qué ha fallado. Pruebe el hook una vez de verdad. Active también la protección de rama en el servidor, porque un hook solo se ejecuta donde está instalado.

Tests y revisión (puntos 6 y 7)

• Un test tiene que fallar primero. Con el código original. Si no, solo demuestra que el agente está de acuerdo consigo mismo.
• Los tests de la tarea los aprueba una persona. CI avisa cuando un PR cambia tests y código a la vez. Decide el revisor.
• Quien lo escribió no lo revisa. Lance la revisión en un contexto nuevo, idealmente con otro modelo. Recibe el diff y sus reglas, no la conversación con el autor.
• CI tiene que bloquear. Un pipeline que solo informa es decoración.

5. De dónde salen las reglas nuevas

De la revisión. Un comentario que aparece por segunda vez no es un error del desarrollador. Es un agujero en las reglas.

Una condición: la revisión se escribe en el pull request, no solo de palabra en una llamada. Una revisión hablada no deja nada de donde sacar una regla.

6. Responsable y medición

Las reglas sin responsable se quedan obsoletas en pocos meses. El agente las sigue obedeciendo aunque ya no apliquen. Copie esto en 90-responsable.md:

Responsable: [nombre]
Regla nueva: PR a .claude/rules/, la aprueba el responsable.
Limpieza: primer lunes del mes, 30 minutos.
Escalera: incumplida dos veces -> un nivel más arriba
  frase -> ajuste o hook -> CI -> lint
Cada mes anotamos: cuántas reglas siguen siendo solo una frase.

Tres cifras que vale la pena seguir cada mes:

• Comentarios de revisión por PR. Si las reglas funcionan, bajan.
• Cuántas veces un control detuvo un cambio. Y cuántas veces el agente lo corrigió después por sí mismo.
• Cuántas reglas siguen siendo solo una frase. Es la lista de tareas del mes siguiente.

No mida commits ni líneas de código. La IA las infla en un segundo.

7. Hoja de trabajo para el equipo (45 minutos)

Imprímala, póngala sobre la mesa y rellénenla juntos.

Está terminada cuando, en cada fila, sabe decir qué la impone y quién es el responsable.