SPFx Dev Skills: Ajanların Bildiği ve Kaçırdığı Detaylar
Yapay zeka tabanlı kodlama ajanları SharePoint Framework (SPFx) projeleri üretebiliyor. Ama doğru araç zincirini, paket sürümlerini ve sürüm yükseltme adımlarını tek başlarına eksiksiz uygulayabileceklerine güvenmek başka bir mesele. Microsoft’un SharePoint ve Developer Relations ekipleri, SPFx Dev Skills önizlemesini yayımlamadan önce ajanların SPFx hakkında ne bildiğini ve nerede zorlandığını ölçmek için ortak bir değerlendirme çalışması yürüttü. Bu yazıda çalışmanın sonuçlarını ve önizlemenin hangi noktalara odaklandığını özetliyorum.
Neden önce ölçüm, sonra skill?
OneDrive & SharePoint SPFx ekibinden Vesa Juvonen ve Bert Jansen ile Developer Relations tarafında Garry Trinder ve Waldek Mastykarz, “doğru bir upgrade nasıl görünmeli” sorusunu birlikte tanımladı ve değerlendirmeleri buna göre tasarladı. Amaç, ajanın adım adım ne yaptığını izleyip başarısızlıkların kökenini bulmak, bu bulguları da ajanların kullandığı yüzeylere (dokümantasyon, CLI, skill) yansıtmaktı.
Değerlendirmelerde CLI for Microsoft 365 bakımcılarının yıllardır sürdürdüğü çalışma da temel bir girdi oldu. spfx project upgrade komutu, sürümden sürüme SPFx yükseltmelerini deterministik biçimde kodluyor. Bu komut hem değerlendirmede referans olarak hem de ajanların keşfetmesi istenen yükseltme yolu olarak kullanıldı.
Temel senaryo: 1.21.1’den 1.22.2’ye yükseltme
İlk senaryo, SPFx 1.21.1 projesini 1.22.2’ye yükseltmekti. Bu yükseltme yalnızca paket sürümlerini değiştirmekten ibaret değil; SPFx 1.22, gulp’tan Heft’e geçişi ve buna bağlı yapılandırma ile proje yapısı değişikliklerini getiriyor.
Değerlendirme Windows üzerinde Visual Studio Code içindeki GitHub Copilot Chat ile Claude Sonnet 4.6 kullanılarak yapıldı. Ajana yalnızca şu istem verildi:
Upgrade the project to 1.22.2
SPFx sözcüğü, dokümantasyon bağlantısı ya da skill kullanılmadan çalıştırıldı. Amaç, ajanın yalnızca proje bağlamı ve kendi bilgisiyle ne yapabildiğini gösteren bir taban çizgisi (baseline) elde etmekti. Dil modelleri deterministik olmadığı için aynı senaryo 5 kez koşuldu; hem projenin derlenip çalışması hem de kısmi yükseltmeyi doğru yükseltmeden ayıran ayrıntılar değerlendirildi.
Baseline sonuçları
| Sınıflandırma | Geçen | Toplam |
|---|---|---|
| Ön koşul | 5 | 5 |
| Deyimsel kullanım | 7 | 10 |
| Bağımlılık güncelliği | 34 | 50 |
| Yapılandırma doğruluğu | 38 | 85 |
Her koşuda proje, yürütme kapılarını geçebilecek şekilde derlenip çalıştı. Yüzeyde başarı gibi görünse de ajan yalnızca ana SPFx sürüm numarasını güncelledi, birçok bağımlılığı ve geçiş ayrıntısını kaçırdı.
Ajan SPFx hakkında ne biliyordu?
İlginç olan, ajanın herhangi bir araç çağırmadan önce dosya ağacına bakarak projenin SPFx olduğunu tanımasıydı. Microsoft paketlerinin güncellenmesi gerektiğini ve TypeScript araç zincirinde değişiklikler olacağını da biliyordu. Sürüm notlarına ihtiyaç duyduğunda arama yapmak yerine, önceki SPFx sürümlerinden öğrendiği URL desenini takip ederek Microsoft Learn adresini doğrudan oluşturuyordu.
Zayıf nokta, bu bilgiyi bulduğu içerikle birleştirmekti. Örneğin 1.22.2’ye yükseltme istenirken ajan yalnızca 1.22 sürüm notlarını çekti, ara sürümlerin sayfalarını atladı. SPFx yükseltmeleri artımlı olduğundan 1.22.0 ve 1.22.1 değişiklikleri hedef 1.22.2 olsa bile önemliydi. Ayrıca ajan, planını dokümanları okumadan önce oluşturuyor ve dokümantasyonu sadece bu planı doğrulamak için kullanıyordu. Sayfadaki CLI for Microsoft 365 ipucu, aynı sayfada görünen ayrıntılı manuel adımlar daha uygulanabilir göründüğü için planı değiştirmiyordu.
Anti-hallucination skill yeterli miydi?
SPFx ekibinin daha önce hazırladığı, ajana SPFx bilgilerini yetkili dokümantasyondan doğrulamasını söyleyen ayrı bir anti-hallucination skill mevcuttu. Baseline bu skill ile ve ardından ek bir dokümantasyon kaynağı olarak context7 MCP sunucusu eklenerek karşılaştırıldı.
| Sınıflandırma | Baseline | + Anti-hallucination | + Anti-hallucination ve context7 |
|---|---|---|---|
| Ön koşul | 5 / 5 | 5 / 5 | 5 / 5 |
| Deyimsel kullanım | 7 / 10 | 10 / 10 | 8 / 10 |
| Bağımlılık güncelliği | 34 / 50 | 40 / 50 | 39 / 50 |
| Yapılandırma doğruluğu | 38 / 85 | 46 / 85 | 47 / 85 |
Anti-hallucination skill sonuçları iyileştirdi ve ortalama token kullanımını yaklaşık %9 azalttı; ama proje hala yalnızca kısmen yükseltilmiş kalıyordu. context7 eklendiğinde anlamlı bir ek katkı görülmedi: 5 koşunun 3’ünde araçlar erişilebilir olmasına rağmen ajan tarafından çağrılmadı. Bir aracın var olması, ajanın planı için onu ilgili hale getirmeye yetmiyordu.
En iyi rehber zaten mevcuttu: CLI for Microsoft 365
CLI for Microsoft 365’in spfx project upgrade komutu, kaynak ve hedef sürümü analiz edip artımlı yükseltme için gereken sürüme özgü değişiklikleri üretiyor. Ajana açıkça CLI’ı kullanması söylendiğinde sonuçlar belirgin biçimde değişti:
| Sınıflandırma | Baseline | + CLI for Microsoft 365 |
|---|---|---|
| Ön koşul | 5 / 5 | 5 / 5 |
| Deyimsel kullanım | 7 / 10 | 4 / 10 |
| Bağımlılık güncelliği | 34 / 50 | 50 / 50 |
| Yapılandırma doğruluğu | 38 / 85 | 83 / 85 |
Yükseltme mantığı zaten CLI içine kodlanmış olduğundan mevcut ürün aracı en güçlü sonucu üretti. Ancak ajan bu aracı kendi başına keşfetmiyordu. SPFx Dev Skills’in odağı bu yüzden şöyle belirlendi: Yükseltme gerektiğinde ajanı CLI’a yönlendirmek.
Dokümantasyon değişikliği ajanın planını nasıl etkiledi?
SPFx sürüm notlarında CLI for Microsoft 365’e dair bir ipucu zaten vardı. Buna rağmen ajanlar manuel planlarına devam ediyordu. Sebep şu: İpucu, mevcut yaklaşımın yanlış olduğunu söylemeden yalnızca bir alternatif sunuyordu. Aynı sayfadaki manuel migration rehberi ise npm komutları ve JSON parçacıklarıyla desteklenmiş, doğrudan uygulanabilir bir içerikti. Ajanlar tutarlı biçimde bu uygulanabilir içeriği seçiyordu.
Fikirleri Microsoft Learn’e yayımlamadan denemek için Dev Proxy kullanıldı. Bazı denemeler sonuç vermedi: İpucunun yerini değiştirmek fark yaratmadı, migration rehberini tamamen kaldırmak ise manuel koşuları zorlaştırırken CLI benimsemesini güvenilir biçimde artırmadı.
Belirleyici adım, ipucunun hemen öncesine, ajanın manuel yaklaşımını doğrudan sorgulayan bir uyarı eklemek oldu:
Upgrading from a previous minor version requires changes across package versions, build configuration files, and toolchain settings that vary depending on your source version. Manually updating package.json alone will result in build failures.
Ayrıntılı migration bağlantısı kaldırıldığında CLI kullanımı 5 koşunun 0’ından 5’e çıktı. Uyarı işe yaradı çünkü ajanın önceden oluşturduğu planı doğrudan hedef alıyordu. Ancak insan okuyucular için değerli rehberliği kaldırmak sürdürülebilir değildi. Adım adım migration rehberi geri konduğunda CLI benimsemesi tekrar 0/5’e düştü. Bunun üzerine rehber, gulp-Heft geçişinde nelerin değiştiğini kavramsal olarak açıklayacak ve bu değişiklikleri uygulamak için CLI for Microsoft 365’e yönlendirecek şekilde yeniden yazıldı. Kavramsal rehber uyarıyı destekler hale geldiğinde ajanlar 5/5 koşuda CLI’ı kullandı ve yapılandırma doğruluğu 85/85’e ulaştı.
Bu iyileştirmeler SPFx dokümantasyonuna gönderildi: Sürüm notu değişiklikleri PR #10855 ile, uyarı ve yeniden yazılan migration rehberi ise PR #10921 ile geldi. Düzeltmelerin kaynakta yapılması, SPFx Dev Skills kullanmayan geliştiricilere ve ajanlara da fayda sağlıyor.
Değerlendirme SPFx Dev Skills’i nasıl şekillendirdi?
Yürütülen değerlendirme, ajanın yükseltme senaryosunda hangi yardımların ölçülebilir katkı sağladığını gösterdi ve neyin skill’e, neyin dokümantasyon ile mevcut araçlara bırakılması gerektiğini netleştirdi. SPFx Dev Skills önizlemesi, SPFx’e özgü karar kurallarını tek ve odaklı bir spfx skill’inde topluyor ve her isteği kendi içinde bağımsız bir playbook’a yönlendiriyor.
Bugün skill şu alanları kapsıyor:
- SPFx web parçaları, uzantılar, kütüphaneler ve Adaptive Card Extensions oluşturma
- CLI for Microsoft 365 ile proje yükseltme
- SPFx 1.22.0 ve sonrası için Heft, öncesi için gulp seçimi
- Fluent UI v9 ile React arayüzleri kurma
- SharePoint ve Microsoft Graph veri erişimi için PnPjs kullanımı
Yükseltme rehberliği, değerlendirmede gözlenen davranışları temel alıyor. Skill ajana önce yüklü sürümü tespit etmesini, Node ve TypeScript uyumluluğunu kontrol etmesini söylüyor. Ardından tüm değişikliklerin sırasıyla CLI for Microsoft 365 üzerinden uygulanmasını ve süreci temiz bir build ile kapatmasını istiyor. Genel yönergeler ayrıca uzun süren SPFx bağımlılık kurulumlarının senkron çalıştırılmasını gerektiriyor; test sırasında sürekli terminal yoklamasının zaman ve token tükettiği görülmüştü.
Yalnızca skill değil, çevredeki yüzeyler de gelişti
Çalışma SPFx dışında da bir fırsat ortaya çıkardı: Microsoft Learn, sayfaları doğrudan Markdown olarak döndürebiliyor. Bu, tüm HTML sayfayı dönüştürmekten daha temiz bir içerik demek. Bulgu GitHub Copilot ekipleriyle paylaşıldı ve GitHub Copilot Chat ile GitHub Copilot CLI’a Accept: text/markdown desteği eklendi.
Yani ajan deneyimindeki sorunlar her zaman skill içinde çözülmüyor. Bu vakada bazı düzeltmeler dokümantasyona, bazıları CLI’a, bir diğeri ise içeriği getiren platforma aitti. Taban çizgisini oluşturmak, hangi yüzeyde çalışmak gerektiğini görünür kıldı.
Önizlemeyi denemek
SPFx Dev Skills şu anda önizleme aşamasında. Depo, taşınabilir spfx skill’ini, göreve özgü referansları ve uyumlu AI kodlama ajanları için manuel kurulum yönergelerini içeriyor. Değerlendirmenin kapsamı yükseltme senaryosuydu; ancak önizlemedeki oluşturma, tasarım, araç zinciri ve veri playbook’ları bunun ötesine geçiyor. Microsoft ekibi, çıktıların gerçek kullanımla doğrulanmaya devam edeceğini ve geliştiricilerin commit ya da yayın öncesi ajanın ürettiği sonucu gözden geçirmesi gerektiğini belirtiyor. Beklenmedik veya hatalı sonuçlar için issue açmak, skill’in bundan sonra neyi öğretmesi ya da hangi yüzeyin düzeltilmesi gerektiğine karar vermeye yardımcı olacak.
Kaynaklar ve İleri Okuma
- Orijinal yazı: Behind SPFx Dev Skills: testing what agents know and fixing what they miss
- SPFx Dev Skills GitHub deposu
- CLI for Microsoft 365
- Dev Proxy
- sp-dev-docs PR #10855
- sp-dev-docs PR #10921
- Microsoft 365 Developer Blog
- İlgili yazı: SharePoint Copilot Apps Geliyor: SPFx’in AI Dönemine Giriş
- İlgili yazı: SharePoint Copilot Apps Public Preview: Niyetten Aksiyona
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
3 comments