Tutoriales

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:

  1. Un resumen de calidad de código: Destaca problemas de mantenibilidad, complejidad y estilo en toda la base de código.
  2. Una auditoría de dependencias: Marca paquetes de terceros obsoletos, vulnerables o no utilizados.
  3. Una evaluación de deuda técnica: Cataloga atajos, soluciones temporales y áreas que necesitan refactorización.
  4. Documentación de cumplimiento: Registra hallazgos contra estándares regulatorios u organizacionales relevantes.
  5. 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

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-travels

Este 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.

/init

Si 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:

  1. Elimina el directorio docs/audit/, que contiene los cinco informes generados.
  2. Si no deseas conservar el contexto del proyecto que Bob generó, elimina el archivo AGENTS.md y la carpeta .bob/ que creó el comando /init.
  3. Elimina el directorio galaxium-travels que clonaste en Configura tu espacio de trabajo.

Próximos pasos

En este tutorial, usaste IBM Bob para:

  • Inicializar el contexto del proyecto con /init para 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:

¿Cómo es este tema?