Denetim raporları ve uyumluluk dokümantasyonu oluştur
Galaxium Travels kod tabanını analiz etmek ve kod kalitesi, bağımlılık sağlığı, teknik borç ve uyumluluk duruşunu kapsayan yapılandırılmış denetim raporları üretmek için IBM Bob'u kullan. AI destekli analizden paydaşlara hazır dokümantasyon nasıl oluşturulacağını öğren.
Yazılım denetimleri, mühendislik ekiplerinin, güvenlik inceleyicilerinin ve uyumluluk paydaşlarının bir sistemi göndermeden, satın almadan veya sertifikalandırmadan önce güvendiği belgesel kanıtları üretir.
Bu eğitimde, Galaxium Travels kod tabanını sistematik olarak analiz etmek ve beş yapılandırılmış yapı oluşturmak için Bob'u kullanıyorsun:
- Bir kod kalitesi özeti: Kod tabanı genelinde bakım yapılabilirlik, karmaşıklık ve stil sorunlarını vurgular.
- Bir bağımlılık denetimi: Eski, savunmasız veya kullanılmayan üçüncü taraf paketleri işaretler.
- Bir teknik borç değerlendirmesi: Kısayolları, geçici çözümleri ve yeniden düzenleme gerektiren alanları kataloglar.
- Uyumluluk dokümantasyonu: İlgili düzenleyici veya organizasyonel standartlara karşı bulguları kaydeder.
- Tüm bulguları birleştiren konsolide bir paydaş denetim raporu: Yukarıdakileri tek bir paylaşılabilir belgede birleştirir.
Düzeltme önerileri olmadan ayrıntılı, kanıta dayalı bulgular elde etmek için promptlarını yapılandırıyorsun.
Bu eğitimin sonunda, paydaşlarla paylaşabileceğin ve düzeltme planlaması için temel olarak kullanabileceğin bir denetim belgeleri setine sahip olacaksın.
Bu eğitimde, Bob'un çıktısı kod tabanının mevcut durumuna bağlı olarak örneklerden farklı olabilir. Oluşturulan raporları başlangıç noktası olarak kullan ve bulguları paydaşlara dağıtmadan önce iyileştir.
Öğreneceğin temel özellikler
- Context mentions: Promptlarında
@sembolünü kullanarak belirli dosyalara ve klasörlere referans ver. Context mentions, Bob'un doğru, kanıta dayalı bulgular için hangi dosyaları analiz edeceğini tam olarak bilmesini sağlar. - Agent modu: Bob'un oluşturulan yapıları projenizde kalıcı hale getirmek için dosyaları özerk olarak yazmasına izin ver.
- Yapılandırılmış çıktı için prompt mühendisliği: Anlatı düzyazısı yerine paydaşlara hazır belgeler elde etmek için istenen çıktı formatını içerecek şekilde promptunu yapılandır.
Ön koşullar
IBM Bob IDE
IBM Bob v2.x veya sonrasını indir ve yükle.
Git
Örnek depoyu klonlamak için Git gereklidir.
Çalışma alanını ayarla
Galaxium Travels deposunu klonla
Terminalinde, Galaxium Travels örnek deposunu klonlamak için aşağıdaki komutu çalıştır:
git clone https://github.com/IBM/galaxium-travelsBu eğitim, bob-learning-path-branch değil, deponun main dalını kullanır. Bu
eğitimin referans verdiği Java hold servisi ve diğer bileşenler yalnızca main'de
mevcuttur.
IBM Bob'u başlat
Bilgisayarında IBM Bob IDE'yi başlat.
Örnek projeyi aç
Bob IDE'de, klonladığın galaxium-travels klasörünü aç. Bob "Bu klasördeki dosyaların
yazarlarına güveniyor musun?" diye sorarsa, Evet, yazarlara güveniyorum'a tıkla.
Uygulama mimarisine genel bir bakış elde etmek için kök dizindeki README.md dosyasını
incele. Galaxium Travels, Python FastAPI backend'i, React/TypeScript frontend'i ve Java
Spring Boot envanter hold servisi ile tam yığın bir uzay yolculuğu rezervasyon
sistemidir.
Bob sohbet arayüzünü aç
Sohbet arayüzü henüz açık değilse, gezinme çubuğundaki Bob simgesine tıkla veya Option + Command + B (Mac) veya Ctrl + Alt + B (Windows) kısayolunu kullan.
Proje bağlamını başlat
Bob, başlangıçta varsayılan olarak Agent modunu kullanır. Modu değiştirdiysen, başlatma komutunu çalıştırmadan önce Agent moduna geç. Bob'un proje bağlamını kurmak için dosya yazması gerekir. Bu eğitim, görev başına izinleri sınırlamak yerine Agent modunun varsayılan yeteneklerini kullanır, bu nedenle Bob ek yapılandırma olmadan dosyaları okuyabilir ve yazabilir.
Sohbet arayüzü giriş alanına /init komutunu gir.
/initOtomatik onay devre dışıysa, Bob dosyaları okumadan ve değişiklikleri yazmadan önce
izin ister. Bu istemler göründüğünde onaylayın — bu, /init komutu ve Bob'un eğitimde
daha sonra yazdığı her rapor için geçerlidir.
Bob, projedeki ilgili dosyaları okur ve kök dizinde ana AGENTS.md dosyasını ve moda
özgü AGENTS.md dosyalarını içeren bir .bob/ klasörü oluşturur. Devam etmeden önce
AGENTS.md ve bir .bob/ klasörünün proje kökünde göründüğünü doğrula. Bob'un proje
yapısı, teknoloji yığını ve temel desenler hakkında ne çıkardığını anlamak için
oluşturulan dosyaları incele. Bu bağlam, sonraki promptlardaki analizin kalitesini
doğrudan artırır.
Kod kalitesi özeti oluştur
Bir kod kalitesi özeti, mühendislere ve inceleyicilere kod tabanı genelindeki sorunların yapılandırılmış bir görünümünü verir: anti-desenler, eksik korumalar, test kapsama boşlukları ve bir projenin ömrü boyunca biriken tutarsızlıklar. Bir linter raporundan farklı olarak, Bob tarafından oluşturulan bir kalite özeti, insan tarafından okunabilir açıklamalar ve önem derecesi bağlamı ile diller ve katmanlar arasında bulguları sentezler.
Galaxium Travels kod tabanı üç farklı yığını kapsar: Python (backend), TypeScript (frontend) ve Java (hold servisi). Her servisi bağımsız olarak analiz etmek ve ardından birleşik bir bulgular tablosu üretmek için promptunu yapılandır. Bob'un hangi dosyaların ilgili olduğunu tahmin etmesine izin vermek yerine Bob'a kesin dosya kapsamı vermek için context mentions kullan.
Yeni bir görev başlat
Yeni bir görev başlatmak için + düğmesine tıkla. Yeni başlamak, bu promptun
bağlamını burada bahsettiğin dosyalarla sınırlı tutar, /init sırasında Bob'un
okuduğu her şeyi taşımak yerine.
Kod kalitesi özetini oluştur
Agent modunda, sohbet giriş alanına aşağıdaki promptu gir:
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 üç servisi analiz eder, henüz yoksa docs/audit/ dizinini oluşturur, Markdown
dosyasını oluşturur ve sohbet arayüzünde bir özet çıktısı verir. Rapor, belirttiğin
bölümleri ve yapıyı içerir ve kanıt olarak belirli dosyalara ve kod satırlarına
referans veren bulgular içerir.
Raporu doğrula
Devam etmeden önce, dosyanın genel bakış tablosu ve bileşen başına bulgularla
oluşturulduğunu doğrulamak için Bob dosya gezgininde docs/audit/code-quality-summary.md'yi
aç.
Bağımlılık denetimi yap
Bir bağımlılık denetimi, bir projenin bağımlı olduğu kütüphanelerin bilinen iyi sürümlere sabitlenip sabitlenmediğini, sabitleme stratejilerinin çok dilli yığın genelinde tutarlı olup olmadığını ve herhangi bir bağımlılık yapılandırma uygulamasının kontrolsüz yükseltme riski getirip getirmediğini belirler. Bu bir CVE taramasından farklıdır: yalnızca bilinen güvenlik açıklarını değil, sürüm yönetimi disiplinini değerlendiriyorsun.
Galaxium Travels projesinin üç bağımlılık manifestosu vardır:
booking_system_backend/requirements.txt (Python),
booking_system_frontend/package.json (Node.js) ve
booking_system_inventory_hold_service/pom.xml (Java/Maven). Üçünü de context
mentions'ına dahil et.
Yeni bir görev başlat
Yeni bir görev başlatmak için + düğmesine tıkla.
Bağımlılık denetimini oluştur
Agent modunda, sohbet giriş alanına aşağıdaki promptu gir:
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 manifestoları analiz eder ve raporu yazar. Sabitleme durumu tablosu ve kesişen bulgular bölümü içerir.
Raporu doğrula
Devam etmeden önce, manifesto başına tabloların ve kesişen bulgular bölümünün mevcut
olduğunu doğrulamak için docs/audit/dependency-audit.md'yi aç.
Teknik borcu değerlendir
Bir teknik borç değerlendirmesi, zaman içinde maliyet biriktiren yapısal, mimari ve operasyonel kararları değerlendirir. Borcu mimari, güvenlik, operasyonel hazırlık ve kod kalitesine ayırmak ve liderliğin öncelik belirleyebilmesi için her öğenin önem derecesini ve düzeltme çabasını derecelendirmek için promptunu yapılandır.
Aşağıdaki prompt, Bob'a çıkarılan mimari ve operasyonel desenler hakkında içgörü vermek
için context mentions'da AGENTS.md'yi içerir, bu da mimari ve operasyonel borcun
değerlendirmesini bilgilendirebilir. Proje bağlamını başlat
bölümünde çalıştırdığın /init komutu AGENTS.md dosyasını oluşturdu.
Yeni bir görev başlat
Yeni bir görev başlatmak için + düğmesine tıkla.
Teknik borç değerlendirmesini oluştur
Agent modunda, sohbet giriş alanına aşağıdaki promptu gir:
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 kod tabanını analiz eder ve raporu yazar, her borç öğesini önem derecesi ve çaba tahminleriyle etiketler.
Raporu doğrula
Devam etmeden önce, dört borç kategorisinin ve özet tablosunun mevcut olduğunu
doğrulamak için docs/audit/technical-debt-assessment.md'yi aç.
Uyumluluk dokümantasyonu oluştur
Uyumluluk dokümantasyonu, düzenleyicilerin, denetçilerin ve kurumsal güvenlik ekiplerinin bir üretim sisteminde bulmayı beklediği kontrollere karşı bir kod tabanının mevcut durumunu eşler. Mühendis olmayan paydaşlar için, bu belge şu soruyu yanıtlar: "Bu sistem hassas verilerle ne yapar, erişim nasıl kontrol edilir ve boşluklar nerede?"
Veri sınıflandırması, kimlik doğrulama ve erişim kontrolü, veri koruma, denetim izi kapsamı ve lisans uyumluluğunu kapsayacak şekilde promptunu yapılandır.
Yeni bir görev başlat
Yeni bir görev başlatmak için + düğmesine tıkla.
Uyumluluk dokümantasyonunu oluştur
Agent modunda, sohbet giriş alanına aşağıdaki promptu gir:
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 kaynak dosyaları analiz eder ve raporu yazar, her kontrolü bir kod referansıyla uygulama durumuna eşler.
Raporu doğrula
Devam etmeden önce, altı bölümün tümünün mevcut olduğunu doğrulamak için
docs/audit/compliance-documentation.md'yi aç.
Paydaş denetim raporu derle
Dört ayrı analiz tamamlandığında, Bob'dan bunları tek bir yönetici odaklı denetim raporunda birleştirmesini iste. Bir paydaş raporu, konu başına analizlerden farklıdır: bulgular özetiyle başlar, en eyleme dönüştürülebilir öğelere öncelik verir ve teknik olmayan okuyucuların üzerinde hareket edebileceği önerilen bir düzeltme sırası sağlar.
Prompt, önceki bölümlerde Bob'un diske yazdığı dört raporu yüklemek için context mentions kullanır. Bob, kaynak kodu yeniden analiz etmek yerine bu dosyaları okur ve bunları tek bir belgede sentezler, böylece çıktı zaten incelediğin bulguları yansıtır.
Yeni bir görev başlat
Yeni bir görev başlatmak için + düğmesine tıkla.
Paydaş denetim raporunu oluştur
Agent modunda, sohbet giriş alanına aşağıdaki promptu gir:
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 kaydedilen dört raporu okur, bulgularını sentezler ve
docs/audit/stakeholder-audit-report.md'yi oluşturur. Bob, kaynak kodu yeniden analiz
etmek yerine zaten incelediğin raporlardan çalıştığı için, konsolide rapor ayrıntılı
bulgularla tutarlı kalır.
Raporu doğrula
Yönetici özetinin, karne kartının ve beş bölümün mevcut olduğunu doğrulamak için
docs/audit/stakeholder-audit-report.md'yi aç. Artık paydaşlarla paylaşmak ve düzeltme
planlaması için temel olarak kullanmak üzere docs/audit/ içinde eksiksiz bir denetim
belgeleri setine sahipsin.
Sorun giderme
Bob'un analizi bir servisi veya dosyayı atlar
Bob'un çıktısında kapsanmasını beklediğin bir bileşen için bulgular eksikse, en olası neden promptun context mention'da dosyayı veya dizini içermemesi veya bağlam penceresinin Bob'un tek bir geçişte referans verilen tüm içeriği okuyamayacak kadar dolu olmasıdır.
Context mentions'ını kontrol et
Promptundaki @ bahsinin doğru yola çözümlendiğini doğrula. Bob sohbet arayüzünde,
Bob bir context mention'ın çözümlenip çözümlenmediğini gösterebilir. Bob bahsi
tanımazsa, yol yanlış yazılmış olabilir veya dizin yerel klonunda mevcut olmayabilir.
Çok sayıda dosya içeren dizinler için, Bob yalnızca bir alt küme okuyabilir. Kapsamı en ilgili alt dizine daralt veya tüm klasöre referans vermek yerine belirli dosyaları listele.
Analizi odaklanmış promptlara böl
Üç servisi de kapsayan tek bir prompt yerine, servis başına bir tane olmak üzere üç ayrı prompt çalıştır ve ardından Bob'dan bulguları birleştirmesini iste. Örneğin, Python ve TypeScript geçişlerini tamamladıktan sonra üçüncü odaklanmış prompt şöyledir:
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.Her odaklanmış analiz tamamlandıktan sonra, Bob'dan bunları birleştirmesini iste:
Combine the three per-service code quality analyses into a single unified
report using the same format we used for the initial report.Raporlar promptlar arasında çelişkili bulgular içeriyor
Çok promptlu bir oturum çalıştırırken, sonraki promptlar öncekilerle çelişiyor gibi görünen bulgular üretebilir. Bu, Bob'un farklı dosya okumalarından farklı çıkarımlar yapması veya önceki bir bulgunun kesin olmaması durumunda olabilir.
Çelişkili iddiaları belirle
Her iki bulguyu da yeni bir promptta alıntıla ve Bob'dan belirli bir dosya referansıyla tutarsızlığı çözmesini iste. Örneğin:
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.Etkilenen raporu güncelle
Bob yetkili bulguyu ürettikten sonra, Bob'dan kaydedilen rapor dosyasındaki belirli bölümü güncellemesini iste. Örneğin, teknik borç değerlendirmesi daha doğruysa, Bob'dan kod kalitesi özetini güncellemesini iste:
Update the error handling finding in docs/audit/code-quality-summary.md to
use the corrected description. Do not change any other section.Bob analize istenmeyen öneriler ekliyor
Bir prompt Bob'dan açık kısıtlamalar olmadan "analiz etmesini" veya "değerlendirmesini" istediğinde, Bob genellikle bulgularla birlikte düzeltme önerileri içerir. Bir uyumluluk veya denetim raporu için, istenmeyen öneriler sorunlu olabilir: yanlış olabilirler, hedef ortam hakkında varsayımları yansıtabilirler ve yalnızca bulgular içeren bir belge bekleyen paydaşları karıştırabilirler.
Bunun önemli olduğu herhangi bir analiz promptuna "Report findings only. Do not generate implementation plans, code, or remediation suggestions." talimatını ekle. Bob zaten karışık içerikli bir rapor oluşturduysa, Bob'dan önerileri kaldırmasını iste. Örneğin, kod kalitesi özeti öneriler içeriyorsa, aşağıdaki promptu gir:
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.Temizlik
Bu eğitimde oluşturulan yapıları kaldırmak için:
- Beş oluşturulan raporu içeren
docs/audit/dizinini sil. - Bob'un oluşturduğu proje bağlamını tutmak istemiyorsan,
/initkomutunun oluşturduğuAGENTS.mddosyasını ve.bob/klasörünü sil. - Çalışma alanını ayarla bölümünde klonladığın
galaxium-travelsdizinini sil.
Sonraki adımlar
Bu eğitimde, IBM Bob'u şunlar için kullandın:
- Bob'un analizinin projenin yapısını ve teknoloji yığınını yansıtması için
/initile proje bağlamını başlattın - Dört odaklanmış denetim yapısı, bir kod kalitesi özeti, bir bağımlılık denetimi, bir teknik borç değerlendirmesi ve uyumluluk dokümantasyonu oluşturdun. Her biri kaynak dosyalardan kanıtlarla destekleniyor
- Dört analizi, üretim hazırlığı karne kartı ve önerilen düzeltme sırası içeren tek bir paydaş denetim raporunda derledin
- Her raporu diske kalıcı hale getirmek için Agent modunu ve context mentions'ı kullandın, analizleri kendi kendine yeten ve token açısından verimli tuttun
Aşağıdaki kaynaklarla devam et:
- Geliştirici araçlarının ve AI ajanlarının üzerinde hareket edebileceği makine tarafından okunabilir SARIF ve OSCAL yapıları üretmek için Audit code and generate reports'u takip et.
- Bulguları temel olarak kullan, ardından bu denetimin ortaya çıkardığı sorunları yeniden tanıtmadan düzeltmek için Generate secure code with an actor-critic workflow'u takip et.
- Daha etkili promptlama stratejileri için Bob best practices'i oku.
Mimari diyagramlar oluştur
Galaxium Travels kod tabanını analiz etmek ve Mermaid UML sınıf diyagramları, sıra diyagramları ve kullanım durumu diyagramları oluşturmak için IBM Bob'u kullan. Kodu keşfetmek için Ask modunda bağlam bahislerini ve sonuçları deponuza kaydetmek için Agent modunu nasıl kullanacağını öğren.
Karmaşık özellikleri planlayın ve uygulayın
IBM Bob'un Plan modunu kullanarak bir AI kodlama ajanıyla karmaşık özelliklerin kapsamını belirleyin, gözden geçirin ve uygulayın. Planlama istemi yazma, oluşturulan planı iyileştirme ve Agent modunda uygulamayı çalıştırma konularını öğrenin.