Genera informes de auditoría y documentación de cumplimiento
Usa IBM Bob para analizar la base de código de Galaxium Travels y producir informes de auditoría estructurados que cubran calidad de código, estado de dependencias, deuda técnica y postura de cumplimiento. Aprende a ensamblar documentación lista para stakeholders a partir de análisis asistido por IA.
Las auditorías de software producen la evidencia documental en la que confían los equipos de ingeniería, revisores de seguridad y stakeholders de cumplimiento antes de enviar, adquirir o certificar un sistema.
En este tutorial, usas Bob para analizar sistemáticamente la base de código de Galaxium Travels y generar cinco artefactos estructurados:
- Un resumen de calidad de código: Destaca problemas de mantenibilidad, complejidad y estilo en toda la base de código.
- Una auditoría de dependencias: Marca paquetes de terceros obsoletos, vulnerables o no utilizados.
- Una evaluación de deuda técnica: Cataloga atajos, soluciones temporales y áreas que necesitan refactorización.
- Documentación de cumplimiento: Registra hallazgos contra estándares regulatorios u organizacionales relevantes.
- Un informe de auditoría consolidado para stakeholders que combina todos los hallazgos: Consolida lo anterior en un único documento compartible.
Estructuras tus prompts para obtener hallazgos detallados y respaldados por evidencia sin sugerencias de remediación.
Al final de este tutorial, tienes un conjunto de documentos de auditoría que puedes compartir con stakeholders y usar como base para la planificación de remediación.
En este tutorial, la salida de Bob puede diferir de los ejemplos dependiendo del estado actual de la base de código. Usa los informes generados como punto de partida y refina los hallazgos antes de distribuirlos a los stakeholders.
Características clave que aprenderás
- Context mentions: Referencia archivos
y carpetas específicos en tus prompts usando el símbolo
@. Los context mentions permiten que Bob sepa exactamente qué archivos analizar para obtener hallazgos precisos y respaldados por evidencia. - Modo Agent: Permite que Bob escriba archivos de forma autónoma para persistir artefactos generados en tu proyecto.
- Ingeniería de prompts para salida estructurada: Estructura tu prompt para incluir el formato de salida deseado y obtener documentos listos para stakeholders en lugar de prosa narrativa.
Requisitos previos
IBM Bob IDE
Descarga e instala IBM Bob v2.x o posterior.
Git
Git es necesario para clonar el repositorio de ejemplo.
Configura tu espacio de trabajo
Clona el repositorio de Galaxium Travels
En tu terminal, ejecuta el siguiente comando para clonar el repositorio de ejemplo de Galaxium Travels:
git clone https://github.com/IBM/galaxium-travelsEste tutorial usa la rama main del repositorio, no bob-learning-path-branch.
El servicio de retención Java y otros componentes a los que hace referencia este
tutorial solo están presentes en main.
Inicia IBM Bob
Inicia el IDE de IBM Bob en tu computadora.
Abre el proyecto de ejemplo
En el IDE de Bob, abre la carpeta galaxium-travels que clonaste. Si Bob pregunta
"¿Confías en los autores de los archivos en esta carpeta?", haz clic en Sí, confío
en los autores.
Revisa el archivo README.md en el directorio raíz para obtener una descripción
general de la arquitectura de la aplicación. Galaxium Travels es un sistema de
reservas de viajes espaciales full-stack con un backend Python FastAPI, un frontend
React/TypeScript y un servicio de retención de inventario Java Spring Boot.
Abre la interfaz de chat de Bob
Si la interfaz de chat no está abierta, haz clic en el ícono de Bob en la barra de navegación o usa el atajo Option + Command + B (Mac) o Ctrl + Alt + B (Windows).
Inicializa el contexto del proyecto
Bob usa el modo Agent por defecto al iniciar. Si has cambiado de modo, cambia al modo Agent antes de ejecutar el comando de inicialización. Bob necesita escribir archivos para configurar el contexto del proyecto. Este tutorial usa las capacidades predeterminadas del modo Agent en lugar de limitar permisos por tarea, por lo que Bob puede leer y escribir archivos sin configuración adicional.
Ingresa el comando /init en el campo de entrada de la interfaz de chat.
/initSi la aprobación automática está deshabilitada, Bob solicita tu permiso antes de
leer archivos y escribir cambios. Aprueba estos prompts cuando aparezcan — esto se
aplica al comando /init y a cada informe que Bob escriba más adelante en el
tutorial.
Bob lee los archivos relevantes en el proyecto y genera el archivo principal
AGENTS.md en el directorio raíz, junto con una carpeta .bob/ que contiene
archivos AGENTS.md específicos del modo. Verifica que AGENTS.md y una carpeta
.bob/ aparezcan en la raíz del proyecto antes de continuar. Revisa los archivos
generados para entender qué ha inferido Bob sobre la estructura del proyecto, el
stack tecnológico y los patrones clave. Este contexto mejora directamente la calidad
del análisis en prompts posteriores.
Genera un resumen de calidad de código
Un resumen de calidad de código proporciona a ingenieros y revisores una vista estructurada de problemas en toda la base de código: anti-patrones, salvaguardas faltantes, brechas en la cobertura de pruebas e inconsistencias que se acumulan durante la vida de un proyecto. A diferencia de un informe de linter, un resumen de calidad generado por Bob sintetiza hallazgos a través de lenguajes y capas con explicaciones legibles por humanos y contexto de severidad.
La base de código de Galaxium Travels abarca tres stacks distintos: Python (backend), TypeScript (frontend) y Java (servicio de retención). Estructura tu prompt para analizar cada servicio de forma independiente y luego producir una tabla de hallazgos unificada. Usa context mentions para dar a Bob un alcance de archivo preciso en lugar de dejar que Bob adivine qué archivos son relevantes.
Inicia una nueva tarea
Haz clic en el botón + para iniciar una nueva tarea. Empezar de nuevo mantiene
el contexto de este prompt limitado a los archivos que mencionas aquí, en lugar de
arrastrar todo lo que Bob leyó durante /init.
Genera el resumen de calidad de código
En modo Agent, ingresa el siguiente prompt en el campo de entrada del chat:
Analyze the code quality of the Galaxium Travels application across all three
services.
For the Python backend, examine @booking_system_backend/server.py,
@booking_system_backend/models.py, @booking_system_backend/services, and
@booking_system_backend/tests.
For the TypeScript frontend, examine @booking_system_frontend/src.
For the Java hold service, examine
@booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice.
Produce a structured Markdown file named `docs/audit/code-quality-summary.md`.
The content should include the following sections:
1. An overview table listing each component, language, files analyzed, and
issue count by severity (Critical, High, Medium, Low).
2. Per-component findings, each with: severity label, issue title, file and
approximate line reference, description, and impact.
Focus on: missing input validation, inconsistent error handling, authentication
and credential storage patterns, test coverage gaps, type safety, and logging
practices. Do not suggest fixes — only report findings with evidence from the
source files.Bob analiza los tres servicios, crea el directorio docs/audit/ si aún no existe,
crea el archivo Markdown y genera un resumen en la interfaz de chat. El informe
contiene las secciones y estructura que especificaste, con hallazgos que hacen
referencia a archivos específicos y líneas de código como evidencia.
Verifica el informe
Abre docs/audit/code-quality-summary.md en el explorador de archivos de Bob para
confirmar que el archivo se creó con la tabla de resumen y los hallazgos por
componente antes de continuar.
Ejecuta una auditoría de dependencias
Una auditoría de dependencias establece si las bibliotecas de las que depende un proyecto están fijadas a versiones conocidas como buenas, si las estrategias de fijación son consistentes en todo el stack políglota y si alguna práctica de configuración de dependencias introduce riesgo de actualización no controlado. Esto es distinto de un escaneo CVE: estás evaluando la disciplina de gestión de versiones, no solo vulnerabilidades conocidas.
El proyecto Galaxium Travels tiene tres manifiestos de dependencias:
booking_system_backend/requirements.txt (Python),
booking_system_frontend/package.json (Node.js) y
booking_system_inventory_hold_service/pom.xml (Java/Maven). Incluye los tres en
tus context mentions.
Inicia una nueva tarea
Haz clic en el botón + para iniciar una nueva tarea.
Genera la auditoría de dependencias
En modo Agent, ingresa el siguiente prompt en el campo de entrada del chat:
Audit the dependency manifests for all three services in the Galaxium Travels
repository.
Analyze @booking_system_backend/requirements.txt,
@booking_system_frontend/package.json, and
@booking_system_inventory_hold_service/pom.xml.
Produce a structured Markdown file named `docs/audit/dependency-audit.md`.
The content should include these sections:
1. Per-manifest findings table: package name, declared version or range,
pinning status (exact, caret/tilde range, or unpinned), and a brief
finding note.
2. Cross-cutting findings: consistency issues, missing tooling (lock files,
audit CI steps, vulnerability scanners), and version drift risks.
3. Findings that require immediate attention before a production deployment,
listed with rationale.
Report findings only. Do not generate upgrade commands or patch suggestions.Bob analiza los manifiestos y escribe el informe. Incluye una tabla de estado de fijación y una sección de hallazgos transversales.
Verifica el informe
Abre docs/audit/dependency-audit.md para confirmar que las tablas por manifiesto
y la sección de hallazgos transversales están presentes antes de continuar.
Evalúa la deuda técnica
Una evaluación de deuda técnica evalúa decisiones estructurales, arquitectónicas y operacionales que acumulan costo con el tiempo. Estructura tu prompt para separar la deuda en arquitectura, seguridad, preparación operacional y calidad de código, y para calificar la severidad y el esfuerzo de remediación de cada elemento para que el liderazgo pueda priorizarlo.
El siguiente prompt incluye AGENTS.md en los context mentions para dar a Bob
información sobre la arquitectura inferida y los patrones operacionales, lo que
puede informar la evaluación de deuda arquitectónica y operacional. El comando
/init que ejecutaste en la sección Inicializa el contexto del proyecto
creó el archivo AGENTS.md.
Inicia una nueva tarea
Haz clic en el botón + para iniciar una nueva tarea.
Genera la evaluación de deuda técnica
En modo Agent, ingresa el siguiente prompt en el campo de entrada del chat:
Conduct a technical debt assessment of the Galaxium Travels application.
Analyze the full codebase across all three services:
@booking_system_backend, @booking_system_frontend, and
@booking_system_inventory_hold_service.
Also review @docker-compose.yml and @AGENTS.md for infrastructure and
operational context.
Produce a structured Markdown file named `docs/audit/technical-debt-assessment.md`.
The content should include these sections: Architecture Debt, Security Debt, Operational Readiness Debt, and Code Quality Debt.
For each debt item include:
- A severity label: [CRITICAL], [HIGH], [MEDIUM], or [LOW]
- An effort-to-resolve label: [DAYS], [WEEKS], or [MONTHS]
- A title
- The affected files or components
- A description of the debt and why it matters
- The consequence of leaving it unaddressed
Conclude with a summary table: category, count by severity, and total items.
Report findings only. Do not generate implementation plans or code.Bob analiza la base de código y escribe el informe, etiquetando cada elemento de deuda con estimaciones de severidad y esfuerzo.
Verifica el informe
Abre docs/audit/technical-debt-assessment.md para confirmar que las cuatro
categorías de deuda y la tabla de resumen están presentes antes de continuar.
Genera documentación de cumplimiento
La documentación de cumplimiento mapea el estado actual de una base de código contra los controles que reguladores, auditores y equipos de seguridad empresarial esperan encontrar en un sistema de producción. Para stakeholders que no son ingenieros, este documento responde la pregunta: "¿Qué hace este sistema con datos sensibles, cómo se controla el acceso y dónde están las brechas?"
Estructura tu prompt para cubrir clasificación de datos, autenticación y control de acceso, protección de datos, cobertura de pista de auditoría y cumplimiento de licencias.
Inicia una nueva tarea
Haz clic en el botón + para iniciar una nueva tarea.
Genera la documentación de cumplimiento
En modo Agent, ingresa el siguiente prompt en el campo de entrada del chat:
Generate compliance documentation for the Galaxium Travels application,
suitable for sharing with security reviewers and compliance stakeholders.
Analyze the following files and directories:
@booking_system_backend/models.py,
@booking_system_backend/server.py,
@booking_system_backend/services,
@booking_system_backend/requirements.txt,
@booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice/domain,
@booking_system_inventory_hold_service/pom.xml,
@booking_system_frontend/src,
@booking_system_frontend/package.json,
@LICENSE.
Produce a structured Markdown file named `docs/audit/compliance-documentation.md`. The content should include these sections:
1. Data Classification — table of data elements, classification tier, storage
location, and retention policy.
2. Authentication and Access Control — table of controls, implementation status
(Implemented / Partial / Not Implemented), and a source reference or gap note.
3. Data Protection — table of controls, implementation status, and notes.
4. Audit Trail Coverage — what is logged, what is not, and where audit records
are stored.
5. License Compliance — table of key dependencies (Python, Node, and Java) with
their license and a compliance note.
6. Regulatory Applicability — brief assessment of GDPR, SOC 2, and PCI DSS
applicability given the data the system handles.
Use neutral, factual language. Do not recommend remediations.Bob analiza los archivos fuente y escribe el informe, mapeando cada control a un estado de implementación con una referencia de código.
Verifica el informe
Abre docs/audit/compliance-documentation.md para confirmar que las seis secciones
están presentes antes de continuar.
Compila un informe de auditoría para stakeholders
Con cuatro análisis separados completos, pide a Bob que los ensamble en un único informe de auditoría orientado a ejecutivos. Un informe para stakeholders difiere de los análisis por tema: comienza con un resumen de hallazgos, prioriza los elementos más accionables y proporciona un orden de remediación recomendado sobre el que los lectores no técnicos pueden actuar.
El prompt usa context mentions para cargar los cuatro informes que Bob escribió en disco en las secciones anteriores. Bob lee esos archivos y los sintetiza en un único documento en lugar de volver a analizar el código fuente, por lo que la salida refleja los hallazgos que ya has revisado.
Inicia una nueva tarea
Haz clic en el botón + para iniciar una nueva tarea.
Genera el informe de auditoría para stakeholders
En modo Agent, ingresa el siguiente prompt en el campo de entrada del chat:
Using @docs/audit/code-quality-summary.md, @docs/audit/dependency-audit.md,
@docs/audit/technical-debt-assessment.md,
and @docs/audit/compliance-documentation.md, compile a consolidated
stakeholder audit report for the Galaxium Travels application.
The audience is engineering leadership and security reviewers who need to
assess the system's production readiness and compliance posture without
reading four separate documents.
Structure the report as follows:
1. Executive Summary: 2-3 paragraphs covering overall state, most critical
risks, and the highest-priority remediation categories.
2. Production Readiness Scorecard: a table scoring the system against six
dimensions (Authentication, Data Protection, Observability, Dependency
Health, Test Coverage, Operational Readiness) with a RAG status
(Red / Amber / Green) and a one-line rationale for each.
3. Critical and High Findings: a consolidated table of all Critical and High
severity findings from all four analyses, with category, finding title,
affected component, and effort to resolve.
4. Recommended Remediation Sequence: an ordered list of the top 5 items to
address first, with a brief rationale for the ordering.
5. Positive Findings: a brief section acknowledging controls and practices
that are already well-implemented.
Do not repeat all findings in full. Reference the detailed documents for
complete findings. Save the report as `docs/audit/stakeholder-audit-report.md`.Bob lee los cuatro informes guardados, sintetiza sus hallazgos y crea
docs/audit/stakeholder-audit-report.md. Debido a que Bob trabaja a partir de los
informes que ya revisaste en lugar de volver a analizar el código fuente, el informe
consolidado permanece consistente con los hallazgos detallados.
Verifica el informe
Abre docs/audit/stakeholder-audit-report.md para confirmar que el resumen ejecutivo,
el scorecard y las cinco secciones están presentes. Ahora tienes un conjunto completo
de documentos de auditoría en docs/audit/ para compartir con stakeholders y usar
como base para la planificación de remediación.
Solución de problemas
El análisis de Bob omite un servicio o archivo
Si la salida de Bob falta hallazgos para un componente que esperabas ver cubierto, la causa más probable es que el prompt no incluyó el archivo o directorio en el context mention, o la ventana de contexto estaba demasiado llena para que Bob leyera todo el contenido referenciado en un solo paso.
Verifica tus context mentions
Verifica que la mención @ en tu prompt se resuelva a la ruta correcta. En la
interfaz de chat de Bob, Bob puede indicar si se resolvió un context mention. Si
Bob no reconoce la mención, la ruta puede estar mal escrita o el directorio puede
no existir en tu clon local.
Para directorios con muchos archivos, Bob puede leer solo un subconjunto. Reduce el alcance al subdirectorio más relevante o enumera archivos específicos en lugar de referenciar toda la carpeta.
Divide el análisis en prompts enfocados
En lugar de un solo prompt que cubra los tres servicios, ejecuta tres prompts separados, uno por servicio, y luego pide a Bob que fusione los hallazgos. Por ejemplo, aquí está el tercer prompt enfocado después de completar los pases de Python y TypeScript:
The code quality analysis we ran earlier covered the Python backend and
TypeScript frontend. Run the same analysis for the Java hold service only,
using @booking_system_inventory_hold_service/src. Use the same output format
and severity labels as the earlier reports.Después de que cada análisis enfocado esté completo, pide a Bob que los fusione:
Combine the three per-service code quality analyses into a single unified
report using the same format we used for the initial report.Los informes contienen hallazgos contradictorios entre prompts
Al ejecutar una sesión de múltiples prompts, los prompts posteriores pueden producir hallazgos que parecen contradecir los anteriores. Esto puede suceder si Bob extrae diferentes inferencias de diferentes lecturas de archivos, o si un hallazgo anterior fue impreciso.
Identifica las afirmaciones contradictorias
Cita ambos hallazgos en un nuevo prompt y pide a Bob que resuelva la discrepancia con una referencia de archivo específica. Por ejemplo:
In the code quality summary you stated that error handling in server.py is
inconsistent. In the technical debt assessment you described the same issue
as absent error handling. Review @booking_system_backend/server.py and clarify
which description is more accurate, with a specific line reference.Actualiza el informe afectado
Después de que Bob haya producido el hallazgo autorizado, pide a Bob que actualice la sección específica en el archivo de informe guardado. Por ejemplo, si la evaluación de deuda técnica es más precisa, pide a Bob que actualice el resumen de calidad de código:
Update the error handling finding in docs/audit/code-quality-summary.md to
use the corrected description. Do not change any other section.Bob agrega recomendaciones no solicitadas al análisis
Cuando un prompt pide a Bob "analizar" o "evaluar" sin restricciones explícitas, Bob a menudo incluye sugerencias de remediación junto con los hallazgos. Para un informe de cumplimiento o auditoría, las recomendaciones no solicitadas pueden ser problemáticas: pueden ser incorrectas, pueden reflejar suposiciones sobre el entorno objetivo y pueden confundir a los stakeholders que esperan un documento solo de hallazgos.
Agrega la instrucción "Report findings only. Do not generate implementation plans, code, or remediation suggestions." a cualquier prompt de análisis donde esto importe. Si Bob ya ha generado un informe con contenido mixto, pide a Bob que elimine las recomendaciones. Por ejemplo, si el resumen de calidad de código contiene recomendaciones, ingresa el siguiente prompt:
Remove all remediation suggestions, implementation guidance, and code examples
from docs/audit/code-quality-summary.md. Keep all finding descriptions,
severity labels, file references, and impact statements exactly as written.Limpieza
Para eliminar los artefactos creados en este tutorial:
- Elimina el directorio
docs/audit/, que contiene los cinco informes generados. - Si no deseas conservar el contexto del proyecto que Bob generó, elimina el
archivo
AGENTS.mdy la carpeta.bob/que creó el comando/init. - Elimina el directorio
galaxium-travelsque clonaste en Configura tu espacio de trabajo.
Próximos pasos
En este tutorial, usaste IBM Bob para:
- Inicializar el contexto del proyecto con
/initpara que el análisis de Bob refleje la estructura y el stack tecnológico del proyecto - Generar cuatro artefactos de auditoría enfocados: un resumen de calidad de código, una auditoría de dependencias, una evaluación de deuda técnica y documentación de cumplimiento. Cada uno respaldado por evidencia de los archivos fuente
- Compilar los cuatro análisis en un único informe de auditoría para stakeholders con un scorecard de preparación para producción y una secuencia de remediación recomendada
- Usar el modo Agent y context mentions para persistir cada informe en disco, manteniendo los análisis autocontenidos y eficientes en tokens
Continúa con los siguientes recursos:
- Sigue Audit code and generate reports para producir artefactos SARIF y OSCAL legibles por máquina sobre los que las herramientas de desarrollo y los agentes de IA pueden actuar.
- Usa los hallazgos como base, luego sigue Generate secure code with an actor-critic workflow para remediar sin reintroducir los problemas que esta auditoría descubrió.
- Lee Bob best practices para estrategias de prompting más efectivas.
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.
Planifica e implementa funciones complejas
Usa el modo Plan de IBM Bob para definir el alcance, revisar e implementar funciones complejas con un agente de codificación de IA. Aprende a escribir un prompt de planificación, refinar el plan generado y ejecutar la implementación en modo Agent.