02 · Onboarding
Entrar a un equipo nuevo ya es suficientemente difícil.
El entorno, el código y las convenciones no deberían serlo.
Este capítulo define cómo una persona nueva se integra al equipo de forma rápida, segura y sin depender de “pregúntale a alguien”.
No busca que memorices todo el playbook el primer día, sino que:
- sepas dónde está la información
- puedas trabajar sin romper cosas
- entiendas por qué trabajamos así
Objetivo del onboarding
Un onboarding exitoso no es “leer documentos”, es poder hacer cosas.
Al finalizar este proceso, cualquier persona del equipo debería poder:
- ejecutar el proyecto localmente
- entender la estructura general del repo
- correr tests y scripts básicos
- hacer un PR pequeño siguiendo las convenciones
Si esto no pasa, el onboarding no funcionó, aunque el checklist esté completo.
Por qué el onboarding suele fallar
En muchos equipos, el onboarding es implícito:
- no está documentado
- depende de personas específicas
- varía según el proyecto
Eso genera:
- semanas de baja productividad
- miedo a tocar cosas
- preguntas repetidas
- errores evitables
Patrón común
“Esto lo aprendí a los 3 meses, nadie me lo explicó.”
Este playbook existe, en parte, para que eso no vuelva a pasar.
Filosofía de este onboarding
Este onboarding sigue tres ideas simples:
1️⃣ Autonomía primero
La documentación debe permitirte avanzar sin bloquearte.
Si necesitas pedir ayuda, perfecto.
Pero no debería ser el único camino.
2️⃣ Convenciones > instrucciones largas
No esperamos que recuerdes todo, pero sí que:
- sepas qué es estándar
- reconozcas cuándo algo se sale del camino habitual
3️⃣ Seguridad para equivocarse
Un buen onboarding:
- reduce el miedo a romper cosas
- deja claro qué es seguro probar
- y qué requiere más cuidado
Qué hacer en los primeros días
No es una lista rígida, es una ruta recomendada.
Día 1 – Orientación y contexto
- Lee el
index.mdpara entender el mapa general - Recorre Visión y principios para entender el por qué
- Clona el repo y corre el proyecto sin modificar nada
El objetivo del primer día no es producir código, sino quitar incertidumbre.
Tip
Si el proyecto no corre localmente en el día 1, hay un problema más grande que onboarding.
Días 2–3 – Manos en el código
- Configura tu entorno (ver Entornos y dependencias)
- Explora la estructura del proyecto
- Corre tests y scripts comunes
- Lee PRs recientes para entender el estilo del equipo
Empiezas a construir modelo mental, no features.
Primer PR – Pequeño y seguro
El primer PR ideal:
- es pequeño
- no toca lógica crítica
- sigue las convenciones
- sirve para practicar el flujo
Ejemplos típicos:
- mejorar documentación
- agregar un test
- refactor mínimo
Info
El objetivo del primer PR no es el impacto técnico,
es aprender a colaborar dentro del sistema.
Qué NO esperamos en onboarding
Para evitar frustraciones innecesarias:
- no se espera que conozcas todo el dominio
- no se espera que memorices el playbook
- no se espera que tomes decisiones arquitectónicas
Eso viene después.
El onboarding es para reducir fricción, no para evaluar performance.
Señales de que el onboarding va bien
- puedes trabajar sin pedir permiso para cada paso
- sabes dónde buscar respuestas
- los PRs son fáciles de revisar
- los errores son pequeños y recuperables
Cuando esto pasa, el equipo escala mejor y el conocimiento deja de estar en pocas cabezas.
Si algo no está claro
Este onboarding asume algo importante:
Regla no negociable
Si algo no está documentado y genera fricción, es responsabilidad del equipo mejorarlo.
Eso incluye:
- pasos faltantes
- supuestos implícitos
- decisiones no explicadas
El playbook no es estático.
Mejora cada vez que alguien nuevo lo recorre.
Cierre
Un buen onboarding no hace que la gente avance más rápido a corto plazo.
Hace que cometa menos errores caros a largo plazo.
Si este capítulo te permitió moverte con más seguridad, entonces está cumpliendo su función.