Claude Code para Equipos: Manual de Estandarización de Habilidades

Reúna a cinco desarrolladores con Claude Code y obtendrá cinco herramientas diferentes. Uno tiene un archivo CLAUDE.md con opiniones firmes sobre las pruebas. Otro nunca ha abierto el directorio de habilidades. Otro instaló una habilidad de depuración de un hilo de GitHub hace tres semanas y olvidó avisar a nadie. Dos están ejecutando las configuraciones predeterminadas, lo que significa que Claude adivina sus convenciones en cada sesión.

El código que llega a su cola de PRs refleja esa división. Algunos diffs vienen con pruebas escritas primero y un historial de commits limpio. Otros vienen con una solución plausible para un error que nadie diagnosticó realmente. Mismo modelo, mismo repo, misma semana, cinco calidades de salida diferentes, y el revisor lo detecta todo manualmente.

Este es un problema de configuración personal disfrazado de problema de equipo. Individualmente, la configuración de cada desarrollador es defendible. Colectivamente, el equipo no tiene un estándar mínimo. Nadie acordó cómo es lo "bueno" cuando Claude hace el primer borrador, por lo que nadie puede mantener esa línea. Este artículo trata sobre la solución: habilidades a nivel de proyecto que residen en el repo en lugar de en los ordenadores portátiles, y la gobernanza e implementación que las hace perdurar.

La solución está en dónde reside la habilidad, no en lo que hace

Claude Code lee habilidades de dos lugares. Las habilidades personales residen en ~/.claude/skills/, vinculadas a una máquina, invisibles para los compañeros de equipo, desaparecidas en el momento en que el desarrollador cambia de ordenador portátil. Las habilidades de proyecto residen en .claude/skills/ dentro del propio repositorio, confirmadas junto con el código que gobiernan.

Esa segunda ubicación es todo el truco. Una habilidad de proyecto es un archivo en git: obtiene un diff, un revisor, un mensaje de commit que explica por qué la depuración debe seguir un ciclo de hipótesis primero en lugar de lo que se sintió correcto ese día. Cuando alguien mejora la habilidad, la mejora se envía a todos en el siguiente pull, de la misma manera que lo hace una actualización de configuración de un linter.

Compare eso con la alternativa a la que la mayoría de los equipos recurren primero: una página wiki titulada "Cómo usamos Claude" que tres personas han leído y nadie aplica. Una página wiki es un consejo. Una habilidad de proyecto se asemeja más a una dependencia: Claude carga su descripción al inicio de cada sesión en ese repo y la aplica automáticamente cuando una tarea coincide, sin que nadie necesite recordar que existe o volver a explicarla en el prompt.

El resultado práctico es que "el estándar de nuestro equipo" deja de ser una frase en un documento de onboarding y se convierte en algo que Claude realmente hace, de forma idéntica, ya sea en la sesión del líder técnico o en la sesión del nuevo empleado el primer día.

Qué estandarizar primero

No intente codificar toda su cultura de ingeniería en habilidades de una sola vez. Tres áreas cubren la mayor parte de la varianza que vemos entre desarrolladores del mismo equipo, y cada una tiene una habilidad probada y puntuada que puede señalar como un ejemplo concreto de cómo es lo "bueno", incluso si termina escribiendo su propia versión adaptada a su stack.

• Una lista de verificación de revisión. La brecha entre una revisión que encuentra errores reales y una revisión que encuentra preferencias de nombres de variables es exactamente lo que cierra una buena habilidad de revisión. Code Review Checklist obtiene 8.4/10 en nuestras pruebas: en un PR de 600 líneas encontró un error real de "off-by-one" y dos rutas de código muerto, y no produjo ninguna crítica solo de estilo. Si cada revisor obtiene esa calidad de primera pasada antes de que un humano abra el diff, los ingenieros senior dedican tiempo de revisión a la arquitectura en lugar de detectar lo que una lista de verificación debería haber detectado.
• Disciplina TDD. Test-Driven Development, de la colección Superpowers de Jesse Vincent, obtiene 9.6/10. Lo ejecutamos en una sesión de tres características y Claude escribió la prueba fallida primero cada vez, negándose a omitir el ciclo incluso con un atajo disponible. Es una habilidad de comportamiento puro, sin scripts ni herramientas externas, lo que la convierte en lo más fácil de universalizar: "escribir la prueba primero" no depende de su framework.
• Un protocolo de depuración. Systematic Debugging, también 9.6/10, reemplaza el bucle predeterminado de "intentar una solución plausible" con reproducir, hipotetizar, instrumentar, verificar. En nuestra prueba, identificó la causa raíz de una race condition que ya había sobrevivido a tres soluciones basadas en conjeturas. Esta es la habilidad que más importa en un equipo, porque la depuración por ensayo y error es de donde proviene la salida de mayor varianza, y un protocolo compartido colapsa esa brecha.

Tres habilidades. No las veinte que se sentirá tentado a añadir una vez que las tres primeras funcionen.

Quién aprueba una nueva habilidad

Una vez que las habilidades residen en el repo, alguien tiene que decidir qué se añade, y esta es la parte que los equipos omiten hasta que les pasa factura. Una habilidad son instrucciones que Claude sigue automáticamente y, a veces, scripts que Claude ejecutará, lo que la coloca en la misma categoría de confianza que un nuevo paquete npm o una acción de CI. Nadie permitiría que un desarrollador añada una dependencia arbitraria a package.json sin una revisión de PR. Una habilidad merece la misma puerta de entrada.

La mecánica es simple una vez que se compromete a tratarlo de esa manera. Una nueva habilidad entra en el repo a través de un pull request normal, con la misma protección de rama que cualquier otro cambio. El revisor lee todo el SKILL.md, buscando instrucciones no relacionadas con el propósito declarado y cualquier llamada de red cuya razón no sea obvia. Si la habilidad incluye scripts, alguien los abre realmente. Esta es la misma auditoría de dos minutos que detallamos en nuestra guía de seguridad.

Asigne un propietario, una persona en lugar de un comité, generalmente quien propuso la habilidad o un líder técnico rotatorio, responsable de que la descripción de la habilidad se mantenga precisa y sus instrucciones actualizadas. Cuando la frase de activación de una habilidad comienza a activarse en tareas incorrectas, o sus instrucciones se desvían del flujo de trabajo para el que fue escrita, ese propietario la corrige o la retira.

Versionela como todo lo demás en el repo. Si una habilidad cambia de comportamiento significativamente, eso merece una nota en la descripción del PR y, para cualquier cosa con un peso conductual real, una mención en el standup para que la gente sepa que sus sesiones actuarán de manera diferente a partir de hoy.

El onboarding es la verdadera característica clave

Aquí está la parte que es fácil de subestimar cuando se presenta esto a un líder de equipo escéptico: un nuevo empleado clona el repo el primer día y obtiene la misma disciplina de revisión, el mismo hábito de "prueba primero" y el mismo protocolo de depuración que la persona que lleva dos años allí. No porque hayan leído detenidamente un documento de onboarding de 40 páginas. Porque las habilidades ya están en .claude/skills/, y Claude las detecta en el momento en que el nuevo empleado abre el proyecto.

Piense en cómo suele ser el onboarding sin esto. Un ingeniero senior explica la filosofía de pruebas del equipo en un 1:1, el nuevo empleado asiente, y tres semanas después la mitad se ha evaporado bajo la presión de los plazos, porque los hábitos formados bajo presión recurren a lo más rápido. Con las habilidades de proyecto, la disciplina no es un recuerdo que el nuevo empleado tenga que mantener. Es infraestructura, aplicada en su primer PR tanto como en el centésimo.

También cierra la brecha entre los niveles de antigüedad. La sesión de un desarrollador junior ejecutando la misma habilidad de depuración que la de un ingeniero de plantilla produce una salida con un nivel de calidad mucho más cercano de lo que ambos alcanzarían sin ayuda, porque gran parte de lo que separa una buena sesión de depuración de una mala es el procedimiento, no la experiencia.

Si aún no ha configurado el resto de la capa de Claude Code, vale la pena hacerlo antes o junto con esto. Nuestra guía de configuración cubre las capas de CLAUDE.md y permisos sobre las que se asientan las habilidades de proyecto.

Cómo saber si realmente está funcionando

Resista la tentación de inventar un dashboard para esto. La señal que desea ya fluye a través de las herramientas que tiene.

• Observe el volumen de comentarios en las revisiones de PR y, lo que es más importante, el tipo de comentario. Si los revisores comienzan a dejar menos comentarios como "¿probaste esto?" y "esto no maneja el caso nulo" y más comentarios sobre las compensaciones de diseño reales, las habilidades de revisión y TDD están haciendo su trabajo. Si el recuento de comentarios disminuye pero los comentarios restantes siguen detectando errores de corrección que la habilidad debería haber detectado, la habilidad aún no está bien ajustada, no el equipo.
• Observe la tasa de regresión. Una habilidad de depuración que impone la disciplina de hipótesis-verificación debería significar menos errores "corregidos" que reaparecen una semana después, ya que las soluciones por ensayo y error son exactamente el tipo que regresan. Esta es una señal más lenta, generalmente visible durante uno o dos meses en lugar de un sprint, pero es lo que más importa para un equipo que ya ha sufrido por errores "corregidos".
• Observe el tiempo hasta la primera aprobación en los PRs, tratando un punto de datos como una pista y un cambio sostenido a lo largo de varios sprints como una señal real. Y hable con la gente: si los desarrolladores sienten que la salida de Claude se ha vuelto más consistente, si un nuevo empleado dice que el codebase se sintió legible más rápido que en su trabajo anterior, vale más que cualquiera de lo anterior en el primer mes.

Implementación de cuatro semanas para un equipo de diez personas

• Semana 1. Elija un repo, no todos, y una habilidad; la lista de verificación de revisión suele ser la más fácil de vender porque los revisores ven el beneficio inmediatamente. Añádala a .claude/skills/ a través de un PR normal. Consiga dos o tres voluntarios para que la usen en sus próximas revisiones e informen en un hilo corto, no en una reunión.
• Semana 2. Añada la habilidad TDD al mismo repo. Esta es la que encuentra más resistencia, ya que cambia cómo la gente escribe código en lugar de cómo lo revisa. Espere fricción y trátela como datos. Mantenga la habilidad de depuración fuera por ahora, y recopile quejas específicas ("se activa en tareas donde no quiero que lo haga") para arreglar la descripción de la habilidad antes de intentar arreglar el comportamiento de las personas.
• Semana 3. Añada la habilidad de depuración. Para ahora el equipo ya tiene una idea de cómo se comportan las habilidades de proyecto, por lo que esta adición debería ir más rápido. Haga una retro corta sobre los datos de las dos semanas: ¿están cambiando los comentarios de revisión, alguien está evitando las habilidades en silencio, por qué? Ajuste las descripciones de los disparadores si una habilidad se activa con demasiada frecuencia o no lo suficiente.
• Semana 4. Implemente las mismas tres habilidades en el resto de los repos del equipo. Escriba una nota corta en el README de cada repo que diga qué hay en .claude/skills/ y por qué, para que el próximo nuevo empleado no tenga que preguntar. Establezca el proceso de aprobación de la sección anterior como una regla permanente, ya que la verdadera prueba de gobernanza es lo que sucede con la cuarta habilidad que alguien propone, no con las tres primeras.

Cuatro semanas, tres habilidades, un repo escalado al resto de la organización. Resista comprimir esto; la fricción en la semana 2 es información que querrá antes de ejecutar cinco habilidades en diez repos.

La opción de plugin para organizaciones con múltiples repos

Las habilidades de proyecto resuelven la estandarización dentro de un repo, pero la mayoría de las organizaciones de ingeniería no son un solo repo. Si sus diez desarrolladores trabajan en quince servicios, copiar .claude/skills/ en cada uno y mantenerlos sincronizados manualmente se convierte en su propio trabajo de mantenimiento, del tipo que deja de ocurrir silenciosamente después del segundo trimestre.

Los plugins de Claude Code resuelven esa capa. Un plugin empaqueta un conjunto de habilidades, además de comandos y otra configuración, en una unidad instalable que no está vinculada al historial de git de un solo repo. En lugar de quince copias de las mismas tres habilidades que se desvían de forma independiente, la organización mantiene un plugin, versionado una vez, y cada repo lo instala. Una actualización de la habilidad de depuración se propaga entonces a todos los lugares donde el plugin está instalado, en lugar de requerir quince PRs separados.

Esto es un paso adelante en complejidad operativa, y no vale la pena tomarlo hasta que haya sentido el dolor de mantener múltiples repos sincronizados. Para un equipo de diez personas en uno o dos repos, el enfoque de habilidades de proyecto en este artículo es el punto de parada correcto. Para una organización que ejecuta los mismos estándares en muchas codebases, nuestra guía de plugins cubre la mecánica de empaquetado y distribución.

El modo de fallo: exigir veinte habilidades el primer día

La forma más común en que esto sale mal no es técnica, es un error de implementación. Un líder técnico lee sobre las habilidades de proyecto, se entusiasma y confirma veinte de ellas en una tarde: revisión, TDD, depuración, más una docena más para convenciones de logging, formato de mensaje de commit, diseño de API, accesibilidad y cualquier otra cosa que pareciera razonable a las 4pm de un jueves.

Dos cosas fallan. Primero, las descripciones superpuestas comienzan a activarse en tareas incorrectas, o entre sí, porque nadie verificó si la frase de activación de la habilidad tres choca con la de la habilidad once; estos conflictos son uno de los defectos más comunes que vemos en las pruebas, y empeoran a medida que aumenta el recuento. Segundo, y más perjudicial, el equipo nunca desarrolla confianza en las habilidades, porque una semana bajo veinte nuevas reglas se siente como un ejercicio de cumplimiento, y la gente comienza a trabajar eludiendo a Claude en lugar de con él.

Tres habilidades, adoptadas durante un mes, con retroalimentación real que da forma a cada una antes de que llegue la siguiente, genera una confianza que veinte habilidades implementadas a la vez nunca lograrán. Si su equipo aún está decidiendo por dónde empezar, nuestras clasificaciones de habilidades de codificación están ordenadas por puntuación probada, lo cual es un filtro razonable para elegir la siguiente después de sus tres primeras.

Preguntas Frecuentes

¿Las habilidades a nivel de proyecto funcionan igual que las personales?

Sí, el formato es idéntico. La única diferencia es la ubicación: .claude/skills/ en el repo en lugar de ~/.claude/skills/ en un ordenador portátil. Claude Code carga ambos de la misma manera. Si una habilidad existe en ambos lugares con el mismo nombre, la versión del proyecto generalmente tiene precedencia para ese repo, que es exactamente el comportamiento que desea para un estándar de equipo.

¿Esto ralentizará a Claude para todos en el equipo?

Apenas. Cada habilidad instalada cuesta aproximadamente 100 tokens de metadatos siempre cargados. Tres habilidades de proyecto en un equipo añaden menos contexto permanente de lo que normalmente lo hace un solo servidor MCP conectado. El costo real de equivocarse en esto no es la velocidad, es la confusión de activación por descripciones superpuestas, por lo que el plan de implementación anterior añade habilidades una a la vez.

¿Qué pasa si un desarrollador no está de acuerdo con el estándar de TDD o depuración del equipo?

Esa es una conversación que debe tenerse antes de que la habilidad se fusione, en la revisión del PR, el mismo lugar donde la tendría sobre una regla de linter. Una vez que está en el repo, se aplica a todos, pero "todos" debería significar que todos tuvieron la oportunidad de opinar durante la revisión, no que una persona decidió unilateralmente y lo subió a main.

¿Deberíamos exigir las habilidades o dejarlas opcionales?

Las habilidades de proyecto se cargan automáticamente para cualquiera que tenga el repo, por lo que no hay un paso de "requerir" separado, simplemente son parte del codebase. Lo que puede hacer opcional es la contribución: no todos los desarrolladores necesitan proponer nuevas habilidades, pero la sesión de cada desarrollador ejecuta las que se fusionan. Trate la decisión de fusión como la puerta de entrada.

¿En qué se diferencia esto de simplemente escribir un CLAUDE.md largo?

Comportamiento de carga. CLAUDE.md se carga en cada sesión independientemente de lo que el desarrollador esté haciendo ese día, lo que lo hace adecuado para hechos que siempre se aplican: comandos de build, arquitectura, convenciones de nomenclatura. Una habilidad se carga solo cuando una tarea coincide con su descripción, lo que la hace adecuada para un procedimiento que necesita a veces: cómo el equipo depura, cómo el equipo revisa. Si su CLAUDE.md tiene una sección larga que describe cómo escribir pruebas o estructurar una revisión, esa sección quiere convertirse en una habilidad en su lugar.