diffox
Blog

Spec-driven development nedir, ne zaman işe yarar?

Spec-driven development’ta ajan koddan önce spec, plan ve görev listesi yazar. Araçları, eleştirileri ve spec’e göre incelemeyi anlatıyoruz.

PaylaşXLinkedIn

Özet. Spec-driven development’ta (SDD) kodlama ajanı, kodu yazmadan önce ne yapılacağını ve nedenini anlatan bir spec yazar; ardından bir plan ve görev listesi çıkarır, kodu da bu belgelere göre üretir. Spec Kit, Kiro ve OpenSpec’i 18 Ekim 2026 günü kendi belgelerinden okuduk. Eleştirileri yazarlarının kendi yazılarından, sahadaki kullanımı da Carnegie Mellon ve Google’dan araştırmacıların uygulayıcılarla yaptığı çalışmadan aldık.

  • Büyük ve riskli işte işe yarıyor. Uygulayıcılar yöntemi her işte değil, işin büyüklüğüne göre kullanıyor; araştırmacıların tahminine göre spec’lerin %82,0’ı yeni bir özelliği anlatıyor. Araçların belgeleri de küçük işler için daha hafif yollar öneriyor.
  • Eleştirinin merkezinde inceleme yükü var. Eleştirenler, okunacak markdown’ın koddan fazla olmasından şikâyet ediyor. Savunanlara göre fark belgede değil, spec’in kodla birlikte değişip değişmemesinde.
  • Kod ile spec iki yoldan kopar. Ajan uygularken spec’ten sapabilir ya da spec sonraki değişikliklerin gerisinde kalabilir. İlkini kabul testleri yakalar; ikincisini, spec’i kodla aynı pull request’te güncellemek önler.
  • İnceleme spec’in diff’iyle başlar. Kabul kriterlerini bir insan yazar ya da onaylar; kontrolü, spec’i ve kodu yazan ajandan başkası yapar.

Spec-driven development nedir?

3aracı kendi belgelerinden okuduk
%82,0spec yeni bir özelliği anlatıyor
%98,3spec dosyasının tek bir yazarı var
2kod ile spec’in birbirinden kopma biçimi

Bir kodlama ajanına iş verdiğinizde ne istediğinizi çoğu zaman sohbette anlatırsınız. Ne istediğiniz yalnızca sohbette kalırsa, oturum kapanınca o da kaybolur. Spec-driven development (SDD) bu niyeti koddan önce bir dosyaya yazar. Spec, yani spesifikasyon, ajanın ne yapacağını ve neden yapacağını anlatan belgedir. Ajan önce spec’i, sonra nasıl yapacağını anlatan teknik planı, sonra görev listesini yazar. Kodu en son, bu belgelere bakarak üretir.

GitHub, Spec Kit’i duyurduğu Eylül 2025 tarihli yazıda fikri tek cümleyle anlatıyor: “We’re moving from “code is the source of truth” to “intent is the source of truth.”” Yani neyin doğru olduğuna kod değil, yazılı niyet karar veriyor. Aynı yazı geliştiriciye düşen işi de söylüyor: “Crucially, your role isn’t just to steer. It’s to verify.” Bu yazı o ikinci cümle üzerine.

Spec’in iş bittikten sonra ne olacağı ise yönteme göre değişiyor. Thoughtworks’ten Birgitta Böckeler’in Ekim 2025’te üç SDD aracını denediği yazıdaki üç seviye, bugün Spec Kit’in kendi belgesinde de geçiyor:

  • Spec-first. Spec koddan önce yazılır; iş bitince atılabilir.
  • Spec-anchored. Spec iş bittikten sonra da tutulur ve sonraki değişikliklerde kullanılır.
  • Spec-as-source. İnsan yalnızca spec’i düzenler; kod spec’ten üretilir ve elle değiştirilmez.

Böckeler’e göre bulduğu yaklaşımların hepsi spec-first; spec’in zamanla nasıl korunacağı ise çoğu zaman belirsiz bırakılıyor. Aşağıda göreceğimiz gibi, kod incelemesini en çok zorlayan yer de bu belirsizlik.

Sahadaki kullanım için dayandığımız ana kaynak, Carnegie Mellon Üniversitesi ve Google’dan araştırmacıların Spec-Driven Development as Prescribed and as Practiced adlı çalışması. arXiv’deki son sürümü 15 Ekim 2026 tarihli. Çalışma Reddit tartışmalarına, 21 uygulayıcıyla yapılan görüşmelere (bunların 8’i araç geliştiriyor) ve GitHub’daki 266 depoya dayanıyor. Yukarıdaki iki yüzde de bu çalışmadan.

Kodlama ajanlarının kural dosyalarını AGENTS.md ve CLAUDE.md yazısında, yapay zekânın yazdığı bir pull request’in nasıl inceleneceğini de ayrı bir yazıda anlattık. Bu yazı ikisinin arasına spec’i koyuyor.

Spec’ten koda giden yol hangi adımlardan geçer?

Araçlar adımlara farklı adlar veriyor ama sıra aynı: önce ne yapılacağı, sonra nasıl yapılacağı, sonra görevler, en son kod. Her adımın sonunda belgeyi siz okuyup düzeltirsiniz; ajan bir sonraki adıma onunla geçer.

Spec Kit’te proje başına bir kez /speckit.constitution çalıştırılır, sonra her özellik için sırasıyla specify, plan, tasks, implement ve converge gelir. Constitution’da projenin ilkeleri durur ve sonraki her adım bu ilkelere göre değerlendirilir; kodlama ajanlarının kural dosyasına benzer. clarify, checklist ve analyze ise isteğe bağlı kalite kontrolleri: belirsizlik olan işlerde eklenir.

Kiro’da her spec üç dosyadan oluşur: requirements.md, design.md ve tasks.md. Gereksinimler EARS adlı bir kalıpla yazılır: “WHEN [koşul] THE SYSTEM SHALL [beklenen davranış]”. Sıra gereksinim, tasarım, görev; elinizde hazır bir mimari varsa tasarımla da başlayabilirsiniz. Kiro’nun kural dosyaları .kiro/steering/ klasöründe durur ve Kiro deponun kökündeki AGENTS.md’yi de okur.

OpenSpec her değişikliği ayrı bir klasörde tutar: openspec/changes/<değişiklik>/ altında gerekçe (proposal.md), gereksinimler (specs/), gerektiğinde tasarım (design.md) ve görevler (tasks.md). Döngü keşif, öneri, inceleme, uygulama ve arşivden oluşur. Değişikliğin spec’i yalnızca farkı yazar: hangi gereksinimin eklendiğini, değiştiğini, kaldırıldığını ya da yeniden adlandırıldığını. Arşivlerken bu farklar openspec/specs/ altındaki ana spec’lere işlenir; ana spec’ler sistemin bugünkü hâlini anlatır. OpenSpec’in README’sindeki örnek bir fark dosyası şöyle:

spec.md
## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Bu fark dosyası incelemede en çok işe yarayacak parça: pull request’te niyetin neresinin değiştiğini tek bakışta gösterir. Aşağıda buna döneceğiz.

Spec Kit, Kiro ve OpenSpec arasındaki fark ne?

Üç aracın belgelerini 18 Ekim 2026 günü okuduk. Tablo, her aracın hangi dosyaları yazdığını, iş bittiğinde neyi kontrol ettiğini ve küçük işlere ne önerdiğini gösteriyor:

Spec Kit, Kiro ve OpenSpec: yazdıkları dosyalar, adımlar, iş bittiğindeki kontrol ve küçük işler için önerdikleri
AraçYazdığı dosyalarAdımlarİş bittiğindeki kontrolKüçük işler için
Spec Kit.specify/memory/constitution.md; her özellik için specs/ altında spec.md, plan.md, tasks.mdconstitution (bir kez), specify, plan, tasks, implement, convergeconverge kodu spec, plan ve görevlerle karşılaştırır; kodu değiştirmez, yalnızca görev eklerAyrı bir hata düzeltme eklentisi: assess, fix, test
Kiro.kiro/specs/ altında requirements.md (hatada bugfix.md), design.md, tasks.md; kurallar .kiro/steering/requirements, design, tasks (ya da önce design)Sohbette #spec ile soru; IDE’de isteğe bağlı property-based testQuick Spec (aşama onayı yok), Plan modu (dosya yazmaz), sohbette hızlı düzeltme
OpenSpecopenspec/changes/ altında proposal.md, specs/ (yalnızca fark), design.md, tasks.md; güncel hâl openspec/specs/explore, propose, review, apply, archiveverify kodu değişikliğin belgeleriyle karşılaştırır ve yalnızca rapor verir; varsayılan kurulumda yokOkuduğumuz sayfalarda ayrı bir yol yok; aşama onayı da yok

Kaynak: her aracın kendi belgesi, 18 Ekim 2026. Komutların yazılışı kullandığınız kodlama ajanına göre değişir (örneğin /speckit.plan ya da /speckit-plan). Kiro’nun belgesine göre property-based testler yalnızca IDE’de çalışır. Kiro’da gereksinimleri tasarımdan önce tutarsızlık ve boşluklar için ayrıca analiz ettirebilirsiniz.

Üçü farklı yerlerde çalışıyor. Spec Kit, kullandığınız kodlama ajanına komut ya da skill olarak eklenen açık kaynak bir araç seti. OpenSpec de mevcut araçlarınıza eklenir; README’si 30+ aracı desteklediğini söylüyor. Kiro ise IDE’si, CLI’ı ve web arayüzü olan bir kodlama ajanı. OpenSpec’in README’si Kiro için “limited to Claude models” diyor; Kiro’nun model sayfasında ise 18 Ekim 2026 itibarıyla GPT-5.6 ve açık ağırlıklı modeller de var. Bir aracın rakibi hakkında söylediğini, rakibin kendi belgesinden kontrol etmekte fayda var.

2025’te bu listede bir isim daha vardı: Tessl. Böckeler de Kiro ve Spec Kit’in yanında onu denemişti. Tessl, Eylül 2025’te ilk ürünlerini spec-driven development üzerine kurulu olarak duyurdu: açık betada bir Spec Registry ve kapalı betada Tessl Framework. Bugünkü belgeleri ise Tessl’i “organizasyon genelinde ajanlı geliştirmeyi yöneten açık bir platform” diye tanımlıyor ve spec-driven development’tan söz etmiyor. Yöntem bugün Tessl’in registry’sinde herkese açık bir eklenti olarak duruyor. Tessl Framework’ün bugün ne durumda olduğunu söyleyen güncel bir sayfa bulamadık.

Spec’le çalışan iki açık kaynak yöntem daha var. Superpowers’da ajan önce sorularla ne istediğinizi çıkarır; küçük değişiklikler sohbette kararlaştırılır, projeler için yazılı bir tasarım belgesi hazırlanır. Alt ajanlarla yürüyen uygulamada her görev iki aşamada incelenir: önce spec’e uygunluk, sonra kod kalitesi. BMAD Method ise sürecin işe göre boyutlandığını söylüyor: küçük değişiklikler doğrudan yapıma geçiyor.

Neden “yeni waterfall” deniyor?

Waterfall, işi önceden tasarlayıp aşamaları sırayla, katı biçimde yürüten yaklaşımdır: gereksinim yazılıp onaylanmadan tasarıma, tasarım bitmeden koda geçilmez. Eleştirenlere göre spec-driven development bu sırayı markdown dosyalarıyla geri getiriyor. İki yazının başlığı bunu doğrudan söylüyor: “The Waterfall Strikes Back” ve “Reinvented Waterfall?”. Eleştirilerin ortak noktası ise sıradan çok inceleme yükü.

Thoughtworks, Ekim 2025. Böckeler, Kiro’dan küçük bir hatayı düzeltmesini istedi. Gereksinim belgesi bu küçük hatayı 4 kullanıcı hikâyesine ve toplam 16 kabul kriterine çevirdi. Spec Kit’i daha büyük bir özellikte denediğinde de okuması gereken markdown dosyalarını işin büyüklüğüne göre fazla buldu: “To be honest, I’d rather review code than all these markdown files.” Bu kadar dosyaya rağmen ajanın talimatların hepsine uymadığını da sık sık gördüğünü yazıyor.

Scott Logic, Kasım 2025. Colin Eberhardt, hobi uygulamasındaki bir özelliği silip Spec Kit’le yeniden yaptırdı ve her adımda harcanan süreyi not etti. Özelliği iki adımda kurdu: önce pistleri yöneten ekranlar, sonra GPS. İlk adımda 2.577 satır markdown ve 689 satır kod çıktı, okuyup incelemesi 3,5 saat sürdü; ikinci adımda 2.262 satır markdown ve yaklaşık 300 satır kod, yaklaşık 2 saat. Aynı özelliği spec’siz, alışık olduğu yoldan yaptığında 15 dakika kod incelemesi ve 9 dakika testle toplam 24 dakika harcadı. Bu, Eberhardt’ın kendi ölçümü: tek geliştirici, tek hobi uygulaması, Spec Kit’in Kasım 2025’teki hâli; converge adımı o yazıda geçmiyor.

Fark kodda değil: spec’siz yolda iki adımın kodu toplam yaklaşık 1.000 satırdı. Süreyi markdown aldı. Eberhardt spec’siz yolda yaklaşık 10 kat hızlı olduğunu yazıyor ve sonucu şöyle bağlıyor: “For now, the fastest path is still iterative prompting and review, not industrialised specification pipelines.” Bu, tek bir geliştiricinin tek bir uygulamadaki deneyimi; genel bir ölçüm değil.

Marmelab, Kasım 2025. François Zaninotto’ya göre teknik spec zaten kod içeriyor. Geliştirici bu kodu çalıştırmadan önce okuyor, hatalar yine çıkacağı için son kodu da okuyor: “As a result, review time doubles.” Gösterdiği örnekte ajan, “verify implementation” görevini tek bir birim testi yazmadan tamamlandı diye işaretlemiş.

Thoughtworks Technology Radar, Kasım 2025. Radar yöntemi “Assess” halkasına koydu ve bazı araçların “lengthy spec files that are hard to review” ürettiğini yazdı. Notu şu cümleyle bitiyor: “We may be relearning a bitter lesson — that handcrafting detailed rules for AI ultimately doesn’t scale.” Bu not Radar’ın güncel sayısında yer almıyor.

Bu eleştirilerin hepsi inceleme yükünden söz ediyor: okunacak markdown’ın kodu geçmesi, aynı şeyin iki kez okunması, ajanın yazılana uymaması. Hepsi de 2025 sonbaharında, araçların o günkü hâliyle yazıldı; Böckeler araçların çok hızlı değiştiğini kendisi not ediyor.

Savunanlar neyi farklı görüyor?

Atomic Object’ten Meg Kretz, Mayıs 2026’daki yazısında benzerliğin belgede, farkın davranışta olduğunu söylüyor: “The difference comes down to four behaviors, which are observable, not philosophical.” Ona göre waterfall belgeleri bir kapı gibi kullanır: yazılır, onaylanır, dondurulur, devredilir. Spec-driven development’ta ise belge kodla birlikte yazılıp yeniden yazılan bir çalışma aracıdır. Saydığı dört davranış şunlar:

  • Spec ne zaman değişir? Yeni bilgi geldiği gün, çoğu zaman aynı saat içinde.
  • Tasarım ile spec nasıl ilerler? Biri diğerinin ardından gelmez; ikisi birbirini değiştirerek birlikte ilerler.
  • İş ne zaman biter? Spec’teki Must/Should/May gereksinimleri kabul kriteridir; karşılandıklarında iş biter.
  • Spec’i kim düzenler? Bir belirsizliğe takılan geliştirici, spec’i o an düzeltir; düzeltme kodla birlikte commit edilir.

Kretz’in “operasyonel test” dediği ölçüt, bu yazının incelemeyle ilgili ana noktası: spec ve kod aynı pull request’te commit edilir. “If specs lag code, the spec is documentation, not source of truth.”

Uygulayıcılar da kazanç bildiriyor, ama temkinli. Carnegie Mellon çalışmasındaki katılımcıların çoğu spec’lerin ajanın işini daha güvenilir yaptığını söylüyor; ancak bu kazancı aynı dönemde modellerin iyileşmesinden ayıramıyorlar. Yöntemi aylarca kullanan bir ekip, kodu iyileştirdiğini kanıtlayamadığını yazmış. Çalışmaya göre SDD maliyeti ortadan kaldırmıyor: token’ı, zamanı ve zihinsel yükü uygulamadan planlamaya taşıyor.

O yazılardan bu yana araçlar da değişti. Spec Kit Haziran 2026’da isteğe bağlı bir hata düzeltme eklentisi ekledi ve spec’lerin iş bittikten sonra nasıl korunacağını yine Haziran 2026’da belgeledi. Kiro’nun belgesinde bugün onay adımı olmayan Quick Spec ve dosya yazmayan Plan modu var. Kiro, Quick Spec’i önerdiği durumlardan birini şöyle yazıyor: “You've been defaulting to Vibe mode because the standard Spec flow felt too heavy”.

Ne zaman işe yarar, ne zaman yük olur?

Carnegie Mellon çalışmasının bulgusu net: uygulayıcıların çoğu SDD’yi her işte değil, işin büyüklüğüne göre kullanıyor. Küçük işlerde, hatalarda ve tek seferlik betiklerde atlıyorlar. Bir katılımcı acil bir üretim düzeltmesi için “there is no time for spec-driven development and the whole flow” diyor. Bazıları ise kararı riske göre veriyor: hata pahalıysa ve niyet netse spec yazıyor.

Depolardaki iz de aynı yönü gösteriyor. Araştırmacılar 1.000 spec’lik bir örneklemi bir dil modeline etiketletti; tahminlerine göre spec’lerin %82,0’ı yeni bir özelliği anlatıyor. Araçların belgeleri de aynı ayrımı yapıyor:

Hangi işe spec, hangisine doğrudan kod?. Araştırmadaki geliştiriciler de araçların belgeleri de işi büyüklüğüne göre ayırıyor. BÜYÜK, YENİ ÖZELLİK Tam spec: Niyet net, hata pahalı: spec, plan ve görevler. 15–60 DAKİKALIK İŞ Önce bir plan: Kiro’nun Plan modu: plan sohbette kalır. HATA, BETİK, ACİL DÜZELTME Doğrudan: Uygulayıcılar burada spec yazmıyor.
Kaynak: Carnegie Mellon çalışmasının ikinci bulgusu ve Kiro’nun Plan modu sayfası, 18 Ekim 2026. Plan modunda plan sohbette kalır; tam spec’in dosyaları .kiro/specs/ altında saklanır.

Ortadaki basamak önemli. Kiro, Plan modunu resmî bir spec’in fazla geleceği 15–60 dakikalık işler için öneriyor. Plan sohbette kalır ve depoya bir spec dosyası girmez; yani sonradan spec’e göre inceleyeceğiniz bir belge de olmaz. Küçük bir iş için bu sorun değil: o pull request’i alışık olduğunuz gibi, diff’e ve açıklamaya bakarak incelersiniz.

Hata düzeltmede Spec Kit ayrı bir yol öneriyor: teşhis, düzeltme ve doğrulama ayrı tutulur, doğrulanmamış bir düzeltme de başarılı sayılmaz. Kiro ise yazım hatası ya da iyi anlaşılmış tek satırlık değişiklikler için sohbette hızlı bir düzeltmeyi yeterli buluyor.

Kod ile spec zamanla nasıl birbirinden kopar?

Carnegie Mellon çalışmasındaki katılımcıların çoğu, kodla spec’in birbirinden ayrıldığını anlatmış. Araştırmacılar bunun iki yolunu ayırıyor ve adlarını koyuyor: implementation drift (kod spec’ten sapar) ve spec decay (spec eskir). Verdikleri örnek, bir oturumun ne kadar süre açık kalacağı:

Kod ile spec nasıl birbirinden kopar?. Kod spec’ten saptı: spec: 30 dakika, kod: 60 dakika. Yanlış olan: Kod. Ajan uygularken spec’ten saptı. Kabul testi yakalar. Spec eskidi: kod: bilerek 60 dakika, spec: hâlâ 30 dakika. Yanlış olan: Spec. Sonraki değişiklik spec’e dokunmadı. Spec’in diff’i istenir. Örnek: bir oturumun açık kalma süresi. Kaynak: Carnegie Mellon çalışması.
Örnek çalışmanın onuncu bulgusundan. Kartlardaki son satır, iki kopuşu neyin yakaladığını söylüyor.

İki durumda da kod 60 dakika, spec 30 dakika diyor; kodla spec’i karşılaştıran bir araç ikisini aynı görür. Farkı yaratan, hangisinin yanlış olduğu. Çalışma bunu açıkça yazıyor: zamanlanmış ajan incelemeleri ya da CI’daki uçtan uca testler kodla spec’in uyuşmadığını gösterebilir, hangisinin yanlış olduğunu gösteremez. O kararı niyetin sahibi verir.

Implementation drift kodun yazıldığı pull request’te olur. Çalışmanın araç yapımcılarına önerisi, kabul kriterlerini ajanın geçmek zorunda olduğu testlere çevirmek; Kiro’nun EARS gereksinimlerinden property-based test üretmesi bunun bir örneği. Spec decay ise sonra, başka bir pull request’te olur: davranışı değiştiren bir değişiklik o davranışı anlatan spec’e dokunmaz. Çalışma bunu en çok yaşayan spec’lerde (living spec), bir değişiklik başka spec’lerin anlattığı davranışı da etkilediğinde görüyor.

Araçların yerleşik kontrolleri işin sonunda çalışıyor. Spec Kit’in converge adımı kodu o özelliğin spec’i, planı ve görevleriyle karşılaştırır ve yalnızca eksik görev ekler; “Converged” sonucundan sonra belge sizi incelemeye ya da pull request açmaya yönlendirir. OpenSpec’in verify adımı, arşivlemeden önce kodu değişikliğin belgeleriyle karşılaştırır ve yalnızca rapor verir. Kiro’da işin kabul kriterlerini karşılayıp karşılamadığını sohbette #spec ile sorabilir, Sync Files ile tamamlanan görevleri işaretletebilirsiniz.

Bu kontrollerin hepsini işi yapan kodlama ajanı çalıştırıyor; okuduğumuz belgeler, kontrolün başka bir modelle ya da ayrı bir oturumda yapılması gerekip gerekmediğini söylemiyor. Çalışma da bu araçlardan herhangi birinin, iş bittikten sonra spec ile kodun hâlâ uyuştuğunu kontrol edip etmediğini tespit edemediğini yazıyor. Spec Kit’in belgesi riski adıyla anıyor: “The main risk is silent divergence.”

Kod, spec’e göre nasıl incelenir?

Yapay zekânın yazdığı bir pull request’i incelemenin genel adımlarını ayrı bir yazıda anlattık: açıklamadaki işi yapıyor mu, istenmeyen neyi değiştirdi, testler gerçekten sınıyor mu. Spec’le çalışan bir ekipte bunlara spec’e özgü birkaç soru eklenir:

Spec’e göre incelerken sorulacaklar. Genel kod incelemesine ek olarak. Spec ile kod aynı pull request’te mi?: Spec gelmiyorsa niyetin değiştiği görünmez. Spec’in diff’inde ne değişti?: Eklenen, değişen, silinen kabul kriterleri. Kriterleri bir insan onayladı mı?: Spec’in geri kalanı ajan için bağlamdır. Her kriterin bir testi var mı?: Görev listesindeki onay işareti test değildir. Kontrolü başka biri yaptı mı?: Spec’i ve kodu yazan ajan tek kontrolcü olmasın. Başka bir spec bozuldu mu?: Değişen davranışı anlatan eski spec’ler de güncellenir.
Kaynak: Carnegie Mellon çalışmasının tartışma bölümü; Spec Kit’in, OpenSpec’in ve Superpowers’ın belgeleri; Kretz’in yazısı, 18 Ekim 2026.

Spec ile kod aynı pull request’te olmalı. Spec Kit kodu ve belge değişikliklerini birlikte incelemeyi söylüyor, OpenSpec de değişiklik klasörünü kodla birlikte commit etmeyi. Spec ayrı bir pull request’te geliyorsa ya da hiç gelmiyorsa, niyetin değişip değişmediğini göremezsiniz.

Önce spec’in diff’ini okuyun. OpenSpec, planı okurken en değerli yerin specs/ olduğunu söylüyor ve tek bir soru soruyor: “Would you accept these requirements as done?” Pull request’te bu soruyu diff’e sorarsınız: hangi kabul kriteri eklendi, hangisi değişti, hangisi silindi. Çalışma da araçlara kabul kriteri değişikliklerini diff olarak göstermelerini öneriyor. Kodu pull request’in getirdiği yeni spec’e göre okursunuz; spec’teki değişikliği ise hedef daldaki eski hâliyle karşılaştırarak. Kodun spec’e uyup uymadığını testler ve araçlar sorabilir; spec değişikliğinin doğru olup olmadığını yalnızca niyetin sahibi cevaplar.

Kabul kriterlerini bir insan yazmalı ya da onaylamalı. Çalışma bunu doğrudan öneriyor: “Practitioners should write or approve acceptance criteria even when agents produce the rest.” Spec’in hepsini aynı dikkatle okumanız gerekmiyor; çalışmaya göre problem tanımı, temel kararlar ve kabul kriterleri niyeti anlatır, geri kalanı ajan için bağlamdır. Kabul kriterlerini koyan ya da ajanın testlerini gözden geçiren katılımcılar doğrulamayı bir sorun olarak anmamış; araştırmacılar bunun hataları önlediğini gösteremediklerini de ekliyor.

Her kriterin bir testi olmalı. Görev listesindeki bir onay işareti test değildir: Zaninotto’nun örneğinde ajan doğrulama görevini test yazmadan kapatmıştı. Her kabul kriterini bir testle eşleştirin. Eşi olmayan kriter, kodda karşılığı olmayan bir sözdür.

Kontrolü işi yazan ajan yapmamalı. Çalışmaya göre spec’i, kodu ve testleri tek bir ajan yazdığında tek bir yanlış anlama üçüne birden geçebilir; bu yüzden bazı katılımcılar “an agent must not review its own implementation” diyor. Spec Kit de kendi kontrol listeleri için aynı çizgiyi çekiyor: uygulama adımı bu listeleri kendi kendine onaylamamalı. Spec incelemesini tamamen bir ajana bırakmanın bedelini de çalışma söylüyor: “Delegating spec review to an agent removes the one point where a person decides what the system should do.”

Başka bir spec’in bozulup bozulmadığına bakın. Spec decay çoğu zaman burada başlar. Çalışmaya göre bir özelliği değiştiren ajan, o anki görevi yerine getiren ve testlerini geçen ama daha eski bir spec’teki bir kısıtı çiğneyen bir davranış ekleyebilir. Değişen davranışı anlatan başka spec’ler varsa, onlar da aynı pull request’te güncellenmeli.

Açık kaynak depolardaki kayıtta bu adımlarda insan pek görünmüyor. Çalışmanın 266 depoluk örnekleminde, geçmişi kayıtlı 36.888 spec dosyasının %98,3’ünün tek bir yazarı var; spec’lere yazılmış 1.731 satır içi yorumun %68,5’ini botlar yazmış. Araştırmacıların deyişiyle bir spec’in ikinci okuru, varsa, genellikle bir bot. Bu sayılar insanların spec’leri ne kadar dikkatle okuduğunu ya da incelemenin başka bir yerde yapılıp yapılmadığını göstermiyor; yalnızca kayda geçen insan katılımının az olduğunu gösteriyor.

İnceleme aracı spec’ten neyi görür?

diffox, 17 uzman ajandan oluşan bir kod inceleme aracı. Spec klasörlerini (specs/, .kiro/specs/, openspec/) okumaz; incelemeye iki metin taşır. Birincisi deponun kökündeki kural dosyası: önce AGENTS.md dosyasına, yoksa CLAUDE.md dosyasına bakar. Dosyayı pull request’in kendi dalından değil, birleşeceği daldan, dalın ayrıldığı noktadaki hâliyle okur; kural dosyasını değiştiren bir pull request bu yüzden merge edilene kadar eski kurallarla incelenir.

diffox kural dosyasından yalnızca bir zorunluluk bildiren cümleleri alır (“must”, “never”, “-malıdır”, “asla” gibi) ve bunları incelemedeki ajanlara, neyin hata sayılacağını belirleyen kurallar olarak verir. Ajanlardan biri, House Rules Agent, değişen satırlar arasında bu kurallardan birini çiğneyeni arar ve listede olmayan bir kural uydurmaz. İkinci metin pull request’in açıklaması: o da ajanların okuduğu bağlama girer.

Spec’le çalışan bir ekip için anlamı şu: her pull request’te kontrol edilmesini istediğiniz yükümlülükler kural dosyasında durmalı. Spec Kit’in mevcut projeler için verdiği constitution örneğindeki “Every database migration must include a rollback plan.” gibi bir cümle, kural dosyasındaysa incelemede bir kural olarak kullanılır; Spec Kit’in .specify/memory/ altındaki constitution dosyasını ise diffox okumaz. Pull request açıklamasına da hangi spec’i uyguladığınızı ve hangi kabul kriterlerinin değiştiğini yazın; aynı açıklamayı incelemeyi yapan insan da okur.

Kendi projenizde nereden başlamalı?

Yöntemi bütün depoya birden yaymak yerine küçük başlayın:

  1. Tek bir büyük özellik seçin. Niyetin net, hatanın pahalı olduğu yeni bir özellik. Hata düzeltmelerini ve küçük işleri alışık olduğunuz yoldan yapmaya devam edin.
  2. Kabul kriterlerini kendiniz yazın ya da tek tek onaylayın. Gerisini ajan yazabilir. EARS ya da WHEN/THEN gibi bir kalıp, kriteri teste çevirmeyi kolaylaştırır.
  3. Spec’in nasıl yaşayacağına baştan karar verin. Spec Kit üç model sayıyor ve hiçbirini varsayılan yapmıyor: her belgenin birbirini güncelleyebildiği flow-back, her değişiklik için yeni bir klasörün açıldığı flow-forward ve spec’in tek kaynak olduğu living spec. Seçtiğiniz modeli constitution’a ya da ekibin başlangıç notlarına yazın.
  4. Spec’i ve kodu aynı pull request’te gönderin. İncelemeye spec’in diff’iyle başlayın.
  5. Kontrolü başka bir göze verin. İşi yapan ajanın converge ya da verify sonucu bir başlangıç; kabul kriterlerine ve spec’in diff’ine bir insan da baksın.

Bir süre sonra iki şeye bakın: spec’ler kodla birlikte değişmeye devam ediyor mu ve inceleme süresi nereye gidiyor. Kretz’in ölçütü basit: spec kodun gerisinde kalıyorsa artık doğruluğun kaynağı değil, bir belgedir.

Sıkça sorulan sorular

Spec-driven development nedir?

Spec-driven development (SDD), kodlama ajanının kodu yazmadan önce ne yapılacağını ve nedenini anlatan bir spec, ardından bir teknik plan ve görev listesi yazdığı, kodu da bu belgelere göre ürettiği bir çalışma biçimidir. Her adımın sonunda belgeyi bir insan okuyup düzeltir. GitHub’ın Spec Kit’i, Kiro ve OpenSpec bu akışı farklı dosya ve komutlarla uygular.

Spec Kit nedir, nasıl kullanılır?

Spec Kit, GitHub’ın açık kaynak araç seti. specify komut satırı aracıyla projeye kurulur ve kullandığınız kodlama ajanına komutlar ya da skill’ler ekler. Proje başına bir kez /speckit.constitution ile ilkeleri yazarsınız; her özellik için sırasıyla specify, plan, tasks, implement ve converge çalıştırırsınız. converge “Converged” diyene kadar implement ve converge tekrarlanır. Hata düzeltme için ayrı, isteğe bağlı bir eklentisi de var.

Spec Kit mi, Kiro mu, OpenSpec mi?

Kullandığınız araca göre değişir. Spec Kit ve OpenSpec mevcut kodlama ajanınıza eklenir; Kiro ise IDE’si, CLI’ı ve web arayüzü olan bir kodlama ajanı. Spec Kit her özellik için spec, plan ve görev dosyası yazar. OpenSpec her değişikliği ayrı bir klasörde, ana spec’e göre yalnızca farkı yazarak tutar. Kiro üç dosyayla çalışır ve küçük işler için Quick Spec ile Plan modunu sunar. 18 Ekim 2026 günü okuduğumuz belgelerin hiçbirinde yöntemin etkisini ölçen bir sayı yok.

Spec-driven development waterfall mı?

Eleştirenler öyle görüyor, çünkü yöntem gereksinim, tasarım ve görev belgelerini koddan önce sırayla yazdırıyor; en çok da inceleme yükünden şikâyet ediyorlar. Savunanlar ise farkın davranışta olduğunu söylüyor: spec aynı gün değişebiliyorsa, kabul kriterleri spec’in içindeyse ve spec kodla aynı pull request’te güncelleniyorsa bu waterfall değil. Atomic Object’ten Meg Kretz’e göre spec’ler yalnızca sprint sınırlarında değişiyorsa yapılan iş waterfall’dur.

Spec’i ajan mı yazmalı, insan mı?

Uygulamada çoğunu ajan yazıyor: Carnegie Mellon çalışmasında spec’lerin çoğunu ajanlar taslak olarak hazırlamış, insanlar okuyup düzeltmiş. Çalışmanın önerisi, gerisi ajandan gelse bile kabul kriterlerini bir insanın yazması ya da onaylaması. Spec incelemesini tamamen bir ajana bırakmak, sistemin ne yapması gerektiğine bir insanın karar verdiği tek noktayı ortadan kaldırır.

Spec-driven development küçük işler için uygun mu?

Çoğu zaman değil. Uygulayıcılar küçük işlerde, hatalarda ve tek seferlik betiklerde spec yazmıyor. Kiro, 15–60 dakikalık işler için dosya yazmayan Plan modunu, iyi bilinen özellikler için aşama onayı olmayan Quick Spec’i öneriyor. Spec Kit’in hata düzeltme için ayrı bir eklentisi var; BMAD Method da küçük değişiklikleri doğrudan yapıma geçiriyor.

diffox spec dosyalarımı okur mu?

Spec klasörlerini okumaz. diffox deponun kökündeki kural dosyasını (önce AGENTS.md, yoksa CLAUDE.md) pull request’in birleşeceği daldan okur ve dosyadaki zorunluluk cümlelerini inceleme kuralı olarak kullanır; pull request’in açıklaması da incelemenin bağlamına girer. Her pull request’te kontrol edilmesini istediğiniz yükümlülükleri kural dosyasına yazın.