Guía interna: Claude Code en equipo — Protocolo de adopción para el equipo de tecnología

De: Angel Celis Botto — CTO
Para: Equipo de tecnología
Fecha: Febrero 2026
Estado: Mandatorio para todos los desarrolladores

Por qué estamos haciendo esto

Tenemos +40 microservicios, 12 microfrontends, y un equipo de 20-35 personas. Varios de ustedes ya usan Claude Code. El problema: cada uno lo usa diferente, el contexto no se comparte, y el código generado con IA no tiene consistencia entre repos.

Esto se llama context rot y nos está costando:

• Inconsistencia técnica: Un servicio usa repository pattern, otro active record, otro direct ORM calls — porque cada Claude empezó de cero.
• Tiempo perdido en code reviews: El reviewer no entiende la intención detrás del código generado. No hay rastro de por qué se tomó una decisión.
• Onboarding lento: Devs nuevos no tienen forma de entender las decisiones de diseño recientes.
• Context perdido entre sesiones: Dev A trabajó 4 horas con Claude en payments-service. Dev B abre Claude al día siguiente — no sabe nada.

Esta guía es el protocolo oficial. No es opcional. Cada herramienta tiene un nivel de prioridad y una fecha límite de adopción.

1. entire.io — Trazabilidad de sesiones (OBLIGATORIO)

Qué es: entire.io graba las sesiones de Claude Code y las asocia directamente a los commits de Git. Cada commit queda vinculado a la conversación que lo generó.

Por qué es estándar del equipo: Necesitamos trazabilidad. Cuando alguien mira un commit de hace 3 meses, necesita poder ver el razonamiento detrás. Esto no es negociable.

Instalación

# 1. Crear cuenta en entire.io
# 2. Instalar el CLI
npm install -g @entire/cli

# 3. Autenticarse
entire login

# 4. Inicializar en cada repo donde trabajes con Claude Code
cd tu-repo
entire init

# 5. Verificar que está activo
entire status

Uso diario

No tienes que hacer nada especial. entire.io corre en background:

1. Abres Claude Code en un repo con entire.io configurado
2. Trabajas normalmente
3. Cuando haces commit, entire.io vincula la sesión automáticamente
4. Para ver el historial: entire log o ve al dashboard web

Qué nos da

• Trazabilidad commit → conversación: ¿Por qué se implementó así? Ve la sesión.
• Code reviews con contexto: El reviewer puede ver la intención original.
• Auditoría: Para servicios financieros (payments, billing), tener el "por qué" de cada cambio es crítico.
• Debugging: Cuando algo falla, puedes ver las decisiones que llevaron a ese código.

Timeline de adopción

• Semana 1: Todos instalan entire.io
• Semana 2: Todo commit desde Claude Code debe tener sesión vinculada
• Semana 4: Lo verificamos en code reviews

2. CLAUDE.md — La base de todo (OBLIGATORIO)

El archivo CLAUDE.md en la raíz de cada repo es lo que Claude Code lee al iniciar sesión. Es nuestra memoria compartida con la IA.

Jerarquía de CLAUDE.md

~/.claude/CLAUDE.md                    → Preferencias personales del dev (no compartido)
~/repo/CLAUDE.md                       → Contexto del proyecto (compartido via Git)
~/repo/src/modules/payments/CLAUDE.md  → Contexto del módulo específico

La regla: el CLAUDE.md del proyecto es compartido y mantenido por el equipo. Es parte del código.

Template para microservicios

Úsenlo tal cual. Solo cambien los valores específicos del servicio:

# [nombre-del-servicio] — CLAUDE.md

## Overview
- **Propósito:** [Descripción de una línea de qué hace este servicio]
- **Stack:** Node.js 20 + TypeScript 5.x + NestJS 10
- **Base de datos:** PostgreSQL 16
- **Cache:** Redis 7
- **Cola:** RabbitMQ / SQS

## Arquitectura
- **Patrón:** Hexagonal Architecture
- **Dependencias upstream:** [@auth-service, @users-service]
- **Dependencias downstream:** [@notifications-service, @analytics-service]
- **Eventos que produce:** [PaymentCompleted, PaymentFailed, RefundInitiated]
- **Eventos que consume:** [OrderCreated, SubscriptionRenewed]

## Estructura del proyecto
src/
├── application/        # Casos de uso (sin dependencias de infra)
│   ├── commands/       # Write operations
│   ├── queries/        # Read operations
│   └── events/         # Event handlers
├── domain/             # Entidades, value objects, interfaces de repositorio
│   ├── entities/
│   ├── value-objects/
│   └── repositories/   # Interfaces (ports)
├── infrastructure/     # Implementaciones (adapters)
│   ├── persistence/    # TypeORM repositories
│   ├── messaging/      # RabbitMQ/SQS publishers
│   └── http/           # Clientes HTTP a otros servicios
└── presentation/       # Controllers, DTOs, guards
    ├── controllers/
    ├── dtos/
    └── guards/

## Comandos clave
npm run dev              # Levantar en local (docker-compose up -d primero)
npm run test             # Unit tests
npm run test:e2e         # Integration tests (necesita DB local)
npm run test:cov         # Coverage (mínimo 80%)
npm run migrate          # Correr migraciones pendientes
npm run migrate:generate # Generar migración desde cambios en entities
npm run lint             # ESLint + Prettier check
npm run build            # Build de producción

## Convenciones de este servicio
- DTOs usan class-validator con decorators explícitos
- Errores custom extienden BaseAppException (ver src/domain/exceptions/)
- Todas las queries via repository pattern — NUNCA queries directas al ORM
- IDs son UUIDs v4, generados en el domain layer
- Fechas en UTC siempre, formato ISO 8601
- Logs estructurados con correlation ID (viene en header X-Correlation-ID)
- Variables de entorno via @nestjs/config con validación Joi en AppModule

## API Conventions
- REST, versionado via path (/v1/, /v2/)
- Responses: { data: T, meta?: { pagination } }
- Errors: { error: { code: string, message: string, details?: any } }
- Status codes estrictos: 200 OK, 201 Created, 400 Bad Request, 401/403, 404, 422 Unprocessable, 500
- Paginación: ?page=1&limit=20 → meta.pagination = { page, limit, total, totalPages }

## Testing
- Unit tests: toda función pública tiene test
- Cada test usa factories (ver test/factories/)
- Mocks solo en infrastructure layer — domain y application se testean sin mocks
- E2E: usa testcontainers para PostgreSQL

## NO hacer
- ❌ No usar `any` — nunca, sin excepciones
- ❌ No hacer queries fuera del repository layer
- ❌ No commitear sin tests para la funcionalidad nueva
- ❌ No usar console.log — usar el Logger inyectado de NestJS
- ❌ No hardcodear secrets — todo via environment variables
- ❌ No crear migraciones manuales — siempre generate desde entities
- ❌ No importar desde infrastructure en domain o application

Template para microfrontends

# [nombre-del-microfrontend] — CLAUDE.md

## Overview
- **Propósito:** [Qué parte de la UI maneja]
- **Stack:** React 18 + TypeScript 5.x + Vite
- **State management:** Zustand
- **Styling:** Tailwind CSS + design tokens compartidos
- **Module Federation:** Webpack 5 / Vite plugin

## Estructura
src/
├── components/         # Componentes de UI (atomic design)
│   ├── atoms/
│   ├── molecules/
│   └── organisms/
├── pages/              # Páginas/rutas
├── hooks/              # Custom hooks
├── stores/             # Zustand stores
├── services/           # API clients
├── types/              # TypeScript interfaces
└── utils/              # Helpers puros

## Comandos clave
npm run dev              # Dev server con HMR
npm run build            # Build de producción
npm run test             # Vitest
npm run storybook        # Storybook dev server
npm run lint             # ESLint + Prettier

## Convenciones
- Componentes funcionales con TypeScript explícito (no FC)
- Props destructured en el parámetro de la función
- Custom hooks para toda lógica que no sea renderizado
- API calls solo via services/ — nunca fetch directo en componentes
- Tailwind para estilos — no CSS modules ni styled-components
- Lazy loading para rutas con React.lazy + Suspense

## Design System
- Importar tokens de @shared/design-tokens
- Colores, tipografía, spacing — todo via tokens
- Componentes base de @shared/ui-kit — no reinventar botones/inputs

## NO hacer
- ❌ No usar useEffect para data fetching — usar React Query
- ❌ No estado global para estado de UI local — useState/useReducer
- ❌ No CSS inline excepto valores dinámicos calculados
- ❌ No importar directamente de otros microfrontends — usar el event bus

Cómo mantener el CLAUDE.md

• Quién lo actualiza: Cualquier dev puede hacer PR al CLAUDE.md
• Cuándo: Cada vez que cambie una convención, se agregue una dependencia, o se descubra un anti-patrón
• Code review: Los cambios al CLAUDE.md requieren approval del tech lead del servicio
• Regla de oro: Si tuviste que explicarle algo a Claude más de 2 veces, ponlo en el CLAUDE.md

3. .claude/rules/ y .claude/agents/ (OBLIGATORIO)

Rules — Reglas modulares por tema

Las rules son archivos markdown en .claude/rules/ que Claude carga automáticamente. Complementan al CLAUDE.md con reglas específicas.

.claude/
├── rules/
│   ├── api-design.md           # Cómo diseñar endpoints REST
│   ├── error-handling.md       # Patterns de manejo de errores
│   ├── testing-standards.md    # Qué testear y cómo
│   ├── security-fintech.md     # Reglas específicas para servicios financieros
│   ├── database-migrations.md  # Reglas para migraciones seguras
│   └── logging-observability.md # Estándares de logging

Ejemplo: .claude/rules/security-fintech.md

# Security Rules — Servicios Financieros

## Siempre
- Validar TODOS los inputs con class-validator antes de procesar
- Sanitizar datos que van a logs (no loggear PII: emails, nombres, números de tarjeta)
- Usar transactions para operaciones que modifican dinero
- Implementar idempotency keys en endpoints de pago
- Rate limiting en endpoints públicos
- Encryption at rest para datos sensibles (AES-256)

## Nunca
- NUNCA loggear tokens, passwords, o datos de tarjeta (ni parciales)
- NUNCA hacer operaciones financieras sin transaction
- NUNCA confiar en datos del frontend para cálculos de dinero — recalcular en backend
- NUNCA exponer IDs internos de transacciones financieras al cliente

Ejemplo: .claude/rules/logistics-api.md (para servicios de logística)

# Logistics API Rules

## Convenciones de dominio
- Coordenadas siempre como { lat: number, lng: number } — lat primero
- Distancias en metros (enteros), convertir a km solo en presentación
- Timestamps de tracking siempre en UTC con timezone del evento como campo separado
- Estados de envío siguen el enum ShipmentStatus — no strings libres
- Direcciones normalizadas via el servicio de geocoding antes de persistir

## Cálculos
- Precios en centavos (integer) — nunca floats para dinero
- ETA calculado server-side, nunca confiar en el estimado del cliente
- Zonas de cobertura via PostGIS — no cálculos geométricos manuales

Agents — Subagentes especializados

Archivos en .claude/agents/ definen agentes que puedes invocar para tareas específicas:

.claude/agents/code-reviewer.md

Eres un code reviewer estricto para nuestro equipo. Al revisar código:

1. Verifica que sigue las convenciones del CLAUDE.md del repo
2. Busca: any types, queries fuera del repository, console.log, secrets hardcoded
3. Verifica que cada función pública nueva tenga test
4. Revisa manejo de errores — ¿hay try/catch donde debe haber?
5. Evalúa naming: ¿los nombres comunican intención?
6. Flag de seguridad: ¿hay inputs sin validar? ¿datos sensibles en logs?

Output: lista de issues por severidad (🔴 blocker, 🟡 warning, 🟢 nit)

.claude/agents/migration-specialist.md

Eres especialista en migraciones de base de datos. Al crear migraciones:

1. Siempre reversible (up + down)
2. No locks largos en tablas grandes — usar pg_repack o migraciones en fases
3. Nuevas columnas: nullable primero, backfill, luego constraint
4. Nunca DROP COLUMN en producción directamente — deprecar primero
5. Índices: CREATE INDEX CONCURRENTLY siempre
6. Validar: ¿la migración corre en menos de 30 segundos en una tabla de 10M rows?

4. GSD — Get Shit Done (Recomendado para proyectos nuevos)

GSD es un framework de spec-driven development que resuelve el context rot con un flujo estructurado.

Instalación

# Instalar el skill de GSD
npx skillsadd cyanheads/gsd

# Esto agrega las instrucciones a tu CLAUDE.md
# Verifica que aparezcan los comandos /gsd:*

Flujo completo

Paso 0: Mapear codebase existente (si ya hay código)

/gsd:map-codebase

Claude analiza la estructura, dependencias, y patrones del código existente.

Paso 1: Nuevo proyecto

/gsd:new-project

Claude te hace preguntas → genera:

• PROJECT.md — Descripción
• REQUIREMENTS.md — V1, V2, fuera de scope
• ROADMAP.md — Fases mapeadas a requirements
• STATE.md — Estado actual

Paso 2: Discutir cada fase

/gsd:discuss-phase 1

Claude captura tus preferencias técnicas para la fase → genera phase-1-CONTEXT.md con tus decisiones.

Paso 3: Planificar

/gsd:plan-phase 1

Claude hace research, genera planes atómicos, los verifica contra requirements. Resultado: phase-1-{N}-PLAN.md — planes concretos y ejecutables.

Paso 4: Ejecutar

/gsd:execute-phase 1

Ejecución en waves paralelas. Context fresco por plan (anti context rot). Un commit por task completado.

Cuándo usar GSD

✅ Usar cuando:

• Proyecto nuevo desde cero
• Refactor grande de un servicio existente
• Migración de arquitectura (ej: monolito → microservicio)
• Feature que toca 3+ módulos

❌ No usar cuando:

• Bug fix rápido
• Feature pequeño (< 1 día)
• Cambio de configuración
• Hotfix en producción

5. skills.sh — Capacidades compartidas (OBLIGATORIO)

Instalación de skills recomendados

Cada dev debe instalar estos skills base:

# Skills oficiales de Anthropic
npx skillsadd anthropics/skills/frontend-design
npx skillsadd anthropics/skills/skill-creator

# Skills de Vercel (para microfrontends)
npx skillsadd vercel-labs/agent-skills/vercel-react-best-practices

# Skills de productividad
npx skillsadd obra/superpowers/test-driven-development
npx skillsadd obra/superpowers/systematic-debugging

Crear skills propios del equipo

Esto es lo más importante a largo plazo. Nuestros skills propios codifican nuestro conocimiento institucional.

# 1. Instalar el skill creator
npx skillsadd anthropics/skills/skill-creator

# 2. Pedirle a Claude que cree un skill
# "Crea un skill para diseño de APIs REST siguiendo nuestras convenciones de [CLAUDE.md]"

# 3. El skill se genera como un archivo .md que puedes pushear a tu repo
# y compartir con el equipo via skills.sh

Skills que vamos a crear internamente:

• equipo/skills/nestjs-service-design — Cómo estructurar un servicio NestJS
• equipo/skills/payment-integration — Patrones para integrar pasarelas de pago
• equipo/skills/microfrontend-setup — Setup estándar de un nuevo microfrontend
• equipo/skills/database-optimization — Queries eficientes, índices, explain analyze

6. SuperClaude — Comandos útiles (Opcional)

No vamos a adoptar SuperClaude completo (30 comandos, 16 agentes — overkill). Cherry-pick de lo que nos sirve:

Instalación

pipx install superclaude
superclaude install

Comandos recomendados para el equipo

• Agente Security: Auditorías de seguridad automáticas antes de PR
• Agente PM: Para convertir tickets de Linear en specs técnicas
• Agente Frontend Architect: Decisiones de UI y componentes
• Modos de comportamiento: Estandarizan cómo Claude responde (verbose, conciso, paso a paso)

Lo que NO usamos de SuperClaude

No instalar: agentes que dupliquen lo que ya tenemos en .claude/agents/ o rules que contradigan nuestro CLAUDE.md. SuperClaude es complemento, no reemplazo.

7. MCP — Model Context Protocol (Semana 4+)

MCPs conectan a Claude Code con herramientas externas. Configuración via .mcp.json en la raíz del repo.

MCPs obligatorios

GitHub MCP

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

PostgreSQL MCP (solo para dev/staging)

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DEV_DATABASE_URL}"
      }
    }
  }
}

Linear MCP (para gestión de tareas)

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@linear/mcp-server"],
      "env": {
        "LINEAR_API_KEY": "${LINEAR_API_KEY}"
      }
    }
  }
}

Seguridad de secretos en MCP

REGLA: Nunca hardcodear secrets en .mcp.json. Siempre usar variables de entorno:

# En tu .env.local (NO commitear)
GITHUB_TOKEN=ghp_xxxx
LINEAR_API_KEY=lin_api_xxxx
DEV_DATABASE_URL=postgres://user:pass@localhost:5432/dev

# En .gitignore (verificar que esté)
.env.local

El .mcp.json SÍ se commitea (usa ${VAR} syntax). Los valores reales NO.

8. Repo team-ai-context (Semana 4+)

Un repositorio centralizado que contiene toda la inteligencia compartida del equipo para IA.

Estructura exacta

team-ai-context/
├── CLAUDE.md                         # Convenciones globales del equipo
├── rules/
│   ├── coding-standards.md           # Estándares de código generales
│   ├── api-conventions.md            # Diseño de APIs REST
│   ├── error-handling.md             # Patterns de errores
│   ├── testing-standards.md          # Qué y cómo testear
│   ├── security-checklist.md         # Checklist de seguridad
│   ├── git-workflow.md               # Branching, commits, PRs
│   ├── security-fintech.md           # Reglas para servicios financieros
│   └── logging-observability.md      # Logging y métricas
├── agents/
│   ├── code-reviewer.md              # Reviewer automático
│   ├── migration-specialist.md       # Experto en migraciones DB
│   ├── onboarding-buddy.md           # Ayuda a nuevos devs
│   ├── incident-responder.md         # Para debugging en producción
│   └── tech-debt-analyzer.md         # Identifica deuda técnica
├── skills/
│   ├── SKILL.md                      # Índice de skills del equipo
│   ├── nestjs-service-design/        
│   ├── payment-integration/          
│   └── microfrontend-setup/          
├── templates/
│   ├── CLAUDE.md.microservice        # Template para nuevos microservicios
│   ├── CLAUDE.md.microfrontend       # Template para nuevos microfrontends
│   ├── .mcp.json.template            # Template de MCP config
│   └── .claude-rules.template/       # Rules base para cualquier repo
└── docs/
    ├── onboarding.md                 # Guía de onboarding con IA
    ├── troubleshooting.md            # Problemas comunes
    └── best-practices.md             # Mejores prácticas actualizadas

Cómo incluirlo en cada repo

# Agregar como submodule
git submodule add [email protected]:equipo/team-ai-context.git .ai-context

# En CLAUDE.md del repo, importar:
# @.ai-context/rules/coding-standards.md
# @.ai-context/rules/api-conventions.md

Cómo mantenerlo

• Cualquier dev puede hacer PR con mejoras
• Tech leads aprueban cambios en rules y agents
• Revisión mensual: primera semana de cada mes, revisamos qué actualizar
• Regla: Si una regla aplica a 3+ repos, va en team-ai-context

9. Flujo completo: Task → PR con Linear

Así es el flujo diario con todas las piezas:

1. Tomar el ticket

# Claude puede leer el ticket directamente via Linear MCP
"Toma el ticket LIN-1234 y analiza qué necesitamos hacer"

2. Abrir Claude Code en el repo

cd ~/repos/payments-service
claude
# → CLAUDE.md se carga automáticamente
# → .claude/rules/ se cargan
# → entire.io empieza a grabar
# → MCP servers se conectan

3. Entender el contexto

"Lee el ticket LIN-1234 de Linear. 
Analiza el código actual relacionado.
Dame un plan de implementación."

4. Implementar

"Implementa el plan paso a paso.
Crea tests para cada función nueva.
Sigue las convenciones del CLAUDE.md."

5. Review pre-PR

"Invoca al agente code-reviewer para revisar los cambios.
Fija todos los issues blocker y warning."

6. Commit y PR

# Claude crea commits descriptivos
git add .
git commit -m "feat(payments): add retry logic for failed webhooks (LIN-1234)"

# entire.io vincula la sesión al commit automáticamente

# Crear PR
gh pr create --title "feat(payments): webhook retry logic" \
  --body "Closes LIN-1234\n\n## Changes\n- Added retry logic with exponential backoff\n- Max 3 retries\n- Dead letter queue after max retries"

7. Actualizar Linear

"Mueve el ticket LIN-1234 a 'In Review' en Linear"

10. Plan de onboarding — 12 semanas

Semanas 1-3: Fundamentos (TODOS)

Semanas 4-6: Estandarización

Semanas 7-9: Flujos avanzados

Semanas 10-12: Multi-agente y optimización

11. Reglas del equipo

Lo que SIEMPRE hacemos

1. ✅ CLAUDE.md en cada repo — es el primer archivo que se crea en un repo nuevo
2. ✅ entire.io activo — toda sesión de Claude Code queda registrada
3. ✅ Tests con código generado — Claude genera el test junto con el código, no después
4. ✅ Review del output — NUNCA hacer merge de código generado sin revisarlo
5. ✅ Commits atómicos — un commit por cambio lógico, mensaje descriptivo
6. ✅ Rules compartidas — las reglas del equipo viven en Git, no en la cabeza de alguien
7. ✅ Secrets en env vars — nunca en .mcp.json, nunca en CLAUDE.md
8. ✅ Feedback al CLAUDE.md — si Claude se equivoca 2 veces en lo mismo, agrego la regla

Lo que NUNCA hacemos

1. ❌ NUNCA merge sin review — código generado por IA recibe el MISMO nivel de review que código humano
2. ❌ NUNCA hardcodear secrets — ni en configs, ni en prompts, ni en rules
3. ❌ NUNCA confiar ciegamente — Claude es un copiloto, no un autopiloto. Tú eres el responsable
4. ❌ NUNCA desactivar entire.io — la trazabilidad no es negociable
5. ❌ NUNCA usar Claude en producción directamente — no correr comandos destructivos en prod con IA
6. ❌ NUNCA compartir contexto sensible — datos de clientes reales, credentials de producción, datos financieros reales NO van en prompts
7. ❌ NUNCA saltar el flujo — task → code → test → review → PR. Sin atajos

12. Preguntas frecuentes y troubleshooting

"Claude no lee mi CLAUDE.md"

• Verifica que el archivo se llame exactamente CLAUDE.md (mayúsculas, sin extensión extra)
• Debe estar en la raíz del repo o en el directorio donde ejecutas claude
• Ejecuta claude (no claude chat) para el modo completo

"Mi sesión de Claude se puso lenta / empezó a dar respuestas malas"

• Context rot en acción. La sesión acumuló demasiado contexto.
• Solución: cierra la sesión, abre una nueva. El CLAUDE.md te da el contexto base de vuelta.
• Para tareas largas: usa GSD que maneja context fresco por plan.

"¿Cuánto cuesta Claude Code por dev?"

• Claude Code usa tu suscripción de Anthropic o API key.
• El equipo tiene API key compartida para desarrollo — pídela al tech lead.
• Monitoreo de uso: revisamos costos semanalmente.

"¿Puedo usar GitHub Copilot también?"

• Sí. Copilot para autocompletar inline, Claude Code para tareas más grandes (features, refactors, debugging complejo).
• No se excluyen mutuamente.

"entire.io no me graba la sesión"

• Verifica: entire status — debe decir "active"
• Verifica: entire init en el repo
• Si sigue sin funcionar, reportar al tech lead con el output de entire status

"¿Cómo actualizo el team-ai-context en mi repo?"

cd tu-repo
git submodule update --remote .ai-context
git add .ai-context
git commit -m "chore: update team-ai-context"

"Claude generó código que rompe los tests existentes"

• Esto pasa cuando el CLAUDE.md no tiene suficiente contexto sobre tests.
• Agrega una sección de testing al CLAUDE.md con los patterns de test del repo.
• Regla: siempre pide a Claude que corra npm run test antes de confirmar que terminó.

"¿Puedo personalizar mi Claude sin afectar al equipo?"

• Sí. Tu ~/.claude/CLAUDE.md personal no se comparte.
• Tus preferencias (tema, verbosidad, idioma) van ahí.
• Las convenciones del equipo van en el CLAUDE.md del repo.

"Los MCP servers no se conectan"

• Verifica que las env vars estén seteadas: echo $GITHUB_TOKEN
• Verifica .mcp.json syntax: cat .mcp.json | python3 -m json.tool
• Los MCP corren localmente — necesitas tener Node.js instalado

"¿Cuándo uso GSD vs. Claude Code normal?"

• GSD: Proyecto nuevo, refactor grande, migración, feature que toca 3+ módulos
• Claude Code normal: Bug fixes, features chicos, exploratory coding, debugging

Próximos pasos

1. Esta semana: Instala Claude Code y entire.io. Lee esta guía completa.
2. Siguiente semana: Crea el CLAUDE.md de tu repo principal. Abre tu primer PR con trazabilidad.
3. Este mes: Completa las semanas 1-3 del onboarding.

Si tienes preguntas, el canal #ai-engineering en Slack es el lugar. Los tech leads de cada squad están disponibles para ayudar con la configuración.

Esto no es una moda. Es cómo vamos a trabajar de ahora en adelante. La IA como multiplicador del equipo, no como juguete individual.

— Angel