Buenas prácticas de Claude Code para equipos: 7 reglas que se mantienen

Las buenas prácticas de Claude Code que importan en un equipo no son trucos de prompting. Son siete reglas que se mantienen aunque nadie esté mirando: un CLAUDE.md corto que la CI mantiene corto, un plugin compartido, permisos y hooks en el repositorio, una issue para una PR, un test que primero falla y un revisor que no escribió el código. Cada una la hace cumplir un archivo o una comprobación, no la memoria.

Así trabajamos en cada repositorio, y la IA escribe la mayor parte de nuestro código. El resto del artículo explica cómo se hace cumplir cada práctica, con los archivos reales.

¿Qué prácticas de Claude Code se mantienen en un equipo?

Los consejos individuales viven en la cabeza de una persona. Una práctica de equipo necesita un lugar donde esté escrita y una comprobación que detecte cuando se rompe:

Lea la tabla también como un orden. Las cuatro primeras cuestan una tarde. Las tres últimas cambian cómo fluye el trabajo.

1. ¿Por qué mantener CLAUDE.md corto y cómo se hace cumplir?

CLAUDE.md y cada archivo de reglas que se carga siempre entran en el contexto en cada petición. La guía de costes de Anthropic recomienda mantenerlo por debajo de 200 líneas y pasar las instrucciones de flujo de trabajo a skills, que solo se cargan cuando se usan.

"Manténgalo corto" dura unas dos semanas. Por eso nuestro validador lo cuenta. Suma CLAUDE.md y todas las reglas que se cargan siempre, y por eso su límite es de 300 líneas, no de 200:

# CLAUDE.md + every .claude/rules/*.md that loads on every session
# (rules scoped with `paths:` load only under matching paths and are skipped)
if [ "$total_lines" -gt 300 ]; then
  log_critical "Context budget exceeded: $total_lines lines (max 300)."
fi

Se ejecuta en la CI de cada repositorio. En los repositorios de empresa y de clientes hace fallar el build; en los repositorios de código, avisa.

La otra mitad es dónde va cada regla. El estilo de trabajo personal pertenece a ~/.claude. Todo lo que debe seguir el equipo entero pertenece al repositorio.

Cómo repartir las reglas entre CLAUDE.md, AGENTS.md y los archivos personales se explica en detalle en Reglas para el código de IA en un equipo.

2. ¿Por qué un plugin compartido en lugar de copias?

Antes copiábamos nuestras skills de planificación, desarrollo y revisión en cada repositorio. En pocas semanas las copias se habían distanciado, y algunas eran esqueletos vacíos. La disciplina no lo arregló. Lo arregló un plugin: wizrd, nuestro plugin y CLI interno para Claude Code (no es público). Las skills, los agentes y los hooks viven en un repositorio, y cada uno de los demás repositorios lo activa con dos líneas de configuración:

{
  "enabledPlugins": { "wizrd@digitaliko": true },
  "extraKnownMarketplaces": {
    "digitaliko": { "source": { "source": "directory", "path": "services/wizrd" } }
  }
}

Una corrección en la skill de revisión llega ahora a cada sesión la próxima vez que se inicia. Cómo estructuramos el propio plugin está en Skills y plugins de Claude Code para un equipo.

3. ¿Por qué poner los permisos en el repositorio?

Porque un deny en el repositorio gana a un allow en cualquier otro sitio. Claude Code comprueba primero las reglas deny, después ask y después allow, en todos los archivos de configuración. Así el equipo decide una sola vez, en .claude/settings.json: deny para los archivos .env y las claves, ask antes de un push, un merge o un deploy, allow para los scripts que el agente necesita para comprobar su propio trabajo.

Todo lo personal se queda en ~/.claude/settings.json. La estructura y nuestras entradas exactas están en Claude Code dangerously-skip-permissions: ¿cuándo es seguro?.

4. ¿Por qué bloquear con hooks en lugar de pedirlo en CLAUDE.md?

Una frase en CLAUDE.md es una petición. Un día de octubre, un agente escribió un pie de atribución a la IA en el cuerpo de varias pull requests de nuestros propios repositorios, en una sesión cuyo CLAUDE.md lo prohibía exactamente con esas palabras.

La solución fue un hook PreToolUse que revisa cada comando git commit, gh pr y gh issue, incluidos los archivos pasados con --body-file, y termina con exit 2. El comentario al principio del script lo resume mejor: "A rule is a request. This is the lock." (Una regla es una petición. Esto es el cerrojo.)

Los hooks tienen su propio modo de fallo: pueden quedarse en silencio y seguir pasando. Las cuatro comprobaciones que lo detectan están en Hooks de Claude Code que en silencio no hacen nada.

5. ¿Por qué una issue para una PR?

Una sesión de agente olvida. Una issue de GitHub, no. Cada tarea empieza como una issue que dice qué significa "terminado", escrita para que un revisor pueda responder sí o no, y termina como una pull request con Closes #N.

Eso da tres cosas que una sesión de chat no puede dar. El plan es visible antes de empezar el trabajo. Dos agentes pueden trabajar en paralelo, cada uno en su propio git worktree y en su propia rama, sin pisarse. Y las pull requests fusionadas son el registro de cambios, así que nadie escribe un registro de trabajo.

El plan mode ayuda dentro de la sesión. Dónde deja de bastar para un equipo se explica en Claude Code plan mode: ¿cuándo basta?.

6. ¿Por qué el test tiene que fallar primero?

Un agente puede escribir tests que pasan tanto si el código funciona como si no. Por eso nuestro gate ejecuta los tests nuevos o modificados contra la rama base, antes de la corrección. Si también pasan ahí, no demuestran nada y la pull request vuelve atrás. Solo cuenta un test que está en rojo sin el cambio y en verde con él. Todo el mecanismo está en TDD red-green con agentes de IA.

7. ¿Por qué debe revisar el código otro agente?

El agente autor ya se ha convencido a sí mismo. Una sesión nueva que solo lee el diff encuentra lo que el autor se saltó. Nuestro revisor en la CI recibe una lista de herramientas de solo lectura (git diff, git log, gh pr diff, Read, Grep) y una checklist de revisión del repositorio. Comenta. Nunca aprueba. La protección de ramas exige una persona, así que el merge es siempre una decisión humana. La configuración y el prompt están en Revisión de código con Claude Code en la CI.

¿Por dónde debe empezar un equipo?

No con las siete a la vez. El orden que nos funcionó:

Los tres primeros llevan un día en un repositorio existente. El cuarto es un hábito, y hacen falta unas semanas de comentarios de revisión antes de que el equipo escriba issues que un agente pueda terminar sin preguntar.

¿Dónde está su equipo hoy?

Cuente lo que ya está en sus repositorios, no lo que la gente dice que hace:

Puede copiar la configuración, los hooks, el gate y el flujo de revisión de nuestro Claude Code production starter, con licencia MIT.

¿Quiere estas prácticas funcionando en sus repositorios?

Las configuramos directamente en los repositorios del equipo, junto con los desarrolladores, como parte de AI-native SDLC para equipos de desarrollo. La IA escribe la mayor parte de nuestro código. Un sénior revisa cada cambio y responde de la producción. Desde 2023 hemos entregado más de 15 proyectos en producción.

Le respondemos en un plazo de dos días hábiles con algunas preguntas sobre su trabajo. Después acordamos qué hacemos primero.

Si prefiere hablar primero, reserve una llamada introductoria de 15 minutos.

¿Cuál de las siete se rompería primero en su equipo si nadie lo comprobara?

Preguntas frecuentes

¿Cuáles son las buenas prácticas más importantes de Claude Code?

Para un equipo: mantener CLAUDE.md corto y hacer cumplir el límite, compartir skills y hooks como un solo plugin, poner los permisos en el repositorio, bloquear con hooks en lugar de pedir en prosa, llevar una issue a una PR, demostrar cada cambio con un test que primero falla y dejar que otro agente lo revise antes de que una persona haga el merge.

¿Qué longitud debe tener CLAUDE.md?

Lo bastante corto para que compense en cada petición. Anthropic recomienda menos de 200 líneas. Nosotros contamos CLAUDE.md junto con cada archivo de reglas que se carga siempre y hacemos fallar la CI por encima de 300 líneas en nuestros repositorios de empresa y de clientes.

¿Hay que subir a git la configuración de Claude Code?

La parte del equipo, sí: .claude/settings.json con permisos y hooks pertenece al repositorio. Las preferencias personales van en ~/.claude/settings.json y los ajustes locales en .claude/settings.local.json, que se queda fuera de git.

¿Cómo se comparten las skills de Claude Code en un equipo?

Como un plugin que cada repositorio activa en su configuración. Las copias de skills en cada repositorio se distancian en pocas semanas; un solo plugin da a cada sesión las mismas skills, agentes y hooks.

¿Es el plan mode una buena práctica para cualquier tarea?

Para explorar antes de un cambio grande, sí. En un equipo, el plan también tiene que vivir donde otros puedan leerlo, por ejemplo en la issue con sus criterios de aceptación, no solo en la sesión de un desarrollador.