Spesifikasyonları CI’da bir spesifikasyon linter’ı ile lintlemek

Spesifikasyon linter’ı, bir spesifikasyonu yapısal hatalara karşı denetleyen ve bunları bulunca bir hata koduyla çıkan bir programdır. Sürekli entegrasyon (CI, continuous integration), önerilen her değişiklikte otomatik bir denetimdir. Sürekli entegrasyon ve sürekli teslim (CI/CD, continuous integration and continuous delivery), bu denetimi çalıştıran ve geçen bir değişikliği yayınlanabilir tutan iş hattıdır. Spesifikasyon odaklı geliştirme (SDD, spec-driven development), spesifikasyonu koddan önce yazmak ve spesifikasyonu doğruluk kaynağı saymaktır. Ürün gereksinimleri belgesi (PRD, product requirements document), sorunu ve kapsamı anlatan düzyazıdır. SpecScore içinde bir gereksinim (REQ), bir özelliğin içindeki adlandırılmış kuraldır; bir kabul kriteri (AC, acceptance criterion) ise 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, specscore/specscore-cli içindeki CLI’dan (Apache-2.0). Easy Approach to Requirements Syntax (EARS), bir gereksinim için cümle kalıbıdır. Bu linter başlıkları, zorunlu bölümleri ve referansları denetler. İngilizceyi notlamaz.

Son güncelleme: 4 Kasım 2026

Bir spesifikasyonu lintlemek ne demektir

Bir spesifikasyonu lintlemek, kodu lintlemekle aynı türden bir denetimdir. Deterministik bir program dosyaları okur ve kural ihlallerini bildirir. Ürünün iyi bir fikir olup olmadığına karar vermez ve gereksinimi daha iyi düzyazıyla yeniden yazmaz. Doğrulayıcılar sayfası bu yapısal denetimi elle yapılan yapay zeka incelemesinden ayırır. specscore spec lint yapısal denetimdir.

Komutun açıklaması, CLI etiketi v0.55.1’deki ve bu deponun iş akışının kurduğu v0.39.1 etiketindeki internal/cli/spec.go dosyasında, spesifikasyon ağacını yapısal konvansiyon ihlallerine karşı doğruladığını söyler. Temiz bir çalıştırma 0 violations found basar ve 0 ile çıkar. İhlal bulan bir çalıştırma bulgu başına bir satır basar ve 1 ile çıkar. Bir CI job’unu düşüren bu çıkış kodudur. Geçersiz argümanlar 2 ile çıkar. Eksik bir specscore.yaml 3 ile çıkar ve ileti specscore init çalıştırmanızı söyler.

Spesifikasyon linter’ı neyi denetler

Kurallar CLI’nindir, ayrı bir bulut hizmetinin değil. Üretilen katalog docs/lint-rules.md, v0.55.1 etiketinde 183 kural listeler. Bu sitenin iş akışı daha eski bir sürüm olan v0.39.1’i kurar; bu yüzden yalnızca sonraki bir etikette var olan bir kural, o job’un çalıştırdığı şey değildir. Bu bölümde adı geçen kurallar her iki etikettedir. Varsayılan --severity değeri error olur. Bir uyarı yalnızca --severity warning ya da info geçildiğinde basılır ve varsayılan komut bir uyarı yüzünden başarısız olmaz. Katalog dogfood-version-bump kuralını uyarı olarak işaretler; bu yüzden iş akışında sabitlenen sürüm ikili dosyanın gerisinde kaldığında varsayılan komut başarısız olmaz.

Zorunlu dosyalar ve bölümler

Kural readme-exists (readme_exists.go), her spesifikasyon dizininde bir README.md ister. Kural oq-section (oq_section.go), bir özellik README’sinin ## Open Questions bölümünü içermesini ister. Eski bir ## Outstanding Questions başlığı ayrı bir bulgudur ve --fix bu başlığı yerinde yeniden yazar. Aşağıdaki örnekteki ileti, «Open Questions section not found», bölümü kaldırılmış bir özellik README’sinden gelen bulgudur.

İndeks satırları ve alt dizinler

Kural index-entries (index_entries.go), bir özellik indeksini diskteki alt dizinlerle karşılaştırır. Listede olmayan bir alt dizin bir ihlaldir; bağlantısı orada olmayan bir alt dizini gösteren satır da bir ihlaldir. --fix hayalet satırı silebilir ve eksik olanı ekleyebilir. Bu, dizin ve indeks bütünlüğüdür. Düzyazıdaki her URL’nin taranması değildir.

Kabul kriteri başlığının biçimi

Kural ac-heading-format (ac_heading.go), başlığı # Feature: olan bir özellik README’sine uygulanır. Kabul kriteri başlığı gibi görünen bir satır, iki noktadan sonra bir boşluk ve kebab-case bir id ile tam olarak ### AC: <id> olmalıdır. ### AC: <id> (verifies ...) biçimindeki bir başlık da kabul edilir. --fix yalnızca aralığı onarır. Büyük harf ya da alt çizgi içeren bir id bildirilir ve bir kişiye bırakılır. Kural **Requirements:** satırını zorunlu tutmaz, «graceful» ya da «fast» gibi sözcüklere puan vermez ve düzyazı Given, When ya da Then içerdiğinde uyarı vermez. Kriterin kendisinin nasıl yazılacağı kabul kriterlerinin nasıl yazılacağı yazısındadır.

Planın bu tanımlayıcılara referansları

Kaynak bir özellik adlandıran bir planda plan_rules.go, o özelliğin README’sindeki ### AC: başlıklarını okur. Kural P-002, bir görevin **Verifies:** değerinin bu başlıklardan biri için <feature-slug>#ac:<ac-slug> biçimine çözülmediğini, boş bir **Verifies:** satırını, eksik ya da tanınmayan bir kaynak satırını veya bir özellik README’sine çözülmeyen bir kaynak özelliği bildirir. Kural P-001, hiçbir görevin kapsamadığı ve ## Deferred AC Coverage altında listelenmeyen bir başlığı bildirir. Fikir kaynaklı planlar (**Source:** idea:<slug>) ve **Source:** none olan planlar muaftır; terminal bir dispozisyon durumundaki plan da muaftır. P-002 için katalogdaki tek satırlık metin «valid dependency references» der; o dosyadaki denetleyici, az önce anlatılan AC referansı denetimidir.

Geçen bir lint ne değildir

Aynı komut, bir gereksinimin belirtilen sorunu çözüp çözmediğine, bir adın anlamlı olup olmadığına ya da iki özelliğin anlamda birbirine ters düşüp düşmediğine karar vermez. Doğrulayıcılar sayfası bunları CLI linter’ının dışında sayar. Senaryo adımı anahtar sözcüklerini de denetlemez. specscore rehearse senaryo dosyalarını çalıştırır. Bu depodaki iş akışı specscore spec lint çalıştırır ve rehearse’i çağırmaz. Katalog başka aileler adlandırır — fikirler, kararlar, varlıklar, nitelikler, dersler, issues ve plan kurallarının geri kalanı — ve her kural, kendisine ait dosyalara uygulanır. Katalog listedir. Bu sayfa 183 açıklamanın tümünü yeniden anlatmaz.

specscore spec lint komutunu CI’da çalıştırmak

Komut, çalışma dizininden yukarı doğru bir specscore.yaml arar. Bu dosya yoksa 3 ile çıkar ve specscore init adını verir. Bir CI job’unun bu yüzden checkout içinde yapılandırma dosyasına ihtiyacı vardır. scripts/install.sh, SPECSCORE_VERSION değerini okur ve değişken tanımlı değilse latest kullanır. Her çalıştırmada aynı kuralları istiyorsanız bir etiket sabitleyin.

Bu deponun denetimi dogfood.yml dosyasıdır. CLI’ı SPECSCORE_VERSION değerini v0.39.1 yaparak kurar, sonra ek bayrak olmadan specscore spec lint çalıştırır; pull request’lerde ve main’e yapılan push’larda. Süreç sıfırdan farklı çıkınca GitHub Actions adımı başarısız işaretler. Aşağıdaki alıntı bu kurulum ve lint adımlarını korur. Dosya ayrıca permissions: contents: read değerini, bir eşzamanlılık grubunu ve sabitlemenin neden latest olmadığını anlatan bir yorumu da ayarlar.

dogfood.yml dosyasındaki kurulum ve lint adımları

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

Hata raporu (specscore 0.55.0, v0.39.1’de aynı satır biçimi)

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)

Temiz rapor

0 violations found

Her bulgu file:line [severity] rule: message biçimindedir. Özet, N violations found artı ayraç içinde bir sayıdır; örneğin (3 errors). Çıkış kodu süreç durumudur, rapordaki bir satır değildir. Yukarıdaki üç satır, Open Questions bölümü kaldırılmış ve indeksi boş bir alt dizini atlamış bir özellik üzerinde specscore 0.55.0 ile yakalandı. CLI sayfasının gösterdiği raporun aynısıdır. --format text (varsayılan), json ya da yaml kabul eder. --rules ve --ignore kural seçer ve birlikte kullanılamaz. --fix, düzelticisi olan bulguları yeniden yazar; Outstanding Questions başlığı da buna dahildir. Dogfood job’u --fix geçmez.

Bu biçimi CI’da lintlemeyen araçlar

Bu CLI’da bir gereksinim kalitesi denetimi, yukarıdaki yapısal denetimdir. Düzyazının notu değildir. Diğer spesifikasyon odaklı araçlar farklı denetimler yayımlar. Aşağıdaki paragraflar yalnızca o projelerin kendi sayfalarının söylediğini kullanır. Araç rehberi aynı sayfaları 30 Ekim 2026’da okunmuş olarak kaydeder; 28 Eylül 2026 basan Spec Kit belge giriş sayfası ve 4 Ağustos 2026 basan Kiro özellik spesifikasyonu sayfası bunun dışındadır.

GitHub Spec Kit, Markdown çıktıları yazan bir ajan iş akışıdır. Ajanlı SDD başvurusu, /speckit.analyze komutunu, dosyaları düzenlemeden spesifikasyon, plan ve görevler arasındaki tutarsızlıkların raporu olarak anlatır. Onu ajanda çalıştırırsınız. Belge giriş sayfası, uyum kapıları ekleyen topluluk uzantılarını da adlandırır; bunlardan birinin adı CI Guard’dır. Bu, bir SpecScore özellik README’sini lintleyen bir komut değildir.

OpenSpec yapısal bir denetimi gerçekten yayımlar. CLI başvurusu içinde belgelenen openspec validate, OpenSpec’in değişiklik ve spesifikasyon yapısını denetler, doğrulama başarısız olunca sıfırdan farklı çıkar ve başvuru, bir CI job’unun çalıştırabileceği bir shell parçası içerir. Bu denetim OpenSpec’in biçimidir; ### AC: başlıkları ya da bir SpecScore indeksi değildir.

Kiro’nun özellik spesifikasyonları sayfası, Analyze Requirements’ı Kiro’nun içinde, tasarımdan önce çalışan bir denetim olarak anlatır; tutarsızlık, belirsizlik, çatışan kısıtlar ve boşluk arar. Bu, dogfood.yml içindeki komut değildir. Kiro’nun yazdığı cümle kalıpları EARS gereksinim sözdizimi yazısındadır.

BMAD Method README’si yöntemin çıktılarını ve ajan iş akışlarını anlatır. CI’da sabit bir spesifikasyon şemasını lintleyen bir komut belgelemez. Task Master README’si bir PRD’yi task-master parse-prd ile görevlere ayrıştırmayı anlatır. O PRD için bir linter anlatmaz. Bir PRD yine de bir SpecScore özelliğinin girdisi olabilir ve özellik dosyasını o zaman denetleyen specscore spec lint olur.

Sık sorulan sorular

Spesifikasyon linter’ı nedir?

Bir spesifikasyon linter’ı spesifikasyon dosyalarını okur ve yapısal ihlalleri bildirir. specscore spec lint, bir SpecScore ağacı için bu komuttur. Seçilen önem düzeyinde bir şey bulmayınca 0 ile çıkar, ihlal bulunca 1 ile çıkar.

Spesifikasyon linter’ı gereksinim kalitesini ifadeye göre yargılar mı?

Hayır. ac-heading-format, ### AC: başlığını denetler. «graceful» ya da «fast» gibi sözcüklere puan vermez ve bir kriter Given, When ya da Then içerdiğinde uyarı vermez. İfade bir yazma işidir. Doğrulayıcılar sayfası bu deterministik lint’i elle yapılan yapay zeka incelemesinden ayırır.

Spesifikasyonları CI’da nasıl lintlerim?

CLI’ı SPECSCORE_VERSION bir yayın etiketine sabitlenmiş olarak kurun, sonra specscore spec lint çalıştırın. Checkout’ta bir specscore.yaml gerekir. dogfood.yml çalışan bir GitHub Actions örneğidir. v0.39.1’i sabitler.

Başarısız bir çalıştırma ne basar?

Bulgu başına bir satır, file:line [severity] rule: message, sonra 3 violations found (3 errors) gibi bir özet. Süreç 1 ile çıkar. Temiz bir ağaç 0 violations found basar ve 0 ile çıkar.

Diğer araçlar spesifikasyonları CI/CD’de doğrular mı?

OpenSpec’in openspec validate komutu bir CI job’unu düşürebilir ve OpenSpec’in kendi değişiklik yapısını denetler. Spec Kit’in /speckit.analyze komutu ajan oturumunda çalışır. Kiro’nun Analyze Requirements’ı Kiro’nun içinde çalışır. BMAD Method ve Task Master README’leri CI için bir biçim linter’ı belgelemez. SpecScore’un dogfood iş akışı, SpecScore ağacı üzerinde specscore spec lint çalıştırır.

Kaynaklar

CLI davranışı 4 Kasım 2026’da specscore-cli etiketleri v0.55.1 ve v0.39.1 karşısında kontrol edildi. Rakip sayfalar aşağıda bağlananlardır; araç rehberi onları 30 Ekim 2026’da okunmuş olarak kaydeder, sayfanın kendi tarihini bastığı yerler dışında.