> ## Content Index > Fetch the complete content index at: https://jonathancanales.com/llms.txt > Use this file to discover other available public pages before exploring further. # Claude Code: trabajo en equipo y buenas prácticas - URL: https://jonathancanales.com/claude-code-trabajo-en-equipo-buenas-practicas/ - Published: 2026-08-14T14:00:00.000Z - Updated: 2026-10-25T21:10:31.000Z - Description: Memoria compartida, permisos versionados y revisión humana: la base para que Claude Code rinda en equipo. - Author: Jonathan Canales - Tags: Tecnología y herramientas En agosto de 2026, Claude Code ha pasado de ser la herramienta personal de cada programador a una pieza compartida del equipo: el mismo agente lee el repositorio, propone cambios y participa en la revisión de código de varias personas a la vez. Ese salto cambia la conversación. Ya alcanza con saber usar el agente; ahora el reto es que todo el equipo lo use de forma coherente, con las mismas reglas, los mismos permisos y el mismo criterio de revisión. Los equipos que resuelven esa parte convierten al agente en un multiplicador estable, y los que la improvisan terminan con cinco configuraciones distintas y resultados impredecibles. Esta guía reúne las prácticas que separan un escenario del otro. ![Doodle de una libreta abierta con una pluma fuente, la plumilla naranja](https://jonathancanales.com/content/images/2026/10/pair18-doodle1.png) ## El contrato del proyecto: CLAUDE.md Toda colaboración seria con Claude Code empieza en el archivo CLAUDE.md, la memoria del proyecto que el agente lee al inicio de cada sesión. En un equipo, ese archivo se convierte en el contrato entre las personas y el agente: ahí viven los comandos de compilación y pruebas, las convenciones de estilo, la estructura del repositorio y las reglas que el agente debe respetar siempre. La documentación oficial de memoria describe cómo Claude Code carga ese archivo y cómo se jerarquizan sus versiones de proyecto, de usuario y locales. Tres prácticas hacen que CLAUDE.md rinda en equipo. La primera es versionarlo en el repositorio como cualquier otro archivo crítico: cada cambio pasa por revisión, y la historia del archivo explica por qué cada regla existe. La segunda es mantenerlo corto y vigente: una memoria de cincuenta líneas precisas supera a una de trescientas que mezcla lo esencial con lo histórico, y una revisión mensual del archivo cabe en la retrospectiva habitual. La tercera es escribirlo en imperativo y con ejemplos: "las pruebas se ejecutan con make test" guía al agente mejor que una descripción vaga del sistema de pruebas. El archivo personal de cada miembro cubre lo demás: preferencias propias, alias y atajos individuales que pertenecen a cada flujo de trabajo y viajan en la configuración de usuario, separados del contrato común. Esa separación entre lo compartido y lo personal es la primera decisión de arquitectura del equipo. ## Permisos y configuración compartida El sistema de ajustes de Claude Code se reparte en varios niveles con precedencia clara: ajustes del proyecto versionados, ajustes locales del proyecto y ajustes de usuario. La documentación de settings detalla esa jerarquía, y aprovecharla bien evita la mitad de las fricciones de equipo. El nivel versionado del proyecto es el lugar correcto para la lista de comandos permitidos: las operaciones que el agente puede ejecutar directamente, como correr pruebas, compilar o formatear. Cuando esa lista vive en el repositorio, cada miembro trabaja con los mismos límites y el agente se comporta igual en todas las máquinas. El nivel local y el de usuario quedan para lo individual: rutas propias, herramientas personales, preferencias de modelo. La regla práctica es sencilla: si un permiso afecta al resultado que llega al repositorio, pertenece a la configuración compartida; si solo afecta a la comodidad de una persona, pertenece a su configuración personal. Revisar esa frontera al incorporar a alguien nuevo ahorra días de sorpresas. ## Flujo de revisión con agentes El patrón sano en equipo es el mismo que con cualquier colaborador: el agente propone, una persona revisa, y la rama se integra después de pasar las pruebas. En la práctica eso significa que Claude Code trabaja sobre ramas, abre cambios acotados y documentados, y la revisión humana mira el diff completo antes de aprobar. Los mensajes de commit siguen la convención del equipo, porque el agente los redacta siguiendo las instrucciones de CLAUDE.md. Dos hábitos refuerzan ese flujo. El primero es pedir al agente un plan antes de ejecutar: una descripción corta de qué archivos tocará y por qué, que la persona revisa antes de autorizar la escritura. El segundo es mantener las tareas acotadas: un agente que modifica tres archivos con un objetivo claro produce revisiones de diez minutos, mientras una petición amplia produce diffs que nadie revisa con cuidado. La calidad de la revisión humana es el límite real del sistema, y todo lo que la protege multiplica el valor del agente. ## Automatización con GitHub Actions La integración de Claude Code con GitHub Actions lleva al agente al lugar donde el equipo ya conversa: las incidencias y las solicitudes de cambio. Con ella, mencionar al agente en un comentario le asigna una tarea, y el flujo de trabajo configurado en el repositorio ejecuta al agente con los permisos y el contexto definidos por el equipo. La documentación oficial de GitHub Actions describe la instalación y las opciones de ese flujo. En equipo, esa automatización rinde más cuando arranca con tareas repetitivas, bien delimitadas y de alto volumen: clasificar incidencias, proponer primeras versiones de cambios pequeños, resumir solicitudes extensas para quien revisa. Cada automatización nueva entra con un período de observación, y las que demuestran valor se quedan. Las solicitudes de cambio abiertas por el agente pasan por la misma revisión humana que cualquier otra, siempre, porque la confianza del equipo se construye sobre diffs verificados. ![Doodle de dos tazas de café con un portapapeles compartido, una casilla marcada en naranja](https://jonathancanales.com/content/images/2026/10/pair18-doodle2.png) ## Convenciones compartidas: AGENTS.md y skills CLAUDE.md convive con AGENTS.md, la convención abierta que varios agentes leen para entender un proyecto. Equipos que usan más de una herramienta suelen mantener AGENTS.md como la fuente común de instrucciones y dejan en CLAUDE.md lo específico de Claude Code, con referencias cruzadas para evitar duplicados que se desactualizan. Las skills compartidas llevan la convención un paso más allá: empaquetan procedimientos del equipo, como el formato de un reporte o los pasos de un despliegue, en archivos que cualquier miembro invoca igual. La guía de [qué son y cómo crear una skill](https://jonathancanales.com/claude-skills-que-son-y-como-crear) cubre la mecánica, y la comparación entre [skills y prompts repetidos](https://jonathancanales.com/claude-skills-vs-prompts-repetidos) explica cuándo conviene convertir una instrucción frecuente en skill. Para el equipo, el criterio es el mismo que con cualquier código compartido: una skill versionada y revisada supera a diez prompts guardados en notas personales. ## Hábitos individuales que escalan al equipo Las buenas prácticas personales, descritas en la guía de [comandos y atajos](https://jonathancanales.com/claude-code-comandos-y-atajos-mas-usados) y en la documentación de Anthropic sobre mejores prácticas, se vuelven prácticas de equipo cuando se escriben y se comparten. Trabajar en tareas pequeñas, leer cada diff, dar contexto completo al agente y corregirlo temprano son hábitos que un equipo adopta como norma: se mencionan en la incorporación de miembros nuevos, se ejemplifican en las revisiones y se refuerzan en la retrospectiva. Los plugins y extensiones completan el ecosistema compartido: un equipo que estandariza sus herramientas de revisión y sus integraciones trabaja con un entorno homogéneo, y la guía de [plugins y extensiones](https://jonathancanales.com/claude-code-plugins-extensiones) ayuda a elegirlos. La regla general se mantiene: lo que afecta al resultado compartido se decide en conjunto y se versiona. ## Incorporar a alguien nuevo al flujo La prueba de fuego de una configuración de equipo es la incorporación de un miembro nuevo. Con CLAUDE.md versionado y los permisos en el repositorio, esa incorporación se reduce a clonar, leer el contrato del proyecto y ejecutar la primera tarea acotada con revisión cercana. La primera semana se dedica a observar: la persona nueva lee diffs producidos por el agente, compara sus expectativas con el resultado y aprende las convenciones del equipo en el terreno real. La segunda semana invierte los papeles: ella pide las tareas y alguien con experiencia revisa sus instrucciones antes de ejecutarlas, corrigiendo el nivel de detalle y el tamaño de cada petición. Ese aprendizaje acompañado cuesta dos semanas y evita meses de hábitos divergentes. Los equipos que lo documentan en la guía de incorporación descubren además un beneficio lateral: explicar el flujo a otra persona es la mejor auditoría del propio sistema, porque cada regla que cuesta explicar señala un punto por simplificar. ## Medición y mejora continua Un equipo que adopta un agente necesita saber si la adopción rinde. Las métricas útiles son las del flujo habitual: tiempo de ciclo de las solicitudes de cambio, porcentaje de revisiones que piden correcciones al agente, tareas completadas por semana con y con asistencia. El método de comparación con proyecto propio, descrito en [cómo probar una herramienta con tu propio proyecto](https://jonathancanales.com/mejor-ia-para-programar-probar-herramienta-tu-proyecto), funciona igual a escala de equipo: mismas tareas, mismas métricas, decisión con evidencia. La mejora continua cierra el círculo: cada mes el equipo revisa qué reglas de CLAUDE.md se usaron, qué permisos sobran y cuáles faltan, qué skills se invocaron y cuáles quedaron olvidadas. El contrato con el agente evoluciona con el proyecto, y esa evolución versionada es, al final, la práctica que sostiene a todas las demás. Vale subrayar lo que hace posible todo lo anterior: la escritura. Un equipo que adopta Claude Code descubre pronto que sus activos más valiosos son textos cortos y cuidados, la memoria del proyecto, la lista de permisos, las convenciones y las skills. Esos textos se escriben una vez, se revisan como código y rinden en cada sesión del agente, para cada miembro, todos los días. ## Un cierre práctico Claude Code en equipo funciona cuando tres cosas están escritas y versionadas: la memoria del proyecto, los permisos compartidos y las convenciones de revisión. Con ese andamiaje, el agente se comporta igual para todos, cada cambio pasa por ojos humanos y la automatización crece sobre tareas probadas. El resultado es un equipo donde la IA suma velocidad y las personas conservan el criterio, combinación que ninguna herramienta entrega por defecto y que cualquier equipo puede construir en unas semanas de práctica deliberada. ## Fuentes - [Anthropic: mejores prácticas para Claude Code](https://www.anthropic.com/engineering/claude-code-best-practices?ref=jonathancanales.com) - [Documentación de memoria de Claude Code](https://code.claude.com/docs/en/memory?ref=jonathancanales.com) - [Documentación de ajustes de Claude Code](https://code.claude.com/docs/en/settings?ref=jonathancanales.com) - [Claude Code y GitHub Actions](https://code.claude.com/docs/en/github-actions?ref=jonathancanales.com) - [AGENTS.md, convención de instrucciones para agentes](https://agents.md/?ref=jonathancanales.com)