Saltar al contenido
Lección 13 de 14

Configuracion de Equipo y Mejores Practicas

10 min read

De Individual a Equipo

Usar Claude Code como desarrollador individual es sencillo. Lo configuras a tus preferencias, aprendes las funcionalidades y desarrollas tus propios flujos de trabajo. Escalarlo a un equipo introduce nuevos desafios: consistencia, gobernanza, gestion de costos y comparticion de conocimiento. Esta leccion cubre como configurar Claude Code para adopcion en equipo de manera que cada desarrollador se beneficie de las mejores practicas compartidas sin sacrificar flexibilidad individual.

Onboarding de Equipo con CLAUDE.md Compartido

La base del uso de Claude Code a nivel de equipo es un archivo CLAUDE.md compartido committeado en la raiz de tu repositorio. Este archivo establece las convenciones que cada sesion de Claude Code de cada desarrollador seguira:

# Proyecto: Acme API

## Arquitectura
- Monorepo con directorio packages/ (api, web, shared)
- API: Express.js con TypeScript, PostgreSQL via Prisma
- Web: Next.js 14 con App Router
- Shared: tipos comunes y utilidades

## Estandares de Codigo
- TypeScript strict mode, no usar tipos `any`
- Usar barrel exports (index.ts) para APIs publicas
- Manejo de errores: clase custom AppError, nunca lanzar strings crudos
- Nomenclatura: camelCase para variables, PascalCase para tipos, kebab-case para archivos

## Convenciones de Git
- Nombrado de ramas: prefijos feat/, fix/, refactor/, docs/
- Mensajes de commit: conventional commits (feat:, fix:, refactor:, etc.)
- Siempre squash-merge PRs a main
- Nunca force-push a main o develop

## Testing
- Tests unitarios con Vitest, tests de integracion con Supertest
- Minimo 80% de cobertura para codigo nuevo
- Nombrado de archivos de test: *.test.ts co-ubicados con el fuente

## Acciones Prohibidas
- NUNCA eliminar archivos de migracion
- NUNCA modificar el middleware de auth sin revision de seguridad
- NUNCA commitear archivos .env o API keys
- NUNCA eliminar tablas de base de datos en scripts de migracion

Cada miembro del equipo que use Claude Code en este repositorio tendra estas instrucciones cargadas automaticamente. Esto elimina el problema de "funciona en mi maquina" para el desarrollo asistido por IA -- el Claude de todos sigue las mismas reglas.

Prueba esto: revisa los estandares de codificacion de tu equipo y traduce las diez reglas principales al formato CLAUDE.md. Haz commit y pide a un companero de equipo que verifique que Claude sigue las reglas en su sesion.

Plugins Compartidos para Flujos de Trabajo de Equipo

Empaqueta los flujos de trabajo comunes de tu equipo en un plugin que cada desarrollador instale:

{
  "name": "acme-dev-toolkit",
  "description": "Standard development workflows for Acme engineering",
  "version": "2.1.0",
  "components": {
    "commands": [
      "commands/pr-review.md",
      "commands/deploy-staging.md",
      "commands/onboard-service.md"
    ],
    "skills": [
      "skills/code-style.md",
      "skills/error-handling.md",
      "skills/api-conventions.md"
    ],
    "hooks": [
      "hooks/pre-commit-lint.sh",
      "hooks/block-env-commits.sh"
    ],
    "agents": [
      "agents/security-reviewer.md"
    ]
  }
}

Distribuye a traves del repositorio Git privado de tu equipo:

# Cada desarrollador ejecuta esto una vez
/plugin install https://github.com/acme-corp/claude-dev-toolkit

Cuando lanzas una nueva version, los desarrolladores actualizan con:

/plugin update acme-dev-toolkit

Estrategias para Monorepos

En monorepos, diferentes servicios frecuentemente tienen diferentes convenciones. Usa archivos CLAUDE.md con alcance por directorio para manejar esto:

monorepo/
  CLAUDE.md                    # reglas de todo el repo
  packages/
    api/
      CLAUDE.md                # reglas especificas de la API
    web/
      CLAUDE.md                # reglas especificas del frontend
    mobile/
      CLAUDE.md                # reglas especificas de mobile

Claude Code fusiona estos archivos jerarquicamente. Al trabajar en packages/api/, Claude ve tanto el CLAUDE.md raiz como el CLAUDE.md especifico de api. El archivo mas especifico puede sobreescribir o extender las reglas raiz.

Ejemplo packages/api/CLAUDE.md:

# Servicio API

## Reglas Adicionales (extiende el CLAUDE.md raiz)
- Usar Zod para todos los esquemas de validacion de requests
- Cada endpoint debe tener middleware de rate limiting
- Las consultas a base de datos van a traves del patron repository, nunca SQL crudo en controllers
- Las respuestas de API siguen el formato envelope: { data, error, meta }

Ejemplo packages/web/CLAUDE.md:

# Aplicacion Web

## Reglas Adicionales (extiende el CLAUDE.md raiz)
- Usar Server Components por defecto, Client Components solo cuando sea necesario
- CSS: solo clases utilitarias de Tailwind, no archivos CSS personalizados
- Imagenes: siempre usar next/image con width y height explicitos
- Gestion de estado: React Server Components + estado en URL, sin stores del lado del cliente

Gobernanza de Seguridad

Los equipos necesitan barreras de proteccion que prevengan danos accidentales. Implementa estas a traves de hooks y politicas de modo de permisos.

Barreras basadas en hooks en .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "command": "bash -c 'echo \"$CLAUDE_TOOL_INPUT\" | grep -qiE \"(rm -rf|drop table|force push|--force)\" && echo \"BLOQUEADO: Comando peligroso detectado\" && exit 1 || exit 0'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "write|edit",
        "command": "bash -c 'echo \"$CLAUDE_TOOL_INPUT\" | grep -qiE \"(API_KEY|SECRET|PASSWORD|PRIVATE_KEY)\" && echo \"BLOQUEADO: Potencial secreto en codigo\" && exit 1 || exit 0'"
      }
    ]
  }
}

Politica de modos de permisos: Documenta que modos son apropiados para cada contexto:

| Contexto | Modo Recomendado | Razon | |----------|-----------------|-------| | Nuevos miembros del equipo | default | Visibilidad completa mientras aprenden | | Desarrollo diario | acceptEdits | Confiar en ediciones, revisar comandos | | Revision de codigo | plan | Analisis de solo lectura | | Pipelines CI/CD | auto + max-turns | Autonomo pero acotado | | Depuracion en produccion | plan | Solo lectura para evitar cambios accidentales |

Gestion de Costos

El desarrollo asistido por IA tiene costos reales. Los equipos necesitan visibilidad y controles:

# Verificar costo de la sesion actual
/cost

# Ver estadisticas de uso acumuladas
/stats

Controles a nivel de equipo:

  • Configura limites de --max-turns en configuraciones CI para prevenir sesiones descontroladas
  • Establece presupuestos mensuales por desarrollador a traves de tu gestion de API keys
  • Usa /effort auto como predeterminado para que Claude calibre el uso de tokens segun la complejidad de la tarea
  • Reserva el pensamiento extendido para problemas genuinamente complejos, no para tareas rutinarias

Practicas de ahorro de costos:

  • Usa /compact regularmente para reducir el tamano del contexto y el consumo de tokens
  • Usa prompts especificos en lugar de abiertos -- los prompts enfocados usan menos tokens
  • Usa claude-sonnet para tareas rutinarias, reserva claude-opus para razonamiento complejo
  • Revisa /stats semanalmente para identificar sesiones inusualmente costosas

Puertas de Calidad de Codigo

Impone estandares de calidad automaticamente a traves de una combinacion de hooks y skills:

# skills/quality-gate.md
---
triggers:
  - pre_commit
---

Antes de commitear cualquier cambio de codigo, verifica:

1. El linter pasa con cero errores: `npm run lint`
2. Todos los tests pasan: `npm test`
3. Sin errores de TypeScript: `npx tsc --noEmit`
4. Sin comentarios TODO o FIXME en los archivos commiteados
5. Las nuevas funciones tienen documentacion JSDoc
6. Los nuevos endpoints de API tienen cobertura de tests

Si alguna verificacion falla, reporta el fallo y NO procedas con el commit.

Este skill se dispara antes de cada commit, asegurando que la calidad del codigo se imponga consistentemente sin importar que desarrollador este trabajando.

Comparticion de Conocimiento

El aspecto mas subestimado de la adopcion de Claude Code en equipo es la comparticion de conocimiento. Cuando un desarrollador descubre un patron de prompt efectivo o un flujo de trabajo, todo el equipo deberia beneficiarse.

Documenta patrones en CLAUDE.md:

## Patrones Probados

### Depurando Tests Inestables
Al investigar tests inestables, usa este enfoque:
1. Ejecuta el test 10 veces para medir la tasa de fallo
2. Verifica estado compartido entre tests
3. Busca dependencias de tiempo o condiciones de carrera
4. Verifica aislamiento de tests (limpieza de BD, restauracion de mocks)

### Investigacion de Rendimiento
Al investigar problemas de rendimiento:
1. Ejecuta el benchmark relevante primero para establecer linea base
2. Usa herramientas de profiling: `npx clinic doctor -- node src/server.ts`
3. Enfocate en la ruta critica identificada por el profiler
4. Despues de la correccion, re-ejecuta el benchmark para confirmar mejora

Crea skills de equipo para tareas comunes que cada desarrollador realiza:

# Estos quedan disponibles para cada desarrollador via el plugin compartido
/pr-review      # revision de codigo estandarizada
/deploy-staging # despliegue seguro a staging
/onboard        # generar documentacion de onboarding para un nuevo servicio

Cumplimiento y Auditoria

Para industrias reguladas, Claude Code proporciona varias funcionalidades relevantes para cumplimiento:

  • Logs de sesion capturan cada prompt y respuesta, proporcionando una pista de auditoria de cambios asistidos por IA
  • Controles de permisos imponen separacion de funciones (solo lectura para auditores, escritura para desarrolladores)
  • Restricciones basadas en hooks pueden bloquear operaciones especificas en entornos de produccion
  • Modo sandbox aisla el entorno de ejecucion de Claude para prevenir acceso no autorizado al sistema

Configura estos en el .claude/settings.json de tu equipo y haz commit de la configuracion al control de versiones para que las reglas de cumplimiento se impongan consistentemente.

Ruta de Migracion: De Individual a Equipo

Sigue esta progresion al desplegar Claude Code en un equipo:

Fase 1 -- Piloto Individual (1-2 semanas). Uno o dos desarrolladores usan Claude Code con configuraciones personales. Identifican que funcionalidades son mas valiosas y documentan patrones iniciales.

Fase 2 -- Configuracion Compartida (1 semana). Crea el CLAUDE.md del equipo, establece convenciones de codificacion y configura hooks basicos. Todos los usuarios piloto cambian a la configuracion compartida.

Fase 3 -- Desarrollo de Plugin (1-2 semanas). Empaqueta los flujos de trabajo mas utiles en un plugin de equipo. Crea skills para tareas comunes y hooks para barreras de proteccion.

Fase 4 -- Despliegue al Equipo (continuo). Todos los desarrolladores instalan el plugin y usan la configuracion compartida. Realiza una sesion de equipo para demostrar flujos de trabajo y responder preguntas.

Fase 5 -- Integracion CI/CD (1-2 semanas). Agrega Claude Code al pipeline CI para revisiones automatizadas, analisis de tests y generacion de documentacion.

Errores Comunes

Configuraciones divergentes. Cuando los desarrolladores mantienen configuraciones personales separadas que entran en conflicto con los estandares del equipo. Solucion: haz commit del CLAUDE.md y la configuracion al repositorio.

Barreras faltantes. No configurar hooks para prevenir operaciones peligrosas. Un rm -rf o force-push accidental puede ser costoso. Solucion: implementa hooks PreToolUse desde el primer dia.

Contexto inflado. Desarrolladores ejecutando sesiones muy largas sin compactar. Solucion: establece una norma de equipo de ejecutar /compact despues de cada subtarea importante.

Modos de permisos inconsistentes. Algunos desarrolladores usando modo auto en bases de datos de produccion mientras otros usan plan. Solucion: documenta modos recomendados por contexto e impone a traves del onboarding.

Ignorar costos. No monitorear el uso hasta que llega la factura mensual. Solucion: revisiones semanales de /stats y alertas de presupuesto por proyecto.

Una configuracion de equipo bien ejecutada convierte a Claude Code de una herramienta de productividad personal en un multiplicador de fuerza para todo el equipo. La inversion en configuracion compartida, gobernanza y flujos de trabajo genera dividendos a medida que cada desarrollador se beneficia de las mejores practicas colectivas.