# Yapay zekâ ajanlarıyla spec odaklı geliştirme rehberi Adres: https://agentvera.dev/blog/spec-odakli-gelistirme/ · Yayın: 2026-10-28 Spec odaklı geliştirme: önce spec, sonra plan, görevler, yapım ve doğrulama. Spec Kit, Kiro, OpenSpec ve plan modlarının karşılaştırması, örnek spec dosyasıyla. **Kısaca:** - Spec odaklı geliştirmede neyin yapılacağını ve nasıl kontrol edileceğini önce bir spec dosyasına yazarsın; ajan planlar, işi görevlere böler, yapar ve sonuç spec’e göre doğrulanır. - GitHub Spec Kit, Kiro spec’leri ve OpenSpec bu döngü için dosya ve komut sağlar; Claude Code ve Codex’teki plan modu ise yalnızca planlama adımını karşılar. - Başlamak için araç şart değil: kabul kriterleri olan kısa bir spec.md, gerçekten okunan bir plan ve her prompt’ta tek görev faydanın çoğunu getirir. Spec odaklı geliştirme (spec-driven development), yapay zekâ kodlama ajanlarıyla çalışırken koddan önce yazılı bir spec hazırladığın yöntemdir. Neyin yapılacağını, neden yapılacağını ve işin bittiğini nasıl anlayacağını yazarsın. Ajan bu spec’i teknik bir plana çevirir, planı küçük görevlere böler, görevleri tek tek uygular ve sonuç spec’teki kabul kriterlerine göre doğrulanır. Spec, plan ve görevler bir sohbetin içinde kaybolmaz; depodaki dosyalardır, oturumdan sonra da yerinde durur ve kod gibi incelenebilir. Bu rehber döngüyü anlatıyor, Ekim 2026 itibarıyla bunu destekleyen araçları (GitHub Spec Kit, Kiro spec’leri, OpenSpec ve Claude Code ile Codex’teki plan modları) karşılaştırıyor, gerçek bir spec dosyası ve prompt’larla küçük bir örnek üzerinden ilerliyor ve tuzakları sıralıyor. Araçlarla ilgili bilgiler Ekim 2026’da her projenin resmi dokümanı ve deposundan kontrol edildi. ## Ajanlarla çalışırken spec neden daha önemli Belirsiz bir iş alan geliştirici soru sorar. Belirsiz bir prompt alan ajan ise genelde tahmin eder, makul görünen kodu yazar ve işin bittiğini söyler. “Kod yazıldı” ile “özellik kastettiğin gibi çalışıyor” arasındaki boşluk, yeniden yapılan işin çoğunun kaynağıdır. Spec bu boşluğu üç yoldan kapatır: - **Kararları baştan aldırır.** Uç durumlar, hata halleri ve kapsam dışı kalanlar, ajan senin yerine seçmeden önce yazıya dökülür. - **Her adıma aynı doğruluk kaynağını verir.** Plan, görevler ve inceleme, bir konuşmadan aklında kalanlara değil tek bir dosyaya bakar. - **“Bitti”yi kontrol edilebilir yapar.** Kabul kriterleri incelemeyi “iyi görünüyor”dan “3. kriter geçiyor, testi bu”ya çevirir. Bunların hiçbiri yeni değil; gereksinim dokümanları ve kabul testleri eski fikirler. Değişen şu: ajanlar o kadar hızlı ki artık yavaş ve değerli olan kısım spec’i yazmak, ucuz olan kısım kod. ## Döngü: spec, plan, görevler, yapım, doğrulama | Adım | Ne üretirsin | İşi kim yapar | Neyi kontrol edersin | | --- | --- | --- | --- | | Spec | Ne ve neden: hedef, kullanıcılar, kapsam dışı, kabul kriterleri | Sen; ajan soru sorarak yardım eder | Belirsiz ya da eksik bir şey var mı? | | Plan | Nasıl: mimari, dosyalar, veri modeli, riskler | Ajan | Kod tabanına ve kısıtlara uyuyor mu? | | Görevler | Küçük, sıralı adımlar; her birinin bir test yolu | Ajan | Her görev tek oturuşta incelenecek kadar küçük mü? | | Yapım | Kod, her seferinde tek görev | Ajan | Diff, testler, görevin dışına taşan bir şey yok | | Doğrulama | Her kabul kriteri için kanıt | Ajan ya da ikinci bir inceleyici | Her kriter bir iddiayla değil kanıtla geçiyor | Döngüyü iki kural çalıştırır. Birincisi, **spec davranışı**, **plan uygulamayı** anlatsın. “Kullanıcı şifresini e-postayla sıfırlayabilir” spec’e girer; “`reset_tokens` tablosu ekle” plana. İkincisi, **her adımda dur ve incele**. Aşağıdaki araçların hepsi bu durak etrafında kurulmuş; durağı atlamak spec odaklı geliştirmeyi uzun bir prompt’a geri çevirir. ## Spec odaklı geliştirmeyi destekleyen araçlar | Araç | Ne | Spec nerede durur | Ana komutlar | Lisans ya da fiyat (Ekim 2026) | | --- | --- | --- | --- | --- | | GitHub Spec Kit | Mevcut ajanın için bir CLI ve skill/komut seti | Her özellik için `spec.md`, `plan.md`, `tasks.md` | `/speckit-specify`, `/speckit-plan`, `/speckit-tasks`, `/speckit-implement` | MIT, ücretsiz | | Kiro spec’leri | Kiro IDE, CLI ve web uygulamasında yerleşik | `.kiro/specs//` | CLI’da `/spec new `, `/spec run ` | 50 krediyle ücretsiz katman, ücretli planlar aylık 20 dolardan | | OpenSpec | Mevcut ajanın için bir CLI ve komut seti | `openspec/changes//` | `/opsx:propose`, `/opsx:apply`, `/opsx:archive` | MIT, ücretsiz | | Claude Code plan modu | Bir izin modu: araştır ve planla, düzenleme yok | Kaydetmezsen konuşmada | Shift+Tab, `/plan`, `--permission-mode plan` | Claude Code’un parçası | | Codex plan modu | Codex CLI’da bir çalışma modu | Kaydetmezsen konuşmada | `/plan`, kalıcı hedef için `/goal` | Codex’in parçası | ### GitHub Spec Kit [Spec Kit](https://github.com/github/spec-kit "GitHub Spec Kit"), GitHub’ın spec odaklı geliştirme araç seti. Bu yıl 1.0’a ulaştı; Ekim 2026 itibarıyla son sürüm v1.2.4. Ajanının yerini almaz: `specify` CLI’ı projeye şablonları ve komutları kurar, adımları ajanının sohbetinde çalıştırırsın. Python 3.11 ya da üstü, [uv](https://docs.astral.sh/uv/ "uv") ve macOS, Linux ya da Windows’ta desteklenen bir ajan gerekir. ```bash uv tool install specify-cli specify init my-project --integration claude # mevcut bir depoda: specify integration install claude ``` Entegrasyon listesi 40’tan fazla ajanı kapsıyor; aralarında Claude Code (`claude`), Codex CLI (`codex`), Gemini CLI (`gemini`), GitHub Copilot (`copilot`), Cursor (`cursor-agent`), Kiro CLI (`kiro-cli`), opencode, Qwen Code ve Amp var. Dokümanlar komutları `/speckit.specify` biçiminde yazıyor; nasıl yazacağın ajana göre değişiyor. Claude Code’da `.claude/skills/` altına skill olarak kurulur ve `/speckit-specify` diye çağrılır; Codex’te `$speckit-specify` olur. Kısa yol `specify → plan → tasks → implement → converge`. Üretime gidecek özellikler için dokümanlar tam yolu öneriyor: 1. Proje başına bir kez `/speckit-constitution`: test kuralları gibi ilkeler için. 2. `/speckit-specify`: düz bir açıklamadan özellik spec’ini yazar. 3. `/speckit-clarify`: en fazla beş hedefli soru sorar ve yanıtları spec’e işler. 4. `/speckit-plan`: stack’ine ve kısıtlarına göre teknik planı yazar. 5. `/speckit-checklist`: “gereksinimlerin için birim testleri” üretir. 6. `/speckit-tasks`: bağımlılık sırasına dizilmiş bir `tasks.md` çıkarır. 7. `/speckit-analyze`: spec, plan ve görevler arasında salt okunur bir tutarlılık kontrolü. 8. `/speckit-implement`: görevleri sırayla yapar. 9. `/speckit-converge`: kodu spec’le karşılaştırır ve kaçan işi `tasks.md`’ye ekler. Converge `Converged` diyene kadar implement ve converge’i tekrarlarsın. Dokümanlar her komutu ayrı çalıştırıp sonucunu incelemeden sonrakine geçmemeyi söylüyor. ### Kiro spec’leri [Kiro](https://kiro.dev/docs/specs/ "Kiro spec’leri") spec’leri ürünün içine yerleştiriyor. Her spec’in `.kiro/specs//` altında üç dosyası var: `requirements.md` (hata için `bugfix.md`), `design.md` ve `tasks.md`. Gereksinimler EARS gösterimiyle, “WHEN [koşul] THE SYSTEM SHALL [davranış]” kalıbında yazılıyor. Özellik spec’leri önce gereksinimlerle ya da önce tasarımla başlayabiliyor; Quick Spec ise üç dosyayı aradaki onay durakları olmadan tek seferde üretiyor. Kiro CLI’da `/spec new ` ile başlıyor, görevleri `/spec run ` ile çalıştırıyorsun. Tüm görevleri çalıştırdığında Kiro `tasks.md`’den bir bağımlılık grafiği kuruyor ve birbirinden bağımsız görevleri paralel dalgalar halinde yürütüyor. Ekim 2026 itibarıyla Kiro’nun 50 krediyle ücretsiz bir katmanı ve kullanıcı başına aylık 20 dolardan başlayan ücretli planları var. Spec akışını yerleşik bir inceleme arayüzüyle istiyorsan ve Kiro’nun içinde çalışmak sana uyuyorsa en iyi seçim Kiro. Claude Code ya da Codex’te kalmak istiyorsan Spec Kit veya OpenSpec daha iyi oturur. ### OpenSpec [OpenSpec](https://github.com/Fission-AI/OpenSpec "OpenSpec"), değişiklikler etrafında kurulmuş, daha hafif ve MIT lisanslı bir alternatif. `/opsx:propose add-dark-mode`, `openspec/changes/add-dark-mode/` klasörünü `proposal.md`, gereksinim ve senaryoları içeren bir `specs/` klasörü, `design.md` ve `tasks.md` ile oluşturur. `/opsx:apply` görevleri yapar, `/opsx:archive` değişikliği arşive taşır ve spec’leri günceller. `/opsx:explore` ise bir öneriye bağlanmadan önceki düşünme adımı. ```bash npm install -g @fission-ai/openspec@latest # Node.js 20.19.0+ gerekir cd your-project openspec init ``` Bağımsız bir ikili dosya ve Homebrew formülü de var. Komutların yazımı ajana göre değişiyor, örneğin Codex’te `$openspec-propose`; `openspec init` seçtiğin araçlar için doğru biçimi gösteriyor. Ekim 2026 itibarıyla son sürüm v1.15.0. ### Claude Code ve Codex’te plan modu Plan modları döngünün tek adımını karşılar: planı. [Claude Code plan modunda](/blog/claude-code-plan-modu/ "Claude Code plan modu") ajan dosyaları okur, kodu keşfeder, sonra bir plan önerir; sen onaylayana kadar düzenleme kapalı kalır. Shift+Tab, prompt’un başına `/plan` ya da `claude --permission-mode plan` ile açılır. Codex CLI’da `/plan` var; sohbeti plan moduna geçirir ve ilk isteği satır içinde alabilir, örneğin `/plan Propose a migration plan for this service`. Codex’te ayrıca `/goal` var: büyük bir iş için kalıcı bir hedef koyar, duraklatılabilir, sürdürülebilir ya da silinebilir. Plan modları ek araç olmadan spec odaklı çalışmaya iyi uyar. Eksik parça kalıcılık: ajandan onaylanan planı ve görevleri dosyalara yazmasını iste ki bir sonraki oturum sıfırdan değil onlardan başlasın. ## Örnek: bir spec dosyası ve dört prompt Claude Code, Codex ya da dosya okuyabilen herhangi bir ajanla çalışan kendin-yap sürümü şöyle. Özellik: küçük bir web uygulamasında başarısız giriş denemelerini sınırlamak. ### 1. Spec’i yaz Bunu `specs/login-rate-limit/spec.md` olarak kaydet: ```markdown # Login rate limiting ## Goal Slow down password guessing on POST /login without bothering normal users. ## Non-goals - No CAPTCHA. - No change to how passwords are stored. ## Acceptance criteria 1. WHEN an IP has 5 failed logins within 15 minutes, THE SYSTEM SHALL answer further attempts with HTTP 429 for 15 minutes. 2. WHEN a login succeeds, THE SYSTEM SHALL reset that IP's failure count. 3. The 429 response SHALL include a Retry-After header in seconds. 4. Limits SHALL be configurable through LOGIN_MAX_FAILS and LOGIN_WINDOW_MIN. 5. Existing login tests SHALL still pass, and new tests SHALL cover 1–4. ## Constraints - Use the existing Redis connection; no new services. ## Open questions - Should the limit be per IP, per account, or both? ``` Bir ekranı geçmesin. Açık sorular bölümü bilerek orada: ajana planlamadan önce itiraz edebileceği bir yer açıyor. Spec’i Türkçe de yazabilirsin; ajanlar iki dilde de okur. ### 2. Netleştir ve planla Plan modunda başla ve ajanı dosyaya yönlendir: ```text Read specs/login-rate-limit/spec.md and the auth code. First, ask me about anything ambiguous, starting with the open questions. Then write a plan to specs/login-rate-limit/plan.md: files to change, data stored in Redis and its expiry, how each acceptance criterion will be tested, and risks. Don't edit any source files. ``` Soruları yanıtla, sonra planı oku. Bir kısıtı görmezden gelen her şeye itiraz et. ### 3. Görevlere böl ```text Turn plan.md into specs/login-rate-limit/tasks.md: a numbered checklist of tasks small enough to review in one diff. For each task, list the files it touches and the test that proves it. Order them by dependency. ``` ### 4. Her seferinde tek görev uygula ```text Do task 1 from specs/login-rate-limit/tasks.md only. Run the tests, tick the task in tasks.md, and stop. Tell me if the spec or plan turned out to be wrong. ``` Prompt başına tek görev diff’leri küçük tutar ve sana doğal bir inceleme noktası verir. Bir görev spec’in yanlış olduğunu ortaya çıkarırsa önce spec’i düzelt, sonra devam et. ### 5. Spec’e göre doğrula Görevler bitince sonucu spec’e göre kontrol et; tercihen yeni bir oturumda ya da başka bir ajanla, yani kodu yazmamış bir inceleyiciyle: ```text Read specs/login-rate-limit/spec.md. For each acceptance criterion, find the code and the test that cover it, run the tests, and report PASS or FAIL with evidence. Don't change any code. ``` Döngünün tamamı bu. `specs/` klasörünü kodla birlikte commit’le; bir sonraki kişi ya da bir sonraki ajan kodun neden böyle olduğunu görebilsin. Prompt’ların kendisini yazmak için [kodlama ajanları için prompt yazmak](/blog/kodlama-ajanlari-icin-prompt-yazmak/ "Kodlama ajanları için prompt yazmak") yazısına bak. ## Tuzaklar - **Aslında plan olan spec’ler.** Spec tablo ve fonksiyon adları veriyorsa ajan daha iyi bir tasarım öneremez, inceleyici de davranışı uygulamadan ayıramaz. “Nasıl” kısmını `plan.md`’de tut. - **Fazla uzun spec’ler.** On sayfalık bir spec bağlamı yer ve kimse okumaz, ajan dahil. Özellik başına bir ekran iyi bir sınır; büyük özellikleri böl. - **Okumadan onaylamak.** Okunmamış bir spec ya da plan sadece daha yavaş bir prompt’tur. Asıl mesele inceleme durağı. - **Fazla büyük görevler.** Bir görev tek oturuşta inceleyemeyeceğin bir diff üretiyorsa böl. - **Spec’in kaymasına göz yummak.** Kod sana yeni bir şey öğrettiğinde spec’i güncelle. Kodla çelişen bir spec, hiç olmamasından kötüdür. - **Yazana doğrulatmak.** Kodu yazan ajan kendi işini onaylamaya meyillidir. Son kontrol için yeni bir oturum, ikinci bir model ya da bir insan kullan. - **Her şeye uygulamak.** Tek satırlık bir düzeltmenin spec’e ihtiyacı yok. Süreci uç durumları olan ya da birden fazla dosyaya dokunan işlere sakla. - **Proje kurallarını her spec’e karıştırmak.** Test komutları ve kod stili gibi kalıcı kurallar her özellik spec’ine değil, [CLAUDE.md ya da AGENTS.md](/blog/claude-md-nasil-yazilir/ "CLAUDE.md nasıl yazılır") dosyasına ya da bir Spec Kit constitution’ına girer. ## AgentVera’da spec odaklı geliştirme AgentVera; macOS, Windows ve Linux için Claude Code’u, Codex’i, Kiro’yu ve diğer kodlama CLI’larını yan yana çalıştıran bir masaüstü uygulaması. Her panel gerçek CLI; Spec Kit komutları, OpenSpec komutları, Kiro’nun `/spec`’i ve plan modu tek başına nasıl çalışıyorsa orada da öyle çalışır. Bazı AgentVera özellikleri aynı spec, plan, yapım, doğrulama düzenini izler: - **[Görev hattı](/ozellikler/gorev-hatti/ "Görev hattı"):** Analiz, Plan, Yapım ve İnceleme ajanlarından oluşan kalıcı bir hat. Her görev kabul kriterleriyle gelir; Analiz `01-analiz.md`’yi, Plan `02-plan.md`’yi yazar, inceleyici her kriteri kanıtıyla işaretler. Reddedilen görev bulgularla birlikte Yapım’a döner. - **[AgentVera Verify](/ozellikler/verify/ "AgentVera Verify"):** bir ajana gönderdiğin mesajdan kabul kriterlerini çıkarır; ajanın turu bitince ayrı bir doğrulayıcı diff’i okur, izin listesindeki test komutlarını çalıştırır ve her kriteri geçti ya da kaldı diye işaretler. Doğrulayıcı dosya düzenleyemez. - **[Paralel ekip](/ozellikler/paralel-ekip/ "Paralel ekip"):** bir ajan büyük bir işi her birinin kendi prompt’u, kabul kriterleri, beklenen dosyaları ve bağımlılıkları olan en fazla 8 parçaya böler, bunları ayrı worktree’lerde çalıştırır ve tek bir branch’te, tek bir PR’da birleştirir. - **Takım kanbanı:** bir kart görev olarak bir kodlama ajanına gönderilebilir, ajanın yanıtı yorum olarak geri gelir. Bkz. [yapay zekâ ajanları için kanban](/blog/yapay-zeka-ajanlari-icin-kanban/ "Yapay zekâ ajanları için kanban"). - **Otomatik kod incelemesi:** tur bittiğinde seçtiğin bir Claude modeli kodu inceler ve bulguları dosya:satır bağlantılarıyla listeler. Görev hattı, Verify, paralel ekip ve takım kanbanı Pro ve Team planlarında. Yalnızca spec dosyalarına ve komutlara ihtiyacın varsa Spec Kit ve OpenSpec ücretsiz ve her terminalde çalışır; AgentVera, birkaç ajan aynı anda spec’ler üzerinden çalıştığında işe yarar. ## Toparlarsak Spec odaklı geliştirme, ajan kod yazmadan önce “ne” ve “bittiğini nasıl anlarım” sorularını yazmak, sonraki her adımı da o dosyaya bağlı tutmak demek. Tek ekranlık bir `spec.md` ve plan moduyla başla. Şablon ve tutarlılık kontrolü istediğinde Spec Kit’e ya da OpenSpec’e, akışın editörün içinde olmasını istiyorsan Kiro’ya geç. Hangisini seçersen seç, her adımda incele ve ajanın özetine göre değil kriterlere göre doğrula. Devamını oku: - [Claude Code plan modu](/blog/claude-code-plan-modu/ "Claude Code plan modu") - [Kodlama ajanları için prompt yazmak](/blog/kodlama-ajanlari-icin-prompt-yazmak/ "Kodlama ajanları için prompt yazmak") - [Görev hattı](/ozellikler/gorev-hatti/ "Görev hattı") AgentVera’yı denemek için [indir](/indir/ "AgentVera’yı indir"). ## Sık sorulanlar **Spec odaklı geliştirme nedir?** Yapay zekâ kodlama ajanlarıyla, yazılı bir spesifikasyonun koddan önce geldiği bir çalışma biçimi. Neyin, neden yapılacağını ve çalıştığını nasıl anlayacağını yazarsın; ajan bunu plana ve görevlere çevirir, kodu yazar ve sonuç spec’e göre kontrol edilir. **Plan modundan farkı ne?** Claude Code ya da Codex’teki plan modu, ajanın bir şeyi düzenlemeden önce plan önermesini sağlar; ama plan tek bir konuşmada kalır. Spec odaklı geliştirmede spec, plan ve görevler depodaki dosyalardır; oturumdan sonra da kalır, incelenir, sürümlenir ve sonradan kontrol için kullanılır. **Bunun için GitHub Spec Kit ya da Kiro gerekir mi?** Hayır. Hedefi, kapsam dışı kalanları ve kabul kriterlerini içeren bir spec.md, incelediğin bir plan ve her prompt’ta tek görev zaten spec odaklı geliştirmedir. Spec Kit, Kiro ve OpenSpec bunun üstüne şablon, komut ve tutarlılık kontrolü ekler. **GitHub Spec Kit ücretsiz mi?** Evet. Spec Kit MIT lisanslı. Ekim 2026 itibarıyla specify CLI’ı uv tool install specify-cli ile kuruyorsun; Python 3.11 ya da üstü ve desteklenen bir kodlama ajanı gerekiyor. **Spec odaklı geliştirme ne zaman gereksiz?** Tek satırlık düzeltmelerde, hızlı denemelerde ve tek cümleyle tam anlatabildiğin değişikliklerde. Spec yazmak zaman alır; bunu birden fazla dosyaya dokunan, uç durumları olan ya da birden fazla ajanın yapacağı işlere sakla. --- **AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/