Eğitimler

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:

  1. Bir kod kalitesi özeti: Kod tabanı genelinde bakım yapılabilirlik, karmaşıklık ve stil sorunlarını vurgular.
  2. Bir bağımlılık denetimi: Eski, savunmasız veya kullanılmayan üçüncü taraf paketleri işaretler.
  3. Bir teknik borç değerlendirmesi: Kısayolları, geçici çözümleri ve yeniden düzenleme gerektiren alanları kataloglar.
  4. Uyumluluk dokümantasyonu: İlgili düzenleyici veya organizasyonel standartlara karşı bulguları kaydeder.
  5. 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

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

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

/init

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

  1. Beş oluşturulan raporu içeren docs/audit/ dizinini sil.
  2. Bob'un oluşturduğu proje bağlamını tutmak istemiyorsan, /init komutunun oluşturduğu AGENTS.md dosyasını ve .bob/ klasörünü sil.
  3. Çalışma alanını ayarla bölümünde klonladığın galaxium-travels dizinini 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 /init ile 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:

Bu konu nasıl?