Yapay zeka ile kodlama için Markdown’da PRD şablonu

Bir ürün gereksinimleri belgesi (PRD, product requirements document), iş görevlere bölünmeden önce sorunu ve kapsamı anlatan düzyazıdır. Bir özellik spesifikasyonu, SpecScore’un ürünün bir yeteneği için tuttuğu dosyadır ve ne yaptığını, neden var olduğunu ve nasıl davrandığını anlatır. Markdown, bu dosyanın düz metin biçimidir. Spesifikasyon odaklı geliştirme (SDD, spec-driven development), spesifikasyonu koddan önce yazmak ve spesifikasyonu doğruluk kaynağı saymaktır. SpecScore içinde bir gereksinim (REQ), bir özelliğin içindeki adlandırılmış kuraldır. Bir kabul kriteri (AC, acceptance criterion), bu kurallardan birine ya da birkaçına işaret eden isteğe bağlı soyut bir koşuldur. Bir senaryo, Given, When ve Then adımlarıyla yazılmış somut bir örnektir. Bir plan, özelliği görevlere bölen belgedir. Bir görev, bir kişinin ya da bir ajanın bitirebileceği bir iş birimidir. Sürekli entegrasyon (CI, continuous integration), önerilen her değişiklikte otomatik bir denetimdir. Denetim, bir komut satırı arayüzü (CLI, command-line interface) komutudur, specscore spec lint, ve specscore/specscore-cli içindeki CLI’dan gelir. Easy Approach to Requirements Syntax (EARS), bir gereksinimin kullanabileceği bir cümle kalıbıdır. Claude Code, bu sitedeki CLI Skills eklentisinin yazıldığı yapay zeka kodlama ajanıdır. Bu özellik spesifikasyonu şablonu, o özellik dosyası ile ona geri işaret eden plan ve görevdir.

Son güncelleme: 5 Kasım 2026

Bu özellik spesifikasyonu şablonu nedir

Bir PRD çoğu zaman bir kişinin okuduğu tek bir düzyazı dosyasıdır. SpecScore aynı özeti, bir linter’ın denetleyebildiği dosyalar olarak tutar. Özellik spesifikasyonu, özelliği ürün spesifikasyonunun atomik birimi olarak adlandırır: spec/features/ altında bir dizin; onun README.md dosyası, özelliğin ne yaptığının tek doğruluk kaynağıdır. Plan spesifikasyonu, planı o özelliği görevlere ayıran belge olarak adlandırır. Senaryo spesifikasyonunda bir senaryo, özelliğin _tests/ dizinindeki somut bir Given/When/Then dosyasıdır. Kabul kriterleri spesifikasyonu kriteri soyut tutar: neyin doğru olması gerektiğini söyler, senaryo ise bunun nasıl kanıtlanacağını söyler.

Aşağıdaki checkout dosyası, doldurulmuş şablondur. Özellikler indeksi, bir spesifikasyon README’si ve specscore.yaml ile birlikte specscore spec lint bunu 0 ihlalle kabul etti. Bu denetim 2 Kasım 2026’da specscore 0.55.1 ile ve dogfood.yml dosyasının kurduğu etiket olan 0.39.1 ile çalıştırıldı. Özellik dosyasındaki Studio araç çubuğu satırı, specscore/specscore içindeki özellik README’lerinin taşıdığı satırdır. Özellik spesifikasyonundaki zorunlu bölümler tablosu onu listelemez.

Özellik README’si

Özellik spesifikasyonundaki zorunlu bölümler tablosu, her özellik README’sinde bir # Feature: {Title} başlığı, başlığın hemen ardından bir **Status:** satırı, bir Summary, bir Problem, bir Behavior bölümü, bir Acceptance Criteria bölümü, bir Open Questions bölümü ve bir uyum altbilgisi olduğunu söyler. Durum değeri şunlardan biridir: Draft, In Review, Approved, Implementing, Stable, Amending, Rejected ya da Deprecated. Contents bölümü yalnızca özelliğin alt dizinleri olduğunda zorunludur. **Source Ideas:** isteğe bağlıdır. Denetlenen dosya bunu — olarak bırakır.

Open Questions hiçbir zaman atlanmaz. Hiç yoksa bölüm None at this time. der. Acceptance Criteria de hiçbir zaman atlanmaz. Tanımlı kriter yoksa o bölüm Not defined yet. der ve Open Questions o zaman Acceptance criteria not yet defined for this feature. cümlesini içermelidir. Altbilgi son satırdır ve URL’si https://specscore.md/feature-specification adresidir.

Artefakt frontmatter konvansiyonu, her artefaktın YAML frontmatter içinde bir format: anahtarı taşıdığını, durum taşıyan bir artefaktın ayrıca status: anahtarını taşıdığını ve bunun gövdedeki **Status:** belirtecinin aynısı olduğunu söyler. Aynı özellik, bunu zorunlu kılan lint kurallarının bir hoşgörü süresinin ardından çıktığını söyler. Denetlenen dosya her iki anahtarı da içerir. Bu sayfa, v0.39.1 pin’inin bunları atlayan bir dosyayı reddettiğini iddia etmez.

specscore spec lint’in kabul ettiği özellik README’si (2 Kasım 2026)

---
format: https://specscore.md/feature-specification
status: Draft
---

# Feature: Checkout validation

> [SpecScore.**Studio**](https://specscore.studio): | [Explore](https://specscore.studio/app/github.com/example/checkout/spec/features/checkout?op=explore) | [Edit](https://specscore.studio/app/github.com/example/checkout/spec/features/checkout?op=edit) | [Ask question](https://specscore.studio/app/github.com/example/checkout/spec/features/checkout?op=ask) | [Request change](https://specscore.studio/app/github.com/example/checkout/spec/features/checkout?op=request-change) |

**Status:** Draft
**Source Ideas:** —

## Summary

The checkout form shows a validation error next to a field when the shopper submits invalid data, and it rejects an email that is not a valid address.

## Problem

A vague sentence such as "the form should handle bad input" does not say which event causes which response. Checkout needs those obligations written so a reviewer and a linter can point at them.

## Behavior

### Field validation

The checkout system checks the form when the shopper submits it.

#### REQ: show-field-error

When a shopper submits the checkout form with invalid data, the checkout system MUST show a validation error next to the invalid field.

#### REQ: reject-invalid-email

If the submitted email is not a valid address, then the checkout system MUST reject the form.

## Acceptance Criteria

### AC: invalid-submission

**Requirements:** checkout#req:show-field-error, checkout#req:reject-invalid-email

Submitting the checkout form with invalid data shows a validation error next to the invalid field, and an email that is not a valid address is rejected.

## Open Questions

None at this time.

---
*This document follows the https://specscore.md/feature-specification*

Aynı lint çalıştırmasındaki özellikler indeksi

---
format: https://specscore.md/features-index-specification
---

# Features

| Feature | Status | Description |
|---|---|---|
| [Checkout validation](checkout/README.md) | Draft | The checkout form shows a validation error next to a field when the shopper submits invalid data, and it rejects an email that is not a valid address. |

## Open Questions

None at this time.

---
*This document follows the https://specscore.md/features-index-specification*

Aynı lint çalıştırmasındaki spesifikasyon README’si

# Checkout specification

## Open Questions

None at this time.

Aynı lint çalıştırmasındaki specscore.yaml

# SpecScore Repo Config Schema: https://specscore.md/repo-config

project:
  title: Checkout sample
  host: github.com
  org: example
  repo: checkout

Özelliğin tanımlayıcısı, spec/features/ konumuna göre dizin yoludur. İndeks bağlantısı checkout/README.md, dosyanın spec/features/checkout/README.md yolunda durduğu anlamına gelir; gereksinimlerin ve kriterlerin kullandığı özellik id’si bu yüzden checkout olur. İndeks, her üst düzey özelliği listeler. Listede olmayan bir alt dizin, index-entries ihlalidir; bunu Spesifikasyonları CI’da bir spesifikasyon linter’ı ile lintlemek anlatır. O ağaçtaki spesifikasyon README’sinin tek bölümü Open Questions’tır ve bölüm None at this time. der. Yapılandırma dosyası, CLI’ın yukarı doğru aradığı dosyadır. specscore.yaml yoksa komut 3 ile çıkar ve specscore init adını verir.

REQ kimlikleri, kabul kriterleri ve senaryolar

Gereksinim spesifikasyonu, her kuralı ## Behavior içindeki bir konu başlığının altına koyar. Başlık #### REQ: {slug} biçimindedir ve iki noktadan sonra bir boşluk vardır. Slug küçük harf, rakam ve tire kullanır. Kanonik id {feature-path}#req:{slug} biçimindedir. Checkout dosyasında bu, checkout#req:show-field-error ve checkout#req:reject-invalid-email olur. Bir gereksinim tek bir yükümlülük belirtir. Spesifikasyon, gereksinimlerin RFC 2119 anahtar sözcükleri MUST, MUST NOT, SHOULD, SHOULD NOT ve MAY’i SHOULD kullanmasını söyler. Bir REQ: başlığı ## Behavior dışında geçerli değildir. Bir EARS cümlesi o düzyazı olabilir. Linter İngilizceyi puanlamaz. Kalıplar EARS gereksinim sözdizimi içindedir.

Kabul kriteri

Kabul kriterleri spesifikasyonu, her kriterin bir ### AC: {slug} başlığı olduğunu, ## Acceptance Criteria içinde, ardından bir **Requirements:** satırı geldiğini ve bu satırın {feature-id}#req:{slug} değerlerini listelediğini, sonra neyin doğru olması gerektiğini söyleyen soyut bir ifade geldiğini söyler. Kriterler isteğe bağlıdır. Spesifikasyon, iki ya da daha çok ilişkili gereksinimi bir araya getirmek açıklık kattığında bir kriter eklenmesini söyler. Checkout dosyası her iki kuralı checkout#ac:invalid-submission içinde bir araya getirir. İfade Given, When ya da Then içermez. Kabul kriterleri nasıl yazılır yazma rehberidir. ac-heading-format kuralı (CLI etiketi v0.55.1’deki ac_heading.go), başlığın kebab-case bir id ile ### AC: <id> olduğunu denetler. Lint makalesi, bu kuralın **Requirements:** satırını zorunlu kılmadığını ve sözcüklere puan vermediğini kaydeder. Kabul kriterleri spesifikasyonu o satırı yine de zorunlu kılar.

Senaryo

Senaryo spesifikasyonu, senaryoyu _tests/ içine koyar; bu bir alt özellik değildir ve özellik indeksinin dışındadır. Dosya # Scenario: {Title} ile, bir gereksinime ya da bir kritere işaret eden bir **Validates:** satırıyla ve anahtar sözcükleri büyük harfle GIVEN, WHEN, THEN ve AND olan bir ## Steps bölümüyle başlar. Her _tests/ dizini, bir senaryo indeksi olan bir README içermelidir. Aşağıdaki örnek bu dosya biçimidir. 2 Kasım lint çalıştırmasının parçası değildi. specscore spec lint senaryo adımı anahtar sözcüklerini denetlemez. specscore rehearse senaryo dosyalarını çalıştırır. Rehearse o çalıştırıcıdır. Dogfood iş akışı linter’ı çalıştırır ve rehearse’i çağırmaz.

Senaryo spesifikasyonundaki senaryo dosyası biçimi

# Scenario: Reject an invalid email

**Validates:** [checkout#ac:invalid-email-rejected](../README.md#ac-invalid-email-rejected)

## Steps

GIVEN the shopper is on the checkout form
WHEN the shopper submits the email "not-an-email"
THEN the page shows "Enter a valid email address" beside the email field
AND the order is not placed

Üç katmanı sırayla okuyun. Gereksinim kuralı söyler. Kabul kriteri, adlandırdığı kurallar için neyin doğru olması gerektiğini söyler. Senaryo tek bir somut akış verir. Yalnızca PRD düzyazısını gören bir ajan bu ayrımı icat etmek zorundadır. Şablon onu zaten taşır.

Planlar ve görevler

Bir plan README’si spec/plans/{plan-slug}/README.md yolunda durur. Plan spesifikasyonu başlığın # Plan: {Title} olmasını ve başlık alanlarının Status, tam olarak bir kaynak satırı, Date, Owner ve Supersedes olmasını zorunlu kılar. Özellik kaynaklı bir plan **Source Feature:** ile özellik slug’ını kullanır; burada bu checkout olur. Diğer geçerli kaynak satırları **Source:** idea:{slug} ve **Source:** none satırlarıdır. Zorunlu bölümler Summary, Approach, Tasks ve Open Questions’tır. Planın içinde her görev bir ### Task N: başlığıdır ve **Verifies:** satırı feature-slug#ac:ac-slug biçimindedir. P-001 kuralı, plan_rules.go içinde, hiçbir görevin kapsamadığı ve ## Deferred AC Coverage altında listelenmeyen bir kabul kriteri başlığını bildirir. P-002 kuralı, bu başlıklardan birine çözülmeyen bir **Verifies:** değeri bildirir. Fikir kaynaklı planlar ve **Source:** none taşıyan planlar P-001 kuralından muaftır.

Aşağıdaki plan, checkout özelliği için o yayımlanmış biçimi izler; format: ve status: frontmatter’ını da içerir. 2 Kasım lint çalıştırmasında yoktu. Bir planın dokunduğu özellik, sütunları Plan, Status, Author ve Approved olan bir ## Plans tablosu içermelidir. Denetlenen özellik dosyasında Plans bölümü yoktur çünkü o ağaçta plan yoktur.

Görev spesifikasyonu, görevi ayrıca planın altında kendi dizini ve README.md dosyası olarak da tanımlar. Başlık # Task: {Title} biçimindedir. Zorunlu alanlar **Status:**, **Depends on:** (bağımlılık yokken birebir none) ve **Model:** (small, medium, large ya da inherit) alanlarıdır. Alt görev dizinleri içeren bir dizin bir plandır, görev değildir. Aşağıdaki görev dosyası bu alanları ilk checkout görevi için kullanır. 2 Kasım lint çalıştırmasında yoktu. Bir görev belgesinin altbilgi URL’si https://specscore.md/task-specification adresidir.

Plan spesifikasyonundaki plan biçimi, checkout için doldurulmuş

---
format: https://specscore.md/plan-specification
status: Draft
---

# Plan: Show checkout validation errors

**Status:** Draft
**Source Feature:** checkout
**Date:** 2026-11-05
**Owner:** @example
**Supersedes:** —

## Summary

This plan decomposes the checkout feature into the work that shows a field error and rejects an email that is not a valid address.

## Approach

Both tasks verify the same acceptance criterion, which bundles the two requirements. Nothing is deferred, so this plan has no Deferred AC Coverage section.

## Tasks

### Task 1: Show a validation error beside the invalid field

**Verifies:** checkout#ac:invalid-submission

When the shopper submits the checkout form with invalid data, show a validation error next to the invalid field.

### Task 2: Reject an email that is not a valid address

**Verifies:** checkout#ac:invalid-submission

If the submitted email is not a valid address, reject the form.

## Open Questions

None at this time.

---
*This document follows the https://specscore.md/plan-specification*

Görev spesifikasyonundaki görev belgesi biçimi

---
format: https://specscore.md/task-specification
status: queued
---

# Task: Show a validation error beside the invalid field

**Status:** queued
**Depends on:** none
**Model:** medium

## Acceptance Criteria

- Submitting the checkout form with invalid data shows a validation error next to the invalid field.

## Open Questions

None at this time.

---
*This document follows the https://specscore.md/task-specification*

Özellik dosyası, checkout formunun ne yapması gerektiğini yanıtlar. Plan, bu işin nasıl bölündüğünü yanıtlar ve her satır içi görev doğruladığı kriteri adlandırır. Görev belgesi, bir kişinin ya da bir ajanın eline aldığı yapraktır. Kriter id’sini sabit tutun. checkout#ac:invalid-submission, hem özelliğin hem planın kullandığı dizedir.

Şablonu CI’da lintlemek

specscore spec lint spesifikasyon ağacını yapısal konvansiyon ihlallerine karşı doğrular. 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. dogfood.yml, CLI’ı SPECSCORE_VERSION değerini v0.39.1 yaparak kurar, sonra specscore spec lint komutunu pull request’lerde ve main’e yapılan push’larda çalıştırır. İş akışı alıntısı, başarısızlık raporu ve kural kataloğu Spesifikasyonları CI’da bir spesifikasyon linter’ı ile lintlemek makalesindedir.

Biçim lisansı CC BY 4.0 olup specscore/specscore deposundadır. CLI lisansı Apache-2.0 olup specscore/specscore-cli deposundadır.

Diğer spesifikasyon odaklı araçlar farklı denetimler yayımlar. Aşağıdaki cümleler yalnızca o projelerin kendi sayfalarının söylediğini kullanır. Spesifikasyon odaklı geliştirme araçları aynı sayfaları 30 Ekim 2026’da okunmuş olarak kaydeder; Spec Kit belge ana sayfası ise 28 Eylül 2026 basar.

OpenSpec, openspec validate komutunu CLI başvurusu içinde belgeler. Bu komut OpenSpec’in değişiklik ve spesifikasyon yapısını denetler ve doğrulama başarısız olunca sıfırdan farklı çıkar. Bir SpecScore ### AC: başlığını ya da bir SpecScore indeksini denetlemez.

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, bu sayfadaki özellik dosyasına yeniden yazdığınız girdi olmayı sürdürebilir. specscore spec lint o zaman özellik dosyasını denetleyen komuttur.

GitHub Spec Kit, aşamaları Markdown artefaktları yazan bir ajan iş akışını anlatır. O belge ana sayfası, bir SpecScore özellik README’sini CI’da lintleyen bir komut anlatmaz. Bu araçların karşılaştırması spesifikasyon odaklı geliştirme araçları sayfasıdır.

Claude Code’un okuyabileceği bir spesifikasyon şablonu

Dosyalar Markdown’dır; bir depoyu okuyabilen bir ajan şablonu da okuyabilir. Claude Code, CLI Skills sayfasının hedeflediği ajandır. O sayfa ai-plugin-specscore eklentisini belgeler: CLI’ı saran hafif bir Claude Code eklentisi. Eklenti deposu specscore/ai-plugin-specscore deposudur. Sayfa, eklentinin specscore spec lint, specscore feature, specscore task ve specscore feature change-status komutlarını eklenti komutları olarak sunduğunu söyler. O sayfadaki kurulum satırları /plugin marketplace add specscore/ai-marketplace ve /plugin install cli-skills@specscore satırlarıdır.

Aynı sayfa, specscore agent setup <agent-name> komutunu claude, copilot, cursor, codex, antigravity.google, pi.dev ya da opencode için belgeler; komut SpecScore’un yönettiği bir projenin içinde çalıştırılır. SpecStudio Skills yönlendirmeli iş akışıdır (/ideate, /specify, /plan, /implement) ve aynı zamanda bir Claude Code eklentisidir. Bu sayfadaki şablon, bu komutların lintlediği dosyadır. Eklenti, özellik README’sinin yerini almaz.

Sık sorulan sorular

Markdown’da PRD şablonu nedir?

Sabit bir biçimi olan Markdown dosyaları olarak yazılmış bir ürün gereksinimleri belgesidir. SpecScore’da bu biçim bir özellik README’sidir: başlık, durum, özet, sorun, #### REQ: kurallarıyla davranış, kabul kriterleri ve açık sorular. Bu sayfadaki checkout dosyası, specscore spec lint komutunun kabul ettiği bir dosyadır.

Bir özellik spesifikasyonu şablonunda REQ kimlikleri nereye konur?

## Behavior içindeki bir konu başlığının altına, #### REQ: {slug} olarak. Id {feature-path}#req:{slug} biçimindedir. Kabul kriterleri bu id’leri **Requirements:** satırında listeler. Bir plan görevi kriter id’sini **Verifies:** satırında listeler.

Bir kabul kriteri ile bir senaryo arasındaki fark nedir?

Bir kabul kriteri soyut bir koşuldur. Bir senaryo, _tests/ içindeki somut bir Given/When/Then akışıdır. Kabul kriterleri spesifikasyonu, kriterin adımları yazmaması gerektiğini söyler. Senaryo dosyası adımları yazar.

Linter PRD düzyazısını notlar mı?

Hayır. specscore spec lint yapıyı denetler: başlıklar, zorunlu bölümler, indeks satırları ve P-001 ile P-002 gibi göndermeler. Ürünün iyi bir fikir olup olmadığına karar vermez. Spesifikasyonları CI’da bir spesifikasyon linter’ı ile lintlemek bu komutun daha uzun anlatımıdır.

Claude Code bu spesifikasyon şablonunu kullanabilir mi?

Evet. Şablon depodaki Markdown’dır. CLI Skills eklentisi specscore spec lint komutunu ve özellik ile görev komutlarını Claude Code içinde sunar. specscore agent setup claude o ajan için bir yönerge dosyası yazar. Eklenti başka bir şablon icat etmez.

Bir plan, özellik spesifikasyonunun yerini alır mı?

Hayır. Özellik README’si, gereksinimlerin ve kabul kriterlerinin kaynağıdır. Plan o özelliği görevlere ayırır ve her görev **Verifies:** ile geriye işaret eder. Plan spesifikasyonu ve görev spesifikasyonu bu ayrımın iki belgesidir.

Kaynaklar

Checkout özelliği, özellikler indeksi, spesifikasyon README’si ve specscore.yaml, 2 Kasım 2026’da specscore spec lint tarafından specscore 0.55.1 ile ve 0.39.1 ile kabul edildi. Plan ve görev örnekleri yayımlanmış spesifikasyonları izler ve o çalıştırmanın parçası değildi. Rakip sayfalar aşağıda bağlananlardır; spesifikasyon odaklı geliştirme araçları onları 30 Ekim 2026’da okunmuş olarak kaydeder, 28 Eylül 2026 basan Spec Kit belge ana sayfası dışında.