Lo que descubres cuando un equipo documenta cómo usa Claude Code sin coordinarse
Hace unas semanas pedí a cada persona del equipo de ingeniería de Orbitant que documentara de forma individual sus aprendizajes con Claude Code: qué funcionaba, qué no, qué configuraciones habían adoptado, qué habían descubierto por cuenta propia. Sin reunión previa y sin compartir respuestas entre ellas antes de responder: solo sus notas y sus semanas de uso real en proyectos de producción.
El resultado de compilar ese ejercicio dice más sobre cómo funciona Claude Code en equipos de ingeniería que cualquier guía de buenas prácticas.
Porque lo primero que me llamó la atención no fue ningún consejo concreto. Fue la convergencia. El equipo había llegado, de forma independiente, a las mismas tres o cuatro conclusiones.
Cuando perfiles muy distintos llegan al mismo sitio sin coordinarse, probablemente no estamos hablando de preferencias personales. Estamos hablando de propiedades reales de la herramienta.
El mayor beneficio no fue entregar más rápido: fue el tiempo que liberó para hacer un trabajo diferente.
La convergencia como diagnóstico
El ejercicio estaba diseñado así a propósito. Cuando preguntas a un equipo en una reunión qué ha aprendido, la dinámica de grupo contamina las respuestas: quien habla primero marca el tono, las opiniones minoritarias se autocensuran y el resultado tiende a parecerse más a un consenso social que a un diagnóstico real. Las respuestas individuales y escritas producen algo mucho más limpio.
El formulario pedía a cada persona documentar tres aspectos de forma separada:
- Sus principales aprendizajes y prácticas adoptadas
- Los patrones que evitaba activamente y por qué
- Su configuración de herramientas y descubrimientos de stack
Al compilar las respuestas, emergieron tres niveles de convergencia:
- Convergencia unánime: prácticas que prácticamente todo el equipo mencionó de forma espontánea, sin estar sugeridas en el formulario.
- Convergencia fuerte: patrones con consistencia notable a lo largo de distintos proyectos y perfiles.
- Variables por contexto: decisiones que dependían del stack o del tipo de proyecto, sin patrón claro.
Que perfiles tan distintos lleguen al mismo sitio sin coordinarse no es un dato menor. En un equipo con trayectorias muy diversas —desde perfiles junior hasta arquitectos con años de experiencia en sistemas complejos— que algo genere ese nivel de acuerdo espontáneo es una señal fuerte. No significa que sea la única forma de trabajar bien con Claude Code. Significa que estas prácticas no son atajos opcionales: son el camino de menor resistencia que la herramienta va marcando a medida que se usa con intensidad real.
Y eso tiene implicaciones directas. El error más frecuente es tratar la adopción de Claude Code como una cuestión de productividad individual: cada persona encuentra su flujo, y ya está. Pero si la herramienta recompensa ciertos patrones con independencia del perfil técnico de quien la usa, estamos ante una cuestión de diseño de flujo de trabajo colectivo. Y eso se gestiona de otra manera.
Sigue nuestro viaje construyendo agentes IA desde dentro
Claude Code en equipos de ingeniería: los tres principios que emergieron
Tres prácticas alcanzaron convergencia unánime o fuerte. Las explico en el orden en que impactan:
1. Planificar antes de ejecutar, siempre
La frase que más se repitió fue una variación de la misma idea: «escribe un plan antes de lanzar el prompt«. El equipo descubrió, por caminos distintos, que estructurar el problema antes de delegarlo mejora los resultados de forma no lineal.
En la práctica: usar el modo de planificación para cualquier tarea no trivial, definir el alcance y las restricciones antes de empezar, y resistir la tentación de probar sin dirección clara. El coste de planificar es bajo y predecible; el coste de iterar sobre un resultado mal orientado, alto y acumulativo. Quien salta este paso ahorra cinco minutos y pierde treinta.
2. CLAUDE.md como fuente de verdad del proyecto
El equipo trata el archivo CLAUDE.md no como documentación opcional sino como el mecanismo principal de persistencia de contexto entre sesiones. Ahí viven las convenciones de naming, las restricciones arquitectónicas, el vocabulario de dominio y cualquier patrón que debe respetarse de forma consistente.
La escala a la que esto llega cuando se toma en serio: hay miembros del equipo con más de 15 archivos CLAUDE.md distribuidos en capas —personal, organización, repositorio, dominio— en proyectos de infraestructura. Es un sistema de conocimiento compartido que crece con el proyecto. Cada convención que no está documentada ahí es una corrección que se repite manualmente, sesión tras sesión.
3. Delegar a nivel de feature, no de línea
El tercer principio es el más difícil de interiorizar porque va en contra del hábito más extendido: usar Claude Code como autocompletado sofisticado. Lo que el equipo ha aprendido es que eso deja la mayor parte del valor sobre la mesa.
El cambio es de granularidad: en lugar de pedir que complete una función, delegar la feature completa —implementación, tests, documentación— y revisar cada diff con atención. Esto produce cambios más pequeños y acotados, más fáciles de revisar con el rigor que la calidad del código requiere. La calidad no está en el output inicial, sino en ese momento de revisión.
Los diffs más pequeños son mucho más fáciles de revisar en profundidad, y ahí es donde viene la calidad real.
Lo que la convergencia revela sobre la herramienta y cómo adoptarla en equipo
La convergencia tiene dos lecturas. Una es que el equipo está encaminado hacia crear sus propias buenas prácticas. La otra es que Claude Code tiene una forma de trabajar que recompensa ciertos patrones de forma consistente, y que esos patrones emergen solos cuando se usa la herramienta con suficiente intensidad.
Si esto segundo es cierto, cambia cómo deberíamos pensar en la adopción. Trabajar con Claude Code en equipos de ingeniería no es un proceso de descubrimiento individual que cada persona tiene que recorrer en solitario. Es un proceso que se puede acelerar:
- Explicitar los principios desde el primer día acorta el tiempo hasta resultados de calidad.
- Compartir la base —mismos
CLAUDE.md, mismas skills, mismo vocabulario para hablar de lo que funciona— genera un punto de partida colectivo que reduce la fricción. - Iterar sobre artefactos compartidos, no sobre configuraciones individuales, convierte el aprendizaje personal en una ventaja de equipo.
Un perfil técnico usando Claude Code bien puede multiplicar su productividad de forma notable. Eso está documentado. Pero un equipo completo usándolo de forma coordinada genera un tipo diferente de ventaja: el conocimiento de cada persona mejora el entorno de todas las demás. Cada skill construida, cada convención documentada, cada aprendizaje explicitado amplifica el resultado colectivo. El valor no crece linealmente. Se compone.
En Orbitant llevamos varios meses construyendo ese sistema de forma deliberada: skills compartidas, CLAUDE.md en capas, y un proceso de incorporación que arranca con los principios, no con la herramienta. En el siguiente artículo de esta serie entro en la arquitectura concreta de ese sistema: qué skills han generado más retorno, cómo están estructurados los CLAUDE.md del equipo, y los problemas que todavía no tienen solución clara.
