El Costo del Onboarding Manual y Por Que AI lo Transforma

Descripción de la capsula

Llegas a un equipo nuevo. Te asignan un codebase de 20K lineas con documentación parcial, una wiki desactualizada, y un companero que "te puede explicar cuando tenga tiempo." Las primeras dos semanas las pasas leyendo código, haciendo grep, preguntando en Slack, y construyendo un mental model fragmentado que no encaja hasta la tercera semana. Es la experiencia universal de onboarding en software — y es extraordinariamente cara.

Esta capsula pone numeros concretos al problema. El onboarding manual a un codebase mediano cuesta entre $15K y $30K en productividad perdida por developer. No por incompetencia — por la naturaleza del proceso: leer código es lento, el contexto se pierde entre archivos, la documentación miente, y el conocimiento tribal vive en la cabeza de personas que estan ocupadas. Vas a entender por que el proceso es lento, que lo hace costoso, y como Claude Code cambia la ecuacion al hacer que la lectura y el análisis de código sean orders of magnitude mas rapidos.

Al final de esta capsula tendras una comprension clara del problema que resolvemos en este módulo, habras visto tu primera demo de Claude Code explorando un proyecto desconocido, y tendras la motivacion basada en datos para invertir en un método sistematico de onboarding con AI.

El Costo Real del Onboarding Manual

Los numeros que nadie mide

Cuando un developer se une a un equipo existente, el tiempo hasta productividad plena sigue un patron predecible:

El costo directo:

Para un developer con salario de $100K-$150K anuales (o equivalente ajustado por región):

Salario diario aproximado: $400-$600
Dias de onboarding (productividad < 50%): 10-20 dias
Costo de productividad perdida: $4,000-$12,000

+ Costo del mentor/buddy que dedica 2-4 hrs/dia: $2,000-$5,000
+ Costo de code reviews mas lentos (explican mas): $1,000-$3,000
+ Costo de bugs por comprension incompleta: $2,000-$10,000

Rango total: $9,000-$30,000 por developer nuevo

Estos numeros son conservadores. En empresas con codebases mas grandes o complejos, el onboarding puede extenderse a 2-3 meses. Y el costo se multiplica: si tu equipo contrata 5 personas al ano, estas gastando $45K-$150K anuales solo en onboarding.

Lo que no aparece en el balance

Mas alla del costo directo, hay costos invisibles:

• El developer nuevo no contribuye features durante semanas. El roadmap se atrasa.
• El mentor pierde sus propias horas productivas. Dos personas operan a capacidad reducida.
• Los primeros PRs del developer nuevo generan mas rondas de code review. El equipo entero se desacelera.
• La frustración es real. Un developer senior que pasa 3 semanas sin poder contribuir se desmotiva. Algunos se van antes de terminar el onboarding.

El costo compuesto

El verdadero impacto se ve a escala:

# Calculo del costo anual de onboarding para un equipo

def calculate_onboarding_cost(
    new_developers_per_year: int = 5,
    cost_per_onboarding_min: int = 9_000,
    cost_per_onboarding_max: int = 30_000,
    turnover_rate: float = 0.15  # 15% de rotacion anual
):
    """
    Calcula el costo anual de onboarding para un equipo.
    Incluye nuevas contrataciones + rotacion interna.
    """
    # Contrataciones nuevas
    new_hires_cost_min = new_developers_per_year * cost_per_onboarding_min
    new_hires_cost_max = new_developers_per_year * cost_per_onboarding_max
    
    # Rotacion interna (cambios de equipo/proyecto)
    internal_changes = int(new_developers_per_year / turnover_rate * 0.10)
    internal_cost_min = internal_changes * (cost_per_onboarding_min * 0.5)
    internal_cost_max = internal_changes * (cost_per_onboarding_max * 0.5)
    
    total_min = new_hires_cost_min + internal_cost_min
    total_max = new_hires_cost_max + internal_cost_max
    
    return {
        "annual_range": f"${total_min:,.0f} - ${total_max:,.0f}",
        "new_hires": f"${new_hires_cost_min:,.0f} - ${new_hires_cost_max:,.0f}",
        "internal_turnover": f"${internal_cost_min:,.0f} - ${internal_cost_max:,.0f}"
    }

result = calculate_onboarding_cost()
print(f"Costo anual total: {result['annual_range']}")
print(f"  Nuevas contrataciones: {result['new_hires']}")
print(f"  Rotacion interna: {result['internal_turnover']}")

# Output esperado:
# Costo anual total: $59,500 - $195,000
# Nuevas contrataciones: $45,000 - $150,000
# Rotacion interna: $14,500 - $45,000

Por Que el Onboarding Es Lento

El onboarding no es lento por falta de inteligencia o habilidad. Es lento por razones estructurales que afectan a todos los developers por igual.

Razon 1: Leer código es mas difícil que escribirlo

Escribir código es un proceso creativo donde tu controlas las decisiones. Leer código es un proceso de ingenieria inversa donde debes reconstruir las decisiones de otro. Es como leer un libro comenzando por el capitulo 7: necesitas inferir lo que paso en los capitulos anteriores.

El código no se lee linealmente. Un archivo importa funciones de otros 5 archivos. Una clase hereda de otra en un módulo diferente. Un decorador modifica el comportamiento de forma no obvia. Para entender una sola función, a veces necesitas leer 10 archivos.

# Ejemplo: para entender QUE hace esta funcion...
@require_auth
@rate_limit(max_calls=100, period=3600)
@cache(ttl=300)
async def get_user_dashboard(user_id: int, db: Session = Depends(get_db)):
    user = await user_service.get_with_preferences(user_id, db)
    stats = await analytics_service.get_user_stats(user_id, db)
    recommendations = await recommendation_engine.for_user(user, stats)
    return DashboardResponse(user=user, stats=stats, recommendations=recommendations)

# ...necesitas entender ESTOS archivos:
# 1. auth/decorators.py        -> que hace @require_auth?
# 2. middleware/rate_limit.py   -> como funciona el rate limiting?
# 3. cache/decorators.py       -> que se cachea y por cuanto?
# 4. dependencies.py           -> que es get_db?
# 5. services/user_service.py  -> que hace get_with_preferences?
# 6. services/analytics.py     -> que stats se calculan?
# 7. services/recommendations.py -> como funciona el engine?
# 8. schemas/dashboard.py      -> que incluye DashboardResponse?

# Son 8 archivos para entender 4 lineas de codigo.

Razon 2: El contexto se pierde entre archivos

Cuando lees user_service.py, entiendes como funciona el servicio de usuarios. Luego abres auth_middleware.py para entender la autenticación. Para cuando terminas auth, ya se te olvido la mitad de lo que leiste en user_service. Es el problema de la memoria de trabajo: un humano puede mantener 5-9 chunks de información activos. Un codebase mediano tiene cientos de chunks relevantes.

# Tu sesion de exploracion manual tipica:
#
# 09:00 - Abres user_service.py      -> "Ah, usa repository pattern"
# 09:15 - Abres user_repository.py   -> "SQLAlchemy, OK"
# 09:30 - Abres auth_middleware.py    -> "JWT tokens, entiendo"
# 09:45 - Abres payment_service.py   -> "Stripe API... espera,
#          como se conecta esto con los usuarios?"
# 10:00 - Vuelves a user_service.py  -> "Ya se me olvido que vi aqui"
# 10:15 - Frustracion. Llevas 1.5 hrs y tu mental model es fragmentado.

Razon 3: La documentación miente

No por malicia — por desactualizacion. El README dice "usa Flask" pero el equipo migro a FastAPI hace 6 meses. La wiki describe una arquitectura de 3 capas pero el código real tiene 5. Los comentarios en el código dicen "TODO: refactorizar esto" desde 2021. La documentación es una snapshot congelada de un codebase que sigue evolucionando.

Razon 4: El conocimiento tribal

"Por que el módulo de pagos tiene esa estructura rara?" "Ah, eso fue porque en 2022 tuvimos un incidente con Stripe y tuvimos que agregar un retry layer de emergencia. Juan lo hizo. Ya no esta en la empresa."

El conocimiento mas valioso sobre un codebase vive en la cabeza de las personas que lo construyeron. Cuando esas personas se van, el conocimiento se pierde. No hay documentación que capture el "por que" detras de cada decisión.

Razon 5: Context switching constante

El onboarding manual es un loop infinito de:

1. Abrir un archivo
2. Encontrar una función interesante
3. Ver que importa algo de otro módulo
4. Abrir ese módulo
5. Perder el hilo de por que abriste el primer archivo
6. Volver al primer archivo
7. Repetir

Cada switch de contexto tiene un costo cognitivo. Después de 2 horas de este loop, la productividad cae dramaticamente.

Como AI Cambia la Ecuacion

La ventaja fundamental: velocidad de lectura

Un humano lee código a ~200-400 lineas por hora con comprension profunda. Claude Code puede procesar miles de lineas en segundos. Pero no es solo velocidad — es la capacidad de mantener todo en contexto simultaneamente.

Cuando le preguntas a Claude Code "como funciona el sistema de autenticación?", no abre un archivo a la vez. Lee todos los archivos relevantes, traza las dependencias, y te da una respuesta que integra información de multiples fuentes. Es como si pudieras leer 20 archivos simultaneamente y recordar cada detalle.

Ventaja 1: Cross-file analysis instantaneo

Lo que a un humano le toma horas (rastrear un flujo de datos a traves de 10 archivos), Claude Code lo hace en una sola interaccion:

# En tu terminal, dentro del directorio del proyecto:
claude

> En este proyecto, como fluye un request desde que llega al endpoint 
  /api/users hasta que se guarda en la base de datos? Muestrame cada 
  archivo y funcion involucrada.

Output esperado de Claude Code:

Flujo de POST /api/users:

1. app/api/routes/users.py:create_user()
   -> Recibe UserCreateSchema (Pydantic validation)
   -> Llama user_service.create()

2. app/services/user_service.py:create()
   -> Verifica email no duplicado via repository
   -> Hash password con bcrypt (core/security.py)
   -> Crea instancia de UserModel

3. app/repositories/user_repo.py:create()
   -> session.add(user_model)
   -> session.commit()
   -> session.refresh(user_model)

4. Retorna UserResponseSchema (excluye password_hash)

Archivos involucrados: 5 (routes, service, repository, schemas, security)

Claude Code lee los archivos relevantes, identifica la cadena de llamadas, y produce un mapa del flujo completo. No pierde contexto entre archivos porque los tiene todos en memoria.

Ventaja 2: Pattern recognition a escala

Un developer nuevo necesita leer suficiente código para detectar los patterns del proyecto. "Ah, aquí usan repository pattern." "Los DTOs se definen con Pydantic." "Los errores se manejan con custom exceptions." Detectar esos patterns manualmente requiere leer docenas de archivos.

claude

> Analiza este proyecto y dime que design patterns se usan. 
  Dame ejemplos concretos de cada uno con el archivo donde se encuentran.

Output esperado:

Design patterns identificados:

1. Repository Pattern
   - user_repo.py, task_repo.py, tag_repo.py
   - Cada entidad tiene un repositorio que encapsula queries
   
2. Service Layer
   - services/ directory completo
   - Logica de negocio separada de endpoints y data access
   
3. DTO Pattern (via Pydantic)
   - schemas/ directory
   - Schemas separados para Create, Update, Response
   
4. Dependency Injection
   - Depends(get_db), Depends(get_current_user)
   - FastAPI DI nativo
   
5. Middleware Pattern
   - CORS, error handling, request logging
   - Registrados en main.py

Consistencia: Alta. Solo el modulo de reportes (reports/) 
no sigue el pattern service->repository — accede a la DB directamente.

Ventaja 3: Preguntas directas, respuestas inmediatas

En el onboarding manual, tienes que esperar a que tu mentor tenga tiempo para responder. Con Claude Code, preguntas y recibes respuesta inmediatamente:

claude

> Por que este proyecto tiene dos modulos de autenticacion 
  (auth/ y auth_v2/)? Cual se usa actualmente?

Output esperado:

auth/ vs auth_v2/:

- auth/ contiene el sistema original basado en sessions.
  Solo lo usa el endpoint legacy /api/v0/login.
  
- auth_v2/ es el sistema actual basado en JWT.
  Lo usan todos los endpoints v1.
  
- El archivo auth/__init__.py tiene un comentario:
  "# DEPRECATED: usar auth_v2. Mantener para backward compatibility."
  
- 95% del codigo usa auth_v2. auth/ se puede considerar legacy.

Recomendacion: para nuevo desarrollo, usa auth_v2 exclusivamente.

Claude Code analiza el código, ve los imports, identifica cual esta activo, y te explica. No necesitas interrumpir a nadie.

Ventaja 4: No se cansa, no se frustra

En la hora 6 de lectura de código, un humano esta fatigado. Su capacidad de retencion cae. Comete errores de comprension. Claude Code mantiene la misma capacidad de análisis en la primera pregunta y en la número 50.

Claude Code: Ventajas Especificas para Onboarding

Lee el codebase en su contexto

Claude Code con el modelo Opus tiene acceso a una ventana de contexto de 1M tokens. Para un codebase mediano (5K-30K lineas), puede tener una porcion significativa del proyecto en contexto simultaneamente. No necesita abrir archivos uno por uno.

Responde preguntas sobre estructura

Una de las primeras cosas que necesitas saber al entrar a un codebase es como esta organizado:

claude

> Describe la estructura de directorios de este proyecto. 
  Que hace cada carpeta principal? Que patron de arquitectura sigue?

Output esperado:

Este proyecto sigue una arquitectura de capas (layered architecture):

src/
+-- api/          -> Capa de presentacion: endpoints FastAPI
|   +-- v1/       -> Versionado de API (v1 activa)
|   +-- deps.py   -> Dependencias compartidas (auth, DB session)
+-- models/       -> Capa de datos: modelos SQLAlchemy
+-- schemas/      -> DTOs: schemas Pydantic para request/response
+-- services/     -> Capa de negocio: logica de dominio
+-- repositories/ -> Capa de acceso a datos: queries a la DB
+-- core/         -> Cross-cutting: config, security, exceptions

Patron: Service Layer + Repository Pattern
- Los endpoints llaman a services
- Los services llaman a repositories
- Los repositories hablan con la DB
- Los schemas validan entrada/salida

Traza flujos de datos

Uno de los análisis mas valiosos y mas dificiles de hacer manualmente:

claude

> Traza el flujo completo de creacion de un usuario: desde el 
  request HTTP hasta el commit en la base de datos. Incluye 
  validaciones, transformaciones, y manejo de errores.

Output esperado:

Flujo de creacion de usuario:

1. POST /api/v1/users (api/v1/users.py:create_user)
   -> Recibe UserCreateSchema (schemas/user.py)
   -> Pydantic valida: email format, password length

2. UserService.create(data) (services/user_service.py:create)
   -> Verifica email no duplicado -> llama repo.get_by_email()
   -> Hash password -> core/security.py:hash_password()
   -> Crea UserModel desde data

3. UserRepository.create(user) (repositories/user_repo.py:create)
   -> session.add(user)
   -> session.commit()
   -> session.refresh(user)

4. Return UserResponseSchema (sin password hash)

Errores posibles:
- 422: Pydantic validation (email invalido, password corto)
- 409: Email duplicado (service level check)
- 500: DB connection error (handled by middleware)

Obtener este nivel de detalle manualmente requiere abrir 5-6 archivos, rastrear imports, y mantener el flujo en la cabeza. Con Claude Code, es una sola pregunta.

Identifica tech debt y quirks

El conocimiento tribal que se pierde cuando la gente se va del equipo, Claude Code lo puede inferir del código:

claude

> Identifica posible tech debt en este proyecto. Hay patterns 
  inconsistentes, codigo duplicado, TODOs pendientes, o practicas 
  que deberian actualizarse?

Output esperado:

Tech debt identificado:

1. TODOs pendientes (7 encontrados):
   - services/payment.py:45 "# TODO: agregar retry logic"
   - models/user.py:12 "# TODO: migrar a UUID"
   - api/v1/tasks.py:89 "# TODO: agregar paginacion"

2. Inconsistencias:
   - reports/ accede a DB directamente (no usa repository pattern)
   - Algunos endpoints retornan dict, otros retornan schemas
   
3. Codigo duplicado:
   - Logica de paginacion copiada en 4 endpoints
   - Validacion de permisos repetida (deberia ser middleware)
   
4. Dependencias desactualizadas:
   - SQLAlchemy 1.4 (actual: 2.0)
   - pydantic v1 (actual: v2)
   
5. Dead code:
   - utils/legacy_helpers.py no tiene imports desde ningun archivo
   - auth/session_auth.py solo lo usa un endpoint deprecated

Primera Demo: Explorando un Proyecto con Claude Code

Vas a ver una sesión real de Claude Code explorando un proyecto desconocido. Este es un proyecto Python mediano — una API REST para gestión de tareas.

Paso 1: Entender la estructura

# Clonas el proyecto
git clone https://github.com/example/task-api.git
cd task-api

# Abres Claude Code
claude

> Acabo de clonar este proyecto y nunca lo he visto antes. Dame un 
  overview de la estructura: que carpetas hay, que framework usa, 
  como esta organizado el codigo.

Output esperado de Claude Code:

Este es un proyecto FastAPI para gestion de tareas.

Estructura principal:
app/
+-- main.py           -> Entry point, crea la app FastAPI
+-- api/
|   +-- routes/       -> Endpoints organizados por recurso
|       +-- tasks.py  -> CRUD de tareas
|       +-- users.py  -> Registro, login, perfil
|       +-- tags.py   -> Etiquetas para tareas
+-- models/           -> Modelos SQLAlchemy (ORM)
|   +-- task.py
|   +-- user.py
|   +-- tag.py
+-- schemas/          -> Pydantic schemas
+-- services/         -> Logica de negocio
+-- db/               -> Config de base de datos, session
+-- core/             -> Settings, auth (JWT), middleware

Tests en tests/ con pytest. Config en pyproject.toml.
Usa Alembic para migraciones (alembic/ dir).
Docker disponible (docker-compose.yml).

Paso 2: Identificar entry points

> Cual es el entry point de la aplicacion? Como se levantan los 
  routes? Muestrame el flujo desde main.py hasta los endpoints.

Output esperado:

Entry point: app/main.py

Flujo:
1. main.py crea FastAPI() app
2. Incluye routers:
   - app.include_router(tasks.router, prefix="/api/v1/tasks")
   - app.include_router(users.router, prefix="/api/v1/users")  
   - app.include_router(tags.router, prefix="/api/v1/tags")
3. Middleware: CORS, error handler global
4. Startup event: conecta a DB, corre migraciones pendientes
5. Se levanta con: uvicorn app.main:app

Cada router define sus endpoints con decoradores @router.get(), 
@router.post(), etc. Dependencies inyectadas via Depends().

Paso 3: Entender un flujo de datos

> Como funciona la creacion de una tarea? Desde que llega el request 
  hasta que se guarda en la DB. Que validaciones hay?

Paso 4: Descubrir patterns

> Que patterns de diseno se usan en este proyecto? Es consistente 
  en su uso? Hay algun modulo que no siga el pattern general?

Paso 5: Identificar posibles problemas

> Ves tech debt o posibles problemas en este codebase? TODOs 
  pendientes, codigo duplicado, inconsistencias, dependencias 
  desactualizadas.

En 5 preguntas y menos de 10 minutos, tienes un overview que manualmente habria tomado 2-3 horas. No es comprension total — pero es suficiente para empezar a ser productivo y saber donde profundizar.

Comparacion: Onboarding Manual vs Onboarding con Claude Code

La diferencia clave: el output

El onboarding manual produce comprension individual efimera. Si no la documentas (y casi nadie lo hace), se pierde cuando cambias de proyecto o cuando alguien nuevo llega.

El onboarding con Claude Code produce un artefacto tangible: un onboarding doc que captura la comprension. Ese documento sirve para ti (referencia futura), para tu equipo (el siguiente developer nuevo), y para el proyecto (documentación actualizada).

Cuando el Onboarding con AI Tiene Mayor Impacto

No todos los escenarios son iguales. El onboarding con AI tiene mayor impacto en:

Alto impacto:

• ✅ Codebase mediano-grande (5K-100K+ lineas): Suficiente complejidad para que la exploracion manual sea costosa
• ✅ Documentación incompleta o desactualizada: Claude Code lee el código real, no la documentación
• ✅ Multiples frameworks o tecnologias: Claude Code conoce la mayoria de frameworks populares
• ✅ Equipo distribuido o sin disponibilidad para mentoring: Claude Code esta siempre disponible
• ✅ Contribucion a open source: No hay mentor; Claude Code es tu guia

Menor impacto:

• ⚠️ Codebase trivial (< 1K lineas): Lo puedes leer directamente en 30 minutos
• ⚠️ Código con documentación excelente y actualizada: La documentación ya te da el context
• ⚠️ Lenguajes o frameworks muy nicho: Claude Code puede tener menos conocimiento especializado

Conexión con Proyecto

Lo que practicaras en el mini-proyecto (capsula 06):

En el proyecto del módulo vas a aplicar exactamente lo que viste en la demo de esta capsula, pero en un codebase real open-source. La diferencia: en la demo viste preguntas aisladas. En el proyecto vas a ejecutar las 5 preguntas en secuencia sistematica (que aprenderas en la capsula 03) y producir un onboarding doc completo.

Como conecta con lo que viene:

Capsula 02 (esta):  Entiendes POR QUE el onboarding es costoso y como AI ayuda
         |
Capsula 03 (siguiente): Aprendes QUE preguntar y EN QUE ORDEN
         |
Capsula 04: Aprendes a construir el MENTAL MODEL
         |
Capsula 05: Aprendes a DOCUMENTAR los hallazgos
         |
Capsula 06: Haces TODO junto en un codebase real

Troubleshooting

Problema 1: "Claude Code no conoce mi framework/lenguaje"

Causa: Frameworks nicho o lenguajes menos populares pueden tener menor cobertura en el modelo.

Solución:

# En vez de preguntar sin contexto:
> Que hace este codigo?

# Proporciona contexto explicito:
> Este proyecto usa el framework Litestar (antes Starlite) para Python.
  Es similar a FastAPI pero con un approach diferente a la DI.
  Explicame la estructura del proyecto sabiendo esto.

También puedes incluir documentación del framework en el prompt usando @-references a archivos relevantes. Para la mayoria de frameworks populares (FastAPI, Django, Flask, Express, Rails, Spring), Claude Code tiene excelente cobertura.

Problema 2: "Las respuestas de Claude Code son demasiado generales"

Causa: Prompt vago o demasiado amplio.

Solución:

# Demasiado general:
> Explicame este proyecto.

# Especifico y accionable:
> Como fluye un request desde el endpoint POST /api/tasks 
  hasta que se guarda en la base de datos? Muestrame cada 
  archivo y funcion involucrada, incluyendo validaciones.

Cuanto mas especifica la pregunta, mas especifica la respuesta. Si la respuesta inicial es general, haz preguntas de seguimiento: "profundiza en el paso 3" o "muestrame el código de esa función."

Problema 3: "El codebase es muy grande y Claude Code no puede leerlo todo"

Causa: Codebases de 100K+ lineas exceden lo que se puede procesar en una sola sesión.

Solución:

# En vez de pedir que analice todo:
> Analiza todo el proyecto.

# Enfoca en modulos especificos:
> Analiza solo la carpeta src/auth/ y explicame como funciona 
  la autenticacion en este proyecto.

Para este módulo, trabaja con codebases medianos (5K-30K lineas). El Módulo 6 cubre context management para proyectos grandes.

Problema 4: "No se si la respuesta de Claude Code es correcta"

Causa: Preocupacion legitima — los modelos pueden cometer errores.

Solución:

# Despues de que Claude Code te explique algo, valida:
> Muestrame el codigo exacto de la funcion create_user en 
  services/user_service.py para verificar lo que me dijiste.

La regla: confia pero verifica. Si Claude Code dice "el entry point es main.py", abre main.py y verifica. La capsula 04 cubre tecnicas de validación del mental model.

Problema 5: "Mi equipo no va a adoptar onboarding con AI"

Causa: Resistencia al cambio o escepticismo.

Solución: No propongas un cambio de proceso. Hazlo tu silenciosamente. Cuando tu onboarding sea 5x mas rápido que el promedio, el resultado habla por si solo. Comparte tu onboarding doc con el equipo como contribucion. Cuando vean la calidad y velocidad, la adopcion ocurre naturalmente.

Ejercicios

Ejercicio 1: Calcular tu costo de onboarding (Fácil)

Piensa en la ultima vez que te uniste a un proyecto existente (trabajo, open source, o proyecto de estudios). Estima:

1. Cuantos dias tardaste en entender la estructura general?
2. Cuantos dias hasta tu primer PR significativo?
3. Cuantas horas de tu mentor o companeros consumiste?

Calcula un costo aproximado usando tu tasa diaria (o la de un developer en tu mercado).

# Calcula tu costo personal de onboarding

structure_days = 5          # dias para entender la estructura general
first_pr_days = 12          # dias hasta el primer PR significativo
mentor_hours = 20          # horas de mentor/companeros consumidas
your_hourly_rate = 50      # tu tasa por hora (USD)
mentor_hourly_rate = 60    # tasa del mentor por hora (USD)

# Calculo
low_productivity_hours = first_pr_days * 4  # 4 hrs/dia de baja productividad
my_cost = low_productivity_hours * your_hourly_rate
mentor_cost = mentor_hours * mentor_hourly_rate
extra_code_review = 400  # estimado conservador

total = my_cost + mentor_cost + extra_code_review
print(f"Costo total estimado: ${total:,.0f}")
print(f"  Mi productividad reducida: ${my_cost:,.0f}")
print(f"  Tiempo de mentor: ${mentor_cost:,.0f}")
print(f"  Code reviews extra: ${extra_code_review:,.0f}")

# Output esperado:
# Costo total estimado: $4,000
#   Mi productividad reducida: $2,400
#   Tiempo de mentor: $1,200
#   Code reviews extra: $400

Ejercicio 2: Identificar razones de lentitud (Fácil)

De las 5 razones por las que el onboarding es lento (listadas en esta capsula), identifica cuales aplican a tu proyecto actual o último proyecto:

1. Leer código es mas difícil que escribirlo
2. El contexto se pierde entre archivos
3. La documentación miente (esta desactualizada)
4. El conocimiento tribal no esta documentado
5. Context switching constante

Para cada una que aplique, da un ejemplo concreto de tu experiencia.

Ejercicio 3: Primera exploracion con Claude Code (Medio)

Clona un proyecto open-source pequeno que nunca hayas visto. Sugerencias:

• httpx — HTTP client para Python
• typer — CLI framework
• rich — Terminal formatting

Abre Claude Code en el directorio del proyecto y haz estas 3 preguntas:

# Clona el proyecto
git clone https://github.com/tiangolo/typer.git
cd typer

# Abre Claude Code
claude

# Pregunta 1:
> Cual es la estructura de este proyecto? Que hace cada carpeta principal?

# Pregunta 2:
> Cual es el entry point principal? Como se usa esta libreria?

# Pregunta 3:
> Que patterns de diseno se usan?

Documenta las respuestas y el tiempo que te tomo.

Pregunta 1 — Estructura (tiempo: ~30 segundos):

typer/
+-- typer/           -> Codigo fuente principal
|   +-- __init__.py  -> Exporta Typer, Argument, Option
|   +-- main.py      -> Clase Typer principal
|   +-- params.py    -> Argument y Option classes
|   +-- models.py    -> Modelos internos
|   +-- testing.py   -> CliRunner para tests
+-- tests/           -> Tests con pytest
+-- docs/            -> Documentacion MkDocs
+-- pyproject.toml   -> Config del proyecto

Pregunta 2 — Entry point (tiempo: ~30 segundos):

El entry point es la clase Typer en typer/main.py.
Uso: crear instancia de Typer(), decorar funciones con @app.command(),
llamar app() en __main__. Click es la base — typer envuelve Click
con type hints.

Pregunta 3 — Patterns (tiempo: ~45 segundos):

- Decorator pattern: @app.command() registra funciones como comandos
- Facade pattern: Typer simplifica la API de Click
- Builder pattern: los parametros se construyen incrementalmente
- Convention over configuration: type hints determinan el comportamiento

Tiempo total: ~2 minutos para un overview funcional.
Manualmente habria tardado 30-60 minutos leyendo archivos.

Ejercicio 4: Comparar manual vs AI (Medio)

Usa el mismo proyecto del ejercicio 3. Intenta responder esta pregunta manualmente (sin AI) cronometrando el tiempo:

"Como maneja este proyecto los errores? Hay custom exceptions? Como llegan los errores al usuario?"

Después, haz la misma pregunta a Claude Code. Compara:

• Tiempo manual vs AI
• Completitud de la respuesta
• Confianza en la respuesta

claude

> Como maneja httpx los errores? Que custom exceptions hay? 
  Como llegan los errores al usuario?

Ejercicio 5: Identificar conocimiento tribal (Avanzado)

En el proyecto open-source que elegiste, pide a Claude Code:

claude

> Identifica decisiones de diseno no obvias en este proyecto. 
  Hay algo que parezca inusual, inesperado, o que solo tendria 
  sentido si supieras el contexto historico?

Evalua la respuesta: identifico cosas que no habrias notado leyendo el código directamente?

claude

> Identifica decisiones de diseno no obvias en el proyecto rich.

1. El modulo console.py es inusualmente grande (~2000 lineas).
   Razon probable: Console es el objeto central que orquesta 
   todo el rendering. Separarlo romperia el flujo de estado.

2. Hay un sistema de "protocol" interno (rich/protocol.py) que 
   permite que objetos se rendericen a si mismos. No es obvio 
   por que no usa __str__ o __repr__ — la razon es que el 
   rendering de Rich es mas complejo que texto plano.

3. El modulo _inspect.py tiene underscore prefix, lo que sugiere
   que es "privado," pero se exporta publicamente como 
   rich.inspect(). El underscore evita conflicto con el builtin 
   inspect de Python.

4. Hay renderables que parecen redundantes (Text vs Padding vs
   Panel) pero cada uno maneja un aspecto diferente del layout
   del terminal.

Ejercicio 6: Disenar tu proceso de onboarding (Avanzado)

Basandote en lo que aprendiste en esta capsula, disena un proceso de onboarding de 5 pasos que usarias la proxima vez que te asignen un codebase nuevo. Para cada paso, escribe:

1. La pregunta principal que harias a Claude Code
2. Que esperas obtener como output
3. Como validarias la respuesta

Resumen

En esta capsula aprendiste:

• ✅ El onboarding manual a un codebase mediano cuesta $9K-30K por developer en productividad perdida
• ✅ Es lento por razones estructurales: leer > escribir, perdida de contexto, docs desactualizadas, conocimiento tribal
• ✅ Claude Code cambia la ecuacion: cross-file analysis instantaneo, pattern recognition a escala, preguntas ilimitadas
• ✅ Las ventajas especificas: lee codebase completo, traza flujos de datos, identifica patterns y tech debt
• ✅ Comparacion directa: mental model en 30-60 min con AI vs 1-2 semanas manual
• ✅ El output del onboarding con AI es un artefacto (documento), no solo comprension individual efimera
• ✅ Mayor impacto en codebases medianos-grandes con documentación incompleta

Proxima capsula: Exploracion Sistematica — Que Preguntar y en Que Orden — las 5 preguntas iniciales, por que el orden importa (big picture primero, detalles después), y prompts practicos para cada pregunta.

Recursos Adicionales

1. The Onboarding Problem in Software Engineering — Stripe Engineering Blog — Perspectiva de una empresa grande sobre el costo del onboarding
2. Working Effectively with Legacy Code — Michael Feathers — Capitulo 1 sobre el costo de no entender código existente
3. Claude Code Documentation — Anthropic — Features de análisis y exploracion de código
4. Measuring Developer Productivity — ACM Queue — Framework para medir productividad de developers (incluye onboarding)
5. The Mythical Man-Month — Fred Brooks — El clasico sobre por que agregar personas a un proyecto no lo acelera linealmente
6. Google's Engineering Practices — Code Review Guide — Como Google maneja code review y onboarding de developers
7. httpx — Python HTTP Client — Proyecto sugerido para ejercicios de exploracion
8. typer — CLI Framework — Proyecto sugerido para ejercicios de exploracion

Siguiente capsula: Exploracion Sistematica — Que Preguntar y en Que Orden — las 5 preguntas iniciales, por que el orden importa (big picture primero, detalles después), y prompts practicos para cada pregunta.

Módulo 1, Capsula 02 — Refactoring & Legacy Code with Claude Code Guide