Spesifikasyon yönetimi: kod olarak spesifikasyonları saklamak, sürümlendirmek ve gözden geçirmek
Spesifikasyon yönetimi, bir ekibin yazılım spesifikasyonunu nasıl sakladığını, her değişikliği nasıl kaydettiğini, o değişikliği nasıl gözden geçirdiğini ve spesifikasyonu nasıl güncel tuttuğunu anlatır. Spesifikasyonun yönetimi aynı iştir: spesifikasyon, yazılımın ne yapması gerektiğini söyleyen belgedir ve onu yönetmek, belgenin bulunabilir ve güvenilir kalmasının yoludur. Spesifikasyonları kod olarak yönetmek, bu belgelerin sürüm kontrol sisteminde dosya olması demektir; böylece bir spesifikasyondaki değişiklik, inceleyenin karşılaştırabileceği bir commit’tir. Spesifikasyon sürümleme, bu commit’lerin geçmişidir; her belgede yazılı durumla birlikte. Spesifikasyonları kodla senkron tutmak, spesifikasyonun yapısını bozan bir önerinin, kod değişikliğinin geçtiği aynı otomatik denetimde başarısız olması demektir. Spesifikasyon odaklı geliştirme (SDD, spec-driven development), spesifikasyonu koddan önce yazmak ve spesifikasyonu doğruluk kaynağı saymaktır. Sürekli entegrasyon (CI, continuous integration), her önerilen değişiklikte otomatik bir denetimdir. Ürün gereksinimleri belgesi (PRD, product requirements document), sorunu ve kapsamı anlatan düzyazıdır; Markdown’da PRD şablonu bu biçimde bir SpecScore özellik dosyasıdır. Easy Approach to Requirements Syntax (EARS), bir gereksinim için cümle kalıbıdır. SpecScore içinde bir gereksinim (REQ), bir özelliğin içindeki adlandırılmış kuraldır ve bir kabul kriteri (AC, acceptance criterion), bu kurallardan birine ya da birkaçına işaret eden isteğe bağlı soyut bir koşuldur. Denetim, komut satırı arayüzü (CLI, command-line interface) komutudur, specscore spec lint; spesifikasyonları CI’da lintlemek sayfasında belgelenmiştir. Biçim, kamu deposu specscore/specscore içindedir (CC BY 4.0). CLI, specscore/specscore-cli içindedir (Apache-2.0).
Son güncelleme: 9 Kasım 2026
Spesifikasyonun saklandığı yer
Spesifikasyon yönetimi, dosyaların yaşayabileceği bir yerle başlar. Bu depoda spesifikasyon spec/ altında Markdown’dır. Spesifikasyon README’si dizinleri sayar: özellikler, planlar, fikirler, kararlar ve dersler. Bir özellik, bir README.md içeren dizindir. Özellik spesifikasyonu o dosyanın sözleşmesidir ve PRD şablonu, bir linter’ın kabul ettiği doldurulmuş bir örnektir.
specscore spec lint hangi ağacı okuyacağını tahmin etmez. internal/cli/spec.go, v0.55.1 etiketinde, ve aynı işlev v0.39.1 etiketinde, çalışma dizininden yukarı doğru specscore.yaml bulana kadar yürür. O işlevin yorumu, komutun dosyayı zorunlu tuttuğunu, dosya yokken çıkış kodu 3 döndürdüğünü ve specscore init çalıştırmanızı söylediğini söyler. Bu depodaki dogfood iş akışı CLI v0.39.1’i kurar ve ardından specscore spec lint çalıştırır; dolayısıyla lintlediği checkout bu yapılandırma dosyasına sahiptir.
Özellik dosyalarının yanında bir indeks durur. feature-index-row-sync kuralı, v0.39.1 ve v0.55.1 lint kataloglarında bir hatadır. Katalog satırı, her özellik indeksi satırının kendi özellik dosyasıyla eşleşmesini zorunlu tuttuğunu söyler. Bu, indeksin işaret ettiği belgeyle hizalı kalmasıdır. Gereksinimin ifadesinin bir kaynak dosyasıyla karşılaştırılması değildir.
Spesifikasyon sürümleme
Git’e commit edilmiş dosyalar için spesifikasyon sürümleme, o dosyaların commit geçmişidir. SpecScore bir özelliğe ikinci bir sürüm numarası eklemez. İnceleyenin baktığı revizyon, daldaki commit’tir. Belgedeki durum satırı, özelliğin yaşam döngüsünde nerede durduğunu söyler; bu, git hash’inden farklı bir olgudur.
Bu depodaki özellik spesifikasyonu kendisi **Status:** Stable değerindedir. Başlıktan hemen sonra bir **Status:** satırı zorunlu tutar ve değer Draft, In Review, Approved, Implementing, Stable, Amending, Rejected ya da Deprecated değerlerinden biri olmalıdır. status-mirror kuralı, yukarıda adı geçen her iki katalogda, durum taşıyan bir artefaktın frontmatter status: değerinin o gövde satırıyla eşleşmesini zorunlu tutar ve durumu olmayan bir türde status: değerini yasaklar. İki kopyayı eşleştirmek, sekiz değerin dışındaki bir sözcüğü reddetmekle aynı şey değildir. İki katalog satırının hiçbiri, bir özellik durumunu bu kümenin dışında reddeden bir kural anlatmaz; bu yüzden bu sayfa böyle bir kural olduğunu ileri sürmez.
Planlar farklı bir küme kullanır. P-006 kuralı, her iki katalogda, tek dosyalık bir planın gövdesindeki **Status:** değerinin Draft, In Review, Approved, Executing, Blocked, Implemented, Failed, Rejected, Withdrawn, Superseded ya da Deprecated olmasını zorunlu kılar. idea-status-values kuralı, o kuralın izin verdiği kümenin dışındaki bir fikir durumunu reddeder. Katalog listedir. Bu sayfa fikir sözcüklerini yeniden anlatmaz.
Bu plan spesifikasyonu ayrıca sütunları Date, Git Hash, Action ve Comment olan isteğe bağlı bir ## Snapshots tablosu anlatır. Her anlık görüntünün, planın o andaki durumunun bir git commit hash’ine referans verdiğini söyler. Bu sayfa için kontrol edilen iki lint kataloğu, o hash’i çözen bir kural adlandırmaz; bu yüzden bu sayfa, linter’ın commit’in var olduğunu denetlediğini ileri sürmez. Hash, bir kişinin git’te izleyebileceği bir göstergedir. Yayımlanmış plan spesifikasyonu, o belgenin biçim sayfasıdır.
Bir spesifikasyonu gözden geçirmek
Bir Markdown spesifikasyonunun gözden geçirilmesi, onu değiştiren pull request’tir. dogfood.yml, pull_request üzerinde ve main dalına yapılan bir push üzerinde çalışır. Job depoyu checkout eder, SPECSCORE_VERSION değerini v0.39.1 yaparak CLI’ı kurar ve ek bayrak olmadan specscore spec lint çalıştırır. Süreç sıfırdan farklı çıkınca GitHub Actions adımı başarısız kılar. İş akışının izinleri contents: read değeridir.
Özellik durumu In Review, özelliğin gözden geçirilmek üzere sunulduğu anlamına gelir. O sözcüğü yazmak, Markdown dosyasında bir düzenlemedir. Pull request, bir kişinin diff’i okuduğu yerdir. status-mirror, frontmatter ile gövdenin aynı durumu adlandırdığını denetler. Bir inceleyenin düzyazıyı onayladığını kaydetmez. Doğrulayıcılar sayfası, bu yapısal denetimi bir kişinin hâlâ yapmak zorunda olduğu okumadan ayırır. specscore spec lint komutunun bildirdiklerinin kural kural anlatısı spesifikasyonları CI’da lintlemek sayfasındadır.
Spesifikasyonları kodla senkron tutmak
Spesifikasyonları kodla senkron tutmak, bu sitede, spesifikasyonun projeyle birlikte depoda olması ve spesifikasyon ağacı biçimi ihlal ettiğinde CI’ın pull request’i başarısız kılması demektir. Bir pull request, bir özellik dosyasını ve kodu aynı diff içinde değiştirebilir. feature-index-row-sync kuralı, bir indeks satırını adlandırdığı özellik dosyasıyla hizalı tutar. Bir kaynak dosyayı okuyup kodun gereksinimi uygulayıp uygulamadığına karar vermez.
Aşağıdaki alıntı, dogfood.yml dosyasındaki kurulum ve lint adımlarıdır. İş akışı dosyası ayrıca izinleri, bir eşzamanlılık grubunu ve sabitlemenin neden latest olmadığını anlatan bir yorumu ayarlar. Bu satırlar burada atlanır. Komutlar, o dosyanın çalıştırdığı komutlardır.
name: Dogfood lint
on:
push:
branches: [main]
pull_request:
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
- name: Install specscore CLI (pinned)
env:
SPECSCORE_VERSION: v0.39.1
run: |
curl -fsSL https://specscore.md/install/get-cli | \
SPECSCORE_INSTALL_DIR="$HOME/.local/bin" sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
specscore --version
- name: Lint spec tree
run: specscore spec lint
O dosyadaki yorum, yüzen bir latest sabitlemesinin deponun altındaki geçidi değiştirdiğini söyler: bir pull request ile hedeflediği main dalı farklı kurallar görebilir. Sabitleme v0.39.1 değeridir. Job --fix geçirmez. Temiz bir çalıştırma ve başarısız bir çalıştırma, file:line [severity] rule: message satırı dahil, spesifikasyonları CI’da lintlemek sayfasında gösterilir.
Kodu artık anlatmayan bir spesifikasyon tümcesi bu bulgulardan biri değildir. specscore spec lint yapıyı doğrular: zorunlu dosyalar ve bölümler, indeks satırları, başlık biçimi ve kuralların adlandırdığı referanslar. Gerçekleştirmenin gereksinimle eşleşip eşleşmediğini notlamaz. Bu sınır, doğrulayıcılar sayfasının konusudur. Düzyazıyı doğru tutmak hâlâ diff’in gözden geçirilmesidir.
Diğer spesifikasyon odaklı araçlar bir spesifikasyonu nasıl denetler
Aşağıdaki paragraflar 9 Kasım 2026’da alınan sayfaları kullanır. O araçların kendi denetimlerini anlatırlar. Kaç ürün olduğunu söylemezler ve bir piyasayı sıralamazlar. Araç rehberi daha uzun karşılaştırmadır.
Bu GitHub Spec Kit ajanlı SDD başvurusu, /speckit.analyze komutunu spec.md, plan.md ve tasks.md üzerinde salt okunur bir denetim olarak anlatır. Çatışmaları, boşlukları ve belirsizlikleri bildirir, dosyaları hiç düzenlemez ve uygulamadan önce ajanda çalıştırılır. Aynı sayfanın komut listesi, bir SpecScore ağacına karşı specscore spec lint çalıştıran bir CI job’u anlatmaz.
OpenSpec, bir değişikliği doğrudan openspec/changes/ altında bir dizin olarak saklar. openspec validate, değişiklikleri ve spesifikasyonları yapısal sorunlara karşı denetler. Başvuru, çıkış kodu 0’ın doğrulanan her öğenin geçtiği anlamına geldiğini, çıkış kodu 1’in ise bir öğenin başarısız olduğunu, rapor isteğinin geçersiz olduğunu, yapılandırmanın okunamadığını ya da çalıştırmanın başarısız olduğunu söylediğini söyler. Bu denetim, gereksinim ve senaryo blokları dahil OpenSpec’in biçimidir; bir SpecScore ### AC: başlığı değildir. Başka bir komutta, openspec status, aynı başvuru, bir değişikliği yükleyemeyen bir toplu işlemin yine 1 ile çıktığını söyler, “so CI doesn’t accept an incomplete report as successful.” Bu tümce openspec status hakkındadır, openspec validate hakkında değildir.
Sık sorulan sorular
Spesifikasyon yönetimi nedir?
Spesifikasyon yönetimi, bir yazılım spesifikasyonunu saklamak, her değişikliği kaydetmek, o değişikliği gözden geçirmek ve spesifikasyonu güncel tutmaktır. SpecScore’da dosyalar git deposunda Markdown’dır ve specscore spec lint, bir CI job’unun başarısız kılabileceği yapısal denetimdir.
Spesifikasyonun yönetimi nedir?
Spesifikasyonun yönetimi aynı pratiktir. Spesifikasyon, yazılımın ne yapması gerektiğini söyleyen belgedir. Onu yönetmek, belgenin bilinen bir yeri, bir geçmişi, bir gözden geçirmesi ve yapısının biçimle hâlâ eşleştiğini denetleyen bir kontrolü olması demektir.
Spesifikasyonları kod olarak yönetmek nasıl çalışır?
Spesifikasyon, spec/ altında bir Markdown dosya ağacıdır; buna depo kökündeki specscore.yaml eklenir. Bir değişiklik bir commit’tir. Bir pull request diff’i gözden geçirir. dogfood.yml, o pull request üzerinde specscore spec lint çalıştırır.
Spesifikasyon sürümleme nasıl çalışır?
Git geçmişi, dosyaların sürüm geçmişidir. Bir özellik ayrıca, özellik spesifikasyonunun zorunlu tuttuğu sekiz değerden biriyle **Status:** taşır. Bir plan, Git Hash’i planın durumunun bir commit’i olan bir ## Snapshots satırı kaydedebilir. Burada anılan linter katalogları, o hash’i çözen bir kural anlatmaz.
Spesifikasyonlar kodla nasıl senkron tutulur?
Spesifikasyonu depoya koyun ve specscore spec lint bir yapısal ihlal bildirdiğinde, özellik dosyasıyla eşleşmeyen bir indeks satırı dahil, pull request’i başarısız kılın. Komut, kodun gereksinimi uygulayıp uygulamadığına karar vermez. Koddan sapmış bir tümceyi hâlâ bir kişinin diff’te okuması gerekir.
Kaynaklar
CLI dosyaları ve lint katalogları 9 Kasım 2026’da specscore-cli etiketleri v0.39.1 (dogfood.yml’in kurduğu sürüm) ve v0.55.1 üzerinde okundu. Özellik ve plan gereksinimleri, aşağıda specscore/specscore içinde bağlanan dosyalardır. Rakip sayfalar aynı gün alındı.
- specscore/specscore — spec/README.md
- specscore/specscore — özellik durum değerleri
- specscore/specscore — plan anlık görüntüleri
- specscore/specscore
- specscore/specscore — CC BY 4.0 lisansı
- specscore/specscore-cli
- specscore-cli — Apache-2.0 lisansı
- specscore-cli v0.39.1 — internal/cli/spec.go
- specscore-cli v0.55.1 — internal/cli/spec.go
- specscore-cli v0.39.1 — lint kuralı kataloğu
- specscore-cli v0.55.1 — lint kuralı kataloğu
- specscore/specscore — dogfood.yml (CLI v0.39.1)
- SpecScore neyi doğrular
- Spesifikasyonları CI’da bir spesifikasyon linter’ı ile lintlemek
- EARS gereksinim sözdizimi örneklerle açıklandı
- Bir yapay zeka ajanının doğrulayabileceği kabul kriterleri nasıl yazılır
- Yapay zeka ile kodlama için Markdown’da PRD şablonu
- Özellik spesifikasyonu
- Plan spesifikasyonu
- GitHub Spec Kit — ajanlı SDD başvurusu (/speckit.analyze)
- OpenSpec CLI başvurusu — openspec validate ve openspec status
- Fission-AI/OpenSpec
- Spesifikasyon odaklı geliştirme araçları
İlgili
- Spesifikasyonları CI’da bir spesifikasyon linter’ı ile lintlemek
- Yapay zeka ile kodlama için Markdown’da PRD şablonu
- Bir yapay zeka ajanının doğrulayabileceği kabul kriterleri nasıl yazılır
- EARS gereksinim sözdizimi örneklerle açıklandı
- Spesifikasyon odaklı geliştirme
- Spesifikasyon odaklı geliştirme araçları
- Özellik spesifikasyonu
- Plan spesifikasyonu
- CLI
- SpecScore neyi doğrular