Tutoriais

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:

  1. Um resumo de qualidade de código: Destaca problemas de manutenibilidade, complexidade e estilo em toda a base de código.
  2. Uma auditoria de dependências: Sinaliza pacotes de terceiros desatualizados, vulneráveis ou não utilizados.
  3. Uma avaliação de dívida técnica: Cataloga atalhos, soluções alternativas e áreas que precisam de refatoração.
  4. Documentação de conformidade: Regista descobertas contra padrões regulatórios ou organizacionais relevantes.
  5. 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

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

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

/init

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

  1. Elimina o diretório docs/audit/, que contém os cinco relatórios gerados.
  2. Se não quiseres manter o contexto do projeto que o Bob gerou, elimina o ficheiro AGENTS.md e a pasta .bob/ que o comando /init criou.
  3. Elimina o diretório galaxium-travels que 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 /init para 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:

Como está este tópico?