Onboarding de Código Base

¿Qué hace Onboarding de Código Base?

Analiza sistemáticamente un código base desconocido y produce una guía de onboarding estructurada. Diseñado para desarrolladores que se unen a un nuevo proyecto o configuran Claude Code por primera vez en un repositorio existente.

Cuándo Usarlo

• Al abrir un proyecto con Claude Code por primera vez
• Al unirse a un nuevo equipo o repositorio
• El usuario pide "ayúdame a entender este código base"
• El usuario pide generar un CLAUDE.md para un proyecto
• El usuario dice "onboarding" o "guíame por este repositorio"

Cómo Funciona

Fase 1: Reconocimiento

Recopila señales sin procesar del proyecto sin leer cada archivo. Ejecuta estas comprobaciones en paralelo:

1. Detección de manifiestos de paquetes
   → package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle,
     Gemfile, composer.json, mix.exs, pubspec.yaml

2. Identificación del framework
   → next.config.*, nuxt.config.*, angular.json, vite.config.*,
     django settings, flask app factory, fastapi main, rails config

3. Localización del punto de entrada
   → main.*, index.*, app.*, server.*, cmd/, src/main/

4. Instantánea de la estructura de directorios
   → Los primeros 2 niveles del árbol de directorios, ignorando node_modules, vendor,
     .git, dist, build, __pycache__, .next

5. Detección de configuración y herramientas
   → .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile,
     docker-compose*, .github/workflows/, .env.example, configuraciones de CI

6. Detección de estructura de pruebas
   → tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js,
     pytest.ini, jest.config.*, vitest.config.*

Fase 2: Mapeo de Arquitectura

A partir de los datos de reconocimiento, identifica:

Stack Tecnológico

• Lenguaje(s) y restricciones de versión
• Framework(s) y bibliotecas principales
• Base(s) de datos y ORMs
• Herramientas de compilación y bundlers
• Plataforma CI/CD

Patrón Arquitectónico

• Monolito, monorepo, microservicios o serverless
• Separación frontend/backend o full-stack
• Estilo de API: REST, GraphQL, gRPC, tRPC

Directorios Clave Mapea los directorios de primer nivel a su propósito:

src/components/  → Componentes de UI de React
src/api/         → Manejadores de rutas de API
src/lib/         → Utilidades compartidas
src/db/          → Modelos y migraciones de base de datos
tests/           → Suites de pruebas
scripts/         → Scripts de compilación y despliegue

Flujo de Datos Traza una solicitud desde la entrada hasta la respuesta:

• ¿Dónde entra una solicitud? (enrutador, manejador, controlador)
• ¿Cómo se valida? (middleware, esquemas, guards)
• ¿Dónde está la lógica de negocio? (servicios, modelos, casos de uso)
• ¿Cómo llega a la base de datos? (ORM, consultas sin procesar, repositorios)

Fase 3: Detección de Convenciones

Identifica patrones que el código base ya sigue:

Convenciones de Nomenclatura

• Nomenclatura de archivos: kebab-case, camelCase, PascalCase, snake_case
• Patrones de nomenclatura de componentes/clases
• Nomenclatura de archivos de prueba: *.test.ts, *.spec.ts, *_test.go

Patrones de Código

• Estilo de manejo de errores: try/catch, tipos Result, códigos de error
• Inyección de dependencias o imports directos
• Enfoque de gestión de estado
• Patrones asíncronos: callbacks, promesas, async/await, channels

Convenciones de Git

• Nomenclatura de ramas a partir de ramas recientes
• Estilo de mensajes de commit a partir de commits recientes
• Flujo de trabajo de PR (squash, merge, rebase)
• Si el repositorio no tiene commits aún o solo tiene un historial superficial (ej. git clone --depth 1), omite esta sección y anota "Historial de Git no disponible o demasiado superficial para detectar convenciones"

Fase 4: Generar Artefactos de Onboarding

Genera dos salidas:

Salida 1: Guía de Onboarding

# Guía de Onboarding: [Nombre del Proyecto]

## Resumen
[2-3 oraciones: qué hace este proyecto y a quién sirve]

## Stack Tecnológico
<!-- Ejemplo para un proyecto Next.js — reemplázalo con el stack detectado -->
| Capa | Tecnología | Versión |
|------|-----------|--------|
| Lenguaje | TypeScript | 5.x |
| Framework | Next.js | 14.x |
| Base de datos | PostgreSQL | 16 |
| ORM | Prisma | 5.x |
| Pruebas | Jest + Playwright | - |

## Arquitectura
[Diagrama o descripción de cómo se conectan los componentes]

## Puntos de Entrada Clave
<!-- Ejemplo para un proyecto Next.js — reemplázalo con las rutas detectadas -->
- **Rutas de API**: `src/app/api/` — manejadores de rutas de Next.js
- **Páginas de UI**: `src/app/(dashboard)/` — páginas autenticadas
- **Base de datos**: `prisma/schema.prisma` — fuente de verdad del modelo de datos
- **Configuración**: `next.config.ts` — configuración de compilación y ejecución

## Mapa de Directorios
[Directorio de primer nivel → propósito]

## Ciclo de Vida de una Solicitud
[Traza una solicitud de API desde la entrada hasta la respuesta]

## Convenciones
- [Patrón de nomenclatura de archivos]
- [Enfoque de manejo de errores]
- [Patrones de pruebas]
- [Flujo de trabajo de Git]

## Tareas Comunes
<!-- Ejemplo para un proyecto Node.js — reemplázalo con los comandos detectados -->
- **Ejecutar servidor de desarrollo**: `npm run dev`
- **Ejecutar pruebas**: `npm test`
- **Ejecutar linter**: `npm run lint`
- **Migraciones de base de datos**: `npx prisma migrate dev`
- **Compilar para producción**: `npm run build`

## Dónde Mirar
<!-- Ejemplo para un proyecto Next.js — reemplázalo con las rutas detectadas -->
| Quiero... | Mirar en... |
|-----------|-----------|
| Añadir un endpoint de API | `src/app/api/` |
| Añadir una página de UI | `src/app/(dashboard)/` |
| Añadir una tabla de base de datos | `prisma/schema.prisma` |
| Añadir una prueba | `tests/` coindicente con la ruta fuente |
| Cambiar configuración de compilación | `next.config.ts` |

Salida 2: CLAUDE.md Inicial

Genera o actualiza un CLAUDE.md específico del proyecto basado en las convenciones detectadas. Si ya existe CLAUDE.md, léelo primero y mejóralo — conserva las instrucciones existentes específicas del proyecto y señala claramente lo que se añadió o cambió.

# Instrucciones del Proyecto

## Stack Tecnológico
[Resumen del stack detectado]

## Estilo de Código
- [Convenciones de nomenclatura detectadas]
- [Patrones detectados a seguir]

## Pruebas
- Ejecutar pruebas: `[comando de prueba detectado]`
- Patrón de prueba: [convención de archivo de prueba detectada]
- Cobertura: [si está configurado, el comando de cobertura]

## Compilación y Ejecución
- Dev: `[comando de desarrollo detectado]`
- Compilar: `[comando de compilación detectado]`
- Lint: `[comando de lint detectado]`

## Estructura del Proyecto
[Directorio clave → propósito]

## Convenciones
- [Estilo de commit si es detectable]
- [Flujo de trabajo de PR si es detectable]
- [Patrones de manejo de errores]

Mejores Prácticas

1. No leas todo — el reconocimiento debe usar Glob y Grep, no Read en cada archivo. Lee selectivamente solo para señales ambiguas.
2. Verifica, no adivines — si se detecta un framework desde la configuración pero el código real usa algo diferente, confía en el código.
3. Respeta el CLAUDE.md existente — si ya existe uno, mejóralo en lugar de reemplazarlo. Señala qué es nuevo vs. existente.
4. Mantén la concisión — la guía de onboarding debe poder escanearse en 2 minutos. Los detalles pertenecen al código, no a la guía.
5. Señala lo desconocido — si no se puede detectar con certeza una convención, dilo en lugar de adivinar. "No se pudo determinar el ejecutor de pruebas" es mejor que una respuesta incorrecta.

Antipatrones a Evitar

• Generar un CLAUDE.md de más de 100 líneas — mantenlo enfocado
• Listar cada dependencia — destaca solo las que dan forma a cómo escribes código
• Describir nombres de directorios obvios — src/ no necesita explicación
• Copiar el README — la guía de onboarding aporta información estructural de la que carece el README

Ejemplos

Ejemplo 1: Primera vez en un nuevo repositorio

Usuario: "Onboarding en este código base" Acción: Ejecutar el flujo de trabajo completo de 4 fases → generar Guía de Onboarding + CLAUDE.md Inicial Salida: Guía de Onboarding impresa directamente en la conversación, más un CLAUDE.md escrito en la raíz del proyecto

Ejemplo 2: Generar CLAUDE.md para un proyecto existente

Usuario: "Genera un CLAUDE.md para este proyecto" Acción: Ejecutar Fases 1-3, omitir Guía de Onboarding, generar solo CLAUDE.md Salida: CLAUDE.md específico del proyecto con convenciones detectadas

Ejemplo 3: Mejorar CLAUDE.md existente

Usuario: "Actualiza el CLAUDE.md con las convenciones actuales del proyecto" Acción: Leer CLAUDE.md existente, ejecutar Fases 1-3, fusionar nuevos hallazgos Salida: CLAUDE.md actualizado con adiciones claramente marcadas