Saltar al contenido
Lección 13 de 14

Configuración de Equipo y Mejores Prácticas

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 desafíos: consistencia, gobernanza, gestión de costos y compartición de conocimiento. Esta lección cubre cómo configurar Claude Code para adopción en equipo de manera que cada desarrollador se beneficie de las mejores prácticas 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 raíz de tu repositorio. Este archivo establece las convenciones que cada sesión de Claude Code de cada desarrollador seguirá:

# 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 tendrá estas instrucciones cargadas automáticamente. Esto elimina el problema de "funciona en mi máquina" para el desarrollo asistido por IA -- el Claude de todos sigue las mismas reglas.

Prueba esto: revisa los estándares de codificación de tu equipo y traduce las diez reglas principales al formato CLAUDE.md. Haz commit y pide a un compañero de equipo que verifique que Claude sigue las reglas en su sesión.

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 través 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 versión, 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 jerárquicamente. Al trabajar en packages/api/, Claude ve tanto el CLAUDE.md raíz como el CLAUDE.md específico de api. El archivo más específico puede sobreescribir o extender las reglas raíz.

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 protección que prevengan daños accidentales. Implementa estas a través de hooks y políticas 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'"
      }
    ]
  }
}

Política de modos de permisos: Documenta qué modos son apropiados para cada contexto:

| Contexto | Modo Recomendado | Razón | |----------|-----------------|-------| | Nuevos miembros del equipo | default | Visibilidad completa mientras aprenden | | Desarrollo diario | acceptEdits | Confiar en ediciones, revisar comandos | | Revisión de código | plan | Análisis de solo lectura | | Pipelines CI/CD | auto + max-turns | Autónomo pero acotado | | Depuración en producción | plan | Solo lectura para evitar cambios accidentales |

Gestión 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 límites de --max-turns en configuraciones CI para prevenir sesiones descontroladas
  • Establece presupuestos mensuales por desarrollador a través de tu gestión de API keys
  • Usa /effort auto como predeterminado para que Claude calibre el uso de tokens según la complejidad de la tarea
  • Reserva el pensamiento extendido para problemas genuinamente complejos, no para tareas rutinarias

Prácticas de ahorro de costos:

  • Usa /compact regularmente para reducir el tamaño del contexto y el consumo de tokens
  • Usa prompts específicos 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 Código

Impone estándares de calidad automáticamente a través de una combinación 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 código se imponga consistentemente sin importar qué desarrollador esté trabajando.

Compartición de Conocimiento

El aspecto más subestimado de la adopción de Claude Code en equipo es la compartición de conocimiento. Cuando un desarrollador descubre un patrón de prompt efectivo o un flujo de trabajo, todo el equipo debería 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. Enfócate 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 Auditoría

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

  • Logs de sesión capturan cada prompt y respuesta, proporcionando una pista de auditoría de cambios asistidos por IA
  • Controles de permisos imponen separación de funciones (solo lectura para auditores, escritura para desarrolladores)
  • Restricciones basadas en hooks pueden bloquear operaciones específicas en entornos de producción
  • Modo sandbox aísla el entorno de ejecución de Claude para prevenir acceso no autorizado al sistema

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

Ruta de Migración: De Individual a Equipo

Sigue esta progresión 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 qué funcionalidades son más valiosas y documentan patrones iniciales.

Fase 2 -- Configuración Compartida (1 semana). Crea el CLAUDE.md del equipo, establece convenciones de codificación y configura hooks básicos. Todos los usuarios piloto cambian a la configuración compartida.

Fase 3 -- Desarrollo de Plugin (1-2 semanas). Empaqueta los flujos de trabajo más útiles en un plugin de equipo. Crea skills para tareas comunes y hooks para barreras de protección.

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

Fase 5 -- Integración CI/CD (1-2 semanas). Agrega Claude Code al pipeline CI para revisiones automatizadas, análisis de tests y generación de documentación.

Errores Comunes

Configuraciones divergentes. Cuando los desarrolladores mantienen configuraciones personales separadas que entran en conflicto con los estándares del equipo. Solución: haz commit del CLAUDE.md y la configuración al repositorio.

Barreras faltantes. No configurar hooks para prevenir operaciones peligrosas. Un rm -rf o force-push accidental puede ser costoso. Solución: implementa hooks PreToolUse desde el primer día.

Contexto inflado. Desarrolladores ejecutando sesiones muy largas sin compactar. Solución: establece una norma de equipo de ejecutar /compact después de cada subtarea importante.

Modos de permisos inconsistentes. Algunos desarrolladores usando modo auto en bases de datos de producción mientras otros usan plan. Solución: documenta modos recomendados por contexto e impone a través del onboarding.

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

Una configuración de equipo bien ejecutada convierte a Claude Code de una herramienta de productividad personal en un multiplicador de fuerza para todo el equipo. La inversión en configuración compartida, gobernanza y flujos de trabajo genera dividendos a medida que cada desarrollador se beneficia de las mejores prácticas colectivas.