Claude Code en equipo: configuración multi-developer

Por qué configurar Claude Code para equipo

Sin configuración compartida, cada developer usa Claude Code de forma diferente: diferentes convenciones de commits, diferentes estilos de código, diferentes reglas de seguridad. El resultado es inconsistencia y bugs.

Con una configuración de equipo, Claude Code se convierte en un miembro más del equipo que sigue las mismas reglas que todos. Lee la guía de Claude Code si es tu primer contacto.

El beneficio no es solo consistencia. Cuando un developer nuevo se une al equipo, no necesita leer un wiki de 50 páginas para entender cómo funciona el proyecto. Claude Code ya lo sabe, porque el CLAUDE.md se lo dice. El onboarding pasa de días a horas.

Los 3 niveles de configuración

Claude Code tiene tres niveles de configuración, de más general a más específico:

1. Global (~/.claude/): configuración personal de cada developer. Preferencias de estilo, API keys, herramientas favoritas. No se comparte. Cada miembro tiene la suya.

2. Proyecto (.claude/): configuración compartida del proyecto. Se commitea a git. Todos los miembros del equipo la comparten. Aquí van las reglas del juego.

3. Sesión: configuración temporal de la sesión actual. No persiste. Para override puntual.

La prioridad es: sesión > proyecto > global. Si el proyecto dice "usa tabs" y tu config global dice "usa spaces", gana el proyecto.

CLAUDE.md compartido: mejores prácticas

El archivo .claude/CLAUDE.md es la pieza central de la configuración de equipo. Debe estar en el repo y commiteado. Es el "briefing" que Claude Code lee al inicio de cada sesión.

# .claude/CLAUDE.md - Ejemplo para equipo

## Proyecto
Aplicación SaaS B2B. Stack: Next.js 14, FastAPI, PostgreSQL.
Repo: monorepo con /frontend, /backend, /shared.

## Convenciones de código
- TypeScript strict mode obligatorio
- Python: black + ruff para formateo y linting
- Commits: Conventional Commits (feat/fix/chore/docs)
- PRs: siempre contra develop, nunca contra main
- Tests: mínimo 80% coverage en nuevo código

## Seguridad
- NUNCA hardcodear secretos. Usar variables de entorno
- NUNCA commitear .env, credentials.json, *.pem
- Sanitizar SIEMPRE input de usuario (SQL injection, XSS)

## Arquitectura
- Backend: Clean Architecture (routes → services → repositories)
- Frontend: App Router, Server Components por defecto
- API: REST, versionado /api/v1/, paginación cursor-based

## Equipo
- Lead: María (backend) - decisiones de arquitectura
- Dev: Pedro (frontend) - decisiones de UX
- Dev: Ana (fullstack) - decisiones de infra

Un buen CLAUDE.md de equipo sigue estas reglas:

• Conciso pero completo: no más de 200-300 líneas. Si necesitas más, divide en archivos por subdirectorio.
• Prioriza las reglas que rompen cosas: seguridad, permisos, convenciones de git van primero.
• Incluye el "por qué": no solo "usa Conventional Commits", sino "para que el changelog se genere automáticamente".
• Actualízalo con cada retro: si el equipo descubre un patrón nuevo o un anti-pattern, añádelo al CLAUDE.md en el mismo PR.

Para más detalle sobre cómo escribir un CLAUDE.md efectivo, lee nuestra guía de CLAUDE.md.

Settings y permisos

El archivo .claude/settings.json configura permisos y comportamiento. En equipo, es crucial para estandarizar lo que Claude Code puede y no puede hacer.

// .claude/settings.json
{
 "permissions": {
 "allow": [
 "Read(**)",
 "Glob(**)",
 "Grep(**)",
 "Bash(npm run lint)",
 "Bash(npm run test)",
 "Bash(npm run build)"
 ],
 "deny": [
 "Bash(rm -rf *)",
 "Bash(git push --force*)",
 "Bash(git reset --hard*)",
 "Bash(docker*)"
 ]
 },
 "hooks": {
 "PreCommit": [{
 "command": "npm run lint && npm run test",
 "description": "Lint y tests antes de commit"
 }]
 }
}

Para entender todos los settings disponibles, revisa la guía de settings de Claude Code.

Comandos compartidos

Los comandos personalizados (.claude/commands/) son workflows reutilizables. En equipo, estandarizan las tareas comunes:

# .claude/commands/review.md
Revisa el código cambiado en esta rama comparado con develop.
Para cada archivo modificado:
1. Verifica que sigue las convenciones del CLAUDE.md
2. Busca bugs potenciales y edge cases
3. Verifica que hay tests para el nuevo código
4. Comprueba que no hay secretos hardcodeados
Genera un informe con findings clasificados por severidad.

# .claude/commands/deploy-check.md
Antes de mergear a develop, verifica:
1. Todos los tests pasan (npm run test)
2. Lint limpio (npm run lint)
3. Build sin errores (npm run build)
4. No hay TODO/FIXME sin issue asociado
5. Las migraciones de DB son reversibles
Genera un checklist con estado de cada punto.

Cualquier miembro del equipo ejecuta estos comandos con /review o /deploy-check. Mismo proceso, misma calidad, independientemente de quién lo ejecute. Más sobre comandos en nuestra guía de comandos de Claude Code.

Guía de onboarding para el equipo

Introducir Claude Code en un equipo que nunca lo ha usado requiere un plan. No puedes enviar un email con "instálalo y úsalo" y esperar que funcione. Aquí tienes un proceso probado en equipos de 3 a 15 personas:

Semana 1: piloto con 1-2 early adopters

• Elige a los developers más curiosos del equipo (no necesariamente los más senior).
• Instalan Claude Code, configuran el CLAUDE.md básico y lo usan durante una semana normal de trabajo.
• Documentan: qué funciona, qué no, qué reglas faltan en el CLAUDE.md.

Semana 2: ajuste de configuración

• Los early adopters ajustan el CLAUDE.md con lo aprendido.
• Crean 3-5 comandos compartidos para las tareas más comunes.
• Configuran el settings.json con permisos y deny lists.
• Commitean todo al repo.

Semana 3: rollout al equipo completo

• Sesión de 30 minutos mostrando los workflows más útiles (no un tutorial completo).
• Cada developer instala Claude Code y ejecuta un comando compartido para verificar que funciona.
• Canal de Slack/Teams dedicado para dudas y tips (no un canal genérico).

Semana 4+: iteración continua

• Retro quincenal de 15 minutos: "qué añadimos al CLAUDE.md, qué quitamos, qué comandos nuevos necesitamos".
• Los PRs que tocan el CLAUDE.md necesitan review, como cualquier otro código.

Modelos de permisos para equipos

No todos los miembros del equipo necesitan los mismos permisos. Claude Code permite configurar permisos a nivel de proyecto (compartido) y a nivel personal (individual). La estrategia correcta depende del tamaño del equipo y del nivel de confianza.

Modelo restrictivo (equipos grandes, 10+ personas):

// .claude/settings.json - Restrictivo
{
 "permissions": {
 "allow": [
 "Read(**)",
 "Glob(**)",
 "Grep(**)",
 "Bash(npm run lint)",
 "Bash(npm run test)"
 ],
 "deny": [
 "Bash(git *)",
 "Bash(rm *)",
 "Bash(docker *)",
 "Bash(npm install *)",
 "Bash(npx *)"
 ]
 }
}

Claude Code solo puede leer y ejecutar lint/tests. Cualquier otra acción requiere aprobación manual. Ideal para equipos con juniors o cuando trabajas con datos sensibles.

Modelo balanceado (equipos medianos, 3-10 personas):

// .claude/settings.json - Balanceado
{
 "permissions": {
 "allow": [
 "Read(**)",
 "Glob(**)",
 "Grep(**)",
 "Edit(**)",
 "Write(src/**)",
 "Write(tests/**)",
 "Bash(npm run *)",
 "Bash(git status)",
 "Bash(git diff *)",
 "Bash(git log *)"
 ],
 "deny": [
 "Bash(git push --force*)",
 "Bash(git reset --hard*)",
 "Bash(rm -rf *)",
 "Write(.env*)",
 "Write(*.pem)"
 ]
 }
}

Claude Code puede editar código y ejecutar scripts del proyecto, pero no puede hacer operaciones destructivas. El sweet spot para la mayoría de equipos.

Modelo permisivo (equipos pequeños, 2-3 seniors):

Sin deny list explícito. Cada developer confía en que Claude Code (y sus compañeros) no harán nada destructivo. Solo funciona cuando todos conocen la herramienta y el proyecto a fondo.

Workflows de code review con IA

El code review es donde Claude Code brilla en equipo. La idea no es reemplazar el review humano, sino complementarlo. Claude Code atrapa errores mecánicos para que el reviewer humano se centre en lógica de negocio y decisiones de diseño.

Flujo recomendado en 3 pasos:

1. Pre-review automático: antes de pedir review humano, el autor ejecuta /review y corrige los findings CRITICAL y HIGH.
2. Review humano enfocado: el reviewer sabe que los errores mecánicos ya se han revisado. Se enfoca en: "¿tiene sentido este enfoque?", "¿hay una forma más simple?", "¿esto escala?".
3. Post-review con Claude Code: si el reviewer pide cambios, el autor usa Claude Code para implementarlos con contexto del feedback recibido.

# .claude/commands/pr-review.md
Lee el diff completo de esta PR contra la rama base.
Analiza:
1. Consistencia con CLAUDE.md y convenciones del proyecto
2. Bugs potenciales (null checks, race conditions, edge cases)
3. Seguridad (inputs sin sanitizar, secretos, SQL injection)
4. Tests: ¿cubren el nuevo código? ¿faltan edge cases?
5. Performance: ¿hay queries N+1, loops innecesarios, memory leaks?

Formato de salida:
- CRITICAL: [archivo:linea] descripción + fix sugerido
- HIGH: [archivo:linea] descripción + fix sugerido
- MEDIUM: [archivo:linea] descripción
- SUGGESTION: [archivo:linea] mejora opcional

NO reportes: estilos (los cubre el linter), typos en comments.

Este comando crea un informe estructurado que el autor puede resolver antes de pedir el review humano. En la práctica, reduce el número de comentarios en PRs un 40-60% porque los errores obvios se corrigen antes de llegar al reviewer.

Estandarizar prompts en el equipo

Uno de los problemas más sutiles en equipos es la inconsistencia de prompts. Un developer pide "refactoriza esto" y otro pide "limpia este archivo, sigue SOLID y añade tests". Los resultados son completamente diferentes.

La solución: comandos compartidos como prompts estandarizados. En lugar de que cada persona escriba su prompt, el equipo acuerda los comandos y todos usan el mismo.

# .claude/commands/implement-feature.md
Para implementar la feature descrita:
1. Analiza los archivos relacionados (usa grep para encontrar código similar)
2. Sigue la arquitectura existente (no inventes nuevos patrones)
3. Crea tests ANTES del código (TDD)
4. Usa los tipos/interfaces existentes, no crees nuevos sin justificación
5. Documenta la API pública con JSDoc/docstrings
6. Ejecuta lint + tests al final

Si algo no está claro en los requisitos, pregunta ANTES de implementar.
NO asumas. NO inventes requisitos.

# .claude/commands/fix-bug.md
Para corregir el bug reportado:
1. Reproduce el bug mentalmente: ¿qué input causa el problema?
2. Encuentra la causa raíz (no el síntoma)
3. Escribe un test que falla con el bug actual
4. Implementa el fix mínimo necesario
5. Verifica que el test ahora pasa
6. Verifica que no se rompen otros tests

NUNCA apliques un hotfix sin entender la causa raíz.
Si el fix requiere cambios en más de 3 archivos, consulta antes.

Estos comandos no limitan la creatividad del developer. Limitan la inconsistencia. Cada persona puede seguir pidiendo cosas a su manera en conversaciones normales, pero para las tareas repetitivas del equipo, todos usan el mismo workflow.

Medir la adopción del equipo

Introducir una herramienta sin medir su impacto es un experimento sin datos. No necesitas un dashboard complejo, pero sí debes trackear estos indicadores:

Métricas cuantitativas:

• Tiempo medio de PR: desde apertura hasta merge. Si baja, Claude Code está acelerando el ciclo.
• Comentarios por PR: si bajan los comentarios de tipo "falta test" o "naming incorrecto", el pre-review automático funciona.
• Frecuencia de commits: si aumenta sin perder calidad, el equipo produce más.
• Número de comandos compartidos: si crece, el equipo está adoptando y creando workflows propios.

Métricas cualitativas:

• Encuesta mensual (1 pregunta): "Del 1 al 10, ¿cuánto te ayuda Claude Code en tu trabajo diario?".
• Retro de equipo: 5 minutos en la retro de sprint para "¿qué mejoraríamos del CLAUDE.md?".
• Bugs en producción: si bajan, la combinación de tests auto + review con IA está funcionando.

Si después de un mes la adopción está por debajo del 50% del equipo, el problema casi siempre es uno de estos: la configuración es demasiado restrictiva, los comandos compartidos no cubren los casos de uso reales, o faltó la fase de piloto.

Herramientas e integraciones

Claude Code no vive aislado. Se integra con el ecosistema de desarrollo del equipo. Estas son las integraciones más útiles:

Git hooks:

• Pre-commit: lint + format + tests unitarios (rápido, <30s).
• Pre-push: tests completos + build + security check.
• Configurados en el settings.json para que Claude Code los ejecute automáticamente.

CI/CD:

• GitHub Actions / GitLab CI ejecutan los mismos checks que Claude Code ejecuta localmente.
• Si Claude Code pasa los checks locales, CI debería pasar también (misma config).
• Comandos como /deploy-check replican el pipeline de CI para detectar problemas antes del push.

Comunicación de equipo:

• Slack/Teams: canal dedicado para compartir tips, nuevos comandos y problemas con Claude Code.
• Documentación interna: enlaza el CLAUDE.md desde el README del proyecto.
• PR templates: incluye un checkbox "He ejecutado /review antes de pedir review".

IDEs:

• VS Code con terminal integrado: Claude Code corre en la terminal mientras editas en el IDE.
• Los comandos compartidos funcionan igual desde cualquier terminal.
• Los hooks se ejecutan independientemente del IDE que use cada developer.

Convenciones de equipo

Git workflow: define en el CLAUDE.md cómo trabajar con git. Ramas, commits, PRs. Claude Code seguirá las mismas convenciones que el equipo.

Code review con IA: usa el comando /review como primera pasada antes del review humano. Captura errores obvios y libera tiempo del reviewer para lógica de negocio.

Documentación: configura hooks para que Claude Code genere o actualice documentación cuando modifica código. Un PostFileWrite hook que actualice el README si cambia la API, por ejemplo.

Onboarding: un nuevo developer clona el repo, ejecuta Claude Code, y el CLAUDE.md le da todo el contexto del proyecto. El onboarding pasa de días a horas.

Preguntas frecuentes

¿Cuántos comandos compartidos debería tener un equipo?

Empieza con 3-5 para las tareas más comunes (review, test, fix, implement). Si llegas a más de 15, probablemente algunos están duplicados o son demasiado específicos. Revisa y consolida cada mes.

¿El CLAUDE.md ralentiza a Claude Code?

Un CLAUDE.md de menos de 300 líneas no tiene impacto perceptible. Si supera las 500 líneas, empieza a consumir contexto útil. Divide en archivos por subdirectorio para proyectos grandes.

¿Funciona con equipos remotos en diferentes husos horarios?

Perfectamente. Los comandos compartidos y el CLAUDE.md son asíncronos. No dependen de que alguien esté online. Cada developer ejecuta los mismos workflows independientemente de cuándo trabaje.

¿Puedo tener diferentes settings para diferentes branches?

Sí. El settings.json se commitea a git, así que cada branch puede tener su propia configuración. Útil para feature branches experimentales donde quieres permisos más amplios.

¿Cómo manejo conflictos entre la config global de un developer y la del proyecto?

La config de proyecto siempre gana. Si un developer tiene preferencias personales que contradicen el proyecto (por ejemplo, idioma de respuesta), la prioridad es: sesión > proyecto > global. Explica esto en el onboarding para evitar confusión.

Siguiente paso

Crea un CLAUDE.md básico con las convenciones de tu equipo, commitéalo, y pide a cada miembro que pruebe Claude Code durante una semana. Recoge feedback, ajusta las reglas, e itera.

Si aún no tienes Claude Code configurado, empieza con la guía de instalación.