Gera relatórios de auditoria e documentação de conformidade
Usa o IBM Bob para analisar a base de código do Galaxium Travels e produzir relatórios de auditoria estruturados cobrindo qualidade de código, saúde de dependências, dívida técnica e postura de conformidade. Aprende a montar documentação pronta para stakeholders a partir de análise assistida por IA.
As auditorias de software produzem a evidência documental em que as equipes de engenharia, revisores de segurança e stakeholders de conformidade confiam antes de enviar, adquirir ou certificar um sistema.
Neste tutorial, usas o Bob para analisar sistematicamente a base de código do Galaxium Travels e gerar cinco artefatos estruturados:
- Um resumo de qualidade de código: Destaca problemas de manutenibilidade, complexidade e estilo em toda a base de código.
- Uma auditoria de dependências: Sinaliza pacotes de terceiros desatualizados, vulneráveis ou não utilizados.
- Uma avaliação de dívida técnica: Cataloga atalhos, soluções alternativas e áreas que precisam de refatoração.
- Documentação de conformidade: Regista descobertas contra padrões regulatórios ou organizacionais relevantes.
- Um relatório de auditoria consolidado para stakeholders que combina todas as descobertas: Consolida o acima num único documento partilhável.
Estruturas os teus prompts para obter descobertas detalhadas e apoiadas por evidências sem sugestões de remediação.
No final deste tutorial, tens um conjunto de documentos de auditoria que podes partilhar com stakeholders e usar como base para o planeamento de remediação.
Neste tutorial, a saída do Bob pode diferir dos exemplos dependendo do estado atual da base de código. Usa os relatórios gerados como ponto de partida e refina as descobertas antes de distribuí-las aos stakeholders.
Recursos principais que aprendes
- Context mentions: Referencia ficheiros e
pastas específicos nos teus prompts usando o símbolo
@. Os context mentions permitem que o Bob saiba exatamente quais ficheiros analisar para descobertas precisas e apoiadas por evidências. - Modo Agent: Permite que o Bob escreva ficheiros autonomamente para persistir artefatos gerados no teu projeto.
- Engenharia de prompts para saída estruturada: Estrutura o teu prompt para incluir o formato de saída desejado para obter documentos prontos para stakeholders em vez de prosa narrativa.
Pré-requisitos
IBM Bob IDE
Descarrega e instala o IBM Bob v2.x ou posterior.
Git
O Git é necessário para clonar o repositório de exemplo.
Configura o teu espaço de trabalho
Clona o repositório Galaxium Travels
No teu terminal, executa o seguinte comando para clonar o repositório de exemplo Galaxium Travels:
git clone https://github.com/IBM/galaxium-travelsEste tutorial usa o branch main do repositório, não o bob-learning-path-branch.
O serviço de retenção Java e outros componentes a que este tutorial se refere estão
presentes apenas no main.
Inicia o IBM Bob
Inicia o IDE IBM Bob no teu computador.
Abre o projeto de exemplo
No IDE do Bob, abre a pasta galaxium-travels que clonaste. Se o Bob perguntar
"Confias nos autores dos ficheiros nesta pasta?", clica em Sim, confio nos autores.
Revê o ficheiro README.md no diretório raiz para obter uma visão geral da arquitetura
da aplicação. O Galaxium Travels é um sistema de reservas de viagens espaciais full-stack
com um backend Python FastAPI, um frontend React/TypeScript e um serviço de retenção de
inventário Java Spring Boot.
Abre a interface de chat do Bob
Se a interface de chat ainda não estiver aberta, clica no ícone do Bob na barra de navegação ou usa o atalho Option + Command + B (Mac) ou Ctrl + Alt + B (Windows).
Inicializa o contexto do projeto
O Bob usa o modo Agent por padrão na inicialização. Se mudaste de modo, muda para o modo Agent antes de executar o comando de inicialização. O Bob precisa de escrever ficheiros para configurar o contexto do projeto. Este tutorial usa as capacidades padrão do modo Agent em vez de limitar permissões por tarefa, para que o Bob possa ler e escrever ficheiros sem configuração adicional.
Introduz o comando /init no campo de entrada da interface de chat.
/initSe a aprovação automática estiver desativada, o Bob pede a tua permissão antes de ler
ficheiros e escrever alterações. Aprova estes prompts quando aparecerem — isto aplica-se
ao comando /init e a cada relatório que o Bob escrever mais tarde no tutorial.
O Bob lê os ficheiros relevantes no projeto e gera o ficheiro principal AGENTS.md no
diretório raiz, juntamente com uma pasta .bob/ contendo ficheiros AGENTS.md
específicos do modo. Verifica que AGENTS.md e uma pasta .bob/ aparecem na raiz do
projeto antes de continuar. Revê os ficheiros gerados para entender o que o Bob inferiu
sobre a estrutura do projeto, stack tecnológico e padrões-chave. Este contexto melhora
diretamente a qualidade da análise em prompts subsequentes.
Gera um resumo de qualidade de código
Um resumo de qualidade de código dá aos engenheiros e revisores uma visão estruturada dos problemas em toda a base de código: anti-padrões, salvaguardas em falta, lacunas na cobertura de testes e inconsistências que se acumulam ao longo da vida de um projeto. Ao contrário de um relatório de linter, um resumo de qualidade gerado pelo Bob sintetiza descobertas através de linguagens e camadas com explicações legíveis por humanos e contexto de gravidade.
A base de código do Galaxium Travels abrange três stacks distintos: Python (backend), TypeScript (frontend) e Java (serviço de retenção). Estrutura o teu prompt para analisar cada serviço independentemente e depois produzir uma tabela de descobertas unificada. Usa context mentions para dar ao Bob um âmbito de ficheiro preciso em vez de deixar o Bob adivinhar quais ficheiros são relevantes.
Inicia uma nova tarefa
Clica no botão + para iniciar uma nova tarefa. Começar de novo mantém o contexto
deste prompt limitado aos ficheiros que mencionas aqui, em vez de transportar tudo o
que o Bob leu durante /init.
Gera o resumo de qualidade de código
No modo Agent, introduz o seguinte prompt no campo de entrada do 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.O Bob analisa os três serviços, cria o diretório docs/audit/ se ainda não existir,
cria o ficheiro Markdown e gera um resumo na interface de chat. O relatório contém as
seções e estrutura que especificaste, com descobertas que referenciam ficheiros
específicos e linhas de código como evidência.
Verifica o relatório
Abre docs/audit/code-quality-summary.md no explorador de ficheiros do Bob para
confirmar que o ficheiro foi criado com a tabela de visão geral e descobertas por
componente antes de continuar.
Executa uma auditoria de dependências
Uma auditoria de dependências estabelece se as bibliotecas de que um projeto depende estão fixadas a versões conhecidas como boas, se as estratégias de fixação são consistentes em todo o stack políglota e se alguma prática de configuração de dependências introduz risco de atualização não controlado. Isto é distinto de uma verificação CVE: estás a avaliar a disciplina de gestão de versões, não apenas vulnerabilidades conhecidas.
O projeto Galaxium Travels tem três manifestos de dependências:
booking_system_backend/requirements.txt (Python),
booking_system_frontend/package.json (Node.js) e
booking_system_inventory_hold_service/pom.xml (Java/Maven). Inclui os três nos teus
context mentions.
Inicia uma nova tarefa
Clica no botão + para iniciar uma nova tarefa.
Gera a auditoria de dependências
No modo Agent, introduz o seguinte prompt no campo de entrada do 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.O Bob analisa os manifestos e escreve o relatório. Inclui uma tabela de estado de fixação e uma seção de descobertas transversais.
Verifica o relatório
Abre docs/audit/dependency-audit.md para confirmar que as tabelas por manifesto e a
seção de descobertas transversais estão presentes antes de continuar.
Avalia a dívida técnica
Uma avaliação de dívida técnica avalia decisões estruturais, arquiteturais e operacionais que acumulam custo ao longo do tempo. Estrutura o teu prompt para separar a dívida em arquitetura, segurança, prontidão operacional e qualidade de código, e para classificar a gravidade e o esforço de remediação de cada item para que a liderança possa priorizar.
O seguinte prompt inclui AGENTS.md nos context mentions para dar ao Bob informações
sobre a arquitetura inferida e padrões operacionais, o que pode informar a avaliação da
dívida arquitetural e operacional. O comando /init que executaste na seção
Inicializa o contexto do projeto criou o ficheiro
AGENTS.md.
Inicia uma nova tarefa
Clica no botão + para iniciar uma nova tarefa.
Gera a avaliação de dívida técnica
No modo Agent, introduz o seguinte prompt no campo de entrada do 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.O Bob analisa a base de código e escreve o relatório, etiquetando cada item de dívida com estimativas de gravidade e esforço.
Verifica o relatório
Abre docs/audit/technical-debt-assessment.md para confirmar que as quatro categorias
de dívida e a tabela de resumo estão presentes antes de continuar.
Gera documentação de conformidade
A documentação de conformidade mapeia o estado atual de uma base de código contra os controlos que reguladores, auditores e equipas de segurança empresarial esperam encontrar num sistema de produção. Para stakeholders que não são engenheiros, este documento responde à pergunta: "O que este sistema faz com dados sensíveis, como é controlado o acesso e onde estão as lacunas?"
Estrutura o teu prompt para cobrir classificação de dados, autenticação e controlo de acesso, proteção de dados, cobertura de trilha de auditoria e conformidade de licenças.
Inicia uma nova tarefa
Clica no botão + para iniciar uma nova tarefa.
Gera a documentação de conformidade
No modo Agent, introduz o seguinte prompt no campo de entrada do 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.O Bob analisa os ficheiros fonte e escreve o relatório, mapeando cada controlo para um estado de implementação com uma referência de código.
Verifica o relatório
Abre docs/audit/compliance-documentation.md para confirmar que todas as seis seções
estão presentes antes de continuar.
Compila um relatório de auditoria para stakeholders
Com quatro análises separadas completas, pede ao Bob para montá-las num único relatório de auditoria voltado para executivos. Um relatório para stakeholders difere das análises por tópico: começa com um resumo de descobertas, prioriza os itens mais acionáveis e fornece uma ordem de remediação recomendada sobre a qual leitores não técnicos podem agir.
O prompt usa context mentions para carregar os quatro relatórios que o Bob escreveu no disco nas seções anteriores. O Bob lê esses ficheiros e sintetiza-os num único documento em vez de reanalisar o código fonte, para que a saída reflita as descobertas que já reviste.
Inicia uma nova tarefa
Clica no botão + para iniciar uma nova tarefa.
Gera o relatório de auditoria para stakeholders
No modo Agent, introduz o seguinte prompt no campo de entrada do 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`.O Bob lê os quatro relatórios guardados, sintetiza as suas descobertas e cria
docs/audit/stakeholder-audit-report.md. Como o Bob trabalha a partir dos relatórios
que já reviste em vez de reanalisar o código fonte, o relatório consolidado permanece
consistente com as descobertas detalhadas.
Verifica o relatório
Abre docs/audit/stakeholder-audit-report.md para confirmar que o resumo executivo, o
scorecard e as cinco seções estão presentes. Agora tens um conjunto completo de
documentos de auditoria em docs/audit/ para partilhar com stakeholders e usar como
base para o planeamento de remediação.
Resolução de problemas
A análise do Bob omite um serviço ou ficheiro
Se a saída do Bob estiver a faltar descobertas para um componente que esperavas ver coberto, a causa mais provável é que o prompt não incluiu o ficheiro ou diretório no context mention, ou a janela de contexto estava demasiado cheia para o Bob ler todo o conteúdo referenciado numa única passagem.
Verifica os teus context mentions
Verifica que a menção @ no teu prompt resolve para o caminho correto. Na interface de
chat do Bob, o Bob pode indicar se um context mention foi resolvido. Se o Bob não
reconhecer a menção, o caminho pode estar mal escrito ou o diretório pode não existir
no teu clone local.
Para diretórios com muitos ficheiros, o Bob pode ler apenas um subconjunto. Reduz o âmbito ao subdiretório mais relevante ou enumera ficheiros específicos em vez de referenciar a pasta inteira.
Divide a análise em prompts focados
Em vez de um único prompt cobrindo todos os três serviços, executa três prompts separados, um por serviço, e depois pede ao Bob para fundir as descobertas. Por exemplo, aqui está o terceiro prompt focado após completar as passagens Python e 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.Após cada análise focada estar completa, pede ao Bob para fundi-las:
Combine the three per-service code quality analyses into a single unified
report using the same format we used for the initial report.Os relatórios contêm descobertas conflituantes entre prompts
Ao executar uma sessão multi-prompt, prompts posteriores podem produzir descobertas que parecem contradizer as anteriores. Isto pode acontecer se o Bob tirar inferências diferentes de diferentes leituras de ficheiros, ou se uma descoberta anterior foi imprecisa.
Identifica as afirmações conflituantes
Cita ambas as descobertas num novo prompt e pede ao Bob para resolver a discrepância com uma referência de ficheiro específica. Por exemplo:
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.Atualiza o relatório afetado
Depois de o Bob ter produzido a descoberta autoritativa, pede ao Bob para atualizar a seção específica no ficheiro de relatório guardado. Por exemplo, se a avaliação de dívida técnica for mais precisa, pede ao Bob para atualizar o resumo de qualidade 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.O Bob adiciona recomendações não solicitadas à análise
Quando um prompt pede ao Bob para "analisar" ou "avaliar" sem restrições explícitas, o Bob frequentemente inclui sugestões de remediação ao lado das descobertas. Para um relatório de conformidade ou auditoria, recomendações não solicitadas podem ser problemáticas: podem estar incorretas, podem refletir suposições sobre o ambiente alvo e podem confundir stakeholders que esperam um documento apenas de descobertas.
Adiciona a instrução "Report findings only. Do not generate implementation plans, code, or remediation suggestions." a qualquer prompt de análise onde isto importa. Se o Bob já gerou um relatório com conteúdo misto, pede ao Bob para remover as recomendações. Por exemplo, se o resumo de qualidade de código contém recomendações, introduz o seguinte 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.Limpeza
Para remover os artefatos criados neste tutorial:
- Elimina o diretório
docs/audit/, que contém os cinco relatórios gerados. - Se não quiseres manter o contexto do projeto que o Bob gerou, elimina o ficheiro
AGENTS.mde a pasta.bob/que o comando/initcriou. - Elimina o diretório
galaxium-travelsque clonaste em Configura o teu espaço de trabalho.
Próximos passos
Neste tutorial, usaste o IBM Bob para:
- Inicializar o contexto do projeto com
/initpara que a análise do Bob reflita a estrutura e stack tecnológico do projeto - Gerar quatro artefatos de auditoria focados: um resumo de qualidade de código, uma auditoria de dependências, uma avaliação de dívida técnica e documentação de conformidade. Cada um apoiado por evidências dos ficheiros fonte
- Compilar as quatro análises num único relatório de auditoria para stakeholders com um scorecard de prontidão de produção e uma sequência de remediação recomendada
- Usar o modo Agent e context mentions para persistir cada relatório no disco, mantendo as análises autocontidas e eficientes em tokens
Continua com os seguintes recursos:
- Segue Audit code and generate reports para produzir artefatos SARIF e OSCAL legíveis por máquina sobre os quais ferramentas de desenvolvimento e agentes de IA podem agir.
- Usa as descobertas como base, depois segue Generate secure code with an actor-critic workflow para remediar sem reintroduzir os problemas que esta auditoria revelou.
- Lê Bob best practices para estratégias de prompting mais eficazes.
Gerar diagramas de arquitetura
Use o IBM Bob para analisar a base de código do Galaxium Travels e gerar diagramas de classes UML Mermaid, diagramas de sequência e diagramas de casos de uso. Aprenda a usar menções de contexto no modo Ask para explorar código e o modo Agent para salvar os resultados no seu repositório.
Planeja e implementa funcionalidades complexas
Usa o modo Plan do IBM Bob para definir o escopo, revisar e implementar funcionalidades complexas com um agente de codificação de IA. Aprende a escrever um prompt de planejamento, refinar o plano gerado e executar a implementação no modo Agent.