Inspeccionar una base de código desconocida
Usa IBM Bob para entender rápidamente una aplicación desconocida, como su propósito, estructura de proyecto, arquitectura, tech stack, componentes clave, cobertura de tests y modelo de despliegue. Todo esto sin depender de documentación desactualizada ni esperar a tus compañeros.
Ponerse productivo en una base de código desconocida implica normalmente horas de lectura de código, buscar documentación y preguntar a los compañeros. En este tutorial, usas Bob en modo Ask para interrogar sistemáticamente la base de código de Galaxium Travels y extraer una imagen completa de la aplicación: su propósito y arquitectura, tech stack, componentes clave, cobertura de tests unitarios e integración, y el modelo de despliegue. Luego cambias al modo Agent para guardar todo lo que Bob descubrió en una referencia Markdown persistente que todo tu equipo puede usar.
Galaxium Travels es una aplicación intencionalmente compleja con estilo real que tiene un frontend en React, un backend en Python FastAPI y un servicio de inventario en Java Spring Boot. Esto la convierte en un candidato ideal para este flujo de trabajo.
La salida de Bob varía según el estado actual de la base de código. Trata los ejemplos de este tutorial como puntos de partida representativos, no como transcripciones exactas. Úsalos para calibrar tus propios prompts y refinar los resultados.
Funciones clave que aprendes
- Modo Ask: Explorar y analizar código sin que Bob modifique ningún archivo.
- Modo Agent: Dejar que Bob escriba archivos de forma autónoma para guardar los artefactos generados en tu proyecto.
- Context mentions: Referenciar
archivos y carpetas específicos con
@para dar a Bob un alcance preciso para el análisis. /init: Inicializar el contexto del proyecto para que Bob entienda las convenciones de la base de código antes de empezar a hacer preguntas.
Requisitos previos
Para completar este tutorial, necesitas lo siguiente:
- Bob IDE instalado.
- Git instalado localmente.
- Familiaridad con el uso básico de Bob. Si eres nuevo en Bob, completa primero el tutorial de inicio rápido.
Configurar tu workspace
Clonar el repositorio de Galaxium Travels
En tu terminal, clona el repositorio de ejemplo:
git clone https://github.com/IBM/galaxium-travels.gitAbrir el proyecto de ejemplo
En el Bob IDE, abre la carpeta galaxium-travels que acabas de clonar. Si Bob pregunta
"Do you trust the authors of the files in the folder?", haz clic en Yes, I trust
the authors.
Abrir la interfaz de chat de Bob
Si la interfaz de chat no está ya abierta, haz clic en el icono de Bob en la barra de navegación o usa el atajo Option + Command + B (Mac) o Ctrl + Alt + B (Windows).
Inicializar el contexto del proyecto
Bob usa el modo Agent de forma predeterminada al iniciarse. Antes de cambiar de modo,
ejecuta el comando /init para que Bob lea el proyecto y genere los archivos de contexto
AGENTS.md que utiliza en interacciones posteriores.
/initSi la aprobación automática está desactivada, Bob pide permiso para leer archivos y
escribir los archivos AGENTS.md. Aprueba cada solicitud. Bob crea un AGENTS.md en
el nivel raíz y una carpeta .bob/ con configuración específica de cada modo.
Revisa el AGENTS.md generado para confirmar que Bob identificó correctamente la
estructura de múltiples servicios del repositorio.
Cambiar al modo Ask
Selecciona Ask en el selector de modo debajo del campo de entrada del chat, o escribe
/ask para cambiar de modo. El modo Ask es estrictamente de solo lectura. Bob analiza
archivos pero no puede crear ni modificar nada, lo que lo hace el modo adecuado para todo
el trabajo de exploración de este tutorial.
Entender el propósito de la aplicación y la estructura del proyecto
Empieza con la pregunta más amplia: ¿qué hace esta aplicación y cómo está organizada la
base de código? Bob lee la estructura del proyecto y los archivos clave, como README.md,
package.json, requirements.txt, archivos de build y otros archivos de configuración.
Bob sintetiza un resumen conciso sin que tengas que rastrear manualmente cada directorio.
En el modo Ask, introduce el siguiente prompt:
What is the purpose of this application? Describe the project structure,
the high-level architecture, and the main responsibilities of each top-level
directory.Bob lee el árbol de archivos y los puntos de entrada clave, y luego produce una salida que incluye lo siguiente:
- Propósito de la aplicación
- Responsabilidades de los directorios de nivel superior
- Un resumen del contenido de cada directorio de nivel superior
- Diagrama de arquitectura de alto nivel
Analizar el tech stack
Con la estructura de alto nivel clara, profundiza en las tecnologías exactas en uso. Este prompt es útil cuando necesitas entender las herramientas de build, evaluar las decisiones de dependencias o valorar el alcance de las actualizaciones.
En el modo Ask, introduce el siguiente prompt:
Analyze the tech stack for the entire application. For each service, list the
programming language, runtime version requirements, framework, key libraries,
database, and build/test tooling.Bob inspecciona los archivos de dependencias y configuración de cada servicio y produce una salida que incluye:
- Análisis detallado del tech stack para cada servicio
- Identificación del framework de tests end-to-end
- Herramientas adicionales del stack CI/CD y scripts de despliegue
- Un diagrama "Stack at a Glance" que resume visualmente el tech stack en todos los servicios y capas
Mapear los componentes clave
Entender el tech stack te dice qué usa una base de código; entender los componentes clave te dice cómo funciona. Este prompt pide a Bob que trace los límites de los componentes y los flujos de datos en los tres servicios, lo que es especialmente útil antes de hacer cambios que cruzan los límites de los servicios.
En el modo Ask, introduce el siguiente prompt con context mentions para apuntar a Bob hacia los archivos más relevantes:
Identify the key components of this application and explain how they interact.
Reference @booking_system_frontend/src/services,
@booking_system_backend/server.py,
@booking_system_backend/services,
@booking_system_backend/models.py,
and @booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice.
Describe the component responsibilities, the data flow for the booking
lifecycle, and any cross-service contracts I need to know before modifying
the codebase.Bob traza la cadena de interacción y produce una salida que contiene:
- Responsabilidades detalladas del frontend, la API del backend, la capa de base de datos y el servicio hold de Java
- Un diagrama de los dos flujos del ciclo de vida de la reserva con interacciones de componentes anotadas
- Un resumen de los cinco contratos entre servicios que debes conocer antes de hacer cambios
- Un mapa de interacción de componentes
Evaluar la cobertura de tests unitarios
Antes de añadir funcionalidades o refactorizar, necesitas saber qué cubre la suite de tests existente y dónde están las lagunas. Este prompt pide a Bob que lea los archivos de tests y produzca una evaluación de cobertura sin ejecutarlos.
En el modo Ask, introduce el siguiente prompt:
Analyze the unit test suites across all three services. Reference
@booking_system_backend/tests,
@booking_system_inventory_hold_service/src/test,
and @booking_system_frontend/src.
For each service, describe what is tested, which testing framework is used,
what the test structure looks like, and identify any obvious gaps where
critical logic appears to be untested.Bob lee los archivos de tests y produce un análisis detallado de la suite de tests que incluye:
- Framework de tests, clases bajo test, número de tests por clase y qué se verifica por clase para cada servicio
- Lagunas críticas en los tests
- Cobertura de tests faltante para la lógica de negocio crítica
Evaluar la cobertura de tests de integración y end-to-end
Los tests unitarios te indican si los componentes individuales funcionan de forma aislada; los tests de integración y end-to-end te indican si los servicios funcionan correctamente juntos. Esto es especialmente importante para Galaxium Travels porque el flujo de confirmación de reserva abarca los tres servicios.
En el modo Ask, introduce el siguiente prompt:
Analyze the end-to-end and integration test coverage. Reference
@tests_e2e and any cross-service test fixtures you can identify.
Describe which cross-service flows are covered, which are not, what test
infrastructure is required to run the suite, and what the tests assert
at the boundary level.Bob lee la suite de tests end-to-end y genera un análisis detallado de cobertura que incluye:
- Infraestructura de tests y requisitos para ejecutar la suite
- Smoke tests
- Decisiones clave de infraestructura
- Flujos entre servicios cubiertos y no cubiertos
- Aserciones de tests a nivel de frontera
Revisar el modelo de despliegue
Entender cómo se despliega una aplicación (sus plataformas de destino, estrategia de contenedorización y automatización de infraestructura) es esencial antes de incorporarte como colaborador o antes de ejecutar la aplicación en cualquier lugar más allá de tu portátil.
En el modo Ask, introduce el siguiente prompt:
Analyze the deployment model for this application. Reference
@docker-compose.yml, @deployment_scripts, @terraform, @.github/workflows,
and the deployment documentation in @docs.
Describe the supported deployment targets, how each service is containerized,
what infrastructure is provisioned, and how CI/CD is configured.Bob lee los artefactos de despliegue y produce un análisis del modelo de despliegue. El análisis incluye:
- Destinos de despliegue soportados
- Estrategia de contenedorización para cada servicio
- Detalles de aprovisionamiento de infraestructura
- Flujos de trabajo CI/CD
- Restricciones y lagunas clave del despliegue
Guardar tus hallazgos en el repositorio
El análisis producido en el modo Ask solo existe en la sesión de chat. Cambia al modo Agent para pedirle a Bob que escriba un documento de referencia de onboarding persistente en el repositorio, para que los futuros colaboradores puedan beneficiarse de este trabajo.
Cambiar al modo Agent
Selecciona Agent en el selector de modo, o escribe /agent en el campo de entrada
del chat.
Crear la referencia de onboarding
Pídele a Bob que consolide todo lo que descubrió en un único archivo Markdown. Bob tiene el contexto completo de la conversación y sintetiza los hallazgos sin volver a leer todos los archivos.
Create a file called docs/ONBOARDING.md.
Create one section for each of these topics:
1. Application overview: purpose, project structure, high-level architecture, and the main responsibilities of each top-level directory.
2. Tech stack analysis, including a "Stack at a Glance" diagram.
3. Key components and their interactions, including a component interaction map.
4. Unit test coverage analysis.
5. End-to-end test coverage analysis.
6. Deployment model analysis.
Populate each section with everything you discovered in this session.
Use clear headings, Mermaid diagrams, and tables where appropriate. Keep the tone concise and technical.Bob escribe el archivo. Si la aprobación automática está desactivada, haz clic en
Approve cuando Bob solicite permiso para escribir docs/ONBOARDING.md.
Verificar la salida
Abre docs/ONBOARDING.md en el editor para confirmar que el documento contiene todo
el contenido que esperas ver. También puedes pedirle a Bob que lo previsualice:
Show me a preview of docs/ONBOARDING.mdBob renderiza el Markdown en la interfaz de chat. Revisa el contenido para comprobar su precisión y completitud antes de hacer el commit.
Hacer commit del archivo
Usa tu flujo de trabajo Git preferido para hacer commit de docs/ONBOARDING.md en tu
repositorio. El documento está ahora disponible para todos los colaboradores y para Bob
mismo en sesiones futuras.
Solución de problemas
El análisis de Bob es superficial o no detecta servicios
De forma predeterminada, Bob lee la estructura del proyecto y una selección de archivos clave. Si en la salida falta un servicio o es menos detallada de lo esperado, añade context mentions explícitas para enfocar el análisis de Bob.
Por ejemplo, si el servicio hold de Java no aparece en el análisis del tech stack,
añade @booking_system_inventory_hold_service/pom.xml al prompt:
Analyze the tech stack for @booking_system_inventory_hold_service/pom.xml
and add the Java hold service to the tech stack summary you produced earlier.Bob no puede encontrar los archivos de tests
Si Bob informa de que no puede encontrar los archivos de tests, usa una context mention para apuntar directamente a los directorios de tests:
Analyze the test coverage in @booking_system_backend/tests and
@tests_e2e. List every test file and summarize what each one covers.El análisis de despliegue de Bob omite un destino
Los artefactos de despliegue de AWS, IBM Cloud y local están distribuidos en varios directorios de nivel superior. Si el resumen de despliegue de Bob está incompleto, indícale los directorios específicos:
Review @deployment_scripts/aws, @terraform, @deployment_scripts/ibm, and
@.github/workflows. Update the deployment model summary to include all three
deployment targets./init genera un AGENTS.md vacío o incorrecto
En la raíz del workspace, el comando /init construye el contexto del proyecto leyendo
archivos ancla como README.md, package.json, requirements.txt, pom.xml,
Makefile y manifiestos similares. Si ninguno de esos archivos existe en la raíz, o si
la raíz del workspace está configurada como un subdirectorio, Bob solo ve una parte del
proyecto y genera un AGENTS.md escaso o incorrecto.
Si el AGENTS.md generado no refleja la estructura de múltiples servicios, comprueba
lo siguiente:
- Raíz del workspace: Confirma que
galaxium-travels/, no un subdirectorio comobooking_system_backend/, está abierto como raíz del workspace. Los tres directorios de servicio deben ser visibles en el nivel superior. - Archivos ancla faltantes: Si la raíz carece de un
README.mdu otro manifiesto,/inittiene poco que leer. Añade unREADME.mden el nivel raíz con una breve descripción del proyecto y vuelve a ejecutar/init.
Después de corregir la raíz, vuelve a ejecutar /init para regenerar los archivos
AGENTS.md.
Estandarizar el comportamiento de Bob
Estandarice el comportamiento de Bob en su equipo utilizando archivos de reglas a nivel de proyecto que le indican a Bob que documente su código y recuerde sus acciones anteriores.
Generar diagramas de arquitectura
Usa IBM Bob para analizar la base de código de Galaxium Travels y generar diagramas de clases UML de Mermaid, diagramas de secuencia y diagramas de casos de uso. Aprende a usar menciones de contexto en el modo Ask para explorar código y el modo Agent para guardar los resultados en tu repositorio.