Cómo usar Claude Code en equipo: la guía definitiva para equipos de ingeniería modernos

Tu equipo tiene 25 desarrolladores, 40 microservicios y 12 microfrontends. Cinco de ellos ya usan Claude Code. El problema: cada uno lo usa diferente, nadie comparte contexto, y el código generado con IA no tiene consistencia entre repos.

Bienvenido al context rot — el enemigo silencioso de los equipos que adoptan IA sin estrategia.

Este artículo es la guía que me hubiera gustado tener hace seis meses. Un playbook completo para pasar de "cada dev usa Claude Code como quiere" a "tenemos un sistema de IA que entiende nuestra arquitectura completa."

El problema real: Context Rot

Cuando un solo desarrollador usa Claude Code, todo funciona bien. Claude aprende el codebase, recuerda las convenciones, genera código coherente.

Pero cuando escalas a un equipo, aparecen tres problemas:

1. Cada agente empieza de cero. Dev A tiene un Claude que entiende el servicio de pagos. Dev B abre una sesión nueva y Claude no sabe nada. El conocimiento se pierde entre sesiones.

2. Convenciones inconsistentes. Sin contexto compartido, Claude genera código con patrones diferentes para cada dev. Un servicio usa repository pattern, otro usa active record, y nadie se dio cuenta hasta el code review.

3. Cero trazabilidad. ¿Quién generó este código? ¿Qué prompt produjo este bug? ¿Cuál era la intención original? Imposible saberlo.

El context rot no es un problema técnico — es un problema organizacional. Y se resuelve con herramientas y protocolo.

La solución: Un stack de herramientas centrado en CLAUDE.md

CLAUDE.md — La piedra angular

CLAUDE.md es el archivo que Claude Code lee automáticamente al iniciar cada sesión. Es la memoria compartida de tu equipo con la IA.

La magia está en la jerarquía:

• Managed CLAUDE.md (~/.claude/CLAUDE.md) — Preferencias globales del dev
• Project CLAUDE.md (raíz del repo) — Contexto del proyecto, compartido via Git
• Local CLAUDE.md (subdirectorios) — Contexto específico de módulos

Para un equipo con microservicios, el Project CLAUDE.md de cada repo es el arma secreta. Define stack, arquitectura, convenciones, comandos clave y anti-patrones. Cada dev que abra Claude Code en ese repo arranca con el mismo contexto.

# payments-service — CLAUDE.md

## Overview
- Stack: Node.js 20 + TypeScript 5.x + NestJS
- DB: PostgreSQL 16
- Patrón: Hexagonal Architecture

## Comandos clave
npm run dev          # Local
npm run test         # Unit tests
npm run test:e2e     # Integration tests

## Convenciones
- DTOs con class-validator
- Errores custom extienden BaseAppException
- Todas las queries via repository pattern

## NO hacer
- No usar any — nunca
- No hacer queries directas al ORM fuera del repository
- No commitear sin tests

Pero CLAUDE.md es solo la base. Lo que lo hace poderoso es el ecosistema que construyes encima.

.claude/rules/ — Reglas modulares

Además del CLAUDE.md, puedes crear reglas específicas en .claude/rules/:

.claude/
├── rules/
│   ├── api-conventions.md      # Cómo diseñar endpoints
│   ├── error-handling.md       # Patrones de errores
│   ├── testing-standards.md    # Qué y cómo testear
│   └── security-checklist.md   # Validaciones de seguridad
├── agents/
│   ├── code-reviewer.md        # Agente especializado en reviews
│   └── migration-specialist.md # Agente para migraciones de DB

Las rules se cargan automáticamente. Los agents son subagentes especializados que puedes invocar para tareas específicas. Ambos se comparten via Git — todo el equipo tiene las mismas reglas y agentes.

entire.io — Trazabilidad de sesiones a commits

entire.io resuelve el tercer problema: la trazabilidad. Graba las sesiones de Claude Code y las asocia directamente a los commits de Git.

¿Por qué importa? Porque seis meses después, cuando alguien mira un commit y se pregunta "¿por qué se implementó así?", puede ver la conversación completa que lo generó. El razonamiento, las alternativas descartadas, las decisiones de diseño — todo queda vinculado al código.

Para equipos, esto es invaluable:

• Code reviews más rápidos — entiendes la intención detrás del código
• Onboarding acelerado — nuevos devs ven cómo se pensó cada pieza
• Debugging con contexto — cuando algo falla, tienes el "por qué" además del "qué"

La recomendación: instalar entire.io como estándar del equipo desde el día uno. La trazabilidad que genera se vuelve más valiosa con el tiempo.

GSD — Spec-Driven Development

GSD (Get Shit Done) es la herramienta más madura para desarrollo guiado por especificaciones con Claude Code. Su flujo ataca directamente el context rot:

1. /gsd:new-project — Genera requirements y roadmap a partir de preguntas
2. /gsd:discuss-phase 1 — Captura las preferencias del dev → genera CONTEXT.md
3. /gsd:plan-phase 1 — Crea planes atómicos con research fresco
4. /gsd:execute-phase 1 — Ejecuta en waves paralelas, un commit por task

Lo brillante de GSD es que cada plan se ejecuta con contexto fresco. No acumula basura de sesiones anteriores. El resultado: código consistente, trazable, con specs que cualquiera del equipo puede leer.

Para equipos con microservicios, GSD es ideal para proyectos nuevos o refactors grandes donde necesitas que Claude mantenga coherencia a lo largo de semanas.

skills.sh — Capacidades compartidas

skills.sh es el ecosistema de skills para Claude Code más grande (72k+ instalaciones). Un skill es un conjunto de instrucciones empaquetadas que cualquier dev puede instalar:

npx skillsadd anthropics/skills/frontend-design
npx skillsadd vercel-labs/agent-skills/vercel-react-best-practices
npx skillsadd obra/superpowers/test-driven-development
npx skillsadd obra/superpowers/systematic-debugging

Pero lo más poderoso: puedes crear skills propios de tu equipo. Imagina un skill tu-empresa/skills/api-design que encode todas las convenciones de diseño de APIs de tu organización. Cada dev lo instala, y Claude genera APIs consistentes sin importar quién lo use.

npx skillsadd anthropics/skills/skill-creator  # Para crear tus propios skills

SuperClaude Framework — Estructura y comandos

SuperClaude ofrece 30 slash commands y 16 agentes especializados. No necesitas adoptarlo completo — la estrategia es cherry-pick:

pipx install superclaude
superclaude install

Los comandos más útiles para equipos:

• Agente Security para auditorías automáticas
• Agente PM para planning
• Agente Frontend Architect para decisiones de UI
• Modos de comportamiento que estandarizan cómo Claude trabaja

Piensa en SuperClaude como un menú de capacidades. Elige las que encajen con tu equipo y descarta el resto.

Subagents y Agent Teams

Claude Code soporta subagents de forma nativa — agentes especializados que viven en .claude/agents/ y se comparten via Git:

# .claude/agents/code-reviewer.md
Eres un reviewer estricto. Revisas:
- Tipos correctos (no any)
- Tests para cada función pública
- Manejo de errores explícito
- Convenciones del CLAUDE.md del repo

Y para features grandes, Agent Teams (experimental) permite correr múltiples instancias de Claude Code en paralelo con coordinación:

// settings.json
{ "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": true }

Un agente trabaja en el backend, otro en el frontend, otro en los tests — todos coordinados bajo las mismas rules y CLAUDE.md.

El flujo completo: De task a PR

Así se ve el flujo diario con todas las piezas integradas:

1. Task asignada (Linear/Jira) → Dev toma el ticket
2. Abre Claude Code en el repo → CLAUDE.md + rules se cargan automáticamente
3. entire.io graba la sesión desde el inicio
4. Si es proyecto nuevo → /gsd:new-project para specs
5. Si es feature → Claude ya tiene contexto del servicio via CLAUDE.md
6. Skills activos aseguran que siga mejores prácticas
7. Subagents se invocan para review o tareas especializadas
8. Commit → entire.io vincula la sesión al commit
9. PR con contexto claro, tests, y trazabilidad completa

El dev no tiene que recordar convenciones, buscar documentación, ni preocuparse por consistencia. Todo está codificado en el sistema.

Plan de onboarding por niveles

No adoptes todo de golpe. Aquí va un plan gradual:

L1 — Fundamentos (Semanas 1-3)

• Instalar Claude Code en todo el equipo
• Crear CLAUDE.md en cada repositorio
• Definir .claude/rules/ con las 5 reglas más importantes
• Instalar entire.io para trazabilidad desde el día uno
• Resultado: todos usan Claude con el mismo contexto base

L2 — Estandarización (Semanas 4-6)

• Instalar skills.sh con los skills recomendados del equipo
• Crear subagents compartidos (reviewer, migration specialist)
• Crear repo team-ai-context con templates y rules centrales
• Resultado: convenciones automatizadas, no solo documentadas

L3 — Flujos avanzados (Semanas 7-9)

• Adoptar GSD para proyectos nuevos
• Configurar MCP servers compartidos (GitHub, DB, project management)
• Cherry-pick comandos útiles de SuperClaude
• Resultado: desarrollo spec-driven con trazabilidad completa

L4 — Multi-agente (Semanas 10-12)

• Activar Agent Teams para features grandes
• Crear agents especializados por dominio (pagos, auth, notificaciones)
• Optimizar CLAUDE.md basado en 3 meses de feedback
• Resultado: equipo opera con IA como multiplicador, no como muleta

El repo central: team-ai-context

Un repo compartido que centraliza la inteligencia del equipo para Claude:

team-ai-context/
├── CLAUDE.md                    # Convenciones globales
├── rules/
│   ├── coding-standards.md
│   ├── api-conventions.md
│   ├── security-checklist.md
│   └── git-workflow.md
├── agents/
│   ├── code-reviewer.md
│   ├── migration-specialist.md
│   └── onboarding-buddy.md
├── skills/
│   └── SKILL.md
└── templates/
    ├── CLAUDE.md.microservice
    ├── CLAUDE.md.microfrontend
    └── .mcp.json.template

Se incluye como submodule en cada repo. Cuando actualizas una regla central, todos los repos la heredan.

Llamado a la acción

El context rot no se resuelve solo. Y esperar "a que las herramientas maduren" es esperar a que tu equipo acumule deuda de conocimiento que después es imposible de pagar.

Empieza hoy:

1. Crea un CLAUDE.md en tu repo más importante
2. Instala entire.io para trazabilidad
3. Define 3 reglas en .claude/rules/
4. En dos semanas, tu equipo va a operar diferente

La IA en equipo no es un problema de tecnología — es un problema de protocolo. Y el protocolo empieza con un archivo de texto en la raíz de tu repo.

¿Tu equipo ya usa Claude Code? ¿Cómo manejan el contexto compartido? Me encantaría saber — escríbeme en @bottico.