# Spesifikasyonunuzdaki her belirsizlik ajanınızın yaktığı bir tokendir.

Canonical: https://specscore.md/tr/

SpecScore, spesifikasyonlar için açık ve linter ile denetlenebilir bir dosya formatıdır; Markdown ve YAML (YAML Ain't Markup Language) ile yazılır — veriler için JSON (JavaScript Object Notation) neyse öyle — ve ajanlarınızın bunları sorgulamak ve düzenlemek için çağırdığı bir komut satırı arayüzü (CLI) ile birlikte gelir, JSON için `jq` gibi.

Son güncelleme: 30 Ekim 2026

Ardından geliştirme ortasında gelen bir soru. Dağıtım sonrasında gereken bir düzeltme. Ve sürekli yeniden açıklamak zorunda kaldığınız bağlam.

 GitHub'da açık kaynak Ajanınız için AI becerileri edinin CLI'yı yükleyin

## Zaten yazdığınız spesifikasyonlar için bir format.

**SpecScore, özellikler (features), gereksinimler ve kabul kriterleri için bir Markdown + YAML formatıdır**. Ekibinizin ve yapay zeka ajanlarınızın aynı şekilde anladığı bir yapı tanımlar — ve bunlar reponuzdaki sıradan dosyalardır.

Bir SpecScore projesi, bir yaşam döngüsü boyunca üç tür yapı taşından (artifact) oluşur: bir **Idea** henüz olgunlaşmamış bir yönü yakalar; bir **Feature**spesifikasyonu üzerinde anlaşılan davranışı dondurur; bir **Plan** ise özelliği, her biri karşıladığı kabul kriterlerine atıfta bulunan sıralı görevlere böler.

**Ajanınız neden önemser?** Yapı makine tarafından okunabilir olduğu için, yapay zeka ajanları her dosyayı okumak yerine spesifikasyonu CLI aracılığıyla sorgulayabilir. *«Sırada ne üzerinde çalışmalıyım?»* diye sorun; CLI açık Feature'ları ve yanıtlanmamış soruları döndürür. Ekibinizin incelediği yapının aynısı; ajanın yüklemek zorunda olduğu çok daha az bağlam.

 Feature → Gereksinimler → Kabul Kriterleri → Senaryolar. idea → feature → plan ÖRNEK ideas/apply-discount.md

```
# Idea: Discount codes at checkout **Status:** Approved **Date:** 2026-05-19 **Owner:** cart-team **Promotes To:** features/apply-discount ## Problem Statement How might we let returning customers redeem a single promo code at checkout without breaking the existing cart math or the site-wide promotion engine? ## Recommended Direction A registered user can apply **one** valid code per cart. Codes are time-bounded and replaceable. Stacking with site-wide promotions follows a deterministic tiebreak rule (higher discount wins; site-wide wins on tie).
```

 ÖRNEK features/checkout/apply-discount.md

```
--- status: approved owners: [cart-team] --- # Feature: Apply Discount A registered user can apply one valid discount code to their cart at checkout. ## Requirements ### R1 — Single-code limit - **AC-1** The cart accepts at most one discount code at a time. - **AC-2** Applying a second code replaces the first, with a visible confirmation. - **AC-3** Removing the code restores the original cart total. ### R2 — Code validity - **AC-1** A code is valid only if `valid_from` ≤ now ≤ `valid_until` . - **AC-2** Invalid codes show a specific error message. ### R3 — Discount application - **AC-1** Percentage discounts apply to subtotal, not shipping. - **AC-2** Discount totals round down to the nearest cent. - **AC-3** Stacking with site-wide promotions follows the higher-of rule. ## Scenario: Apply a valid percent-off code **GIVEN** a cart with subtotal $50.00 and shipping $10.00 **WHEN** the user applies code `SAVE20` (20% off) **THEN** the cart shows subtotal $40.00, shipping $10.00, total $50.00
```

 ÖRNEK plans/apply-discount/README.md

```
# Plan: Apply Discount **Status:** approved **Features:** - [apply-discount](../../features/apply-discount.md) **Author:** cart-team **Effort:** M **Impact:** high ## Context The apply-discount Feature is Approved. This plan breaks it into ordered tasks; each task cites the acceptance criteria it satisfies. ## Tasks ### T1 — Accept a `code` field on the cart Cites: R1.AC-1, R1.AC-2, R1.AC-3 ### T2 — Validate code time-window Cites: R2.AC-1, R2.AC-2 ### T3 — Apply percentage to subtotal, round down Cites: R3.AC-1, R3.AC-2 ### T4 — Higher-of tiebreak vs site-wide promo Cites: R3.AC-3 ### T5 — Confirmation toast on apply / replace Cites: R1.AC-2
```

## Spesifikasyonlar hiyerarşiktir. Spesifikasyon ağacınız da öyle olmalı.

Elli Feature içeren düz bir liste zamanla çöplüğe döner. SpecScore ağacı gezilebilir tutar: üst öğeler kapsamı, alt öğeler ayrıntıları yönetir ve dizin yapısı ekibinizin ürün hakkında zaten akıl yürüttüğü biçimi birebir yansıtır.

**Açık sorular yukarı taşınır.** Hangi derinlikte olursa olsun çözülmemiş sorular her üst öğenin dizininde görünür. Bir sürümü neyin engellediğini ağacın tepesinden, derinlemesine kazmak zorunda kalmadan görürsünüz.

Çoğu spesifikasyon aracı düz bir listenin yeterli olacağını varsayar. Yeterli de gelebilir — ta ki gelmeyene kadar. SpecScore, «bu Feature nerede duruyor?» sorusunun önem kazandığı anlar için tasarlanmıştır.

[specscore-cli üzerinde canlı görün →](https://specscore.studio/app/github.com/specscore/specscore-cli/spec/features/cli?op=explore)

 KAYNAK specscore-cli/spec/features/cli/

```
spec/features/cli/ ├── agent/ │ └── setup/ ├── feature/ │ ├── change-status/ │ ├── deps/ │ ├── info/ │ ├── list/ │ ├── new/ │ ├── refs/ │ └── tree/ ├── idea/ │ ├── change-status/ │ ├── new/ │ └── relocate/ ├── spec/ │ └── lint/ │ ├── issue-rules/ ← alt-alt-Feature │ └── plan-rules/ ├── task/ │ ├── info/ │ ├── list/ │ └── new/ └── … 10 üst düzey Feature daha
```

## Olmadığında ne bozulur?

- ### 🌀 Spesifikasyonlar senkronizasyonunu kaybeder. Belgedeki spesifikasyon, Slack'teki tartışma ve PR'daki kod haftalarca sessizce birbirinden uzaklaşır. Kimse konuşmanın hangi sürümünün kanonik olduğunu bilemez. Çözüm Tek bir kanonik spesifikasyon; reponun içinde, kodla birlikte sürüm kontrolünde. `specscore lint` her push'ta CI üzerinde çalışır; git geçmişi denetim izidir. Spesifikasyon, tartışma ve PR sessizce ayrılamaz — inceleme altındaki aynı dosyayı paylaşırlar.
- ### 🌫️ Kabul kriterleri belirsiz kalır. *"Hataları zarif bir şekilde ele al"* ifadesi*"bir toast mesajı göster ve geri al"* anlamına mı geliyordu? Yoksa *"logla ve yeniden dene"* miydi? Ajan tahmin yürütmek zorunda kalır. Çözüm Linter, tek bir satır kod yazılmadan önce belirsiz kriterleri yakalar. Fiil linter'dan geçemez çünkü somut bir nesnesi veya koşulu yoktur. Uyarıyı çözmek, *"ele al"* ifadesinin gerçekte ne anlama geldiğini açıkça yazmanızı zorunlu kılar.
- ### 🤖 Ajanlar amaçlanmayan şeyleri teslim eder. İnsanlar yorumlar, soru sorar, netleştirir. Yapay zeka ajanları ise bunu yapmaz — eğitim verilerindeki en yaygın deseni uygularlar. Kod incelemeden geçer çünkü mantıklı **bir şeyler**yapıyordur. Yalnızca sizin amaçladığınız şey değildir. Çözüm Yapılandırılmış girdi. Yapay zeka ajanları REQ ID'lerini, AC ID'lerini ve `GIVEN / WHEN / THEN`senaryolarını deterministik olarak ayrıştırır — yorumlanacak hiçbir şey kalmaz. Her Plan görevi karşıladığı AC ID'lerine atıfta bulunmalıdır; böylece inşa edilen şey, belirtilen şeye karşı her zaman doğrulanabilir.
- ### 🔁 Belirsiz bir spesifikasyon için iki kat ödersiniz. Ajan belirsiz bir talimata dayanarak bir şeyler inşa eder, yanlış olduğunu görürsünüz ve dört farklı şekilde yeniden istersiniz. Yarım yamalak her özellik ve her yeniden deneme token olarak faturalandırılır. Spesifikasyon ne kadar belirsizse, doğru sonuca ulaşmak o kadar çok tur gerektirir. Çözüm Ajan çalışmadan önce spesifikasyonu lint edin.`specscore lint` belirsiz fiilleri ve eksik kabul kriterlerini en başından reddeder; böylece ajan denemeler arasında tahmin yürütmek yerine tek seferde somut bir talimatı uygular. En ucuz çalıştırma, tekrarlamak zorunda kalmadığınız çalıştırmadır.
- ### 💸 Ajanlar spesifikasyonlarınızı yeniden okumak için para harcar. *"Bu özelliğe ne bağımlı?"* sorusuna yanıt veren bir yapay zeka ajanı özelliğin tüm README'sini okur. Ardından her üst dizin indeksini. Ardından ne olur ne olmaz diye kardeş özellikleri. Her sorgu yeni bir ayrıştırmadır. Tokenlar erir, gecikme artar ve maliyet yükselir. Çözüm Dosya okuma yerine yapılandırılmış sorgular.`specscore feature tree` hiyerarşiyi YAML olarak döndürür;`feature deps` geçişli bağımlılık zincirini tarar;`feature info` durumu, sorumluyu ve açık soruları sunar — her biri tek bir çağrıda. Ajan düz metni değil, grafı dolaşır.
- ### 🔗 Kod spesifikasyonunu unutur. Altı ay sonra bir fonksiyonu debug ediyorsunuz ve kimse onun hangi özelliği uyguladığını hatırlamıyor. Kod ile spesifikasyon arasındaki bağ birinin aklındaydı ve o kişi artık şirkette değil. Onu getiren PR ise arşivlerde kayboldu. Çözüm Kaynak kod içi açıklamalar (annotations).`// specscore: features/checkout/apply-discount/R1.AC-2`gibi yorumlar bağı makine tarafından okunabilir kılar ve her refactoring'e dayanır. `specscore code deps` tek çağrıda*"bu dosya hangi spesifikasyonu uyguluyor?"* sorusunu yanıtlar; linter silinmiş spesifikasyonları gösteren referansları uyarır.
- ### 🏷️ Durum değişiklikleri gözden kaçar. Bir özelliği README dosyasında *Draft* durumundan*Approved* durumuna taşırsınız, ancak üst dizindeki features-index onu hala Draft olarak listeler. Üç hafta sonra indeksi okuyan bir ajan özelliğin hala incelemede olduğunu düşünür. Durum iki yerde yaşar ve birbiriyle çelişir. Çözüm `specscore feature change-status` özelliğin Status alanını yeniden yazar ve features-index satırını tek bir atomik adımda yeniden senkronize eder — lint başarısız olursa değişiklik geri alınır. Durum tek bir kanonik yerde yaşar; indeks bu durumun oluşturulmuş bir görünümüdür.
- ### 📋 Spesifikasyonlar bilmediklerini unutur. Bir spesifikasyon tamamlanmış gibi görünür — ta ki*"peki saat dilimlerine ne oluyor?"* sorusunun iki ay önceki bir Slack yazışmasında kaybolduğunu ve hiçbir zaman belgeye girmediğini hatırlayana kadar. Şimdi geliştirme aşamasındasınız ve kimse cevabın ne olduğunu bilmiyor. Çözüm Her SpecScore özelliğinin zorunlu bir **Outstanding Questions**bölümü vardır. Linter bu bölümü atlayan özellikleri reddeder — boş olması kabul edilir (`"None at this time."`), ancak tamamen eksik olması reddedilir. Çözülmemiş sorular belgede görünür, CLI'dan sorgulanabilir ve unutulması imkansızdır.

## Başlamanın en kolay yolu: Yapay zeka ajanları için SpecStudio Skills.

[SpecStudio Skills](https://github.com/specscore/specstudio-skills), SpecScore yaşam döngüsünü dört eğik çizgi (slash) komutuna dönüştüren bir Claude Code eklentisidir. Bir kez yükleyin, ardından sırayla çalıştırın — ham fikirden yürütülebilir bir plana kadar.

```
$ /plugin marketplace add specscore/ai-marketplace $ /plugin install specstudio@specscore
```

 Claude Code otomatik tamamlama

```
> /specstudio: /specstudio:ideate Ham bir fikri bir SpecScore Idea'sına dönüştürün /specstudio:specify Onaylanmış bir Idea'yı bir Feature spesifikasyonuna dönüştürün /specstudio:plan Bir Feature'ı görevlerden oluşan bir Plan'a bölün /specstudio:implement Plan'daki bir sonraki görevi yürütün
```

 /ideate → /specify → /plan → /implement Claude Code /ideate

```
> /ideate Checkout süreci için sepet ekranının nasıl görünmesi gerektiğini düşünelim.
```

 Claude Code /specify

```
> /specify spec/ideas/checkout-basket.md dosyasını tanımlayalım
```

 Claude Code /plan

```
> /plan spec/features/checkout/basket/README.md dosyasını uygulayalım
```

 Claude Code /implement

```
> /implement spec/plans/checkout-basket/README.md dosyasını yürüt
```

Ticari kullanım dahil her kullanım için ücretsizdir. Eklenti kodu[specscore/specstudio-skills](https://github.com/specscore/specstudio-skills) adresindedir — MIT lisanslıdır.

## Spesifikasyonunuzu iki adımda kontrol edin.

Hızlı, deterministik bir linter ve ardından daha derin bir yapay zeka incelemesi — az önce gördüğünüz spesifikasyon üzerinde çalıştırılır. İki adım, iki tür kesinlik.

### Linter'ı çalıştırın.

 deterministik

```
$ specscore spec lint features/apply-discount/README.md:0 [error] oq-section: Open Questions section not found features/apply-discount/README.md:0 [error] index-entries: Child directory not listed in index: refunds features/apply-discount/refunds:0 [error] readme-exists: README.md not found 3 violations found (3 errors) # exit code 1
```

Her çalıştırmada aynı sonuç. Ücretsiz, hızlı, her commit'te çalışır.

### Yapay zeka ile inceleyin ve puanlayın.

 deterministik olmayan

```
> /score apply-discount.md Grade: B — ready with edits AC-2 vague trigger — name the actor and event AC-3 no error path for an expired code prose reads clean; criteria need tightening
```

İnsan bir incelemeci gibi anlam arayarak okur.

## İşte yakalayamayacağı şeyler.

Her şeyi yakalayabileceğini iddia eden bir linter yalan söylüyordur. SpecScore katmanlı bir sistemdir — deterministik bir linter, bir yapay zeka inceleyicisi ve sizin kendi muhakemeniz — ve her katmanın gerçek bir sınırı vardır. Hepsini yazdık: linter'ın neyi yakaladığı, yapay zekanın neyi yakaladığı ve henüz hiçbir araç yapamadığı için neyin tamamen size kaldığı.

[Linter'ın yakalayamayacağı şeyler →](/tr/validators/#limits)

## Kutudan ne çıkıyor?

### Format

Markdown + YAML. Metin açabilen her editörde çalışır. Yazmaya başlamak için yeni araçlar gerekmez.

### Linter

Go ile yazılmış CLI. Yapıyı, referansları ve bütünlüğü doğrular. Hata durumunda sıfırdan farklı bir çıkış kodu verir — hem terminalinizde hem de CI ortamınızda çalışır.

## Kendi araçlarınızı getirin.

SpecScore sadece reponuzdaki dosyalardan ibarettir. Kaydolmanız gereken bir SaaS yoktur. Zorunlu bir orkestratör yoktur. Linear, Jira, GitHub Projects, bir klasördeki düz Markdown ile veya hiçbir proje yönetim aracı olmadan kullanın. Format ve linter için görevlerinizin nerede yaşadığı fark etmez.

## SpecScore nasıl karşılaştırılır?

Spesifikasyon odaklı geliştirme kalabalık bir alan. İşte alternatiflere kıyasla SpecScore'un tam olarak durduğu yer — dürüstçe.

 Plain Markdown Varsayılan yaklaşım. SpecScore, Markdown'ınızın evrildiği yerdir. OpenSpec İyi bir başlangıç rampası. SpecScore ise güvenlik bariyerleridir. Spec Kit Spec Kit iş akışıdır. SpecScore ise ortaya çıkan yapıdır (artifact). Datarim Datarim hattı çalıştırır. SpecScore ise geride kalıcı olandır. CodeSpeak CodeSpeak bir derleyiciye odaklanır. SpecScore bir formata odaklanır. Kiro Kiro spesifikasyonu IDE’sinde taslaklar. SpecScore, CI’ın lint edebildiği biçimdir. Tessl Tessl spesifikasyonu kaynak sayar. SpecScore, spesifikasyonu kodun yanında lint eder. BMAD Method BMAD çevik döngüyü çalıştırır. SpecScore, bir pull request’in denetleyebildiği artifakttır. Task Master AI Task Master bir PRD’yi görevlere böler. SpecScore, bu görevlerin atıf yapabildiği spesifikasyondur.

[Karşılaştırmanın tamamını görün →](/tr/vs/)

## CLI'yı mı tercih edersiniz?

Yapay zeka ajanları kullanmıyor musunuz veya CI hattınızda spesifikasyon doğrulamasını mı istiyorsunuz? Bunun için bir CLI var. 60 saniyede yüklenir — hesap yok, telemetri yok, Markdown spesifikasyonları içeren herhangi bir klasörde çalışır.

 Linux / macOS Windows

```
$ curl -fsSL https://specscore.md/install/get-cli | sh
```

```
> irm https://specscore.md/install/get-cli.ps1 | iex
```

İkili dosya ile birlikte gelen örnek spesifikasyona linter'ı uygulayın:

```
$ specscore lint examples/checkout/apply-discount.md
```

Çıktıya bakın:

```
examples/checkout/apply-discount.md ✓ R1 has acceptance criteria ✓ R2 has acceptance criteria ✗ R3 no acceptance criteria ✗ link "Related Feature: discount-tiers" not found ✗ section "Open Questions" missing 3 problems exit 1
```

[Tüm belgeleri okuyun](/docs/) · [GitHub'da katkıda bulunun](https://github.com/specscore/specscore)

## SpecScore üzerine inşa edildi.

- ### DataTug DataTug ile veritabanı şemalarını keşfedin, sorgular oluşturup çalıştırın ve sonuçları anlayın. Gereksinimlerini ve kabul kriterlerini SpecScore yönlendirir. [datatug.app →](https://datatug.app)[İş akışı araçları →](https://datatug.app/en/under-the-hood/tools-we-built/)
- ### MeaningGraph Veri modelleri ve anlamsal tanımlar için açık kayıt; tanımlar kendi Git depolarınızda tutulur, modellere ve koda bağlanır. [meaninggraph.io →](https://meaninggraph.io/)[Kaydı keşfedin →](https://meaninggraph.io/registry/)
- ### Codegrapher Hızlı kod tabanı keşfi ve spesifikasyonlar ile kod arasında çift yönlü bağlantı için kod grafiği motoru. [codegrapher.dev →](https://codegrapher.dev/)
- ### DALgo Go için veri erişim katmanı, SpecScore ile belirtilmiştir. [dal-go.github.io →](https://dal-go.github.io/)
- ### inGitDB Git tabanlı, sürüm kontrollü veritabanı, SpecScore ile belirtilmiştir. [ingitdb.com →](https://ingitdb.com/)
- ### Rehearse Kabul kanıtı katmanı: bir spesifikasyonun kabul kriterlerini yeniden kullanılabilir kontrollerle ve ara kod yazmadan gerçekten çalıştırın. [rehearse.ink →](https://rehearse.ink)
- ### SpecScore Studio SpecScore spesifikasyonlarını görselleştirmek ve düzenlemek için web arayüzü. [specscore.studio →](https://specscore.studio)

## Sorularınız mı var?

Bunlar insanların en çok sorduğu sorular. Her biri[SSS sayfasında](/tr/faq/) eksiksiz cevaba yönlendirir.

 SpecScore'un spec-kit'ten farkı nedir?

spec-kit bir metodolojidir; SpecScore ise yazdığınız spesifikasyonlar için bir depolama formatı ve bir CLI'dır. Birbirini tamamlarlar — SpecScore formatında yazan bir spec-kit uzantısı yoldadır.

 Tam yanıt → SpecStudio Skills'in Superpowers ve agent-skills'ten farkı nedir?

Ruh olarak benzerler — üçü de yapay zeka ajanlarını ideate → specify → plan → implement adımları boyunca yönlendirir. SpecStudio Skills, SpecScore formatında yapılar yazar ve sorgulamalar ile durum değişiklikleri için `specscore` CLI'ını kullanır; diğerleri doğrudan dosyaları okur ve yazar. Token tüketimi önemli olduğunda SpecStudio'yu seçin.

 Tam yanıt → Neden bir CLI — yalnızca becerileri yüklemek yetmez mi?

Beceriler her dosyayı okumadan referans bütünlüğünü güvenilir biçimde garanti edemez, filtrelenmiş sorgular döndüremez veya doğru durum alanını doğru zamanda güncelleyemez. CLI bu işlemlerin her birini tek bir çağrıda yapar. Beceriler ise aynı şeyi yapmak için her dosyayı okumak zorunda kalır.

 Tam yanıt → Neden «SpecScore» — neyi puanlıyor?

İki anlamı var, ikisi de kasıtlı. Müzikal partisyon (score) — gereksinimlerin yapılandırılmış bir notasyonu. Ve kelimenin tam anlamıyla bir kalite puanı — CLI linter'ı deterministik nottur; `/score` becerisi ise yapının olgunluğuna ilişkin yapay zekanın A'dan F'ye verdiği nottur.

 Tam yanıt → Token tasarrufu rakamları nerede?

Habr yazısından önce ölçülmüş yan yana bir karşılaştırma yoldadır. Yapısal olarak: CLI küçük, yapılandırılmış bir liste döndürür; CLI'sız bir ajan ise bunun yerine N tane belgenin tamamını okur.

 Tam yanıt → SpecScore hangi lisansla yayımlanır?

Herkese açık [specscore/specscore](https://github.com/specscore/specscore) deposundaki belirtim ve belgeler [CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE) lisanslıdır. [specscore/specscore-cli](https://github.com/specscore/specscore-cli) deposundaki referans komut satırı arayüzü (CLI) [Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE) lisanslıdır.

 Tam yanıt → SpecScore belirli bir yapay zekâ aracı ister mi?

Hayır. Spesifikasyonlar depodaki düz metin dosyalarıdır. CLI yerel bir programdır. Bu sitedeki AI Skills, skill çalıştırabilen ajanlar için o CLI'yi sarar. Format tek bir satıcı gerektirmez.

 Tam yanıt → Spesifikasyon güdümlü geliştirme (SDD) nedir?

Spesifikasyon güdümlü geliştirme (SDD), koddan önce test edilebilir bir spesifikasyon — gereksinimler ve kabul ölçütleri — yazmak, sonra sonucu o spesifikasyona göre denetlemektir. SpecScore bu spesifikasyonlar için bir dosya formatıdır.

 Tam yanıt →

## Başarıyı tanımlayın. Sonra ona yer açın.

SpecScore projenizin ne zaman tamamlandığını tanımlar. Haftalık taahhüt, sıradaki adımı seçmenize yardımcı olur. İkisini kısa bir kanıt değerlendirmesiyle birleştirin.

 Bitireceğiniz bir sonraki sonucu seçin → CommittedMe’yi tanıyın (İngilizce) →