SpecGuard - Yapay zeka kodlamasından önce spesifikasyonu denetleyen CLI/Codex eklentisi

Merhaba. SpecGuard adlı bir açık kaynak araç geliştiriyorum.

Codex, Claude Code gibi yapay zeka kodlama araçlarını kullanınca geliştirme hızı gerçekten artıyor. Ancak bunu birkaç kez tekrarlı şekilde kullandıktan sonra, benim pratikte sık karşılaştığım sorun "yapay zeka kod yazamıyor"dan çok "yapay zekaya verdiğim spesifikasyonun kendisi eksik" durumuna daha yakındı.

Spesifikasyonda kusur varsa yapay zeka o boşlukları kendi yorumuyla tahmin edip uygular. İlk bakışta makul görünse de, geliştirme ilerledikçe şu sorunlar büyüdü.

• Kodun kalitesi ve yapısı giderek bozuluyor.
• Spesifikasyon ile kod giderek birbirinden uzaklaşıyor.
• Bir süre sonra hatanın kodda mı olduğu, spesifikasyonun mu eskidiği, yoksa ilk gereksinimlerin mi muğlak olduğu ayırt edilmesi zor hale geliyor.

Bu yüzden, yalnızca uygulama sonrasında yapılan kod incelemesinin yeterli olmadığını düşündüm. Kusurlu spesifikasyon uygulama ajanına olduğu gibi aktarılmadan önce, spesifikasyonun kendi boşluklarını ortaya çıkaran bir aşama gerekiyordu.

SpecGuard, bu sorunu azaltmak için oluşturulmuş bir CLI/Codex eklentisidir. Kod üretildikten sonra çıktıyı denetleyen bir araç değil; uygulamayı yapay zekaya bırakmadan önce spesifikasyonu denetleyen bir araçtır.

Amaçladığım temel akış şöyle.

1. İnsan ürün spesifikasyonunu yazar.
2. Spesifikasyon SpecGuard ile denetlenir.
3. Sonuç NOT_READY ise spesifikasyon güçlendirilir.
4. READY olduğunda Codex/Claude Code gibi uygulama ajanlarına devredilir.

SpecGuard ağırlıklı olarak şu tür boşlukları bulur.

• kimlik doğrulama/yetki sınırlarının belirsiz olması
• tenant/user ownership kapsamının eksik olması
• idempotency, replay, race condition işleyişinin olmaması
• süre dolumu/iptal/durum geçişi kurallarının muğlak olması
• dış yan etkiler, webhook, background job yeniden deneme politikasının olmaması
• yalnızca istemci doğrulamasına güvenen gereksinimler

Sonuçlar genel olarak üçe ayrılıyor.

• READY: uygulama ajanına devredilebilir
• READY_WITH_WARNINGS: devredilebilir ama dikkat edilmesi gereken noktalar var
• NOT_READY: Critical/Major sorunlar var, spesifikasyonun güçlendirilmesi gerekiyor

Varsayılan yol --no-llm sezgisel denetimdir. Çünkü CI veya PR Review ortamında sonucun hızlı ve yeniden üretilebilir olması gerektiğini düşünüyorum. OpenAI Platform ya da Codex tabanlı ayrıntılı inceleme de eklenebiliyor, ancak şimdilik bunu daha derine inmek istendiğinde isteğe bağlı kullanılan yardımcı bir yol olarak tutuyorum.

v0.4.0 ile eklenenler

Bu v0.4.0 sürümünde Codex uygulaması için eklenti MVP'sini ekledim.

pip install spec-guard  
specguard --help  
codex plugin marketplace add KoreaNirsa/spec-guard --ref main  

Codex uygulamasında SpecGuard Plugins kaynağını seçip SpecGuard eklentisini kurarsanız, Codex içinden SpecGuard çalıştırılmasını isteyebilirsiniz. Örneğin örnek bir spesifikasyon oluşturduktan sonra

specguard example copy specs/your-feature-name --force  

Codex'te ilgili klasörü açıp şu şekilde istekte bulunabilirsiniz.

1. @SpecGuard, `specs/your-feature-name` için SpecGuard çalıştır.  
2. @SpecGuard, `specs/your-feature-name` spesifikasyon paketi için SpecGuard çalıştır ve `READY`/`NOT_READY` durumunu ve ana bulguları özetle.  
3. @SpecGuard, `specs/your-feature-name` için SpecGuard çalıştır. Varsayılan sezgisel denetimle ilerle ve sonuç durumunu ve sıradaki yapılacak işi özetle.  

Eklenti, SpecGuard motorunu yeniden uygulamaz. Var olan specguard CLI'ını çağırır ve üretilen sonucu okuyarak mevcut durumu ve sonraki eylemi özetler.

SpecGuard READY durumunu oluşturduğunda, uygulama ajanına verilebilecek bir handoff belgesi üretmeyi ve ardından Codex'in uygulamaya başlamasını amaçlıyorum.

PR Review desteği de var

GitHub Actions tabanlı bir SpecGuard PR Review iş akışı da sunuyorum.

PR'da spesifikasyon paketi değiştiğinde SpecGuard Review çalıştırılıp sonucun PR'a bırakıldığı bir akış söz konusu. Bu özellik OpenAI çağrısı yapılarak çalışır.

Buradaki hedef "yapay zekanın ürettiği kodu incelemek" değil, "yapay zekaya vermeden önce spesifikasyon girdisini incelemek"tir.

Ekipte şu tür kurallar koymak istediğinizde kullanılabilir.

• NOT_READY spesifikasyonları uygulamaya devretmemek
• Critical/Major bulguları önce PR içinde görünür kılmak
• çıktı kalitesinden önce gereksinim girdisinin kalitesini yönetmek

Kurulum için CLI'da specguard actions install-pr-review kullanılabilir ya da Codex'e @specguard SpecGuard PR Review iş akışını kur. diye istek gönderilebilir.

Ancak bu hâlâ deneysel bir özellik olduğundan otomatik kurulum desteği yok; bu yüzden GitHub Secret içinde aşağıdaki gibi ayar yapılması gerekir.

SPECGUARD_OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx  
SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano  
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name  

Mevcut durum ve sınırlamalar

Henüz erken sürüm olduğu için her spesifikasyonu kusursuz biçimde değerlendiren bir araç değil.

Yine de yapay zeka ile kodlama yaparken "spesifikasyon zayıf olduğu için uygulamanın raydan çıkması" sorununu yaşıyorsanız, uygulamadan önce bir kez filtreleyen güvenlik katmanı olarak denenebilir.

Geri bildirim almak istiyorum. Özellikle şunları merak ediyorum.

• hangi tür spesifikasyonlarda iyi sonuç verdiği
• hangi bulguların fazla ya da yetersiz olduğu
• Codex eklenti akışının pratikte gerçekten kullanılabilir olup olmadığı
• PR Review ile bunu zorunlu kılmanın ekip iş akışına uyup uymadığı

Şu anda hâlâ beta öncesi, geliştirmesi yeni yeni ilerleyen bir seviyede; ancak zamanla gerçek iş ortamında yeterince kullanılabilir bir projeye dönüştürmek istiyorum.

İlgilenenlerin issue/PR katkılarını da memnuniyetle karşılarım. Depodaki issue ve PR'lar şu anda ağırlıklı olarak İngilizce yönetiliyor, ancak Türkçe yazmanız da sorun olmaz.

GitHub : https://github.com/KoreaNirsa/spec-guard

[veltrix]

Bu proje hakkında daha ayrıntılı bilgiyi https://nirsa.tistory.com/487 adresinde bulabilirsiniz.