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:
- Ringkasan kualitas kode: Menyoroti isu maintainability, complexity, dan style di seluruh codebase.
- Audit dependency: Menandai package pihak ketiga yang usang, rentan, atau tidak digunakan.
- Assessment technical debt: Mengatalogkan shortcut, workaround, dan area yang perlu di-refactor.
- Dokumentasi compliance: Mencatat temuan terhadap standar regulasi atau organisasi yang relevan.
- 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
IBM Bob IDE
Unduh dan pasang IBM Bob v2.x atau yang lebih baru.
Git
Git diperlukan untuk meng-clone repository contoh.
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-travelsTutorial 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.
/initJika 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:
- Hapus direktori
docs/audit/, yang berisi lima laporan yang dihasilkan. - Jika kamu tidak ingin menyimpan konteks proyek yang dibuat Bob, hapus file
AGENTS.mddan folder.bob/yang dibuat oleh command/init. - Hapus direktori
galaxium-travelsyang kamu clone di Siapkan workspace kamu.
Langkah selanjutnya
Dalam tutorial ini, kamu menggunakan IBM Bob untuk:
- Menginisialisasi konteks proyek dengan
/initagar 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:
- Ikuti Audit code and generate reports untuk menghasilkan artefak SARIF dan OSCAL yang machine-readable, sehingga tooling developer dan agen AI bisa menindaklanjutinya.
- Gunakan temuan tersebut sebagai baseline, lalu ikuti Generate secure code with an actor-critic workflow untuk melakukan remediation tanpa mengembalikan masalah yang ditemukan audit ini.
- Baca Bob best practices untuk strategi prompting yang lebih efektif.
Hasilkan diagram arsitektur
Gunakan IBM Bob untuk menganalisis codebase Galaxium Travels dan menghasilkan diagram UML class, sequence diagram, dan use case diagram Mermaid.
Rencanakan dan implementasikan fitur kompleks
Gunakan Plan mode Bob untuk membuat cakupan, meninjau, dan mengimplementasikan fitur kompleks dengan agen coding AI. Pelajari cara menulis planning prompt, menyempurnakan rencana yang dihasilkan, dan menjalankan implementasi di Agent mode.