Yabancı bir kod tabanını inceleme
IBM Bob'u kullanarak yabancı bir uygulamayı hızla anlayın; amacını, proje yapısını, mimarisini, teknoloji yığınını, temel bileşenlerini, test kapsamını ve dağıtım modelini keşfedin. Bunu güncel olmayan belgelere güvenmeden veya takım arkadaşlarını beklemeden yapabilirsiniz.
Yabancı bir kod tabanında üretken olmak genellikle saatlerce kod okumak, belge aramak ve takım arkadaşlarından bağlam istemek anlamına gelir. Bu öğreticide, Galaxium Travels kod tabanını sistematik olarak sorgulamak ve uygulamanın tam bir resmini çıkarmak için Ask modunda Bob'u kullanıyorsun: amacı ve mimarisi, teknoloji yığını, temel bileşenler, birim ve entegrasyon testi kapsamı ve dağıtım modeli. Ardından Agent moduna geçerek Bob'un keşfettiklerinin tamamını tüm ekibinin kullanabileceği kalıcı bir Markdown referansına kaydediyorsun.
Galaxium Travels, React frontend, Python FastAPI backend ve Java Spring Boot envanter servisi olan kasıtlı olarak karmaşık, gerçek dünya tarzı bir uygulamadır. Bu da onu bu workflow için güçlü bir aday yapıyor.
Bob'un çıktısı kod tabanının mevcut durumuna göre değişir. Bu öğretici kapsamındaki örnekleri tam transkriptler olarak değil, temsili başlangıç noktaları olarak değerlendir. Kendi promptlarını kalibre etmek ve sonuçları iyileştirmek için bunları kullan.
Öğreneceğin temel özellikler
- Ask modu: Bob hiçbir dosyayı değiştirmeden kodu keşfet ve analiz et.
- Agent modu: Bob'un oluşturulan artefaktları projeye kaydetmek için dosyaları özerk biçimde yazmasına izin ver.
- Bağlam bahisleri: Bob'a analiz için
kesin kapsam vermek üzere
@ile belirli dosya ve klasörlere başvur. /init: Soru sormaya başlamadan önce Bob'un kod tabanı kurallarını anlaması için proje bağlamını başlat.
Ön koşullar
Bu öğreticiyi tamamlamak için aşağıdakilere ihtiyacın var:
- Bob IDE yüklü olmalı.
- Git yerel olarak yüklü olmalı.
- Bob'un temellerini kullanmaya aşinalık. Bob'a yeniysen önce Hızlı Başlangıç öğreticisini tamamla.
Çalışma alanını ayarlama
Galaxium Travels deposunu klonla
Terminalinde örnek depoyu klonla:
git clone https://github.com/IBM/galaxium-travels.gitÖrnek projeyi aç
Bob IDE'de az önce klonladığın galaxium-travels klasörünü aç. Bob
"Do you trust the authors of the files in the folder?" diye sorarsa
Yes, I trust the authors'a tıkla.
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) ya da Ctrl + Alt + B (Windows) kısayolunu kullan.
Proje bağlamını başlat
Bob başlangıçta varsayılan olarak Agent modunda açılır. Modları değiştirmeden önce /init
komutunu çalıştır; böylece Bob projeyi okur ve sonraki etkileşimlerde kullandığı
AGENTS.md bağlam dosyalarını oluşturur.
/initOtomatik onay devre dışıysa Bob dosyaları okumak ve AGENTS.md dosyalarını yazmak için
izin ister. Her isteği onayla. Bob kök düzeyinde bir AGENTS.md ve moda özgü yapılandırma
içeren bir .bob/ klasörü oluşturur.
Bob'un deponun çok servisli yapısını doğru şekilde tanıdığını onaylamak için oluşturulan
AGENTS.md'yi gözden geçir.
Ask moduna geç
Sohbet giriş alanının altındaki mod seçiciden Ask'i seç ya da modları değiştirmek için
/ask yaz. Ask modu tamamen salt okunurdur. Bob dosyaları analiz eder ama hiçbir şey
oluşturamaz veya değiştiremez; bu da onu bu öğreticideki tüm keşif çalışmaları için
doğru mod yapar.
Uygulamanın amacını ve proje yapısını anlama
En geniş soruyla başla: bu uygulama ne yapıyor ve kod tabanı nasıl düzenlenmiş?
Bob, proje yapısını ve README.md, package.json, requirements.txt, derleme dosyaları
ve diğer yapılandırma dosyaları gibi temel dosyaları okur. Bob, her dizini manuel olarak
izlemek zorunda kalmadan özlü bir özet üretir.
Ask modunda şu promptu gir:
What is the purpose of this application? Describe the project structure,
the high-level architecture, and the main responsibilities of each top-level
directory.Bob dosya ağacını ve temel giriş noktalarını okur, ardından şunları içeren bir çıktı üretir:
- Uygulama amacı
- Üst düzey dizin sorumlulukları
- Her üst düzey dizinin içeriğinin özeti
- Üst düzey mimari diyagramı
Teknoloji yığınını analiz etme
Üst düzey yapı netleştikten sonra, kullanılan tam teknolojileri incele. Bu prompt; derleme araçlarını anlamak, bağımlılık seçimlerini değerlendirmek veya yükseltme kapsamını tahmin etmek için kullanışlıdır.
Ask modunda şu promptu gir:
Analyze the tech stack for the entire application. For each service, list the
programming language, runtime version requirements, framework, key libraries,
database, and build/test tooling.Bob her servisin bağımlılık ve yapılandırma dosyalarını inceleyerek şunları içeren bir çıktı üretir:
- Her servis için ayrıntılı teknoloji yığını analizi
- Uçtan uca test framework'ünün tanımlanması
- CI/CD yığını ve dağıtım betiklerinden ek araçlar
- Tüm servisler ve katmanlar genelinde teknoloji yığınını görsel olarak özetleyen "Stack at a Glance" diyagramı
Temel bileşenleri haritalama
Teknoloji yığınını anlamak kod tabanının ne kullandığını söyler; temel bileşenleri anlamak nasıl çalıştığını söyler. Bu prompt, özellikle servis sınırlarını aşan değişiklikler yapmadan önce, Bob'dan üç servis genelindeki bileşen sınırlarını ve veri akışlarını izlemesini ister.
Ask modunda, Bob'u en ilgili dosyalara yönlendiren bağlam bahisleriyle şu promptu gir:
Identify the key components of this application and explain how they interact.
Reference @booking_system_frontend/src/services,
@booking_system_backend/server.py,
@booking_system_backend/services,
@booking_system_backend/models.py,
and @booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice.
Describe the component responsibilities, the data flow for the booking
lifecycle, and any cross-service contracts I need to know before modifying
the codebase.Bob etkileşim zincirini izler ve şunları içeren bir çıktı üretir:
- Frontend, backend API, veritabanı katmanı ve Java hold servisinin ayrıntılı sorumlulukları
- Bileşen etkileşimleri açıklamalı iki rezervasyon yaşam döngüsü akışının diyagramı
- Değişiklik yapmadan önce bilmen gereken beş servisler arası sözleşmenin özeti
- Bileşen etkileşim haritası
Birim testi kapsamını değerlendirme
Özellik eklemeden veya yeniden düzenlemeden önce mevcut test paketinin ne kapsadığını ve boşlukların nerede olduğunu bilmen gerekir. Bu prompt, Bob'dan testleri çalıştırmadan test dosyalarını okuyarak bir kapsam değerlendirmesi üretmesini ister.
Ask modunda şu promptu gir:
Analyze the unit test suites across all three services. Reference
@booking_system_backend/tests,
@booking_system_inventory_hold_service/src/test,
and @booking_system_frontend/src.
For each service, describe what is tested, which testing framework is used,
what the test structure looks like, and identify any obvious gaps where
critical logic appears to be untested.Bob test dosyalarını okur ve şunları içeren ayrıntılı bir test paketi analizi üretir:
- Her servis için test framework'ü, test edilen sınıflar, sınıf başına test sayısı ve sınıf başına doğrulanan içerik
- Testteki kritik boşluklar
- Kritik iş mantığı için eksik test kapsamı
Entegrasyon ve uçtan uca test kapsamını değerlendirme
Birim testleri, bileşenlerin izole çalışıp çalışmadığını söyler; entegrasyon ve uçtan uca testler, servislerin birlikte doğru çalışıp çalışmadığını söyler. Rezervasyon onay akışı üç servisin tamamını kapsadığı için bu, Galaxium Travels için özellikle önemlidir.
Ask modunda şu promptu gir:
Analyze the end-to-end and integration test coverage. Reference
@tests_e2e and any cross-service test fixtures you can identify.
Describe which cross-service flows are covered, which are not, what test
infrastructure is required to run the suite, and what the tests assert
at the boundary level.Bob uçtan uca test paketini okur ve şunları içeren ayrıntılı bir kapsam analizi üretir:
- Paketi çalıştırmak için gereken test altyapısı ve gereksinimler
- Smoke testler
- Temel altyapı kararları
- Kapsanan ve kapsanmayan servisler arası akışlar
- Sınır düzeyinde test iddiaları
Dağıtım modelini gözden geçirme
Bir uygulamanın nasıl dağıtıldığını (hedef platformlar, kapsayıcılaştırma stratejisi ve altyapı otomasyonu) anlamak, katkıda bulunan olarak katılmadan veya uygulamayı dizüstü bilgisayarının ötesinde bir yerde çalıştırmadan önce gereklidir.
Ask modunda şu promptu gir:
Analyze the deployment model for this application. Reference
@docker-compose.yml, @deployment_scripts, @terraform, @.github/workflows,
and the deployment documentation in @docs.
Describe the supported deployment targets, how each service is containerized,
what infrastructure is provisioned, and how CI/CD is configured.Bob dağıtım artefaktlarını okur ve bir dağıtım modeli analizi üretir. Analiz şunları içerir:
- Desteklenen dağıtım hedefleri
- Her servis için kapsayıcılaştırma stratejisi
- Altyapı sağlama ayrıntıları
- CI/CD iş akışları
- Temel dağıtım kısıtlamaları ve boşlukları
Bulgularını depoya kaydetme
Ask modunda üretilen analiz yalnızca sohbet oturumunda bulunur. Gelecekteki katkıda bulunanların bu çalışmadan yararlanabilmesi için Agent moduna geçerek Bob'dan depoya kalıcı bir oryantasyon referans belgesi yazmasını iste.
Agent moduna geç
Mod seçiciden Agent'ı seç ya da sohbet giriş alanına /agent yaz.
Oryantasyon referansını oluştur
Bob'dan keşfettiği her şeyi tek bir Markdown dosyasında birleştirmesini iste. Bob konuşmanın tam bağlamına sahip olduğundan tüm dosyaları yeniden okumadan bulguları sentezler.
Create a file called docs/ONBOARDING.md.
Create one section for each of these topics:
1. Application overview: purpose, project structure, high-level architecture, and the main responsibilities of each top-level directory.
2. Tech stack analysis, including a "Stack at a Glance" diagram.
3. Key components and their interactions, including a component interaction map.
4. Unit test coverage analysis.
5. End-to-end test coverage analysis.
6. Deployment model analysis.
Populate each section with everything you discovered in this session.
Use clear headings, Mermaid diagrams, and tables where appropriate. Keep the tone concise and technical.Bob dosyayı yazar. Otomatik onay devre dışıysa Bob docs/ONBOARDING.md yazmak için
izin istediğinde Approve'a tıkla.
Çıktıyı doğrula
Belgenin beklediğin tüm içeriği kapsadığını onaylamak için editörde docs/ONBOARDING.md'yi
aç. Bob'dan önizleme yapmasını da isteyebilirsin:
Show me a preview of docs/ONBOARDING.mdBob, Markdown'ı sohbet arayüzünde işler. Commit etmeden önce içeriği doğruluk ve tamlık açısından gözden geçir.
Dosyayı commit et
docs/ONBOARDING.md'yi deponuza commit etmek için tercih ettiğin Git workflow'unu kullan.
Belge artık her katkıda bulunana ve Bob'un kendisine ilerideki oturumlarda erişilebilir.
Sorun giderme
Bob'un analizi yüzeysel veya servisleri atlıyor
Bob varsayılan olarak proje yapısını ve temel dosyaların bir seçkisini okur. Çıktıda bir servis eksikse veya beklenenden daha az ayrıntılıysa, Bob'un odağını daraltmak için açık bağlam bahisleri ekle.
Örneğin, Java hold servisi teknoloji yığını analizine yansımıyorsa prompta
@booking_system_inventory_hold_service/pom.xml ekle:
Analyze the tech stack for @booking_system_inventory_hold_service/pom.xml
and add the Java hold service to the tech stack summary you produced earlier.Bob test dosyalarını bulamıyor
Bob test dosyalarını bulamadığını bildirirse, doğrudan test dizinlerine işaret etmek için bir bağlam bahsi kullan:
Analyze the test coverage in @booking_system_backend/tests and
@tests_e2e. List every test file and summarize what each one covers.Bob'un dağıtım analizi bir hedefi atlıyor
AWS, IBM Cloud ve yerel dağıtım artefaktları birden fazla üst düzey dizine yayılmıştır. Bob'un dağıtım özeti eksikse, onu belirli dizinlere yönlendir:
Review @deployment_scripts/aws, @terraform, @deployment_scripts/ibm, and
@.github/workflows. Update the deployment model summary to include all three
deployment targets./init boş veya yanlış AGENTS.md oluşturuyor
Çalışma alanı kökünde /init komutu, README.md, package.json, requirements.txt,
pom.xml, Makefile ve benzeri manifest dosyaları gibi çıpa dosyalarını okuyarak proje
bağlamı oluşturur. Bu dosyaların hiçbiri kökde yoksa ya da çalışma alanı kökü bir alt
dizine ayarlanmışsa, Bob projenin yalnızca bir parçasını görür ve seyrek ya da yanlış
bir AGENTS.md üretir.
Oluşturulan AGENTS.md çok servisli yapıyı yansıtmıyorsa şunları kontrol et:
- Çalışma alanı kökü: Çalışma alanı kökü olarak
booking_system_backend/gibi bir alt dizin değil,galaxium-travels/'ın açık olduğunu doğrula. Üç servis dizininin tamamı üst düzeyde görünür olmalıdır. - Eksik çıpa dosyaları: Kökde
README.mdveya başka bir manifest yoksa/initokuyacak az şey bulur. Kısa bir proje açıklaması içeren kök düzeyinde birREADME.mdekle, ardından/init'i yeniden çalıştır.
Kökü düzelttikten sonra AGENTS.md dosyalarını yeniden oluşturmak için /init'i
yeniden çalıştır.
Bob'un davranışını standartlaştırın
Bob'a kodunu belgelemesini ve önceki eylemlerini hatırlamasını söyleyen proje düzeyinde kural dosyaları kullanarak ekibiniz genelinde Bob'un davranışını standartlaştırın.
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.