Onboarding de Codebase

¿Qué hace Onboarding de Codebase?

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

Cuándo usarlo

• Primera vez que abres un proyecto con Claude Code
• Unirte a un nuevo equipo o repositorio
• El usuario pregunta "ayúdame a entender esta base de código"
• El usuario pide generar un CLAUDE.md para un proyecto
• El usuario dice "incorpórame" o "guíame a través de este repositorio"

Cómo funciona

Fase 1: Reconocimiento

Recopila señales sin procesar sobre el 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. Identificación de puntos de entrada
   → main.*, index.*, app.*, server.*, cmd/, src/main/

4. Instantánea de la estructura de directorios
   → Los 2 niveles superiores 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 librerías principales
• Base(s) de datos y ORMs
• Herramientas de construcción y bundlers
• Plataforma de CI/CD

Patrón de arquitectura

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

Directorios clave Mapea los directorios de nivel superior a su propósito:

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

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

• ¿Por dónde entra una solicitud? (router, handler, controller)
• ¿Cómo se valida? (middleware, schemas, guards)
• ¿Dónde está la lógica de negocio? (services, models, use cases)
• ¿Cómo llega a la base de datos? (ORM, consultas directas, repositories)

Fase 3: Detección de convenciones

Identifica patrones que la base de código ya sigue:

Convenciones de nombrado

• Nombrado de archivos: kebab-case, camelCase, PascalCase, snake_case
• Patrones de nombrado de componentes/clases
• Nombrado 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 importaciones directas
• Enfoque de gestión de estado
• Patrones asíncronos: callbacks, promesas, async/await, channels

Convenciones de Git

• Nombrado de ramas según ramas recientes
• Estilo de mensajes de commit según commits recientes
• Flujo de trabajo de PR (squash, merge, rebase)
• Si el repositorio no tiene commits o solo tiene un historial superficial (por ejemplo, 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 incorporación

Produce dos salidas:

Salida 1: Guía de incorporación

# Guía de incorporación: [Nombre del proyecto]

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

## Stack tecnológico
<!-- Ejemplo para un proyecto Next.js — reemplazar 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 — reemplazar con las rutas detectadas -->
- **Rutas API**: `src/app/api/` — Manejadores de rutas de Next.js
- **Páginas 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 construcción y ejecución

## Mapa de directorios
[Directorio de nivel superior → propósito]

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

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

## Tareas comunes
<!-- Ejemplo para un proyecto Node.js — reemplazar 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`
- **Construir para producción**: `npm run build`

## Dónde buscar
<!-- Ejemplo para un proyecto Next.js — reemplazar con las rutas detectadas -->
| Quiero... | Mirar en... |
|-----------|-------------|
| Agregar un endpoint API | `src/app/api/` |
| Agregar una página UI | `src/app/(dashboard)/` |
| Agregar una tabla en la base de datos | `prisma/schema.prisma` |
| Agregar una prueba | `tests/` coincidiendo con la ruta fuente |
| Cambiar la 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 CLAUDE.md ya existe, léelo primero y mejóralo — preserva las instrucciones existentes específicas del proyecto y señala claramente lo que se agregó o cambió.

# Instrucciones del proyecto

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

## Estilo de código
- [Convenciones de nombrado detectadas]
- [Patrones detectados a seguir]

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

## Construcción y ejecución
- Desarrollo: `[comando de desarrollo detectado]`
- Construcción: `[comando de construcción detectado]`
- Lint: `[comando de lint detectado]`

## Estructura del proyecto
[Directorio clave → mapa de 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 Leer 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 versus existente.
4. Mantén la concisión — la guía de incorporación debe poder escanearse en 2 minutos. Los detalles pertenecen al código, no a la guía.
5. Señala lo desconocido — si una convención no se puede detectar con confianza, 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 aquellas que moldean cómo escribes código
• Describir nombres de directorios obvios — src/ no necesita explicación
• Copiar el README — la guía de incorporación agrega información estructural de la que el README carece

Ejemplos

Ejemplo 1: Primera vez en un nuevo repositorio

Usuario: "Incorpórame a esta base de código" Acción: Ejecuta el flujo de trabajo completo de 4 fases → produce Guía de incorporación + CLAUDE.md inicial Salida: Guía de incorporación 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: Ejecuta las Fases 1-3, omite la Guía de incorporación, produce solo CLAUDE.md Salida: CLAUDE.md específico del proyecto con las convenciones detectadas

Ejemplo 3: Mejorar CLAUDE.md existente

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