İş Akışları

Bu kılavuz, OpenSpec için yaygın iş akışı desenlerini ve her birinin ne zaman kullanılacağını kapsar. Temel kurulum için Başlarken bölümüne bakın. Komut referansı için Komutlar bölümüne bakın.

Felsefe: Eylemler, Aşamalar Değil

Geleneksel iş akışları sizi aşamalara zorlar: planlama, sonra uygulama, sonra tamamlanma. Ancak gerçek çalışma kutulara düzgünce sığmaz.

OPSX farklı bir yaklaşım benimser:

Geleneksel (faz kilitli):

  PLANLAMA ────────► UYGULAMA ────────► TAMAMLANDI
      │                    │
      │   "Geri dönülemez" │
      └────────────────────┘

OPSX (akışkan eylemler):

  proposal ──► specs ──► design ──► tasks ──► implement

Temel ilkeler:

• Eylemler, aşamalar değil - Komutlar, içine sıkışıp kaldığınız aşamalar değil, yapabileceğiniz şeylerdir
• Bağımlılıklar etkinleştiricidir - Sırada neyin yapılması gerektiğini değil, neyin mümkün olduğunu gösterirler

Özelleştirme: OPSX iş akışları, yapıt dizilerini tanımlayan şemalar tarafından yönlendirilir. Özel şemalar oluşturma hakkında ayrıntılar için Özelleştirme bölümüne bakın.

İş Akışına Genel Bakış

Varsayılan iş akışı esnek kalır: keşif ve doğrulama isteğe bağlıdır ve uygulama yeni bir şey ortaya çıkardığında planlama belgelerini güncelleyebilirsiniz.

flowchart TD
    Idea["Fikir veya sorun"] --> Explore["/opsx:explore<br/>(isteğe bağlı)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planlama belgeleri<br/>hazır mı?"}
    Review -->|"İyileştir"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Uygula"| Apply["/opsx:apply"]
    Apply -->|"Plan değişti"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(isteğe bağlı, özel seçim)"]
    Apply --> Sync["/opsx:sync<br/>(arşivlemeden önce isteğe bağlı)"]
    Verify --> Verified{"Arşivlemeye hazır mı?"}
    Verified -->|"Uygulamayı düzelt"| Apply
    Verified -->|"Planı revize et"| Update
    Verified -->|"Hazır"| Sync
    Verified -->|"Hazır"| Archive
    Sync --> Archive

AI asistanı iş akışını yönlendirirken, CLI deterministik iskelet, durum ve belge talimatları sağlar:

sequenceDiagram
    actor İnsan
    participant Asistan as AI asistanı
    participant CLI as OpenSpec CLI
    participant Dosyalar as Planlama ve uygulama dosyaları

    İnsan->>Asistan: /opsx:propose "değişiklik"
    Asistan->>CLI: openspec new change
    CLI->>Dosyalar: Değişiklik meta verilerini iskeletle
    Asistan->>CLI: Durum ve belge talimatları iste
    CLI-->>Asistan: Oluşturma sırası, yollar ve şablonlar
    Asistan->>Dosyalar: Şema tanımlı planlama belgelerini yaz
    Asistan-->>İnsan: İnceleme için belgeleri sun

    İnsan->>Asistan: /opsx:apply
    Asistan->>CLI: Uygulama talimatları iste
    CLI-->>Asistan: Bağlam dosyaları ve görev durumu
    Asistan->>Dosyalar: Görevleri uygula ve onay kutularını güncelle
    Asistan-->>İnsan: Uygulama durumunu raporla

    İnsan->>Asistan: /opsx:archive
    Asistan->>CLI: Arşiv girdileri ve belge durumu iste
    CLI-->>Asistan: Planlama yolları ve belge tamamlanma durumu
    Asistan->>Dosyalar: Görev durumunu oku ve delta spesifikasyonlarını karşılaştır
    opt Delta spesifikasyonları mevcut
        Asistan-->>İnsan: Arşivlemeden önce senkronize etmeyi teklif et
        alt Senkronizasyon kabul edildi
            İnsan->>Asistan: Senkronizasyonu onayla
            Asistan->>Dosyalar: Delta spesifikasyonlarını ana spesifikasyonlarla birleştir
        else Senkronizasyon atlandı
            İnsan->>Asistan: Senkronize etmeden arşivle
        end
    end
    Asistan->>Dosyalar: Değişikliği arşive taşı
    Asistan-->>İnsan: Arşiv konumunu ve senkronizasyon sonucunu raporla

    Not over İnsan,CLI: CLI alternatifi: openspec archive change-name --yes onay istemlerini atlar. Yine de doğrular, ardından delta spesifikasyonlarını uygular ve arşivler

İki Mod

Varsayılan Hızlı Yol (core profili)

Yeni kurulumlar core profilini varsayılan olarak kullanır ve şunları sağlar:

• /opsx:explore
• /opsx:propose
• /opsx:apply
• /opsx:update
• /opsx:sync
• /opsx:archive

Tipik akış:

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

Keşfederek başlayın (oluşturulmaya değer alışkanlık)

/opsx:explore varsayılan profilin bir parçasıdır, gelişmiş bir eklenti değil. Bir sorununuz olduğunda ancak henüz bir planınız yokken yapılacak harekettir; bir AI asistanı ile bu çoğu zaman geçerlidir.

Siz: /opsx:explore

AI:  Ne keşfetmek istersiniz?

Siz: Arama sonuçlarımız bayat görünüyor. Bunun önbellekleme mi,
     dizinleme mi yoksa sorgunun kendisi mi olduğundan emin değilim.

AI:  Bakayım... [arama hizmetini ve önbellek katmanını okur]
     Sorun dizin: yalnızca gece yeniden oluşturuluyor, bu yüzden düzenlemeler
     ertesi güne kadar görünmüyor. İki seçenek: yazmada yeniden oluştur (basit,
     daha fazla yük) veya kısa TTL'li önbellek geçersiz kılma (daha fazla hareketli parça,
     daha az yük). Yazma hacminiz düşük olduğundan, yazmada yeniden oluşturma
     daha temiz bir düzeltme. Kapsamını belirlemek ister misiniz?

Siz: Evet.

Siz: /opsx:propose rebuild-search-index-on-write

Keşif hiçbir belge oluşturmaz ve kod yazmaz. Belirsiz bir endişeyi kesin bir değişikliğe dönüştüren ücretsiz, risksiz bir konuşmadır; böylece ardından gelen öneri keskin olur. Tam olarak ne istediğinizi zaten biliyor musunuz? Bunu atlayın ve doğrudan /opsx:propose'a gidin. Tam kılavuz: Önce Keşfet.

Genişletilmiş/Tam İş Akışı (özel seçim)

Açık iskelet ve oluşturma komutları istiyorsanız (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), bunları şu şekilde etkinleştirin:

openspec config profile
openspec update

İş Akışı Desenleri (Genişletilmiş Mod)

Hızlı Özellik

Ne oluşturmak istediğinizi bildiğinizde ve yalnızca yürütmeniz gerektiğinde:

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Örnek konuşma:

Siz: /opsx:new add-logout-button

AI:  openspec/changes/add-logout-button/ oluşturuldu
     Oluşturulmaya hazır: proposal

Siz: /opsx:ff

AI:  Tüm planlama belgeleri oluşturuluyor...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Uygulamaya hazır!

Siz: /opsx:apply

AI:  Görevler üzerinde çalışılıyor...
     ✓ Başlığa çıkış düğmesi eklendi
     ✓ Oturum temizleme uygulandı
     ✓ Onay iletişim kutusu eklendi
     Tüm görevler tamamlandı!

Siz: /opsx:archive

AI:  ✓ Spesifikasyonlar birleştirildi
     ✓ Değişiklik arşivlendi

En uygun: Küçük ve orta ölçekli özellikler, hata düzeltmeleri, basit değişiklikler.

Keşif

Gereksinimler net olmadığında veya önce araştırmanız gerektiğinde:

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

Örnek konuşma:

Siz: /opsx:explore

AI:  Ne keşfetmek istersiniz?

Siz: Sayfa yükleme performansını iyileştirmek istiyorum ama darboğazların
     nerede olduğundan emin değilim.

AI:  Araştırmanıza yardımcı olayım...
     [Paket boyutlarını analiz eder, yavaş sorguları belirler, bileşen
     işleme desenlerini inceler]

     Üç ana darboğaz buldum:
     1. Büyük, optimize edilmemiş görseller
     2. ProductList içinde senkron veri getirme
     3. Bağlam değişikliklerinden kaynaklanan yeniden işlemeler

     Hangisini önce ele almak istersiniz?

Siz: Veri getirme sorununu ele alalım.

Siz: /opsx:new optimize-product-list-fetching

AI:  Değişiklik oluşturuldu. Oluşturulmaya hazır: proposal

Siz: /opsx:continue

AI:  Keşfimize dayalı öneri oluşturuluyor...
     [Araştırma içgörülerini içeren öneriyi yazıyor]

     Oluşturulmaya hazır: specs, design
     Sırada hangisini istersiniz?

Siz: /opsx:continue

AI:  Spesifikasyonlar oluşturuluyor...

En uygun: Performans optimizasyonu, hata ayıklama, mimari kararlar, net olmayan gereksinimler.

Paralel Değişiklikler

Aynı anda birden fazla değişiklik üzerinde çalışın:

Değişiklik A: /opsx:new ──► /opsx:ff ──► /opsx:apply (devam ediyor)
                                         │
                                    bağlam değişimi
                                         │
Değişiklik B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

Örnek konuşma:

Siz: add-dark-mode üzerinde çalışıyorum ama bir hata düzeltmesine çekildim

Siz: /opsx:new fix-login-redirect

AI:  openspec/changes/fix-login-redirect/ oluşturuldu

Siz: /opsx:ff

AI:  ✓ Planlama belgeleri oluşturuldu

Siz: /opsx:apply

AI:  fix-login-redirect üzerinde çalışılıyor...
     [Düzeltmeyi uygular]
     Tüm görevler tamamlandı!

Siz: /opsx:archive

AI:  ✓ fix-login-redirect arşivlendi

Siz: Karanlık moda geri dönelim

Siz: /opsx:apply add-dark-mode

AI:  add-dark-mode devam ediliyor...
     Görev 2.3'ten devam ediliyor: Header güncellenmesi...

En uygun: Paralel iş akışları, acil kesintiler, ekip işbirliği.

Tamamlanmış birden fazla değişikliğiniz olduğunda /opsx:bulk-archive kullanın:

Siz: /opsx:bulk-archive

AI:  3 tamamlanmış değişiklik bulundu:
     - add-dark-mode (tüm görevler tamam)
     - fix-login-redirect (tüm görevler tamam)
     - update-footer (tüm görevler tamam)

     Spesifikasyon çakışmaları kontrol ediliyor...
     ⚠ add-dark-mode ve update-footer her ikisi de specs/ui/ ile ilgilidir

     Çözüm için kod tabanı inceleniyor...
     Her iki değişiklik de uygulanmış. Kronolojik sırada uygulanacak.

     Üç değişikliği de arşivleyelim mi?

Siz: Evet

AI:  ✓ add-dark-mode arşivlendi
     ✓ fix-login-redirect arşivlendi
     ✓ update-footer arşivlendi
     Spesifikasyonlar sırayla birleştirildi: add-dark-mode → update-footer

Toplu arşivleme, birden çok değişikliğin aynı spesifikasyonlara dokunmasını algılar ve fiilen neyin uygulandığını kontrol ederek çakışmaları çözer.

Değişikliği Tamamlama

Önerilen tamamlama akışı:

/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              doğrular          gerekirse
              uygulamayı        senkronize etmeyi
                                önerir

Doğrula: Çalışmanızı Kontrol Edin

/opsx:verify, uygulamanızı belgelerinize karşı üç boyutta doğrular:

Siz: /opsx:verify

AI:  add-auth doğrulanıyor...

     TAMAMLIK
     ✓ tasks.md içindeki 12 görevin tümü işaretli
     ✓ Spesifikasyonlardaki tüm gereksinimlerin karşılık gelen kodu var
     ⚠ "Etkinlik sonrası oturum zaman aşımı" senaryosu test edilmedi

     DOĞRULUK
     ✓ Uygulama, spesifikasyonun amacıyla eşleşiyor
     ✓ Senaryolardan gelen uç durumlar ele alınıyor
     ✓ Hata durumları spesifikasyon tanımlarıyla eşleşiyor

     TUTARLILIK
     ✓ Tasarım kararları kod yapısına yansıtılmış
     ✓ Adlandırma kuralları design.md ile tutarlı
     ⚠ Tasarım "olay güdümlü" derken uygulama yoklama kullanıyor

     ÖZET
     ─────────────────────────────
     Kritik sorunlar: 0
     Uyarılar: 2
     Arşivlemeye hazır: Evet (uyarılarla)

     Öneriler:
     1. Oturum zaman aşımı senaryosu için test ekleyin
     2. Tasarıma uygun olarak olay güdümlü yeniden düşünmeyi değerlendirin veya design.md dosyasını güncelleyin

Doğrulama neyi kontrol eder:

Boyut	Ne doğrular
Tamamlık	Tüm görevler yapıldı, tüm gereksinimler uygulandı, senaryolar kapsandı
Doğruluk	Uygulama spesifikasyonun amacıyla eşleşiyor, uç durumlar ele alınıyor
Tutarlılık	Tasarım kararları koda yansıtılmış, desenler tutarlı

Doğrulama arşivlemeyi engellemez, ancak önce ele almak isteyebileceğiniz sorunları yüzeye çıkarır.

Arşivle: Değişikliği Sonlandırın

/opsx:archive, değişikliği tamamlar ve arşive taşır:

Siz: /opsx:archive

AI:  add-auth arşivleniyor...

     Belge durumu:
     ✓ proposal.md mevcut
     ✓ specs/ mevcut
     ✓ design.md mevcut
     ✓ tasks.md mevcut (12/12 görev tamam)

     Delta spesifikasyonları: Ana spesifikasyonlarla henüz senkronize edilmedi
     → Şimdi senkronize etmek ister misiniz?

Siz: Evet

AI:  ✓ Spesifikasyonlar openspec/specs/auth/spec.md dosyasına senkronize edildi
     ✓ openspec/changes/archive/2025-01-24-add-auth/ konumuna taşındı

     Değişiklik başarıyla arşivlendi.

Arşivleme, spesifikasyonlar senkronize edilmediyse sorar. Tamamlanmamış görevlerde engellemez, ancak sizi uyarır.

Ne Zaman Ne Kullanılır

/opsx:ff vs /opsx:continue

Durum	Kullan
Net gereksinimler, oluşturmaya hazır	/opsx:ff
Keşif yapıyor, her adımı gözden geçirmek istiyor	/opsx:continue
Spesifikasyonlardan önce öneri üzerinde yineleme yapmak istiyor	/opsx:continue
Zaman baskısı, hızlı ilerleme gerekiyor	/opsx:ff
Karmaşık değişiklik, kontrol istiyor	/opsx:continue

Genel kural: Tam kapsamı baştan tanımlayabiliyorsanız /opsx:ff kullanın. Yol boyunca çözüyorsanız /opsx:continue kullanın.

Güncelleme vs Baştan Başlama Ne Zaman

Sık sorulan bir soru: mevcut bir değişikliği güncellemek ne zaman uygundur ve ne zaman yeni bir tane başlatmalısınız?

Aşağıdaki durumlarda mevcut değişikliği güncelleyin:

• Aynı amaç, iyileştirilmiş yürütme
• Kapsam daralır (önce MVP, sonra geri kalan)
• Öğrenmeye dayalı düzeltmeler (kod tabanı beklediğiniz gibi değil)
• Uygulama keşiflerine dayalı tasarım ayarlamaları

Aşağıdaki durumlarda yeni bir değişiklik başlatın:

• Amaç temelden değişti
• Kapsam tamamen farklı bir işe patladı
• Orijinal değişiklik bağımsız olarak "tamamlandı" olarak işaretlenebilir
• Yamalar kafa karıştırmaktan çok netleştirmez

                     ┌─────────────────────────────────────┐
                     │     Bu aynı iş mi?                  │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Amaç aynı mı?      >%50 örtüşme var mı?    Orijinal, bu
          Sorun aynı mı?      Kapsam aynı mı?         değişiklikler olmadan
                 │                  │                  "tamam" olabilir mi?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      EVET              HAYIR EVET         HAYIR  HAYIR         EVET
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    GÜNCELLE          YENİ  GÜNCELLE     YENİ  GÜNCELLE      YENİ

Örnek: "Karanlık mod ekle"

• "Ayrıca özel temaları da desteklememiz gerekiyor" → Yeni değişiklik (kapsam patladı)
• "Sistem tercihi algılaması beklediğimden zor" → Güncelleme (aynı amaç)
• "Önce anahtarı gönderelim, tercihleri sonra ekleyelim" → Güncelle, ardından arşivle, sonra yeni değişiklik

En İyi Uygulamalar

Değişiklikleri Odaklı Tutun

Her değişiklik için bir mantıksal iş birimi. Eğer "X özelliğini ekle ve aynı zamanda Y'yi yeniden düzenle" yapıyorsan, iki ayrı değişiklik olarak düşün.

Neden önemlidir:

• İncelenmesi ve anlaşılması daha kolay
• Daha temiz bir arşiv geçmişi
• Bağımsız olarak yayınlanabilir
• Gerekirse geri alma daha basit

Belirsiz Gereksinimler için /opsx:explore Kullanın

Bir değişiklik yapmaya başlamadan önce, sorun alanını keşfedin:

You: /opsx:explore

AI:  Neyi keşfetmek istersiniz?

You: API'mız için hız sınırlandırmasını nasıl ele almalıyız?

AI:  Mevcut kurulumunuzu ve seçenekleri araştırayım...
     [Kod tabanını araştırır, desenleri dikkate alır]

     Görebildiğim kadarıyla üç yaklaşım var:
     1. Middleware tabanlı (basit, uç nokta başına)
     2. Redis destekli (ölçeklenebilir, paylaşılan durum)
     3. Kullanıcı başına token kovası (adil, karmaşık)

     Mevcut yığınınız #1 veya #2'yi öneriyor. Ölçeğiniz nedir?

Keşif, artifact'lerinizi oluşturmadan önce düşünmeyi netleştirir.

Arşivlemeden Önce Doğrulayın

Uygulamanın artifact'lerle eşleştiğini kontrol etmek için /opsx:verify kullanın:

You: /opsx:verify

AI:  add-dark-mode doğrulanıyor...

     ✓ tasks.md'deki tüm görevler işaretlendi
     ✓ spec'lerdeki gereksinimlerin karşılık gelen kodu var
     ✓ Tasarım kararları uygulamaya yansıtılmış

     Arşivlenmeye hazır!

Değişikliği kapatmadan önce uyumsuzlukları yakalar.

Değişiklikleri Açıkça Adlandırın

İyi adlar openspec list komutunu faydalı kılar:

İyi:                           Kaçınılacak:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

Komut Hızlı Referansı

Tüm komut detayları ve seçenekler için Commands sayfasına bakın.

Komut	Amaç	Kullanım Zamanı
/opsx:propose	Değişiklik + planlama artifact'leri oluştur	Hızlı varsayılan yol (core profili)
/opsx:explore	Yapay zeka ile fikirleri düşünerek değerlendir	Emin olmadığınızda buradan başlayın: belirsiz gereksinimler, araştırma, seçenekleri karşılaştırma
/opsx:new	Değişiklik iskeleti başlat	Genişletilmiş mod, açık artifact kontrolü
/opsx:continue	Sonraki artifact'i oluştur	Genişletilmiş mod, adım adım artifact oluşturma
/opsx:ff	Tüm planlama artifact'lerini oluştur	Genişletilmiş mod, net kapsam
/opsx:apply	Görevleri uygula	Kod yazmaya hazır
/opsx:verify	Uygulamayı doğrula	Genişletilmiş mod, arşivlemeden önce
/opsx:sync	Delta spec'leri birleştir	Genişletilmiş mod, isteğe bağlı
/opsx:archive	Değişikliği tamamla	Tüm iş bitti
/opsx:bulk-archive	Birden çok değişikliği arşivle	Genişletilmiş mod, paralel çalışma

Sonraki Adımlar

• İyi Spec'ler Yazmak - Güçlü bir gereksinim ve senaryonun nasıl göründüğü ve bir değişikliğin kapsamının nasıl doğru belirleneceği
• Bir Değişikliği İncelemek - Kod yazmadan önce taslak plan üzerinde iki dakikalık bir geçiş
• Ekip Olarak OpenSpec - Değişikliklerin dallara ve çekme isteklerine nasıl uyduğu
• Komutlar - Seçenekleriyle birlikte tam komut referansı
• Kavramlar - Spec'ler, artifact'ler ve şemalara derinlemesine bakış
• Özelleştirme - Özel iş akışları oluşturma