Tutorial

Membuat laporan audit dan dokumentasi compliance

Gunakan IBM Bob untuk menganalisis codebase Galaxium Travels dan menghasilkan laporan audit terstruktur yang mencakup kualitas kode, kesehatan dependency, technical debt, dan posture compliance. Pelajari cara menyusun dokumentasi siap pakai untuk stakeholder dari analisis berbantuan AI.

Audit perangkat lunak menghasilkan bukti dokumenter yang diandalkan tim engineering, reviewer keamanan, dan stakeholder compliance sebelum mengirim, mengakuisisi, atau mensertifikasi sebuah sistem.

Dalam tutorial ini, kamu menggunakan Bob untuk menganalisis codebase Galaxium Travels secara sistematis dan menghasilkan lima artefak terstruktur:

  1. Ringkasan kualitas kode: Menyoroti isu maintainability, complexity, dan style di seluruh codebase.
  2. Audit dependency: Menandai package pihak ketiga yang usang, rentan, atau tidak digunakan.
  3. Assessment technical debt: Mengatalogkan shortcut, workaround, dan area yang perlu di-refactor.
  4. Dokumentasi compliance: Mencatat temuan terhadap standar regulasi atau organisasi yang relevan.
  5. Laporan audit stakeholder terkompilasi yang menggabungkan semua temuan: Mengonsolidasikan seluruh hasil di atas menjadi satu dokumen yang bisa dibagikan.

Kamu akan menyusun prompt agar menghasilkan temuan yang rinci dan didukung bukti tanpa saran remediation.

Pada akhir tutorial ini, kamu akan memiliki sekumpulan dokumen audit yang bisa kamu bagikan kepada stakeholder dan gunakan sebagai baseline untuk perencanaan remediation.

Dalam tutorial ini, output Bob bisa berbeda dari contoh tergantung pada kondisi codebase saat ini. Gunakan laporan yang dihasilkan sebagai titik awal lalu sempurnakan temuannya sebelum membagikannya kepada stakeholder.

Fitur utama yang dipelajari

  • Context mentions: Rujuk file dan folder tertentu di prompt menggunakan simbol @. Context mentions membantu Bob mengetahui file mana yang tepat untuk dianalisis agar temuannya akurat dan didukung bukti.
  • Agent mode: Biarkan Bob menulis file secara mandiri untuk menyimpan artefak yang dihasilkan ke proyekmu.
  • Prompt engineering untuk output terstruktur: Susun prompt dengan format output yang kamu inginkan agar mendapatkan dokumen siap pakai untuk stakeholder, bukan prosa naratif.

Prasyarat

Siapkan workspace kamu

Clone repository Galaxium Travels

Di terminal, jalankan command berikut untuk meng-clone repository contoh Galaxium Travels:

git clone https://github.com/IBM/galaxium-travels

Tutorial ini menggunakan branch main milik repository, bukan bob-learning-path-branch. Java hold service dan komponen lain yang dirujuk dalam tutorial ini hanya ada di main.

Jalankan IBM Bob

Jalankan IBM Bob IDE di komputermu.

Buka proyek contoh

Di Bob IDE, buka folder galaxium-travels yang sudah kamu clone. Jika Bob bertanya "Do you trust the authors of the files in the folder?", klik Yes, I trust the authors.

Tinjau file README.md di direktori root untuk mendapatkan gambaran umum arsitektur aplikasi. Galaxium Travels adalah sistem pemesanan perjalanan luar angkasa full-stack dengan backend Python FastAPI, frontend React/TypeScript, dan layanan inventory hold berbasis Java Spring Boot.

Buka chat interface Bob

Jika chat interface belum terbuka, klik ikon Bob di navigation bar atau gunakan shortcut Option + Command + B (Mac) atau Ctrl + Alt + B (Windows).

Inisialisasi konteks proyek

Bob secara default menggunakan Agent mode saat startup. Jika kamu sudah mengganti mode, kembali ke Agent mode sebelum menjalankan command inisialisasi. Bob perlu menulis file untuk menyiapkan konteks proyek. Tutorial ini menggunakan kemampuan default Agent mode alih-alih membatasi izin per tugas, sehingga Bob bisa membaca dan menulis file tanpa konfigurasi tambahan.

Masukkan command /init di field input chat interface.

/init

Jika auto-approval dinonaktifkan, Bob akan meminta izinmu sebelum membaca file dan menulis perubahan. Setujui prompt ini saat muncul — ini berlaku untuk command /init dan untuk setiap laporan yang Bob tulis nanti dalam tutorial.

Bob membaca file-file relevan di proyek dan menghasilkan file AGENTS.md utama di direktori root, beserta folder .bob/ yang berisi file AGENTS.md khusus mode. Pastikan AGENTS.md dan folder .bob/ muncul di root proyek sebelum melanjutkan. Tinjau file-file yang dihasilkan untuk memahami apa yang Bob simpulkan tentang struktur proyek, tech stack, dan pola penting. Konteks ini secara langsung meningkatkan kualitas analisis di prompt berikutnya.

Buat ringkasan kualitas kode

Ringkasan kualitas kode memberi engineer dan reviewer pandangan terstruktur tentang isu lintas codebase: anti-pattern, safeguard yang hilang, celah cakupan test, dan inkonsistensi yang menumpuk sepanjang umur proyek. Berbeda dari laporan linter, ringkasan kualitas yang dibuat Bob mensintesis temuan lintas bahasa serta layer dengan penjelasan yang mudah dibaca dan konteks severity.

Codebase Galaxium Travels mencakup tiga stack berbeda: Python (backend), TypeScript (frontend), dan Java (hold service). Susun promptmu untuk menganalisis setiap layanan secara terpisah lalu menghasilkan satu tabel temuan terpadu. Gunakan context mentions agar Bob punya cakupan file yang presisi alih-alih membiarkan Bob menebak file mana yang relevan.

Mulai task baru

Klik tombol + untuk memulai task baru. Memulai dari awal membuat konteks prompt ini terbatas pada file yang kamu sebutkan di sini, alih-alih membawa semua yang Bob baca saat /init.

Buat ringkasan kualitas kode

Dalam Agent mode, masukkan prompt berikut ke field input 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 menganalisis ketiga layanan, membuat direktori docs/audit/ jika belum ada, membuat file Markdown, lalu menampilkan ringkasan di chat interface. Laporan tersebut berisi bagian dan struktur yang kamu tentukan, dengan temuan yang merujuk ke file serta baris kode tertentu sebagai bukti.

Verifikasi laporan

Buka docs/audit/code-quality-summary.md di file explorer Bob untuk memastikan file berhasil dibuat dengan overview table dan temuan per komponen sebelum kamu melanjutkan.

Jalankan audit dependency

Audit dependency menetapkan apakah library yang digunakan proyek sudah dipatok ke versi yang diketahui aman, apakah strategi pinning konsisten di seluruh stack poliglot, dan apakah ada praktik konfigurasi dependency yang menimbulkan risiko upgrade tak terkendali. Ini berbeda dari CVE scan: kamu menilai kedisiplinan pengelolaan versi, bukan hanya kerentanan yang sudah diketahui.

Proyek Galaxium Travels memiliki tiga manifest dependency: booking_system_backend/requirements.txt (Python), booking_system_frontend/package.json (Node.js), dan booking_system_inventory_hold_service/pom.xml (Java/Maven). Sertakan ketiganya dalam context mentions milikmu.

Mulai task baru

Klik tombol + untuk memulai task baru.

Buat audit dependency

Dalam Agent mode, masukkan prompt berikut ke field input 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 menganalisis manifest dan menulis laporannya. Laporan itu mencakup tabel status pinning dan bagian temuan lintas area.

Verifikasi laporan

Buka docs/audit/dependency-audit.md untuk memastikan tabel per manifest dan bagian temuan lintas area sudah ada sebelum kamu melanjutkan.

Nilai technical debt

Assessment technical debt mengevaluasi keputusan struktural, arsitektural, dan operasional yang menumpuk biaya seiring waktu. Susun promptmu untuk memisahkan debt ke dalam kategori arsitektur, keamanan, kesiapan operasional, dan kualitas kode, serta menilai severity dan effort remediation tiap item agar pimpinan bisa memprioritaskannya.

Prompt berikut menyertakan AGENTS.md dalam context mentions untuk memberi Bob wawasan tentang arsitektur dan pola operasional yang disimpulkan, yang bisa menginformasikan penilaian debt arsitektural dan operasional. Command /init yang kamu jalankan di bagian Inisialisasi konteks proyek membuat file AGENTS.md.

Mulai task baru

Klik tombol + untuk memulai task baru.

Buat assessment technical debt

Dalam Agent mode, masukkan prompt berikut ke field input 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 menganalisis codebase dan menulis laporan, memberi label tiap item debt dengan estimasi severity dan effort.

Verifikasi laporan

Buka docs/audit/technical-debt-assessment.md untuk memastikan keempat kategori debt dan summary table sudah ada sebelum kamu melanjutkan.

Buat dokumentasi compliance

Dokumentasi compliance memetakan kondisi codebase saat ini terhadap kontrol yang diharapkan regulator, auditor, dan tim keamanan enterprise pada sistem produksi. Bagi stakeholder yang bukan engineer, dokumen ini menjawab pertanyaan: "Apa yang dilakukan sistem ini terhadap data sensitif, bagaimana akses dikendalikan, dan di mana letak celahnya?"

Susun promptmu untuk mencakup klasifikasi data, autentikasi dan access control, perlindungan data, cakupan audit trail, dan compliance lisensi.

Mulai task baru

Klik tombol + untuk memulai task baru.

Buat dokumentasi compliance

Dalam Agent mode, masukkan prompt berikut ke field input 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 menganalisis source file dan menulis laporan, memetakan tiap kontrol ke status implementasi dengan referensi kode.

Verifikasi laporan

Buka docs/audit/compliance-documentation.md untuk memastikan keenam bagian sudah ada sebelum kamu melanjutkan.

Kompilasi laporan audit untuk stakeholder

Setelah empat analisis terpisah selesai, minta Bob menyusunnya menjadi satu laporan audit untuk eksekutif. Laporan stakeholder berbeda dari analisis per topik: laporan ini dimulai dengan ringkasan temuan, memprioritaskan item paling bisa ditindaklanjuti, dan memberikan urutan remediation yang disarankan agar pembaca non-teknis bisa bertindak.

Prompt ini menggunakan context mentions untuk memuat empat laporan yang Bob tulis ke disk di bagian sebelumnya. Bob membaca file-file itu dan mensintesisnya menjadi satu dokumen alih-alih menganalisis ulang source code, sehingga output mencerminkan temuan yang sudah kamu tinjau.

Mulai task baru

Klik tombol + untuk memulai task baru.

Buat laporan audit stakeholder

Dalam Agent mode, masukkan prompt berikut ke field input 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 membaca keempat laporan yang tersimpan, mensintesis temuannya, dan membuat docs/audit/stakeholder-audit-report.md. Karena Bob bekerja dari laporan yang sudah kamu tinjau alih-alih menganalisis ulang source code, laporan gabungan ini tetap konsisten dengan temuan rinci.

Verifikasi laporan

Buka docs/audit/stakeholder-audit-report.md untuk memastikan ringkasan eksekutif, scorecard, dan kelima bagiannya ada. Sekarang kamu memiliki set lengkap dokumen audit di docs/audit/ untuk dibagikan kepada stakeholder dan digunakan sebagai baseline untuk perencanaan remediation.

Troubleshooting

Analisis Bob melewatkan layanan atau file

Jika output Bob tidak memuat temuan untuk komponen yang kamu harapkan tercakup, penyebab yang paling mungkin adalah prompt tidak menyertakan file atau direktori itu dalam context mention, atau context window terlalu penuh sehingga Bob tidak bisa membaca semua konten yang dirujuk dalam satu kali proses.

Periksa context mention milikmu

Pastikan mention @ di promptmu mengarah ke path yang benar. Di chat interface Bob, Bob mungkin menunjukkan apakah sebuah context mention berhasil di-resolve. Jika Bob tidak mengenali mention tersebut, path-nya mungkin salah ketik atau direktorinya tidak ada di clone lokalmu.

Untuk direktori dengan banyak file, Bob mungkin hanya membaca sebagian. Persempit cakupan ke subdirektori yang paling relevan atau sebutkan file-file tertentu alih-alih merujuk ke seluruh folder.

Pecah analisis menjadi prompt yang fokus

Alih-alih satu prompt yang mencakup ketiga layanan sekaligus, jalankan tiga prompt terpisah, satu untuk tiap layanan, lalu minta Bob menggabungkan temuannya. Sebagai contoh, berikut prompt terfokus ketiga setelah menyelesaikan analisis Python dan 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.

Setelah tiap analisis terfokus selesai, minta Bob menggabungkannya:

Combine the three per-service code quality analyses into a single unified
report using the same format we used for the initial report.

Laporan memuat temuan yang saling bertentangan antar prompt

Saat menjalankan sesi dengan banyak prompt, prompt berikutnya bisa menghasilkan temuan yang terlihat bertentangan dengan yang sebelumnya. Ini bisa terjadi jika Bob menarik inferensi yang berbeda dari pembacaan file yang berbeda, atau jika temuan sebelumnya kurang presisi.

Identifikasi klaim yang bertentangan

Kutip kedua temuan itu di prompt baru dan minta Bob menyelesaikan perbedaannya dengan referensi file yang spesifik. Contohnya:

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.

Perbarui laporan yang terpengaruh

Setelah Bob menghasilkan temuan yang otoritatif, minta Bob memperbarui bagian tertentu di file laporan yang disimpan. Misalnya, jika assessment technical debt lebih akurat, minta Bob memperbarui ringkasan kualitas kode:

Update the error handling finding in docs/audit/code-quality-summary.md to
use the corrected description. Do not change any other section.

Bob menambahkan rekomendasi yang tidak diminta ke analisis

Saat prompt meminta Bob untuk "analyze" atau "assess" tanpa batasan eksplisit, Bob sering menyertakan saran remediation di samping temuan. Untuk laporan compliance atau audit, rekomendasi yang tidak diminta bisa bermasalah: bisa jadi salah, bisa mencerminkan asumsi tentang lingkungan target, dan bisa membingungkan stakeholder yang mengharapkan dokumen yang hanya berisi temuan.

Tambahkan instruksi "Report findings only. Do not generate implementation plans, code, or remediation suggestions." ke prompt analisis apa pun saat ini penting. Jika Bob sudah menghasilkan laporan dengan konten campuran, minta Bob menghapus rekomendasinya. Misalnya, jika ringkasan kualitas kode berisi rekomendasi, masukkan prompt berikut:

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.

Bersihkan

Untuk menghapus artefak yang dibuat dalam tutorial ini:

  1. Hapus direktori docs/audit/, yang berisi lima laporan yang dihasilkan.
  2. Jika kamu tidak ingin menyimpan konteks proyek yang dibuat Bob, hapus file AGENTS.md dan folder .bob/ yang dibuat oleh command /init.
  3. Hapus direktori galaxium-travels yang kamu clone di Siapkan workspace kamu.

Langkah selanjutnya

Dalam tutorial ini, kamu menggunakan IBM Bob untuk:

  • Menginisialisasi konteks proyek dengan /init agar analisis Bob mencerminkan struktur proyek dan tech stack
  • Menghasilkan empat artefak audit yang terfokus: ringkasan kualitas kode, audit dependency, assessment technical debt, dan dokumentasi compliance. Masing-masing didukung bukti dari source file
  • Mengompilasi keempat analisis itu menjadi satu laporan audit stakeholder dengan production readiness scorecard dan urutan remediation yang disarankan
  • Menggunakan Agent mode dan context mentions untuk menyimpan tiap laporan ke disk, menjaga analisis tetap mandiri dan efisien dari sisi token

Lanjutkan dengan resource berikut:

Bagaimana topik ini?