Mi Plante — Kit de Onboarding para Desarrolladores Nuevos

Mi Plante — Hero

Bienvenido. Te estás uniendo a Mi Plante, un marketplace de crédito fintech colombiano construido sobre Laravel 12, Inertia.js, Vue 3 y MySQL. El equipo de ingeniería anterior ya no está. El producto está en producción. Los clientes lo están usando para comprar a crédito en este momento. Estás entrando en frío.

Este kit es el puente. Es la diferencia entre una curva de ramp-up de seis semanas y una de cinco días. Si lo lees en el orden que sugiere, manejas Claude Code con los prompts que te entrega y sigues el currículo de la semana 1, vas a entregar tu primer PR antes del viernes y llegarás a la semana 2 con el conocimiento operativo de un desarrollador que lleva dos meses aquí.

Toma este kit en serio. Fue construido para ti por un equipo de auditoría que leyó cada línea del código que importa, mapeó cada integración externa y catalogó cada landmine. Dieciséis mil líneas de documentación entraron en él. El kit que estás leyendo ahora mismo existe para que todo ese esfuerzo aterrice en tu cabeza lo más rápido posible.

El pitch de 30 segundos

Mi Plante es un marketplace de crédito para colombianos que no pueden obtener fácilmente una tarjeta de crédito. Los clientes (llamados clientes) navegan productos de negocios aliados (llamados aliados), los compran a crédito con cuotas mensuales (llamadas cuotas), y pagan esas cuotas a través de la factura de servicios públicos de EMCALI que ya llega a su casa todos los meses. El ticket promedio es alrededor de 3.000.000 COP (~600 USD).

Stack: Laravel 12 + Inertia.js + Vue 3 + MySQL. Dos guards de autenticación (web para clientes, app para aliados y administradores). Seis integraciones externas (TransUnion, Experian CrossCore, DataCrédito, Certicámara, EMCALI, SHIVAM core). Español para términos del dominio, inglés para conceptos del framework.

Si quieres una sola línea para un pitch deck: “Klarna se encuentra con MercadoLibre se encuentra con tu factura de la luz.”

Para quién es este kit

Cada nuevo desarrollador en Mi Plante. Backend, frontend, full-stack, senior, mid, junior. El kit está estratificado: cada sección abre con contexto compartido que todo desarrollador necesita, y luego se estrecha en profundizaciones específicas por rol. El orden de lectura abajo tiene tracks para cada rol.

Si no eres desarrollador (PM, ops, customer success, sales engineering), lee solo 01-business/. Detente ahí. El resto está orientado a ingenieros y asume fluidez en Laravel/Vue.

Lo que podrás hacer para el viernes

A las 5pm del Día 5, cada nuevo desarrollador que sigue el currículo tiene:

La aplicación completa corriendo localmente en localhost:8000, incluyendo queue worker, visor de logs, Inertia SSR y hot reload de Vite.
Un modelo mental funcional del pipeline de crédito: las siete fases, las llamadas a APIs externas, los modos de fallo.
La capacidad de trazar cualquier petición HTTP desde routes/web.php (o routes/ally/web.php) a través de controller, service, DTO, model, queue job, listener, event y respuesta.
Una short-list memorizada de los landmines activos: dónde en el código no se puede pisar sin coordinación.
Al menos un PR fusionado a staging que cierre una tarea Tier 1 de 05-first-contributions/01-tier-1-tasks.md.
Claude Code instalado, configurado y usado como pair programmer para al menos una docena de prompts reales sobre el codebase real.

Esa es la meta. El resto de este README explica cómo llegar ahí.

Cómo usar este kit

El ritmo de 5 días

El plan completo hora por hora para la semana 1 vive en week-1-curriculum.md. Ábrelo antes de hacer cualquier otra cosa. Marca el ritmo del kit para que no tengas que descifrar el orden tú mismo. El Día 1 es negocio y arquitectura; el Día 2 es setup local y trazado de requests; el Día 3 es el pipeline de crédito y los landmines; el Día 4 entregas tu primer PR; el Día 5 entregas un segundo y haces un retro personal.

El currículo es una sugerencia, no un contrato. Más rápido está bien. Más lento está bien. Los MILESTONES diarios al final de cada bloque importan más que los tiempos del reloj.

El orden de lectura (recomendado)

Si lees este kit de tapa a tapa en este orden, cada página construye sobre la anterior y nada se desperdicia:

README.md (este archivo) — 10 minutos.
01-business/01-what-is-mi-plante.md — 30 minutos. El modelo de negocio de punta a punta.
01-business/02-who-are-the-users.md — 20 minutos. Las tres audiencias y las siete personas.
01-business/03-the-money-flow.md — 30 minutos. A dónde va cada peso.
02-codebase-tour/01-from-30000-feet.md — 60 minutos. El mapa de arquitectura.
02-codebase-tour/02-trace-a-request.md — 45 minutos. Browser a DB, una sola request.
02-codebase-tour/03-trace-a-sale.md — 60 minutos. Carrito a cuotas, venta completa.
02-codebase-tour/04-trace-a-credit-approval.md — 60 minutos. El pipeline de siete fases.
03-development-setup/01-local-environment.md — 90 minutos (mayormente esperando composer install).
03-development-setup/02-seed-data-walkthrough.md — 30 minutos. Qué hay en la base de datos.
03-development-setup/03-common-gotchas.md — 30 minutos. Trampas del desarrollo local.
04-the-landmines/01-known-bugs.md — 90 minutos. Las 2.487 líneas de peligros catalogados. Skim, luego indexa.
04-the-landmines/02-code-archaeology.md — 45 minutos. Por qué existen esos landmines.
06-ai-pair-programming/01-claude-code-setup.md — 30 minutos. Una vez, luego revisitar.
06-ai-pair-programming/03-prompt-cookbook.md — bookmark, no leer de punta a punta.
06-ai-pair-programming/04-when-not-to-trust-the-ai.md — 30 minutos. Las barreras de seguridad.
05-first-contributions/01-tier-1-tasks.md — 45 minutos. Elige uno.
05-first-contributions/03-how-to-ship.md — 30 minutos. Rama, commit, PR, deploy.
05-first-contributions/02-tier-2-tasks.md — 45 minutos. Elige uno para la semana 2.

Tiempo total estimado de lectura: alrededor de 12 horas. Repartido en la semana de 40 horas, eso deja 28 horas para setup, exploración, prompting con Claude Code, escribir código y entregar. El currículo te mantiene al ritmo.

El mapa por audiencia

Si quieres optimizar para tu rol, empieza donde tu rol lo exige y vuelve atrás:

Rol	Día 1 empieza aquí	Prioridad del Día 2	Saltar en el Día 1
Desarrollador backend	`02-codebase-tour/01-from-30000-feet.md` luego `02-codebase-tour/04-trace-a-credit-approval.md`	`docs/audit/01-er-diagram.md`, `docs/audit/12-credit-approval-workflow-diagram.md`	Ninguno — lee todo en `01-business/` eventualmente
Desarrollador frontend	`02-codebase-tour/01-from-30000-feet.md` luego `docs/audit/13-frontend-page-map.md`	`02-codebase-tour/02-trace-a-request.md` desde el lado de Vue	La mecánica profunda del pipeline de crédito puede esperar al Día 3
Desarrollador full-stack	De arriba a abajo en el orden anterior	Dedica el Día 2 a `02-codebase-tour/` de punta a punta	Nada — necesitas todo
Tech lead / arquitecto	`04-the-landmines/01-known-bugs.md` primero, luego `docs/audit/16-deep-validation-study.md`	`docs/audit/06-architecture-diagram.md`, `docs/audit/09-event-job-dependency-graph.md`	Tareas Tier 1 (delégalas)
PM / ops / no-ingeniero	`01-business/` de punta a punta, luego detente	`docs/audit/15-glossary.md` para términos del dominio en español	Todo en `02-codebase-tour/` en adelante

El kit es leer primero, luego escribir. Resiste el impulso de abrir php artisan serve y hurgar antes de haber leído 02-codebase-tour/01-from-30000-feet.md. El codebase recompensa los modelos mentales más de lo que recompensa la exploración.

Qué hay en este kit

Abajo hay un inventario de cada archivo en el kit de onboarding, agrupado por propósito, con anotaciones de una línea y una indicación del peso del archivo. Úsalo como tu mapa.

Sustrato de IA (carga automáticamente con Claude Code / Cursor)

Estos archivos no necesitan leerse manualmente. Se cargan solos en el contexto de tu pair programmer de IA en cada sesión. Están listados aquí para que sepas lo que sabe tu IA.

CLAUDE.md (raíz del repo) — 346 líneas. Contexto primario de IA. Glosario en español, convenciones de código, mapa de integraciones, punteros a landmines, marcadores de foco actual.
app/Services/CLAUDE.md — 177 líneas. Convenciones Service-DTO para los 29 services en el codebase.
app/Jobs/CLAUDE.md — 139 líneas. Patrones de queue, idempotencia, handlers de fallo.
app/Http/Controllers/AprobarCliente/CLAUDE.md — 216 líneas. Las reglas del pipeline de crédito de siete fases, cadena de middleware, manejo de errores.
.cursor/rules/mi-plante.mdc — 123 líneas. El mismo contexto, formateado para usuarios de Cursor.
.claude/commands/onboarding-day-1.md — 116 líneas. Walkthrough interactivo del Día 1. Corre con /onboarding-day-1.
.claude/commands/explain-this-service.md — 97 líneas. Auto-resumen de cualquier archivo de service.
.claude/commands/trace-a-flow.md — 127 líneas. Traza un flujo a través de controller, service, model, queue.
.claude/commands/find-landmines-near.md — 77 líneas. Saca a flote landmines relevantes a un archivo o carpeta.
.claude/commands/safe-to-refactor.md — 165 líneas. Verificación de riesgo de un refactor antes de empezar.
.claude/commands/add-aliado-feature.md — 171 líneas. Andamia una nueva funcionalidad del portal de aliados.

Total del sustrato de IA: ~1.754 líneas que se cargan con cada prompt. No tienes que memorizarlas. Te siguen a todas partes donde Claude Code o Cursor vayan dentro de este repo.

`01-business/` — Contexto de negocio (mañana del Día 1)

No puedes construir un fintech sin entender las finanzas. Estos tres archivos son lo más cercano a un briefing de product management que este equipo tiene.

01-business/01-what-is-mi-plante.md — 435 líneas. Qué vende la empresa, por qué existe, la brecha de crédito colombiana, el insight de EMCALI, la economía unitaria.
01-business/02-who-are-the-users.md — 247 líneas. Tres audiencias (cliente, aliado, admin). Siete personas extraídas de la base de clientes real.
01-business/03-the-money-flow.md — 533 líneas. A dónde va cada peso desde el momento en que un cliente hace clic en “comprar” hasta el momento en que el aliado recibe el pago. Incluye comisiones, el seguro de vida, días de desfase, cálculos de mora.

`02-codebase-tour/` — La disposición técnica del terreno (tarde del Día 1 → Día 2)

Esta es la orientación técnica. Desde el mapa de arquitectura hasta tres walkthroughs profundos de flujos.

02-codebase-tour/01-from-30000-feet.md — 590 líneas. El mapa de arquitectura. Dos guards, tres archivos de rutas, seis integraciones, el queue worker, el scheduler. Incluye diagramas Mermaid.
02-codebase-tour/02-trace-a-request.md — 685 líneas. Una sola petición HTTP, trazada de punta a punta. Cadena de middleware, puente de Inertia, compartido de props.
02-codebase-tour/03-trace-a-sale.md — 690 líneas. Una compra completa desde el carrito hasta las cuotas confirmadas. Dos caminos (checkout e iniciado por aliado), eventos, jobs, máquina de estados.
02-codebase-tour/04-trace-a-credit-approval.md — 657 líneas. El pipeline de crédito de siete fases en detalle. Validación de identidad, OTP, HDC, scoring, asignación de cupo.

`03-development-setup/` — Setup local (mañana del Día 2)

Pon la aplicación corriendo en tu máquina.

03-development-setup/01-local-environment.md — 455 líneas. Desde git clone hasta un composer dev corriendo. Versiones de PHP, Node, MySQL. Plantilla de .env con defaults seguros. Setup de SSR.
03-development-setup/02-seed-data-walkthrough.md — 415 líneas. Qué crea cada seeder. Logins de muestra, productos de muestra, ventas de muestra. Cómo loguearte como cliente, como empleado de aliado, como admin.
03-development-setup/03-common-gotchas.md — 378 líneas. El archivo “seguí el setup y se rompió”. Permisos, manifest de Vite, queue worker olvidando reiniciar, los inevitables typos en .env.

`04-the-landmines/` — Dónde NO pisar (mañana del Día 3)

Lee esto antes de tocar credit approval, sales, queue jobs o webhooks. Obligatorio.

04-the-landmines/01-known-bugs.md — 2.487 líneas. El archivo más importante de este kit. Cada bug activo, cada flujo silenciosamente roto, cada “la función miente sobre lo que hace”. Rúbrica de severidad (Critical / High / Medium / Low). Referencias archivo:línea. Fixes recomendados. Este es tu mapa del campo minado.
04-the-landmines/02-code-archaeology.md — 539 líneas. Por qué existen esos landmines. Reconstrucción especulativa pero bien respaldada de las decisiones históricas que produjeron la forma actual. Lee esto para entender el por qué, no solo el qué.

`05-first-contributions/` — Tus primeros PRs (tarde del Día 3 → Día 5)

Esta es la mitad trasera de la semana 1. Dejas de leer y empiezas a escribir.

05-first-contributions/01-tier-1-tasks.md — 912 líneas. Cinco tareas de bugfix graduadas (T1-01 a T1-05). Cada tarea: dificultad, estimación de tiempo, el bug, por qué importa, archivos a tocar, prompt sugerido para Claude Code, criterios de aceptación, plantilla de PR, qué NO hacer. Tarea recomendada para iniciar el Día 4: T1-01 (el logger del interceptor frontend).
05-first-contributions/02-tier-2-tasks.md — 822 líneas. Tres tareas del tamaño de funcionalidad (T2-01 a T2-03). Mayor superficie, más archivos, más dominio. Recomendado para la semana 2.
05-first-contributions/03-how-to-ship.md — 383 líneas. Nomenclatura de ramas, convenciones de commit, plantilla de PR, el flujo de deploy manual (no hay CI/CD hoy — ver landmine L-23), monitoreo post-deploy.

`06-ai-pair-programming/` — Usa IA como un pro (entrelazado a lo largo de la semana)

Estos documentos son material de referencia. Lee 01-claude-code-setup.md una vez en la tarde del Día 3, y luego deja 03-prompt-cookbook.md abierto en una pestaña para siempre.

06-ai-pair-programming/01-claude-code-setup.md — 517 líneas. Instalación, checklist de primera ejecución, tuneo específico del proyecto. Por qué Claude Code para Mi Plante específicamente (nombrado en español, lógica de negocio no documentada, particularidades de integraciones).
06-ai-pair-programming/02-cursor-setup.md — 364 líneas. El mismo playbook para usuarios de Cursor. El archivo .cursor/rules/mi-plante.mdc es el equivalente de CLAUDE.md.
06-ai-pair-programming/03-prompt-cookbook.md — 1.587 líneas. El archivo más útil que vas a referenciar en todo el año. Prompts validados para: “explica este service”, “qué llama a esta función”, “es seguro refactorizar esto”, “traza una venta”, “agrega una feature sin pisar un landmine”. Hazle bookmark.
06-ai-pair-programming/04-when-not-to-trust-the-ai.md — 468 líneas. Las barreras de seguridad. Cuándo la IA es estructuralmente débil (matemática de dinero, idempotencia, timing de integraciones). Cuándo debes verificar corriendo el código, no leyendo el resumen de la IA.

`media/` — Acompañantes multi-modales

Media generada o generable como acompañante. Nada de esto es requerido — el kit escrito es completamente autocontenido — pero usados junto con la lectura, aceleran la retención.

media/podcasts/README.md — 96 líneas. Cómo generar la serie de podcast de cinco episodios en NotebookLM. Duración total: ~74 minutos.
media/podcasts/SOURCE-ep1-01-what-is-mi-plante.md — 29 líneas. Fuente para el Ep 1 (12 min).
media/podcasts/SOURCE-ep2-architecture-tour.md — 41 líneas. Fuente para el Ep 2 (15 min).
media/podcasts/SOURCE-ep3-credit-pipeline.md — 47 líneas. Fuente para el Ep 3 (18 min).
media/podcasts/SOURCE-ep4-sale-lifecycle.md — 51 líneas. Fuente para el Ep 4 (15 min).
media/podcasts/SOURCE-ep5-landmines.md — 33 líneas. Fuente para el Ep 5 (14 min).
media/videos/README.md — 94 líneas. Cómo producir los cuatro videos guionizados (salida de video de NotebookLM, o Loom).
media/videos/STORYBOARD-codebase-tour.md — 325 líneas. Storyboard completo del video tour del codebase.
media/videos/STORYBOARD-credit-approval.md — 336 líneas. Storyboard completo del video de credit approval.
media/videos/STORYBOARD-sale-lifecycle.md — 307 líneas. Storyboard completo del video del ciclo de vida de una venta.
media/videos/STORYBOARD-local-setup.md — 266 líneas. Storyboard completo del video de setup local.
media/images/PROMPTS-personas.md — 237 líneas. Prompts de generación de imágenes para los siete retratos de personas.
media/images/PROMPTS-illustrations.md — 225 líneas. Prompts de generación de imágenes para imágenes hero y aperturas de sección (7 prompts de ilustración; 14 prompts en total entre los dos archivos).
media/diagrams/README.md — 153 líneas. Pipeline de renderizado de Mermaid. Instalación de mmdc CLI, script de build, convención de salida.
media/diagrams/architecture-poster.mmd — 139 líneas. La arquitectura completa en un Mermaid imprimible.
media/diagrams/credit-pipeline.mmd — 125 líneas. El pipeline de siete fases visualizado.
media/diagrams/sale-lifecycle.mmd — 58 líneas. La máquina de estados de la venta.
media/diagrams/er-spine.mmd — 133 líneas. El ER simplificado (comparado con el ER completo de 38 tablas de la auditoría, esta es la espina dorsal).
media/diagrams/integration-map.mmd — 96 líneas. Las seis integraciones externas y qué hacen.
media/diagrams/event-job-dependency.mmd — Grafo evento/listener/job en cuatro dominios (postulación, ValidationLog, cadena pagaré-crédito, código muerto).
media/diagrams/07-uml-venta-module.md — UML oficial del módulo Venta producido por el equipo original. La fuente más autoritativa sobre la intención de clases, métodos y relaciones del flujo de ventas. Léelo en pareja con 02-codebase-tour/03-trace-a-sale.md.
media/diagrams/08-uml-aprobar-cupo-module.md — UML oficial del módulo AprobarCupo producido por el equipo original. Incluye tres “DISCREPANCY ALERT” documentadas (regla de aprobación 3+ vs runtime ≥5, proveedor del Legal Check Transunion vs Experian, HDC como placeholder). Léelo en pareja con 02-codebase-tour/04-trace-a-credit-approval.md y antes de tocar el pipeline de crédito.
media/diagrams/09-db-diagram-original.png — Diagrama de base de datos (PNG de baja calidad) compartido por el equipo original. Acompañante visual de docs/audit/01-er-diagram.md.

`_internal/` — Archivos de mantenimiento del kit (no para consumo de nuevos devs)

_internal/first-ships.md — 41 líneas. El log de cada primer PR fusionado de un nuevo dev. Actualiza esto en el Día 5 de tu semana.

Referencia: la auditoría existente (más profunda de lo que este kit necesita)

El kit que estás leyendo fue construido sobre una auditoría exhaustiva de 18 documentos. La auditoría es la fuente de la verdad para todo lo escrito aquí. No necesitas leerla durante la semana 1, pero es tu referencia para la semana 2 y más allá.

docs/audit/01-er-diagram.md — El ER completo para las 38 tablas de MySQL.
docs/audit/02-route-inventory.md — Cada ruta del sistema, por guard.
docs/audit/03-env-config-matrix.md — Cada variable de entorno, qué hace, valor por defecto, dónde se lee.
docs/audit/04-notification-catalog.md — Cada notificación (email, SMS, push) que el sistema puede enviar.
docs/audit/05-queue-catalog.md — Cada queue job, sus triggers, su historia de idempotencia, su modo de fallo.
docs/audit/06-architecture-diagram.md — La arquitectura, con más profundidad que 02-codebase-tour/01-from-30000-feet.md.
docs/audit/07-auth-authorization-map.md — Ambos guards, roles, permisos, cada ruta protegida.
docs/audit/08-sale-lifecycle-state-machine.md — La máquina de estados completa de EstadoVenta.
docs/audit/09-event-job-dependency-graph.md — Cada evento, cada listener, cada job despachado, en un grafo.
docs/audit/10-external-integrations-map.md — Las seis integraciones en detalle (endpoints, reintentos, proxies mock).
docs/audit/11-data-flow-diagram.md — Flujo de datos de punta a punta para los flujos mayores.
docs/audit/12-credit-approval-workflow-diagram.md — Las siete fases de credit approval, cada llamada externa.
docs/audit/13-frontend-page-map.md — Cada página de Vue y su controller de respaldo. Crítico para devs frontend.
docs/audit/14-request-lifecycle-flowchart.md — El ciclo de vida completo de una petición HTTP desde nginx hasta la respuesta.
docs/audit/15-glossary.md — El glosario completo de dominio español-inglés.
docs/audit/16-deep-validation-study.md — El reporte de validación que fundamenta cada landmine.
docs/audit/17-critical-additional-findings.md — Hallazgos de etapa tardía que el equipo de auditoría marcó después del primer pase.
docs/audit/19-strategic-architecture-recommendation.md — Recomendación estratégica fix-vs-rebuild, stack a adoptar, roadmap priorizado.

Si alguna vez sientes que el kit de onboarding está pasando por encima de un tema, la auditoría es donde excavar. Cada landmine tiene una citación de la auditoría. Cada flujo tiene un diagrama de la auditoría. El kit resume; la auditoría certifica.

La primera hora del Día 1

Ahora mismo, antes del almuerzo de tu primer día, completa este checklist. Es literalmente la primera hora. No dejes que nada más la interrumpa.

Clona el repo: git clone <repo-url> ext-miplante && cd ext-miplante. Pídele a tu team lead la URL si no la tienes.
Instala Claude Code: npm install -g @anthropic-ai/claude-code. Necesitas Node 18+. Confirma con claude --version.
Inicia Claude Code en el repo: claude. La primera ejecución te pedirá autenticarte. Usa las credenciales de Anthropic proporcionadas por tu team lead.
Verifica que CLAUDE.md cargó. Al inicio, Claude Code imprime los archivos de contexto cargados. Deberías ver al menos el CLAUDE.md de la raíz del repo. Si no, estás en el directorio equivocado.
Corre el comando slash incluido: escribe /onboarding-day-1 dentro de Claude Code. Corre un walkthrough interactivo que confirma el estado de tu repo, saca a flote los landmines activos y te orienta. Toma alrededor de 10 minutos.
Abre docs/onboarding/01-business/01-what-is-mi-plante.md en tu editor. Lee las secciones 1, 4 y 10 si solo tienes 10 minutos; lee la cosa entera si tienes 30.
Abre docs/onboarding/week-1-curriculum.md en otra pestaña. De aquí en adelante, el currículo marca el ritmo de tu día.

Esa es la primera hora. Si terminas más rápido, genera el Episodio 1 del Podcast en NotebookLM (ver media/podcasts/README.md) y escúchalo mientras comes. Si vas más lento, no te preocupes — el currículo tiene colchón.

La filosofía AI-first

Este kit asume que estás usando IA para hacer onboarding. Eso no es una elección estilística; es la elección operacional que hizo posible el kit.

Por qué AI-first

El codebase de Mi Plante tiene tres propiedades que lo hacen especialmente adecuado para onboarding asistido por IA:

Nomenclatura de dominio en español. La mitad del código se lee en español (Venta, Cuota, Cliente, Cupo, Aliado, Empresa, Sucursal, Pagare, Mora). La otra mitad se lee en inglés (Service, Controller, DTO, Listener). Un grep sin el glosario no devuelve nada útil. Claude Code lee CLAUDE.md automáticamente y aprende el diccionario en cada sesión.
Lógica de negocio no documentada. El pipeline de crédito de siete fases llama a cuatro APIs colombianas externas (TransUnion, Experian CrossCore, DataCrédito, EMCALI). Nada de eso está en los comentarios del controller. Todo está en docs/audit/12-credit-approval-workflow-diagram.md y 02-codebase-tour/04-trace-a-credit-approval.md. Claude puede leer ambos a la vez y responder preguntas como “¿qué pasa si Experian hace timeout en la fase 4?” en segundos.
Landmines activos. El codebase tiene varios bugs de producción sin arreglar (GenerarCreditoDeVenta no tiene handler failed(), el handler de excepciones de la API no devuelve su respuesta, el flujo del pagaré de Certicámara genera cuotas dos veces, el composable del wishlist asume una respuesta no paginada). Necesitas saber estos ANTES de editar cualquier cosa en esos vecindarios. 04-the-landmines/01-known-bugs.md los documenta; find-landmines-near.md es un comando slash de Claude Code que los saca a flote automáticamente.

Línea de fondo: el codebase es dos veces más difícil de aprender sin IA que con ella. Usa la IA.

Calibración

La IA no es un oráculo. Es un pair programmer rápido y bien leído. Va a sonar segura cuando está equivocada, y va a estar equivocada en tres temas específicos:

Matemática de dinero. Ante la duda, corre el código, no confíes en el resumen de la IA.
Idempotencia. Los resúmenes de la IA pasan por encima de si un job es seguro para reintentar. Lee el código del job mismo.
Timing de integraciones. La IA no puede ver “DataCrédito a veces devuelve 503” — solo el runtime puede. Mira los logs.

El playbook completo de calibración vive en 06-ai-pair-programming/04-when-not-to-trust-the-ai.md. Léelo antes de tu primer PR.

Convenciones

Estas convenciones se mantienen a lo largo del codebase y a lo largo de este kit. Síguelas; desviarte produce fricción.

Idioma

Español para términos del dominio. Venta, Cuota, Cliente, Cupo, Aliado, Empresa, Sucursal, Pagare, Estrato, Mora, HDC, EstadoVenta, EstadoCuota, OrdenCompraEstado. No los anglifiques. El docs/audit/15-glossary.md de la auditoría es el diccionario.
Inglés para conceptos del framework. Service, Controller, DTO, Listener, Event, Job, Middleware, Provider, Migration, Seeder. Estos son conceptos de Laravel y se quedan en inglés.
Inglés para todo lo demás en el kit de onboarding. Según la instrucción global en ~/.claude/CLAUDE.md, toda la documentación está escrita en inglés sin importar el idioma del codebase subyacente.

Referencias de código

Las referencias a archivos toman la forma path/to/file.php:line-range. Ejemplo: app/Services/AprobarCupoService.php:42-78.
Referencias a Vue: resources/js/pages/Checkout/Confirm.vue:35.
Referencias a DB: migration_name para tablas, Model::field para columnas.
Citaciones de auditoría: docs/audit/12-credit-approval-workflow-diagram.md:section-3 o (audit 12, section 3) cuando va en línea.

Estilo

Sin emojis. No en código, no en docs, no en mensajes de commit. Por convención del proyecto.
Formato Prettier. 150 chars de ancho de línea, comillas simples, indentación de 4 espacios. El sorter de clases de Tailwind está configurado. Corre npm run format antes de hacer commit.
PHP-CS-Fixer / Pint. Corre composer pint antes de hacer commit. Convenciones de Laravel.
Soltura en TypeScript. Sin modo strict; any está permitido pero desincentivado. Úsalo con moderación.

Ayuda y escalación

Te vas a atascar. Todo el mundo lo hace. Aquí va la escalera de escalación, en orden:

Usa Claude Code. El soporte de primera línea es tu pair programmer. Prueba /explain-this-service en el archivo que te confundió, o /trace-a-flow en el workflow que estás debuggeando. O simplemente pega la pregunta. La IA conoce el codebase tan bien como cualquiera que quede en el equipo.
Busca en el kit. Usa ripgrep o el full-text search de tu editor a lo largo de docs/onboarding/. El kit responde el 70%+ de las preguntas de la semana de onboarding.
Busca en la auditoría. Si el kit está pasando por encima, la auditoría docs/audit/01 a 16 es la fuente de la verdad. Dieciocho documentos, cada afirmación con fuente.
Pregunta en el canal del equipo. El equipo es pequeño y receptivo. Sé específico: incluye el archivo:línea que estás mirando y el prompt que corriste en Claude Code primero. “Le pregunté a Claude X, obtuve Y, pero el código dice Z, ¿qué me falta?” es una gran pregunta. “Ayuda” no lo es.
Coordina para cambios en zona de landmines. Si estás editando cualquier archivo mencionado en 04-the-landmines/01-known-bugs.md, no hagas push sin hablar con el team lead. La entrada del landmine te dice si un cambio coordinado es seguro; ante la duda, pregunta.

Quién mantiene este kit

Autor: el equipo de auditoría.
Custodio: el equipo de ingeniería actual de Mi Plante. Eso eres tú, ahora, también.
Cadencia de actualización: el kit está vivo. Cada onboarding produce feedback. Cada nuevo landmine produce una entrada en 01-known-bugs.md. Cada gotcha produce una entrada en 03-common-gotchas.md. El retro personal del Día 5 alimenta directamente las actualizaciones del kit.

Si encuentras un lugar donde este kit está equivocado, arréglalo en un PR. Incluso un typo. El kit es la memoria de trabajo colectiva del equipo y mejora con cada contribución.

Roadmap para el kit en sí

El kit está entregado. Algunos de los acompañantes multi-modales están aún pendientes de generación; nada aquí bloquea el onboarding, pero vale la pena conocer la cola:

Generar los cinco episodios del podcast en NotebookLM. Las fuentes están en media/podcasts/SOURCE-*.md. Tiempo estimado: 30 minutos de clickear y esperar por episodio. El primer dev de onboarding debería generar el Ep 1 en la mañana del Día 1 durante su primer break de café (el currículo tiene un slot de 15 minutos para esto).
Producir los cuatro storyboards de video. Ya sea alimentando los storyboards al feature de video de NotebookLM (limitado pero mejorando) o grabando videos reales de Loom siguiendo el guion. Alrededor de 4 horas de trabajo por video.
Generar los retratos de personas y las ilustraciones. Los prompts de imágenes están en media/images/. Usa Midjourney v6 o Flux Pro según las recomendaciones. Alrededor de 2 horas en total.
Renderizar los diagramas Mermaid a SVG. El pipeline está documentado en media/diagrams/README.md. Alrededor de 15 minutos en total: npm install -g @mermaid-js/mermaid-cli luego mmdc -i diagram.mmd -o diagram.svg por archivo.
Retro del primer ship el viernes. Registra el primer PR de cada nuevo dev en _internal/first-ships.md. Este es el KPI vivo del kit.

Cuando un team lead tenga 2-3 horas de ancho de banda, despachar la generación de media produce un kit completo. Hasta entonces, el kit escrito es totalmente suficiente.

Agradecimientos

Este kit se apoya en los hombros de la auditoría técnica de Mi Plante (docs/audit/01-17 + 19). La auditoría fue el trabajo lento, cuidadoso y costoso de leer cada línea que importaba, validar cada afirmación contra el código a nivel archivo:línea, y producir 18 documentos referenciados cruzadamente. El kit de onboarding es el puente desde esa auditoría hasta el primer PR de un nuevo desarrollador. Sin la auditoría, este kit no existiría.

Gracias al equipo de auditoría por la base, a Martin por la pista, y a quienquiera que esté leyendo esto en su primer día — estás a punto de heredar un codebase que tiene uso real en producción, clientes colombianos reales y landmines reales. El kit está aquí para que no tengas que encontrar ninguno de ellos por sorpresa.

Bienvenido a Mi Plante. Ahora abre week-1-curriculum.md y pongámonos a trabajar.