Iniciación a Codebase

Nivel: POTENTE
Categoría: Ingeniería
Ámbito: Documentación / Experiencia del desarrollador

Descripción general

Analiza un código fuente y genera documentación de incorporación para ingenieros, responsables técnicos y colaboradores externos. Esta habilidad está optimizada para la recopilación rápida de datos y la generación de resultados de incorporación repetibles.

Capacidades principales

• Identificación de la arquitectura y la pila tecnológica a partir de señales del repositorio
• Inventario de archivos clave y de configuración para nuevos colaboradores
• Configuración local y generación de guías para tareas comunes
• Estructuración de la documentación adaptada al público destinatario
• Estructura de listas de comprobación para la depuración y las contribuciones

Cuándo utilizarlo

• Al incorporar a un nuevo miembro del equipo o a un colaborador externo
• Reestructuración de documentación obsoleta tras refactorizaciones importantes
• Preparación de la documentación interna de traspaso
• Creación de un paquete de incorporación estandarizado para los servicios

Inicio rápido

# 1) Recopilar datos sobre el código fuente
python3 scripts/codebase_analyzer.py /ruta/al/repositorio

# 2) Exportar los resultados en formato legible por máquina
python3 scripts/codebase_analyzer.py /ruta/al/repositorio --json

# 3) Utilizar la plantilla para redactar los documentos de incorporación
# Véase references/onboarding-template.md

Flujo de trabajo recomendado

1. Ejecuta scripts/codebase_analyzer.py en el repositorio de destino.
2. Recopila los datos clave: número de archivos, lenguajes detectados, archivos de configuración y estructura de nivel superior.
3. Rellena la plantilla de incorporación que se encuentra en references/onboarding-template.md.
4. Adapta el nivel de detalle de la información según el público:
   • Junior: configuración + medidas de seguridad
   • Experto: arquitectura + aspectos operativos
   • Contratista: alcance de la responsabilidad + límites de integración

Plantilla de documento de incorporación

La plantilla detallada y los ejemplos de secciones se encuentran en:

• references/onboarding-template.md
• references/output-format-templates.md

Errores habituales

• Redactar documentación sin validar los comandos de configuración en un entorno limpio
• Mezclar análisis en profundidad de la arquitectura con documentación orientada a los contratistas
• Omitir los pasos de resolución de problemas y verificación
• Dejar que la documentación de incorporación se desvíe del estado actual del repositorio

Buenas prácticas

1. Mantén las instrucciones de configuración ejecutables y con plazos definidos.
2. Documentar el «porqué» de las decisiones arquitectónicas clave.
3. Actualizar la documentación en la misma solicitud de incorporación de cambios (PR) en la que se modifique el comportamiento.
4. Trata los documentos de incorporación como activos operativos vivos, no como entregables puntuales.