Kavramlar
Bu rehber, OpenSpec'in temel kavramlarını ve bu kavramların nasıl bir arada çalıştığını açıklar. Pratik kullanım için Başlangıç ve İş Akışları bölümlerine bakın.
Felsefe
OpenSpec, dört ilke etrafında inşa edilmiştir:
fluid not rigid — no phase gates, work on what makes sense
iterative not waterfall — learn as you build, refine as you go
easy not complex — lightweight setup, minimal ceremony
brownfield-first — works with existing codebases, not just greenfieldBu İlkeler Neden Önemli
Akışkan, katı değil. Geleneksel spesifikasyon sistemleri sizi fazlara kilitleyebilir: önce planlarsınız, ardından uygularsınız ve iş biter. OpenSpec daha esnektir — işiniz için mantıklı olan herhangi bir sırayla artefakt oluşturabilirsiniz.
İteratif, şelale değil. Gereksinimler değişir. Anlayış derinleşir. Başlangıçta iyi görünen bir yaklaşım, kod tabanını gördükten sonra geçerliliğini yitirebilir. OpenSpec bu gerçeği benimser.
Basit, karmaşık değil. Bazı spesifikasyon çerçeveleri kapsamlı kurulum, katı formatlar veya ağır süreçler gerektirir. OpenSpec önünüze engel olmaz. Saniyeler içinde başlatın, hemen çalışmaya başlayın, yalnızca ihtiyacınız varsa özelleştirin.
Brownfield öncelikli. Yazılım geliştirme çalışmalarının çoğu sıfırdan inşa etmek değil, mevcut sistemleri değiştirmektir. OpenSpec'in delta tabanlı yaklaşımı, yeni sistemleri açıklamak yerine mevcut davranışlardaki değişiklikleri belirtmeyi kolaylaştırır.
Genel Bakış
OpenSpec, çalışmalarınızı iki ana alana organize eder:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Source of truth │◄─────│ Proposed modifications │ │
│ │ How your system │ merge│ Each change = one folder │ │
│ │ currently works │ │ Contains artifacts + deltas │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specs (spesifikasyonlar) doğruluk kaynağıdır — sisteminizin şu anki davranışını tanımlarlar.
Changes (değişiklikler) önerilen değişikliklerdir — birleştirmeye hazır olana kadar ayrı klasörlerde tutulurlar.
Bu ayrım çok önemlidir. Çakışma olmadan birden fazla değişiklikle paralel çalışabilirsiniz. Bir değişikliği ana spesifikasyonları etkilemeden önce inceleyebilirsiniz. Ve bir değişikliği arşivlediğinizde, delta'ları doğruluk kaynağına sorunsuz bir şekilde birleşir.
Spesifikasyonlar
Spesifikasyonlar, sisteminizin davranışını yapılandırılmış gereksinimler ve senaryolar kullanarak tanımlar.
Yapı
openspec/specs/
├── auth/
│ └── spec.md # Kimlik doğrulama davranışı
├── payments/
│ └── spec.md # Ödeme işleme
├── notifications/
│ └── spec.md # Bildirim sistemi
└── ui/
└── spec.md # Arayüz davranışı ve temalarSpesifikasyonları alan bazında organize edin — sisteminiz için mantıklı olan gruplamalar. Yaygın kalıplar:
- Özellik alanına göre:
auth/,payments/,search/ - Bileşene göre:
api/,frontend/,workers/ - Sınırlı bağlama göre:
ordering/,fulfillment/,inventory/
Spesifikasyon Formatı
Bir spesifikasyon gereksinimler içerir ve her gereksinimin senaryoları vardır:
# Auth Specification
## Purpose
Authentication and session management for the application.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.
#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued
### Requirement: Session Expiration
The system MUST expire sessions after 30 minutes of inactivity.
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticateTemel unsurlar:
| Unsur | Amaç |
|---|---|
## Purpose | Bu spesifikasyonun alanının yüksek düzeyde tanımı |
### Requirement: | Sistemin sahip olması gereken belirli bir davranış |
#### Scenario: | Gereksinimin uygulamadaki somut bir örneği |
| SHALL/MUST/SHOULD | Gereksinim gücünü gösteren RFC 2119 anahtar kelimeleri |
Spesifikasyonları Bu Şekilde Yapılandırma Nedeniyle
Gereksinimler "ne"dir — sistemin ne yapması gerektiğini uygulama detaylarını belirtmeden ifade ederler.
Senaryolar "ne zaman"ıdır — doğrulanabilir somut örnekler sağlarlar. İyi senaryolar:
- Test edilebilir (onlar için otomatik bir test yazabilirsiniz)
- Hem başarılı yolu hem de kenar durumlarını kapsar
- Given/When/Then veya benzeri yapılandırılmış format kullanır
RFC 2119 anahtar kelimeleri (SHALL, MUST, SHOULD, MAY) niyeti iletir:
- MUST/SHALL — mutlak gereksinim
- SHOULD — önerilir, ancak istisnalar mevcuttur
- MAY — isteğe bağlı
Spesifikasyon Nedir (ve Ne Değildir)
Bir spesifikasyon bir davranış sözleşmesidir, uygulama planı değildir.
İyi spesifikasyon içeriği:
- Kullanıcıların veya aşağı akış sistemlerinin güvendiği gözlemlenebilir davranışlar
- Girdiler, çıktılar ve hata koşulları
- Dış kısıtlamalar (güvenlik, gizlilik, güvenilirlik, uyumluluk)
- Test edilebilir veya açıkça doğrulanabilir senaryolar
Spesifikasyonlarda kaçınılması gerekenler:
- Dahili sınıf/fonksiyon adları
- Kütüphane veya çerçeve seçimleri
- Adım adım uygulama detayları
- Detaylı uygulama planları (bunlar
design.mdveyatasks.mddosyalarına aittir)
Hızlı test:
- Uygulama, dışarıdan görünen davranışı değiştirmeden değişebiliyorsa, muhtemelen spesifikasyona ait değildir.
Hafif Tutun: Kademeli Katılık
OpenSpec bürokrasiden kaçınmayı hedefler. Değişikliği doğrulanabilir kılan en hafif seviyeyi kullanın.
Lite spesifikasyon (varsayılan):
- Kısa, davranış odaklı gereksinimler
- Net kapsam ve kapsam dışı hedefler
- Birkaç somut kabul kontrolü
Tam spesifikasyon (daha yüksek risk için):
- Ekipler arası veya depolar arası değişiklikler
- API/sözleşme değişiklikleri, migrasyonlar, güvenlik/gizlilik endişeleri
- Belirsizliğin pahalı yeniden çalışmaya yol açma olasılığı olan değişiklikler
Çoğu değişiklik Lite modda kalmalıdır.
İnsan + Ajan İş Birliği
Birçok ekipte insanlar keşfeder ve ajanlar artefaktları taslaklar. Planlanan döngü şudur:
- İnsan niyet, bağlam ve kısıtlamaları sağlar.
- Ajan bunu davranış odaklı gereksinimlere ve senaryolara dönüştürür.
- Ajan uygulama detaylarını
design.mdvetasks.mdiçinde tutar,spec.mdiçinde değil. - Doğrulama, uygulama öncesinde yapıyı ve netliği onaylar.
Bu, spesifikasyonları insanlar için okunabilir ve ajanlar için tutarlı tutar.
Değişiklikler
Bir değişiklik, sisteminize önerilen bir değişikliktir ve onu anlamak ve uygulamak için gereken her şeyi içeren bir klasör olarak paketlenir.
Değişiklik Yapısı
openspec/changes/add-dark-mode/
├── proposal.md # Neden ve ne
├── design.md # Nasıl (teknik yaklaşım)
├── tasks.md # Uygulama kontrol listesi
├── .openspec.yaml # Değişiklik meta verisi (isteğe bağlı): schema, created, skip_specs, retire_capabilities
└── specs/ # Delta spesifikasyonlar
└── ui/
└── spec.md # ui/spec.md'de ne değişiyorHer değişiklik kendi kendine yeterlidir. İçeriği:
- Artefaktlar — niyeti, tasarımı ve görevleri yakalayan belgeler
- Delta spesifikasyonlar — eklenen, değiştirilen veya kaldırılanların spesifikasyonları
- Meta veri — bu spesifik değişiklik için isteğe bağlı yapılandırma
Değişiklikler Neden Klasörlerdir
Bir değişikliği klasör olarak paketlemenin birkaç avantajı vardır:
Her şey bir arada. Öneri, tasarım, görevler ve spesifikasyonlar tek bir yerde tutulur. Farklı konumlar arasında arama yapmanıza gerek kalmaz.
Paralel çalışma. Birden fazla değişiklik çakışmadan eş zamanlı var olabilir.
add-dark-modeüzerinde çalışırkenfix-auth-bugda devam ediyor olabilir.Temiz geçmiş. Arşivlendiğinde, değişiklikler tüm bağlamları korunarak
changes/archive/dizinine taşınır. Geriye dönüp sadece ne değiştiğini değil, neden değiştiğini de anlayabilirsiniz.İncelemeye uygun. Bir değişiklik klasörü incelemesi kolaydır — açın, öneriyi okuyun, tasarımı kontrol edin, spesifikasyon delta'larını görün.
Artefaktlar
Artefaktlar, bir değişiklik içindeki çalışmayı yönlendiren belgelerdir.
Artefakt Akışı
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
why what how steps
+ scope changes approach to takeArtefaktlar birbirinin üzerine inşa edilir. Her artefakt sonraki için bağlam sağlar.
Artefakt Türleri
Öneri (proposal.md)
Öneri, niyeti, kapsamı ve yaklaşımı yüksek düzeyde yakalar.
# Proposal: Add Dark Mode
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.
## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage
Out of scope:
- Custom color themes (future work)
- Per-page theme overrides
## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.Öneriyi ne zaman güncellemelisiniz:
- Kapsam değişikliği (daraltma veya genişletme)
- Niyet netleştiğinde (sorunun daha iyi anlaşılması)
- Yaklaşım temel olarak değiştiğinde
Spesifikasyonlar (specs/ içindeki delta spesifikasyonlar)
Delta spesifikasyonlar, mevcut spesifikasyonlara göre ne değiştiğini tanımlar. Aşağıdaki Delta Spesifikasyonlar bölümüne bakın.
Tasarım (design.md)
Tasarım, teknik yaklaşımı ve mimari kararları yakalar.
# Design: Add Dark Mode
## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.
## Architecture Decisions
### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency
### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution
## Data Flow
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)Tasarımı ne zaman güncellemelisiniz:
- Uygulama, yaklaşımın işe yaramayacağını ortaya koyduğunda
- Daha iyi bir çözüm keşfedildiğinde
- Bağımlılıklar veya kısıtlamalar değiştiğinde
Görevler (tasks.md)
Görevler, uygulama kontrol listesidir — onay kutularıyla somut adımlar.
# Tasks
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
- [ ] 1.4 Add system preference detection
## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle
## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
- [ ] 3.3 Test contrast ratios for accessibilityGörev en iyi uygulamaları:
- İlgili görevleri başlıklar altında gruplayın
- Hiyerarşik numaralandırma kullanın (1.1, 1.2 vb.)
- Görevleri tek bir oturumda tamamlanabilecek kadar küçük tutun
- Tamamladıkça görevleri işaretleyin
Delta Spesifikasyonlar
Delta spesifikasyonlar, OpenSpec'in mevcut geliştirme (brownfield) için çalışmasını sağlayan temel kavramdır. Tüm spesifikasyonu yeniden ifade etmek yerine ne değiştiğini tanımlarlar.
Format
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.
#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation
#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP
## MODIFIED Requirements
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated
## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)Delta Bölümleri
| Bölüm | Anlamı | Arşivlemede Ne Olur |
|---|---|---|
## ADDED Requirements | Yeni davranış | Ana spesifikasyona eklenir |
## MODIFIED Requirements | Değişen davranış | Mevcut gereksinimi değiştirir |
## REMOVED Requirements | Eski davranış | Ana spesifikasyondan silinir; son gereksinimin kaldırılması yeteneği emekliye ayırır ve spesifikasyon dosyasını siler, değişiklik retire_capabilities: true beyan ettiğinde |
## Purpose | Tamamen yeni bir yeteneğin amacı | Oluşturulan ana spesifikasyonun Purpose alanını tohumlar; spesifikasyon zaten mevcut olduğunda yok sayılır |
Delta'lar Neden Tam Spesifikasyon Yerine
Netlik. Delta tam olarak ne değiştiğini gösterir. Tam spesifikasyon okursanız, mevcut sürümle zihinsel olarak karşılaştırmanız gerekir.
Çakışma önleme. İki değişiklik aynı spesifikasyon dosyasına dokunabilir ama farklı gereksinimleri değiştiriyorlarsa çakışma olmaz.
İnceleme verimliliği. İnceleyiciler değişimi görür, değişmeyen bağlamı değil. Önemli olan şeylere odaklanın.
Mevcut geliştirme uyumu. Çoğu çalışma mevcut davranışı değiştirir. Delta'lar değişiklikleri birincil sınıf yapar, sonradan eklenen bir düşünce değil.
Schemalar
Schemalar, bir iş akışının artefakt türlerini ve bağımlılıklarını tanımlar.
Schemalar Nasıl Çalışır
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # Bağımlılık yok, ilk oluşturulabilir
- id: specs
generates: specs/**/*.md
requires: [proposal] # Oluşturmadan önce proposal gerekli
- id: design
generates: design.md
requires: [proposal] # specs ile paralel oluşturulabilir
- id: tasks
generates: tasks.md
requires: [specs, design] # Önce hem specs hem de design gerekliArtefaktler bir bağımlılık grafiği oluşturur:
proposal
(kök düğüm)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)Bağımlılıklar kapı değil, olanak sağlar. Ne oluşturulabileceğini gösterir, sıradaki ne oluşturulması gerektiğini değil. Gerekmiyorsa design adımını atlayabilirsiniz. specs'i design'dan önce veya sonra oluşturabilirsiniz — her ikisi de yalnızca proposal'a bağımlıdır.
Yerleşik Schemalar
spec-driven (varsayılan)
Spec odaklı geliştirme için standart iş akışı:
proposal → specs → design → tasks → implementEn uygun olduğu durumlar: Uygulama öncesinde spec'ler üzerinde anlaşmak istediğiniz çoğu özellik geliştirme işi.
Özel Schemalar
Ekip iş akışınız için özel schemalar oluşturun:
# Sıfırdan oluşturun
openspec schema init research-first
# Veya mevcut birini çatallayın
openspec schema fork spec-driven research-firstÖzel schema örneği:
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # Önce araştırma yapın
- id: proposal
generates: proposal.md
requires: [research] # Araştırmadan beslenen proposal
- id: tasks
generates: tasks.md
requires: [proposal] # specs/design atlanır, doğrudan tasks'a geçilirÖzel schemalar oluşturma ve kullanma hakkında tüm detaylar için Özelleştirme sayfasına bakın.
Arşivleme
Arşivleme, bir değişikliğin delta spec'lerini ana spec'lere birleştirerek ve değişikliği geçmiş için koruyarak tamamlar.
Arşivlediğinizde Ne Olur
Arşivleme öncesi:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ birleştirme
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
Arşivleme sonrası:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Artık 2FA gereksinimlerini içerir
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Geçmiş için korunur
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdArşivleme Süreci
Deltaları birleştir. Her delta spec bölümü (ADDED/MODIFIED/REMOVED), karşılık gelen ana spec'e uygulanır.
Arşive taşı. Değişiklik klasörü, kronolojik sıralama için tarih öneki ile
changes/archive/dizinine taşınır.Bağlamı koru. Tüm artefaktler arşivde olduğu gibi kalır. Bir değişikliğin neden yapıldığını her zaman geriye dönüp anlayabilirsiniz.
Arşivleme Neden Önemlidir
Temiz durum. Aktif değişiklikler (changes/) yalnızca devam eden işleri gösterir. Tamamlanan işler yolun dışına taşınır.
Denetim izi. Arşiv, her değişikliğin tam bağlamını korur — yalnızca ne değiştiği değil, neden değiştiğini açıklayan proposal, nasıl değiştiğini açıklayan design ve yapılan işi gösteren tasks.
Spec evrimi. Spec'ler, değişiklikler arşivlendikçe organik olarak büyür. Her arşivleme, deltalarını birleştirerek zaman içinde kapsamlı bir spesifikasyon oluşturur.
Her Şey Nasıl Bir Arada Çalışır
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC AKIŞI │
│ │
│ ┌────────────────┐ │
│ │ 1. DEĞİŞİKLİK │ /opsx:propose (çekirdek) veya /opsx:new (genişletilmiş) │
│ │ BAŞLAT │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. ARTEFAKT │ /opsx:ff veya /opsx:continue (genişletilmiş iş akışı) │
│ │ OLUŞTUR │ proposal → specs → design → tasks oluşturur │
│ │ │ (schema bağımlılıklarına göre) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. GÖREVLERİ │ /opsx:apply │
│ │ UYGULA │ Görevleri işleyin, işaretleyin │
│ │ │◄──── Öğrendikçe artefaktleri güncelleyin │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. İŞİ DOĞRULA│ /opsx:verify (isteğe bağlı) │
│ │ │ Uygulamanın spec'lerle uyumlu olduğunu kontrol edin │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. DEĞİŞİKLİK │────►│ Delta spec'ler ana spec'lere birleşir │ │
│ │ ARŞİVLE │ │ Değişiklik klasörü archive/ dizinine taşınır│ │
│ └────────────────┘ │ Spec'ler artık güncel doğruluk kaynağıdır │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘Erdemli döngü:
- Spec'ler mevcut davranışı tanımlar
- Değişiklikler modifikasyonlar önerir (delta olarak)
- Uygulama değişiklikleri gerçeğe dönüştürür
- Arşivleme deltaları spec'lere birleştirir
- Spec'ler artık yeni davranışı tanımlar
- Sonraki değişiklik güncellenmiş spec'ler üzerine inşa edilir
Sözlük
| Terim | Tanım |
|---|---|
| Artefakt | Bir değişiklik içindeki belge (proposal, design, tasks veya delta spec'ler) |
| Arşivleme | Bir değişikliği tamamlayıp deltalarını ana spec'lere birleştirme süreci |
| Değişiklik | Sisteme önerilen bir modifikasyon, artefaktlerle birlikte klasör olarak paketlenir |
| Delta spec | Mevcut spec'lere göre değişiklikleri (ADDED/MODIFIED/REMOVED) tanımlayan spec |
| Domain | Spec'ler için mantıksal gruplama (ör. auth/, payments/) |
| Gereksinim | Sistemin sahip olması gereken belirli bir davranış |
| Senaryo | Bir gereksinimin somut örneği, genellikle Given/When/Then formatında |
| Schema | Artefakt türlerinin ve bağımlılıklarının tanımı |
| Spec | Sistem davranışını tanımlayan, gereksinimler ve senaryolar içeren spesifikasyon |
| Doğruluk kaynağı | Mevcut üzerinde anlaşmaya varılan davranışı içeren openspec/specs/ dizini |
Sonraki Adımlar
- Başlangıç - Pratik ilk adımlar
- İş Akışları - Yaygın kalıplar ve her birinin ne zaman kullanılacağı
- Komutlar - Tam komut referansı
- Özelleştirme - Özel schemalar oluşturma ve projenizi yapılandırma