Dokümantasyonu kod tabanınla senkronize tutma

Senaryo 1: İlk proje dokümantasyonu

Minimal dokümantasyonla bir depo devraldın. Yeni takım üyeleri kod tabanını anlamakta güçlük çekiyor ve kapsamlı dokümantasyonu hızlı bir şekilde oluşturman gerekiyor.

Çalışma alanını kurma

1. Depoyu IBM Bob IDE'de aç.
2. Bob sohbet arayüzünü aç: Option + Command + B (macOS) veya Ctrl + Alt + B (Windows)

/init ile yapay zeka tarafından okunabilir bağlam oluşturma

İlk adım Bob'a projen hakkında bilgi vermektir. Agent moduna geç ve şunu çalıştır:

/init

Bob deponuzu tarar ve şunları oluşturur:

• Deponun kök dizininde AGENTS.md (ana proje bağlamı)
• .bob/rules-code/AGENTS-code.md (Agent moduna özgü bağlam)
• .bob/rules-plan/AGENTS-plan.md (Plan moduna özgü bağlam)
• .bob/rules-ask/AGENTS-ask.md (Ask moduna özgü bağlam)

Bu dosyalar şunları içerir:

• Kod yapısı ve önemli dizinler
• Teknoloji yığını ve bağımlılıklar
• Build, test ve lint komutları
• Kod kalıpları ve kurallar

Bu neden önemli: Bu AGENTS.md dosyaları, Bob'un her konuşmada başvurduğu bilgi tabanları olarak hizmet eder. Her seferinde tüm kod tabanını yeniden analiz etmek yerine Bob'un projen hakkında kalıcı bağlamı vardır.

Oluşturulan bağlamı inceleme

AGENTS.md'yi aç ve Bob'un ne keşfettiğini incele:

cat AGENTS.md

Projenin yapılandırılmış bir özetini göreceksin. Bob önemli ayrıntıları kaçırdıysa (iş kuralları, dağıtım kuralları, takım uygulamaları), AGENTS.md'yi düzenleyerek bunları ekle. Bu dosya özelleştirilmek üzere tasarlanmıştır.

Docs Architect modu oluşturma

Şimdi kullanıcıya yönelik dokümantasyon oluşturan özel bir mod oluştur. Bu mod, yapay zeka için değil insanlar için dokümantasyon oluşturmak üzere AGENTS.md bağlamını kullanacak.

1. Ayarları açmak için Bob panelindeki settings simgesine tıkla.
2. Modes sekmesini seç.
3. Yeni bir mod oluşturmak için + simgesine tıkla.
4. Aşağıdaki değerleri doldur:

Mode-specific Custom Instructions alanı için aşağıdakileri kopyalayıp yapıştır:

When documenting a project:
1. Review AGENTS.md files to understand project structure and technical details
2. Create user-facing documentation (READMEs, getting started guides, tutorials)
3. Avoid duplicating technical details from AGENTS.md (build commands, code patterns)
4. Focus on user workflows, conceptual overviews, and practical code examples
5. Include code blocks with clear explanations
6. Add docstrings and JSDoc comments to improve code quality

Generate:
- README.md explaining project purpose and navigation
- CONTRIBUTING.md with onboarding steps for new contributors
- Getting started guide with code snippets
- Conceptual documentation explaining architectural decisions

Kaydet'e tıkla.

Bob, .bob içinde Docs Architect mod yapılandırmasını içeren bir custom_modes.yaml dosyası oluşturur. Gelecekteki değişiklikleri yapmak için bu dosyayı doğrudan düzenleyebilirsin.

İlk dokümantasyonu oluşturma

Docs Architect moduna geç ve şunu yaz:

I've run /init to establish project context. Please create comprehensive documentation for this project:

1. Review AGENTS.md to understand the project structure
2. Create a README.md with:
   - Project overview and purpose
   - Quick start guide with code examples
   - Project structure explanation
   - Links to additional documentation
3. Create CONTRIBUTING.md with:
   - Development setup instructions
   - How to run tests
   - How to submit a pull request
   - Code style guidelines
4. Identify gaps in the codebase that need better documentation (missing docstrings, unclear functions)

Focus on making the technical details from AGENTS.md accessible to new developers.

Bob dokümantasyon dosyaları oluşturur. Doğruluk açısından incele, düzenlemeler yap, ardından commit'le:

git add AGENTS.md .bob/ README.md CONTRIBUTING.md
git commit -m "docs: initial project documentation with AI assistance"

Sonuç: Saatler değil dakikalar içinde minimal dokümantasyondan kapsamlı belgelere geçtin.

Senaryo 2: Yeni bir özelliği belgeleme

Az önce yeni bir özellik uyguladın. Kod çalışıyor, ancak README'n, katkı kılavuzun ve API belgeleriniz hâlâ projenin eski durumunu açıklıyor. Dokümantasyonun geride kaldığı en yaygın nokta budur — özellik hazır, ancak belgeler henüz yetişmedi.

Bob kullanarak bu boşluğu nasıl kapatacağın aşağıda gösterilmektedir.

Özelliği Bob'un yardımıyla yazma

Geliştirme sırasında Bob'un uygulamaya yardımcı olabilmesi için Agent moduna geç. Bob'un zaten Senaryo 1'de çalıştırdığın /init'ten proje bağlamı olduğu için, kod yapını, bağımlılıklarını ve kurallarını anlıyor — bu da önerilerini sıfırdan başlamaktan daha alakalı hale getiriyor.

Özelliği normalde yaptığın gibi yaz, kod tamamlama, yeniden düzenleme veya mevcut kod tabanı hakkında sorular sormak için Bob'u kullan.

Yapay zeka bağlamını güncellemek için /init'i yeniden çalıştırma

Özellik uygulandıktan sonra Bob'un bağlamı eskidir — yeni kodun var olmadan önce oluşturuldu. Güncelle:

/init

Bob depoyu yeniden tarar ve AGENTS.md'yi değişenleri yansıtacak şekilde günceller — yeni modüller, güncellenmiş bağımlılıklar ve algıladığı yeni kod kalıpları.

Güncellemenin değişikliklerini yakaladığını onayla:

git diff AGENTS.md .bob/

Diff yeni özelliğini gösteriyorsa Bob doğru dokümantasyon oluşturmaya hazırdır. Önemli bir şey eksikse devam etmeden önce AGENTS.md'yi manuel olarak düzenle.

Yeni özellik için dokümantasyon oluşturma

Şimdi Docs Architect moduna geç. AGENTS.md'yi yeni güncellediğin için Bob'un yeni özelliğin doğru bir resmini var ve gerçek uygulamayı yansıtan — tahmin değil — dokümantasyon oluşturabilir.

Bob'dan güncellenmesi gerekenleri iste:

I've added a new feature to the project. Please update the documentation:

1. Add a section to README.md explaining:
   - What the feature does
   - How to configure and use it
   - A code snippet showing basic usage
2. Update CONTRIBUTING.md if the development workflow has changed
3. Create a dedicated docs page that covers:
   - How the feature works
   - Relevant API endpoints or interfaces
   - Code examples for common use cases
   - Code explanations for non-obvious logic
   - Troubleshooting tips

Include code blocks with clear explanations. Add docstrings to any functions that lack them.

Oluşturulan dokümantasyonu doğruluk açısından incele — kod örneklerinin uygulamanla gerçekten eşleştiğini kontrol et — ardından her şeyi birlikte commit'le:

git add src/ AGENTS.md .bob/ README.md CONTRIBUTING.md docs/
git commit -m "feat: add [feature name] with documentation"

Sonuç: Özelliğin ve dokümantasyonu birlikte geliştirilir ve aynı pull request'te commit'lenir.

Senaryo 3: Dokümantasyon kontrolleriyle kod incelemesi

Bir takım üyesi yeni bir API endpoint'i ekleyen bir pull request gönderiyor. Dokümantasyonun güncellendiğinden emin olman gerekiyor.

Kod değişikliklerini inceleme

git diff main feature-branch

Yeni API endpoint'leri görüyorsun ama dokümantasyon güncellemesi yok.

/init'in çalıştırılıp çalıştırılmadığını kontrol etme

git diff main feature-branch -- AGENTS.md .bob/

AGENTS.md'de değişiklik yoksa geliştirici /init'i çalıştırmamıştır. Şunları yapmasını iste:

1. Yapay zeka bağlamını güncellemek için /init çalıştırsın
2. Kullanıcıya yönelik belgeleri güncellemek için Docs Architect'i kullansın

Eksik dokümantasyonu oluşturma

PR'yi inceliyorsan dokümantasyonu kendin oluşturabilirsin:

git checkout feature-branch

Bob'da /init çalıştır, ardından Docs Architect moduna geç:

I'm reviewing a pull request that adds new API endpoints. Please update the documentation:

1. Review the new endpoints in src/api/
2. Update README.md with a brief mention of the new endpoints
3. Update docs/api.md with:
   - Endpoint descriptions
   - Request/response examples with code blocks
   - Authentication requirements
   - Error codes
4. Add JSDoc comments to the endpoint handlers if missing

Focus on making the API easy to understand for other developers.

Dokümantasyon güncellemelerini commit'le:

git add AGENTS.md .bob/ README.md docs/api.md src/api/
git commit -m "docs: add documentation for new API endpoints"
git push

Sonuç: Dokümantasyon, kod inceleme sürecinin bir parçasıdır, sonradan düşünülen bir şey değil.

Senaryo 4: Yeni bir takım üyesini işe alıştırma

Takımına yeni bir geliştirici katılıyor. Kod tabanını hızla anlaması gerekiyor.

/init çalıştırmasını sağlama

Yeni geliştirici depoyu klonlar ve şunu çalıştırır:

/init

Bob, kod tabanının mevcut durumunu yansıtan yeni AGENTS.md dosyaları oluşturur. Yeni geliştirici artık şunları yapabilir:

1. Proje yapısını anlamak için AGENTS.md'yi okur
2. Başlangıç talimatları için README.md'yi okur
3. Geliştirme iş akışı için CONTRIBUTING.md'yi okur

Keşif için Ask modunu kullanma

Yeni geliştirici kod tabanını keşfetmek için Bob'un Ask modunu kullanabilir:

@src/auth Explain how authentication works in this project

@src/api What API endpoints are available and what do they do?

@tests How do I run tests for a specific module?

Bob, AGENTS.md'deki bağlamı ve gerçek kaynak kodunu kullanarak yanıt verir.

Kişiselleştirilmiş işe alıştırma belgeleri oluşturma

Projenin işe alıştırma dokümantasyonu yoksa Docs Architect'i kullan:

Create an onboarding guide for new developers joining this project:

1. Prerequisites (tools, accounts, access)
2. Initial setup steps with code blocks
3. How to run the project locally
4. How to run tests
5. Overview of the codebase structure
6. Common development tasks with examples
7. Where to find help

Make it practical and include code snippets for each step.

Sonuç: Yeni takım üyeleri günler yerine saatler içinde hız kazanabilir.

Senaryo 5: Zaman içinde dokümantasyonu sürdürme

Projen aylardır geliştirilmektedir. Kod önemli ölçüde değişti ve dokümantasyon sapmaya başladı.

Dokümantasyon sapmasını tespit etme

Neyin değiştiğini görmek için /init'i çalıştır:

/init

Diff'i incele:

git diff AGENTS.md .bob/

Büyük değişiklikler önemli bir kod evrimi olduğuna işaret eder. Bu, kullanıcıya yönelik dokümantasyonun güncellemelere ihtiyaç duyduğunun sinyalidir.

Dokümantasyonu sistematik olarak güncelleme

Dokümantasyonu yenilemek için Docs Architect'i kullan:

I've run /init and noticed significant changes to the project structure. Please review and update the documentation:

1. Review AGENTS.md changes to understand what's different
2. Update README.md to reflect current project structure
3. Update CONTRIBUTING.md if development workflow has changed
4. Identify any new features that lack documentation
5. Remove documentation for deprecated features
6. Update code examples to match current API

Focus on accuracy—make sure documentation matches the current codebase.

Bakım takvimi oluşturma

Dokümantasyon güncellemelerini düzenli iş akışına ekle:

• Aylık: /init çalıştır ve değişiklikleri incele
• Sürümlerden önce: Tüm dokümantasyonu güncelle
• Büyük yeniden düzenlemelerden sonra: Etkilenen dokümantasyonu yeniden oluştur
• Kod incelemelerinde: /init'in çalıştırılıp çalıştırılmadığını ve belgelerin güncellenip güncellenmediğini kontrol et

Sapma tespitini otomatikleştirme (gelişmiş)

CI'da dokümantasyon hijyenini zorlamak isteyen takımlar için AGENTS.md ve .bob/'un güncel olduğunu doğrulayan bir pull request kontrolü ekle. Kontrol, /init'i branch'e karşı çalıştırır, ardından çıktı commit edilenden farklıysa başarısız olur — geliştiricinin PR'yi açmadan önce yapay zeka bağlamını güncellemeyi unuttuğunu sinyalleyerek. Bunu en iyi uygulamalar bölümündeki PR şablonu kontrol listesiyle birleştirerek dokümantasyon güncellemelerini inceleme sürecinin zorunlu bir parçası haline getir.

Sonuç: Dokümantasyon, düzenli bakım sayesinde kodla senkronize kalır.