Örnekler ve Tarifler

Gerçek değişiklikler, baştan sona. Her tarif, yazacağınız komutları ve geri alacağınız çıktıları gösterir; böylece durumunuza uygun bir kalıbı bulup kopyalayabilirsiniz. Bunlar varsayılan core komutlarını (propose, explore, apply, update, sync, archive) kullanır; genişletilmiş komut seti işe yaradığında belirtilir.

Başlamadan önce bir hatırlatma: /opsx:propose gibi slash komutları AI asistanınızın sohbetine yazılır, openspec komutları ise terminalinize. Eğer bu yeni bir şeyse, önce Komutlar Nasıl Çalışır sayfasını okuyun. Aşağıdaki transkriptlerde You: ve AI: satırları sohbeti, $ ile başlayan satırlar ise terminali temsil eder.

Ne inşa ettiğinize henüz emin değil misiniz? Bu tariflerin çoğu, önce /opsx:explore ile düşünerek başlarsanız daha keskin hale gelir. Tarif 3 bunu uygulamada gösterir ve Önce Keşfet rehberi tam gerekçeyi sunar.

Tarif 1: Küçük bir özellik, hızlı yol

Ne zaman kullanılır: Ne istediğinizi biliyorsunuz ve sınırlı bir iş parçası söz konusu. Bu en yaygın tarif.

Bütün işlem üç komut. Öner, inşa et, arşivle.

You: /opsx:propose add-logout-button

AI:  Created openspec/changes/add-logout-button/
     ✓ proposal.md — why and what
     ✓ specs/      — the new requirement and its scenarios
     ✓ design.md   — technical approach
     ✓ tasks.md    — implementation checklist
     Ready for implementation. Run /opsx:apply.

Şimdi planı okuyun. Öneriyi ve delta spec'i açın. Bu, OpenSpec'in tasarlandığı an: yanlış bir varsayımı hâlâ bir paragrafken yakalamak, 400 satır kod yazdıktan sonra değil. Bir şey ters gittiyse herhangi bir artefaktı doğrudan düzenleyin, sonra devam edin.

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Add logout button to header
     ✓ 1.2 Clear session on click
     ✓ 1.3 Add confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  Archiving add-logout-button...
     ✓ Merged specs into openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
     Done. Ready for the next change.

Bu kadar. Çıkış davranışı artık spec'lerinizin bir parçası ve değişiklik tüm bağlamıyla arşivlendi.

Tarif 2: Bir hata düzeltmesi

Ne zaman kullanılır: Bir şey bozuk ve düzeltmeyi davranışa bilinçli bir değişiklik olarak kaydetmek istiyorsunuz, gizemli bir commit değil.

Hata düzeltmeleri özelliklerle birebir aynı şekilde çalışır. Fark, öneriyi nasıl çerçevelediğinizde: doğru davranışı tanımlayın, sadece "hatayı düzelt" demeyin.

You: /opsx:propose fix-login-redirect-loop

AI:  Created openspec/changes/fix-login-redirect-loop/
     The proposal captures the current broken behavior and the
     intended behavior. The delta spec MODIFIES the redirect
     requirement so it's now precise and testable.
     Ready for implementation.

Düzeltme MODIFIED gereksinimi olarak ve taze bir senaryo ile geldiği için, sonraki kişi (veya sonraki AI oturumu) sadece düzelttiğinizi değil, "doğru"nun ne anlama geldiğini de görür. Sonra /opsx:apply ve /opsx:archive normalde olduğu gibi.

İpucu: bir düzeltme için iyi bir senaryo, düzyazıdaki regresyon testidir. "GIVEN oturumu kapatılmış bir kullanıcı, WHEN geçerli kimlik bilgilerini gönderdiğinde, THEN panele yönlendirilir ve tekrar yönlendirilmez." Bunu yazın, uygulama net bir hedefe sahip olur.

Tarif 3: Taahhütten önce keşif

Ne zaman kullanılır: Bir sorununuz var ama henüz planınız yok. Ne inşa edeceğinize veya hangi yaklaşımın doğru olduğuna emin değilsiniz.

/opsx:explore ile başlayın. Yapısı olmayan ve artefakt oluşturmayan bir düşünce ortağıdır. Kod tabanınızı okur ve karar vermenize yardımcı olur.

You: /opsx:explore

AI:  What would you like to explore?

You: Page loads feel slow but I don't know where the time goes.

AI:  Let me look... I found three likely culprits:
     1. Large unoptimized images on the product list
     2. Synchronous data fetching that blocks render
     3. Re-renders triggered by context changes
     Which should we tackle first?

You: The data fetching one.

You: /opsx:propose optimize-product-list-fetching

AI:  Created the change, with a proposal informed by what we just
     found. Ready for implementation.

Keşif, bir değişiklik harcamadan önce düşüncelerinizi netleştirir. İçgörü kristalleştiğinde önerin, AI bağlamı ileri taşır.

Tarif 4: İki değişikliği aynı anda yönetme

Ne zaman kullanılır: Bir özelliğin ortasındasınız ve acil bir düzeltme sıraya atlıyor.

Değişiklikler bağımsız klasörlerdir, bu yüzden paralel çalışma çakışmaz. Düzeltmeyi başlatın, gönderin, sonra özelliğe bıraktığınız yerden devam edin.

You: I'm partway through add-dark-mode, but I need to fix a login bug now.

You: /opsx:propose fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/. Ready for implementation.

You: /opsx:apply

AI:  Implemented the fix. All tasks complete.

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect.

You: Back to dark mode.

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode. Picking up at task 2.3: Update Header...

Birden fazla değişiklik aktifken /opsx:apply add-dark-mode ile değişikliği adlandırmanız, AI'ı belirli bir değişikliğe yönlendirmenin yoludur. Görevler tasks.md içinde tamamlanmayı takip ettiği için, AI tam olarak nerede durduğunuzu bilir.

Birden fazla değişiklik aynı anda tamamlandığında, genişletilmiş /opsx:bulk-archive onları birlikte arşivler ve neyin gerçekten uygulandığını kontrol ederek spec çakışmalarını çözer. Akışlar sayfasına bakın.

Tarif 5: Davranış değişikliği olmadan yeniden yapılandırma

Ne zaman kullanılır: Kodu yeniden yapılandırıyorsunuz ve dışarıdan görünen davranış aynı kalmalı.

Bu ilginç bir durum, çünkü saf bir yeniden yapılandırmanın spec'lerinize ekleyeceği hiçbir şeyi yoktur. Davranış sözleşmesi değişmez; sadece uygulama değişir. Bu yüzden iş tasarım ve görevlerde yaşar, spec delta'sı boş veya yoktur.

You: /opsx:propose refactor-payment-module

AI:  Created the change. The proposal states the goal (split the
     payment module, no behavior change) and the design captures
     the new structure. No spec changes, since behavior is identical.
     Ready for implementation.

Değişikliğin .openspec.yaml dosyasında skip_specs: true ayarlayarak boş delta'yı açıkça beyan edin:

schema: spec-driven
skip_specs: true

İşaret olmadan, openspec validate sıfır delta'lı bir değişikliği reddeder (böylece unutulmuş bir spec aşaması yine de yakalanır); işaret ile doğrulama geçer ve openspec status spec aşamasını bekleyen değil, açıkça atlanmış olarak gösterir. Yeniden yapılandırma sonunda davranışı değiştirdiyse, .openspec.yaml dosyasından skip_specs'i kaldırın ve delta spec'lerini yazın — doğrulama, işaret ile spec dosyalarını bir çelişki olarak değerlendirir, böylece eski işaret sessizce kalamaz.

İşaretli bir değişikliği arşivlemek ek bayrak gerektirmez (birleştirilecek delta yoktur). Bağımsız olarak, --skip-specs bayrağı terminal komutuna spec adımını açıkça atlamasını söyler:

$ openspec archive refactor-payment-module --skip-specs

Aynı bayrak araçlar, CI ve yalnızca dokümantasyon değişiklikleri için de kullanışlıdır. İlke: spec'ler davranışı tanımlar, bu yüzden davranış değişmediyse spec de değişmemeli. Kavramlar sayfasına bakın.

Tarif 6: Adım adım kontrol (genişletilmiş komutlar)

Ne zaman kullanılır: Karmaşık veya riskli bir değişiklikte, devam etmeden önce her artefaktı incelemek istiyorsunuz.

Çekirdek /opsx:propose her şeyi bir anda taslaklar. Bir adım bir adım gitmek isterseniz genişletilmiş komutları açın:

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

Artık iskeleti oluşturabilir ve kademeli olarak inşa edebilirsiniz:

You: /opsx:new add-2fa

AI:  Created openspec/changes/add-2fa/. Ready to create: proposal.

You: /opsx:continue

AI:  Created proposal.md. Now available: specs, design.

You: /opsx:continue

AI:  Created specs/auth/spec.md. Now available: design.

Her artefakt geldiğinde inceleyin, serbestçe düzenleyin ve memnun kaldığınızda devam edin. Geri kalanını bir seferde taslaklamak istediğinizde, /opsx:ff kalan planlama artefaktlarını hızlıca ileri sarar. Arşivlemeden önce /opsx:verify, uygulamanın gerçekten spec'lerle eşleştiğini kontrol eder. Akışlar sayfasına bakın.

Tarif 7: Tüm döngüyü uygulamalı öğrenme

Ne zaman kullanılır: OpenSpec'i kurdunuz ve iş akışını kendi kodunuzda, oyuncak bir örnekte değil, hissetmek istiyorsunuz.

Genişletilmiş komutları açın (Tarif 6'ya bakın), sonra:

You: /opsx:onboard

AI:  Welcome to OpenSpec! I'll walk you through a complete change
     using your actual codebase. Let me scan for a small, safe
     improvement we can make together...

/opsx:onboard gerçek (küçük) bir iyileştirme bulur, bunun için bir değişiklik oluşturur, uygular ve arşivler, her adımı anlatarak. 15 ila 30 dakika sürer ve geride tutabileceğiniz veya atabileceğiniz gerçek bir değişiklik bırakır. Öğrenmenin en nazik yoludur. Komutlar sayfasına bakın.

Terminalden işinizi kontrol etme

Her zaman, terminalinizden durumları inceleyebilirsiniz:

$ openspec list                      # active changes
$ openspec show add-dark-mode        # one change in detail
$ openspec validate add-dark-mode    # check structure
$ openspec view                      # interactive dashboard

Bunlar okuma ve inceleme araçlarıdır. Önerme ve inşa etme hâlâ sohbet içindeki slash komutları üzerinden yapılır. Tam ayrıntılar CLI referansı sayfasındadır.

Sonraki adımlar

• Önce Keşfet: emin olmadığınızda önerilen başlangıç yolu
• Akışlar: yukarıdaki kalıplar, her birinin ne zaman kullanılacağına dair karar rehberliği ile
• Komutlar: her slash komutunun ayrıntılı açıklaması
• Başlangıç: standart ilk değişiklik anlatımı
• Kavramlar: parçaların neden bu şekilde bir arada çalıştığı