OpenSpec

Başlangıç ​

Bu kılavuz, OpenSpec'i kurup başlattıktan sonra nasıl çalıştığını açıklar. Kurulum talimatları için ana README veya Kurulum kılavuzu sayfasına bakın. Tüm dokümantasyon setine yeni mi? Dokümantasyon ana sayfası her şeyi haritalandırır.

Bu komutları nereye yazacağım? İki yer var ve bunları karıştırmak en yaygın başlangıç hatasıdır.

  • openspec ... komutları (ör. openspec init) terminalinizde çalışır.
  • /opsx:... komutları (ör. /opsx:propose) AI asistanınızın sohbet penceresinde çalışır; yani ona kod yazmasını istediğiniz aynı kutu.

Başlatmanız gereken ayrı bir "etkileşimli mod" yoktur. Sadece sohbet penceresinde slash komutunu yazarsınız ve asistanınız oradan devam eder. Tam açıklama: Komutlar Nasıl Çalışır.

İlk Beş Dakikanız ​

Her adımın nerede gerçekleştiği etiketlenmiş tam döngü:

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (isteğe bağlı: önce düşünün)
AI CHAT      /opsx:propose add-dark-mode      (AI planı taslaklar; siz inceler)
AI CHAT      /opsx:apply                      (AI inşa eder)
AI CHAT      /opsx:archive                    (spesifikasyonlar güncellenir, değişiklik arşivlenir)

Kurulum için iki terminal adımı, ardından sohbet penceresinde devam edersiniz. Bu kılavuzun geri kalanı her adımın ne yaptığını ve ne göreceğinizi açıklar.

Terminal kısmını kendiniz yapmak istemiyor musunuz? Kurulum istemini asistanınıza yapıştırın; iki satırı da halleder ve oluşturduklarını raporlar.

Ne inşa edeceğinize henüz emin değil misiniz? /opsx:explore ile başlayın. Hiçbir riski olmayan bir düşünce ortağıdır; kod tabanınızı okur, seçenekleri tartar ve bulanık bir fikri somut bir plana dönüştürür — tüm bunlar herhangi bir artefakt veya kod var olmadan. Resim netleştiğinde /opsx:propose'a devreder. AI ile çalışırken yanlış şeyi güvenle inşa etmesini önlemek için en iyi alışkanlık budur. Explore kılavuzuna bakın.

Nasıl Çalışır ​

OpenSpec, herhangi bir kod yazılmadan önce siz ve AI kodlama asistanınızın ne inşa edileceğinde anlaşmanıza yardımcı olur.

Varsayılan hızlı yol (core profili):

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (isteğe bağlı)

Ne yapacağınızı araştırırken /opsx:explore ile başlayın veya zaten biliyorsanız doğrudan /opsx:propose'a atlayın. Explore varsayılan profildedir, bu yüzden istediğinizde her zaman oradadır.

Genişletilmiş yol (özel iş akışı seçimi):

text
/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Varsayılan global profil core'dur ve propose, explore, apply, update, sync ile archive komutlarını içerir. Genişletilmiş iş akışı komutlarını openspec config profile ile etkinleştirip ardından openspec update çalıştırarak kullanabilirsiniz.

OpenSpec Ne Oluşturur ​

openspec init çalıştırdıktan sonra projenizde bu yapı oluşur:

openspec/
├── specs/              # Gerçeklik kaynağı (sisteminizin davranışı)
│   └── <domain>/
│       └── spec.md
├── changes/            # Önerilen güncellemeler (değişiklik başına bir klasör)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta spesifikasyonlar (ne değişiyor)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Proje yapılandırması (isteğe bağlı)

İki ana dizin:

  • specs/ - Gerçeklik kaynağı. Bu spesifikasyonlar sisteminizin şu an nasıl davrandığını açıklar. Alan bazında düzenlenir (ör. specs/auth/, specs/payments/).

  • changes/ - Önerilen değişiklikler. Her değişikliğin tüm ilgili artefaktlarıyla kendi klasörü vardır. Bir değişiklik tamamlandığında spesifikasyonları ana specs/ dizinine birleştirilir.

Artefaktları Anlama ​

Her değişiklik klasörü, çalışmayı yönlendiren artefaktlar içerir:

ArtefaktAmaç
proposal.md"Neden" ve "ne" — niyeti, kapsamı ve yaklaşımı yakalar
specs/EKLENEN/DEĞİŞTİRİLEN/KALDIRILAN gereksinimleri gösteren delta spesifikasyonlar
design.md"Nasıl" — teknik yaklaşım ve mimari kararlar
tasks.mdOnay kutularıyla uygulama kontrol listesi

Artefaktlar birbirinin üzerine inşa edilir:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            öğendikçe güncelle

Uygulama sırasında daha fazla öğendikçe her zaman önceki artefaktlara dönüp onları iyileştirebilirsiniz.

Delta Spesifikasyonlar Nasıl Çalışır ​

Delta spesifikasyonlar OpenSpec'in ana kavramıdır. Mevcut spesifikasyonlarınıza göre ne değiştiğini gösterirler.

Biçim ​

Delta spesifikasyonlar değişiklik türünü belirtmek için bölümler kullanır:

markdown
# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

Arşivlemede Ne Olur ​

Bir değişikliği arşivlediğinizde:

  1. EKLENEN gereksinimler ana spesifikasyona eklenir
  2. DEĞİŞTİRİLEN gereksinimler mevcut sürümün yerine geçer
  3. KALDIRILAN gereksinimler ana spesifikasyondan silinir

Değişiklik klasörü denetim geçmişi için openspec/changes/archive/ dizinine taşınır.

Örnek: İlk Değişikliğiniz ​

Bir uygulamaya koyu mod eklemeyi adım adım ele alalım.

1. Değişikliği Başlat (Varsayılan) ​

text
You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

Genişletilmiş iş akışı profilini etkinleştirdiyseniz bunu iki adımda da yapabilirsiniz: /opsx:new ardından /opsx:ff (veya kademeli olarak /opsx:continue).

2. Ne Oluşturulur ​

proposal.md - Niyeti yakalar:

markdown
# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

specs/ui/spec.md - Yeni gereksinimleri gösteren delta:

markdown
# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

tasks.md - Uygulama kontrol listesi:

markdown
# 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

## 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. Uygula ​

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

Uygulama sırasında tasarımın ayarlama gerektirdiğini fark ederseniz, sadece artefaktı güncelleyip devam edin.

4. Arşivle ​

You: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

Delta spesifikasyonlarınız artık ana spesifikasyonların bir parçası ve sisteminizin nasıl çalıştığını belgelemektedir.

Doğrulama ve İnceleme ​

Değişikliklerinizi kontrol etmek için CLI'ı kullanın:

bash
# Aktif değişiklikleri listele
openspec list

# Değişiklik detaylarını görüntüle
openspec show add-dark-mode

# Spesifikasyon biçimlendirmesini doğrula
openspec validate add-dark-mode

# Etkileşimli gösterge paneli
openspec view

Sonraki Adımlar ​