AIDive

Video paketi

Git'te yapay zeka spec ve planlarını yönetmek: beş kural, drift gate, kaynaklar

11 dk okuma

TL;DR

  • Yapay zekanın yazdığı spec ve planları commit'leyin. Her araç bunu zaten varsayılan olarak yapıyor; açık soru bunların yönetimi.
  • Her ekibe CODEOWNERS satırı olan tek bir klasör verin; böylece bir spec değişikliği kodun sahiplerinden review ister.
  • Her ortak spec'e ADR tarzı bir başlık koyun: status, superseded-by, owner, dokunulan yollar, review tarihi. Kabul edilmiş bir spec'i asla yeni bir karara dönüştürecek şekilde yeniden yazmayın.
  • CI'da bir drift gate çalıştırın: kabul edilmiş her spec için, adını verdiği bir yol artık yoksa build'i başarısız yapın.
  • Çıktı yolunu CLAUDE.md içinde kalın tek bir emir cümlesiyle yönlendirin, kişisel planları CLAUDE.local.md ve .git/info/exclude içinde tutun, main'de değil bir branch'te yazın.
  • Spec'i yalnızca ekip sınırını aşan ya da 90 gün sonra yeniden okunacak işler için yazın. Spec odaklı çalışmalar yaklaşık iki kat süre ve üç kat token'a mal oluyor.

Kaynaklar ne diyor

Varsayılanlar: herkes commit'liyor

Superpowers'ın writing-plans skill'i planları docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md yoluna kaydeder; altındaki bir satır, plan konumuna dair kullanıcı tercihlerinin bu varsayılanı geçersiz kıldığını söyler s1. Brainstorming skill'i onaylanan tasarımı docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md dosyasına yazar ve "Commit the design document to git" ile biter s2. Spec Kit, spec.md, plan.md ve tasks.md içeren, 001, 002 diye numaralanan specs/[branch-name]/ düzenini ve memory/constitution.md içinde bir constitution kurar s6. Kiro, özellik başına bir klasörle .kiro/specs/ tutar ve ekipleri "collaborate with team members on different features simultaneously" diye davet eder s8. Anthropic'in playbook'u açık konuşur: "Every stage commits an artifact the next stage can read", "Commit the approved plan as plan.md" ve "When implementation departs from the plan, update plan.md in the same commit" s5.

Bu belgelerin hiçbiri, commit'lenmiş bir spec'in kime ait olduğunu ve ne zaman doğru olmaktan çıktığını söylemez. Belgelenmiş üç hata tam bu boşlukta yaşıyor.

Hata 1: herkese açık sızıntı

2026-06-05'te açılan issue 1690, varsayılan docs/superpowers/ konumunun iç planları Sphinx ve Read the Docs üzerinden yayımlanan dokümantasyona sızdırabildiğini bildirir s15. Etkilenen proje, 273 yıldızlı bir Python kütüphanesi olan okama'ydı. Düzeltme commit'i 5 planı ve 3 spec'i geri ekledi, bir .gitignore satırını kaldırdı ve şöyle yazıyor: "track superpowers plans/specs in git, excluded from the Sphinx build" s21. docs/conf.py'nin 84. satırında artık exclude_patterns = ["_build", "Thumbs.db", "superpowers"] var s22. Bugün klasörde 8 plan ve 6 spec duruyor s15. Ekip uygulamayı korudu, build'i düzeltti.

Hata 2: main'deki planlar

2026-04-22'de açılan ve hâlâ açık olan issue 1246, geliştirme branch'i henüz yokken planın neden commit'lendiğini sorar. Bir kullanıcı "I'm getting 10 to 15 commits" diyor; bir diğeri: "Yes please, no plans and specs on main branch!" s16. Eklenti bir branch kuralı uygulamaz; aşağıdaki checklist uygular.

Hata 3: modelin atladığı override'lar

Issue 337, 2026-03-10'da maintainer'ın şu notuyla kapandı: v5.0'dan itibaren eklenti, projenizin CLAUDE.md'sini kendi varsayılanlarının önüne koyuyor; örnek satır: "Save plans to ~/.superpowers/plans/ instead of docs/plans/" s17. v5.0.6 üzerindeki issue 939 sınırı gösterir: CLAUDE.md içindeki bir "Output Paths" tablosu yok sayıldı ve spec'ler docs/superpowers/specs/ içine düşmeye devam etti. İşe yarayan çözüm, tablonun altına kalın bir emir cümlesi koymaktı: design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18. Talimat sırasını değiştiren pull request 1020 birleştirilmeden kapatıldı s19. Override bir ayar değil, bir prompt'tur: her eklenti sürümünden sonra yeniden kontrol edin. Eklentinin kendi geçici dosyaları için issue 1780, v6.0.3 ile kapandı: .superpowers/sdd/ klasörü kendini yok sayıyor ve içine * yazan kendi .gitignore dosyasını bırakıyor s20.

Kişisel ve ortak

Claude Code bu ayrımı belgeler: "For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed" s3. Dizin başına CLAUDE.md dosyaları gerektiğinde yüklenir, "Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file", ve claudeMdExcludes ayarı bir monorepo'da diğer ekiplerin dosyalarını gizler s4. Git üç ignore katmanı sunar: $XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude ve .gitignore s24; ortadaki, ortak bir dosyaya dokunmadan kişisel plan klasörünü gizler. Sahiplik yarısını CODEOWNERS halleder: "Code owners are automatically requested for review when someone opens a pull request that modifies code that they own" s23.

ADR gibi yaşam döngüsü

Michael Nygard'ın 2011 tarihli yazısı şablondur: bir karar "may be 'proposed' if the project stakeholders haven't agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement" ve "If a decision is reversed, we will keep the old one around, but mark it as superseded" s9. Thoughtworks spec kullanımını spec-first (görev için bir kez yazılır), spec-anchored (özelliği geliştirmek için tutulur) ve spec-as-source (yalnızca spec düzenlenir) diye ayırır; yazarı ekler: "I'd rather review code than all these markdown files" s10. Superpowers spec-first dosyalar yazar ve onları sonsuza dek tutar: varsayılan olarak drift.

Drift ve gate

arXiv makalesi sorunu "silent spec-code drift: code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair" diye adlandırır ve "a drift gate that makes spec-code divergence a blocking merge condition" önerir s11. Spec Kit'in kendi rehberi uyarır: "Do not leave a lower-level change in tasks.md or code if spec.md still says something different" s7. TrueFoundry yönetişim argümanını açıkça koyar: "forty-one specs and nine agent files aren't a tidiness problem", bunlar "forty-one unversioned behavior inputs and nine competing standing policies" ve drift "is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable". Aynı yazı spec başına yaklaşık 300 satır ve 150 ila 200 kalıcı talimatlık bir bütçe önerir s13. Bir uygulayıcı elle yapılan sürümü anlatır: "I've had to have Claude compare the spec files to the codebase and see if anything is missing" s26.

Maliyeti ne

Deney Sonuç Kaynak
Spec Kit ile güncel tarihi gösteren bir özellik 8 dosya ve 1,300 satır metin s14
OpenSpec karşılaştırması, aynı gereksinimler, spec aracı ve düz Claude Code OpenSpec 3 boşluk daha buldu; %50 daha fazla kod ve %50 daha fazla döngüsel karmaşıklık; iki kat uzun ve üç kat pahalı s12
Aylarca spec-driven development yürüten bir ekip "two to three times as many tokens and take about twice as long"; kodun iyileştiğine dair kanıt yok s25

Karşılaştırma tek bir deney ve yazarı da bunu söylüyor, ama yön üçünde de aynı. Öyleyse: mimari yol için spec yazın, sınırlı yolu sınırlı tutun ve uygulayıcıların tekrarladığı iki satırı izleyin, "don t spec too big / read the generated specs" s26.

Pazartesi yapılacaklar

  • Ekip başına docs/specs/<squad>/ oluşturun ve her klasör için o ekibin reviewer'larını gösteren bir CODEOWNERS satırı ekleyin.
  • Proje CLAUDE.md'sine kalın tek bir emir cümlesi ekleyin: plan ve spec'ler docs/specs/<squad>/ altına MUST be saved, docs/superpowers/ altına NOT. Bir brainstorm çalıştırın ve dosyanın nereye düştüğünü kontrol edin.
  • Kişisel planları .git/info/exclude içinde listelenen bir klasöre taşıyın ve geliştirici başına tercihleri, kendisi de yok sayılan CLAUDE.local.md içinde tutun.
  • Her ortak spec'e bir başlık koyun: status (proposed, accepted, superseded), superseded-by, owner, paths, review-by.
  • Drift gate'i yazın: status: accepted olan her spec için adı geçen yolları çıkarın ve biri eksikse pull request'i başarısız yapın. Yaklaşık on beş satırlık shell ya da Python.
  • Bir branch kuralı ekleyin: hiçbir spec ya da plan commit'i pull request dışında main'e inmez.
  • Repo dokümantasyonu Sphinx ya da benzeriyle yayımlıyorsa, spec klasörünü bugün exclude_patterns içine ekleyin.
  • Boyut bütçesini koyun: bir spec yaklaşık 300 satırda kalır ve yalnızca ekip sınırını aşan ya da 90 gün sonra yeniden okunacak iş için yazılır.

Daha ileri

  • Başlık şemasını seçmeden önce üç spec kullanım kategorisini (spec-first, spec-anchored, spec-as-source) okuyun; yaşam döngüsü yalnızca spec-anchored dosyalar için önemlidir s10.
  • arXiv makalesi yol kontrollerinin ötesine, tam drift denetimli bir mimariye gider; on beş satırlık gate fazla kaba gelmeye başlayınca işe yarar s11.
  • Spec Kit'in rehberi aynı-commit kuralına denk düşen üç evrim akışını (Flow-Forward, Living Spec, Flow-Back) adlandırır s7.
  • Playbook, plan ve diff senkronunu zorlamak için bir hook önerir; bu konudaki Reddit başlığında 43 puan ve sahadan raporlar içeren 27 yorum var s5, s27.
  • TrueFoundry'nin, spec değişikliğinin bir politika değişikliği olduğu ve bu yüzden çalıştırma metadata'sıyla bir eval gate'in arkasına ait olduğu argümanı, CI yol kontrollerinden sonraki adımdır s13.
  • İki açık issue'yu izleyin: 1246 (main'deki planlar) ve 939 (yok sayılan override'lar); biri kapandığında bu paketteki bir kural eklentide varsayılan olur s16, s18.
  • Marmelab'ın tam yazısı 1,300 satırın neden ortaya çıktığını ve Spec Kit'in nerede gerçekten işe yaradığını açıklar s14.

Kaynaklar

FAQ

İlk günden beş kuralın hepsi gerekli mi?

Hayır. CLAUDE.md yönlendirmesi ve Sphinx hariç tutması on dakika sürer. Bir spec ilk kez ekipleri aştığında CODEOWNERS ve başlığı, kabul edilmiş bir spec bir sprint eskidiğinde de drift gate'i ekleyin.

Drift gate neyi kaçırır?

Değişen davranışı. Yalnızca adı geçen yolun hâlâ var olup olmadığına bakar; bu yüzden tersine çevrilmiş bir koşul geçer. Onu aynı-commit kuralı ve review ile birlikte kullanın.

Klasörü neden gitignore'a eklemeyelim?

Çünkü spec'i sonradan okuyan ajanın ona ihtiyacı var ve denetim izi ancak ara parçalar sürümlenirse işe yarar. okama ekibi gitignore'u denedi ve build'den hariç tutarak commit'lemeye geri döndü.