Claude Code en equipo de desarrollo 2026: workflows compartidos, CLAUDE.md colectivo y cómo no pisarse (guía para tech leads)

Guía escrita para quien lidera el equipo, no para quien ya lo usa solo.

El problema real: cinco devs, cinco configuraciones

El primer mes de Claude Code en un equipo suele ir así: cada dev configura sus permisos, sus comandos y sus estilos; el código generado por uno no sigue las convenciones del otro; las PRs empiezan a tener discusiones de estilo que antes no existían; y el tech lead concluye que "la IA rompe la consistencia". El problema no es la herramienta: es que el conocimiento implícito del equipo seguía implícito, y ahora un colaborador muy rápido lo ignora.

La solución es institucionalizarlo:

El CLAUDE.md colectivo: la convención en código

El CLAUDE.md en la raíz del repositorio (commiteado, versionado en git) es la definición compartida de "cómo trabajamos aquí". Estructura que funciona:

1# Proyecto: [nombre] — monorepo Next.js + FastAPI
2 
3## Convenciones que el equipo ya decidió
4- Commits: conventional commits en español; el cuerpo explica el "por qué"
5- TypeScript estricto; prohibido `any` (usar `unknown` + guardas)
6- Tests: pytest backend (cobertura de rutas nuevas obligatoria), vitest frontend
7- Nunca tocar: `lib/legacy/`, migraciones ya aplicadas
8 
9## Comandos
10- `pnpm dev` · `pnpm test` · `docker compose up`
11 
12## Antipatrones del proyecto (los que ya nos quemaron)
13- No uses `useEffect` para fetching: server components + actions
14- No inventes endpoints: consulta `docs/api.md` primero

Reglas de mantenimiento: se modifica por PR (como el código, porque es código del proceso), se revisa cada sprint, y cada entrada debe ser una decisión real del equipo — no consejos genéricos que Claude ya sabe.

Permisos y seguridad: la parte que un solo dev no ve

En equipo, los permisos dejan de ser preferencia y pasan a ser política:

• Archivo de settings versionado (.claude/settings.json): comandos permitidos, dominios permitidos para MCP. El dev individual decide su configuración local; el repo define el máximo común.
• Secretos fuera: los MCP que tocan bases de datos de staging van en la config local de cada dev, nunca en el repo.
• Entornos de prueba obligatorios: la política "Claude no ejecuta contra producción" se escribe en el CLAUDE.md y se refuerza con permisos.

Subagentes y MCP compartidos: el siguiente nivel

Cuando el equipo ya vive en Claude Code:

• Subagentes por rol (code-reviewer, migration-writer, test-writer) definidos en el repo: cualquiera los usa y mejoran por PR, igual que el CLAUDE.md.
• MCP comunes al stack del proyecto (servidor de issues, docs internas): documentados en el repo, instalables con un comando.
• Un agente de revisión en la PR: correr Claude como revisor primero reduce el tiempo del humano a lo que de verdad es discusión de arquitectura.

Qué cambia en el workflow de PRs

Con Claude Code bien configurado, el ciclo de PR se parece a:

1. Spec corta en la issue (3-5 líneas): qué, para qué, qué no.
2. Claude implementa con contexto completo (CLAUDE.md + docs del repo): el dev revisa la dirección, no cada línea.
3. Tests escritos primero o con el agente: la cobertura se verifica en CI, no en la confianza.
4. Revisión humana de arquitectura y edge cases: el lead revisa decisiones, no estilo (eso lo decidieron los archivos de convención).

La ganancia medida en equipos que lo hacen bien no es "escribir más código": es menos tiempo entre idea y PR revisada, con la revisión humana concentrada en lo que importa.

Si el equipo no da el salto solo

El patrón que más vemos fallar: la herramienta se instala, cada dev improvisa, y a los dos meses el equipo vuelve a programar a mano con la sensación de "no aporta". Lo que falta no es la herramienta, es la sesión de adopción: convenciones escritas, permisos decididos y workflows acordados. Ese onboarding de equipo es justamente lo que hacen los programas de formación in-company con Claude Code que imparte Javier Santos Criado, y hay una comparativa de proveedores en España en esta misma web si prefieres otra vía.

Preguntas frecuentes

¿Debería el CLAUDE.md ir commitado al repositorio?

Sí, siempre: es la fuente de verdad de las convenciones y debe revisarse como código (por PR, con historial). La configuración con secretos y preferencias personales sí va en archivos locales fuera del repo.

¿Cómo evito que cada dev configure Claude Code de forma distinta?

El repo define el máximo común (settings versionado con permisos y CLAUDE.md colectivo); cada dev puede añadir sus preferencias locales por encima, pero no relajar las del proyecto. La revisión del CLAUDE.md entra en la rutina del sprint.

¿Claude Code sustituye la revisión de código entre humanos?

No: mueve la revisión humana hacia arriba (arquitectura, casos borde, decisiones) y absorbe la capa de estilo y errores mecánicos. En equipos maduros, el revisor humano revisa menos líneas y decide más.

¿Cuánto tarda un equipo en adoptar Claude Code con estas prácticas?

Una semana para la configuración base (CLAUDE.md, permisos, subagentes) y un mes de calibrado hasta que las convenciones reflejan el flujo real. El error opuesto — instalar sin convenciones — suele terminar en abandono al segundo mes.