Özelleştirme

OpenSpec üç düzeyde özelleştirme sunar:

Düzey	Ne Yapar	Kimler İçin Uygun
Proje Yapılandırması	Varsayılanları ayarlar, bağlam/kural enjekte eder	Çoğu ekip
Özel Şemalar	Kendi iş akışı artefaktlarınızı tanımlar	Benzersiz süreçlere sahip ekipler
Küresel Geçersiz Kılmalar	Şemaları tüm projeler arasında paylaşır	Gelişmiş kullanıcılar

---

Proje Yapılandırması

openspec/config.yaml dosyası, OpenSpec'i ekibiniz için özelleştirmenin en kolay yoludur. Size şunları yapma imkânı tanır:

• Varsayılan şema belirlemek - Her komutta --schema kullanmaktan kaçının
• Proje bağlamı enjekte etmek - AI teknoloji yığınınızı, kurallarınızı vb. görür
• Artefakt başına kurallar eklemek - Belirli artefaktlar için özel kurallar
• İşlem başına yönlendirme eklemek - apply ve archive işlemleri için danışmanlık tercihleri
• Entegrasyon tercihlerini hatırlamak - örn. GitHub Copilot cloud coding agent seçeneği

Hızlı Kurulum

openspec init

Bu komut, yapılandırmayı etkileşimli olarak oluşturmanız için sizi adım adım yönlendirir. Veya manuel olarak oluşturun:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

Nasıl Çalışır

Varsayılan şema:

# Without config
openspec new change my-feature --schema spec-driven

# With config - schema is automatic
openspec new change my-feature

Bağlam ve kural enjeksiyonu:

Herhangi bir artefakt oluşturulurken, bağlamınız ve kurallarınız AI promptuna enjekte edilir:

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

• Bağlam TÜM artefaktlarda görünür
• Kurallar YALNIZCA eşleşen artefakt için görünür

İşlem yönlendirmesi:

operations.apply.guidance ve operations.archive.guidance, bir ajanın bu işlemleri nasıl yürüteceğine dair isteğe bağlı danışmanlık talimatları dizileridir. Bunlar rules alanından ayrıdır: işlem yönlendirmesi artefakt içeriğini kısıtlamaz ve artefakt kuralları asla işlem yönlendirmesi olarak yeniden etiketlenmez.

Apply ve archive, bu girdileri çalışma zamanında alır:

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

Her iki yüzey de mevcut proje context değerini ve eşleşen operationGuidance değerini ayrı isteğe bağlı alanlar olarak döndürür. Her çağrı, çözümlenmiş kök dizinden taze bir anlık görüntü okur. --store <id> seçildiğinde, değişiklik, bağlam ve yönlendirme mevcut depodan değil, o depodan gelir. Archive instruction komutu salt okunurdur: delta spec'leri denetlemez veya birleştirmez, ana spec'leri yazmaz, değişikliği taşımaz veya statik archive iş akışını çalıştırmaz.

Proje bağlamı zorunlu bir prompt düzeyi girdisidir. Oluşturulan iş akışları bunu okur ve ilgili proje gerçeklerini, kurallarını ve kısıtlamalarını uygular. İşlem yönlendirmesi isteğe bağlı ek danışmanlık niteliğindedir: iş akışları her girdiyi değerlendirir ve yerleşik iş akışıyla uyumlu ve geçerli olan girdileri uygular.

Her iki alan da CLI tarafından kontrol edilen durumdan, çözümlenmiş yollardan, yerleşik adımlardan, açık kullanıcı tercihlerinden ve artefakt kurallarından ayrı kalır. Bir iş akışı, bağlam çakışmalarını kontrol eden değeri koruyarak raporlar. Geçersiz veya çelişkili yönlendirmeleri uygulamaz ve nedenini açıklar. Ne bağlam ne de yönlendirme zorlayıcı bir denetim niteliğindedir ve iş akışları, kullanıcı ayrı olarak bu içeriği talep etmedikçe metinlerini uygulama dosyalarına, spec'lere, değişiklik artefaktlarına veya özetlere kopyalamaz.

Archive ve spec-sync girdi güvenliği:

Archive, toplu archive ve bağımsız sync, tek delta-spec kaynağı olarak openspec status --json çıktısındaki artifactPaths.specs.existingOutputPaths değerini kullanır. specs artefaktı olmayan bir şema veya somut çıktı listesi boş olan bir değişiklik için senkronize edilecek hiçbir şey yoktur; diğer artefaktlar delta spec'leri çıkarım yapmak için kullanılmaz.

Anlamsal birleştirme ana spec yazmadan önce, iş akışı mevcut openspec instructions specs --change <name> --json çıktısını tüketir. Döndürülen specs kuralları yalnızca o birleştirmeden üretilen ana spec'leri kısıtlar. Tekil archive geçişi o anlık görüntüyü satır içi sync'e iletir, bağımsız sync onu doğrudan alır ve toplu archive, ilk spec yazımından önce gerekli tüm anlık görüntüleri elde eder. Sıfırdan farklı veya geçersiz JSON archive/specs instruction yanıtı bir arama hatasıdır, boş girdi değildir: iş akışı, etkilenen spec yazımı veya değişiklik taşımadan önce durur (toplu archive için, herhangi bir toplu yazım veya taşımadan önce).

Bu yapılandırma, archive çalışma aşamalarını, kullanıcı istemlerini, dosya sistemi işlemlerini, anlamsal birleştirme sahipliğini, doğrudan openspec archive komutunu veya artefakt rules yapısını ve çıktısını değiştirmez.

Şema Çözümleme Sırası

OpenSpec bir şemaya ihtiyaç duyduğunda, şu sırayla kontrol eder:

1. CLI bayrağı: --schema <name>
2. Değişiklik metadata'sı (değişiklik klasöründeki .openspec.yaml)
3. Proje yapılandırması (openspec/config.yaml)
4. Varsayılan (spec-driven)

---

Özel Şemalar

Proje yapılandırması yeterli olmadığında, tamamen özelleştirilmiş bir iş akışıyla kendi şemanızı oluşturun. Özel şemalar, projenizin openspec/schemas/ dizininde bulunur ve kodunuzla birlikte sürüm kontrolü altında tutulur.

your-project/
├── openspec/
│   ├── config.yaml        # Proje yapılandırması
│   ├── schemas/           # Özel şemalar burada bulunur
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Değişiklikleriniz
└── src/

Mevcut Bir Şemayı Çatala (Fork)

Özelleştirmenin en hızlı yolu, yerleşik bir şemayı çatallamaktır:

openspec schema fork spec-driven my-workflow

Bu komut, spec-driven şemasının tamamını openspec/schemas/my-workflow/ dizinine kopyalar ve burada serbestçe düzenleyebilirsiniz.

Neler elde edersiniz:

openspec/schemas/my-workflow/
├── schema.yaml           # İş akışı tanımı
└── templates/
    ├── proposal.md       # Öneri çıktısı için şablon
    ├── spec.md           # Spesifikasyonlar için şablon
    ├── design.md         # Tasarım için şablon
    └── tasks.md          # Görevler için şablon

Artık iş akışını değiştirmek için schema.yaml dosyasını düzenleyebilir veya AI'ın ürettiği içeriği değiştirmek için şablonları düzenleyebilirsiniz.

Sıfırdan Şema Oluşturma

Tamamen yeni bir iş akışı için:

# Etkileşimli
openspec schema init research-first

# Etkileşimsiz
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Şema Yapısı

Bir şema, iş akışınızdaki çıktıları ve bunların birbirine bağımlılığını tanımlar:

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

Temel alanlar:

Alan	Amaç
id	Benzersiz tanımlayıcı, komutlarda ve kurallarda kullanılır
generates	Çıktı dosya adı (globs desteklenir, örn. specs/**/*.md)
template	templates/ dizinindeki şablon dosyası
instruction	Bu çıktıyı oluşturmak için AI talimatları
requires	Bağımlılıklar - hangi çıktıların önce var olması gerektiği

Çıktıları yazılmasını istediğiniz sırada listeleyin. requires neyin mümkün olduğunu belirler; artifacts: listesindeki sıra ise birden fazla çıktı aynı anda hazır olduğunda hangisinin önce geleceğini belirler.

Şablonlar

Şablonlar, AI'ı yönlendiren markdown dosyalarıdır. İlgili çıktı oluşturulurken istem (prompt) içine enjekte edilirler.

<!-- templates/proposal.md -->
## Why

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

Şablonlar şunları içerebilir:

• AI'ın doldurması gereken bölüm başlıkları
• AI için yönlendirme içeren HTML yorumları
• Beklenen yapıyı gösteren örnek formatlar

Şemanızı Doğrulayın

Özel bir şemayı kullanmadan önce doğrulayın:

openspec schema validate my-workflow

Bu komut şunları kontrol eder:

• schema.yaml sözdizimi doğru mu
• Tüm referans verilen şablonlar mevcut mu
• Döngüsel bağımlılık var mı
• Çıktı kimlikleri geçerli mi

Özel Şemanızı Kullanma

Oluşturulduktan sonra şemanızı şu şekilde kullanın:

# Komut satırında belirtin
openspec new change feature --schema my-workflow

# Veya config.yaml içinde varsayılan olarak ayarlayın
schema: my-workflow

Şema Çözümlemesini Hata Ayıklama

Hangi şemanın kullanıldığını bilmiyor musunuz? Şu komutla kontrol edin:

# Belirli bir şemanın nereden çözümlendiğini görün
openspec schema which my-workflow

# Tüm kullanılabilir şemaları listele
openspec schema which --all

Çıktı, şemanın projenizden, kullanıcı dizininden mi yoksa paketten mi geldiğini gösterir:

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

Not: OpenSpec, projeler arasında paylaşım için ~/.local/share/openspec/schemas/ konumunda kullanıcı düzeyinde şemaları da destekler, ancak kodunuzla birlikte sürüm kontrolü altında tutuldukları için openspec/schemas/ içindeki proje düzeyinde şemalar önerilir.

---

Örnekler

Hızlı İterasyon İş Akışı

Hızlı iterasyonlar için minimal bir iş akışı:

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

İnceleme Çıktısı Ekleme

Varsayılanı çatalla ve bir inceleme adımı ekle:

openspec schema fork spec-driven with-review

Sonra schema.yaml dosyasını düzenleyerek şunu ekleyin:

  - id: review
    generates: review.md
    description: Pre-implementation review checklist
    template: review.md
    instruction: |
      Create a review checklist based on the design.
      Include security, performance, and testing considerations.
    requires:
      - design

  - id: tasks
    # ... mevcut görev yapılandırması ...
    requires:
      - specs
      - design
      - review    # Artık görevler inceleme gerektiriyor

---

Topluluk Şemaları

OpenSpec, bağımsız depolar üzerinden dağıtılan topluluk tarafından sürdürülen şemaları da destekler. Bunlar, OpenSpec'i diğer araçlar veya sistemlerle bütünleştiren görüş bildiren iş akışları sağlar; tıpkı github/spec-kit'in topluluk eklenti kataloğu gibi.

Topluluk şemaları OpenSpec çekirdeğine dahil edilmez — kendi depolarında ve kendi yayın takvimleriyle yaşarlar. Kullanmak için şema paketini projenizin openspec/schemas/<schema-name>/ dizinine kopyalayın (her depoyu README dosyası kurulum talimatlarını içerir).

Şema	Bakım Veren	Depo	Açıklama
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	Uygulama öncesi değişiklik niyetini, gözlemlenebilir davranışı, teknik tasarımı ve kalıcı mimari kararları yakalar. Değişiklik düzeyinde bir ADR inceleme manifesti ekler ve uygun uzun ömürlü kararları değiştirilemez, geçersiz kılınabilir ADR'ler olarak yazar.
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	OpenSpec'in çıktı yönetişimini obra/superpowers yürütme becerileriyle (beyin fırtınası, plan yazma, alt ajanlar aracılığıyla TDD, kod incelemesi, bitirme) bütünleştirir. Superpowers'ın yerel olarak kapsamadığı bir boşluğu dolduran kanıt öncelikli bir retrospective çıktısı ekler.
nanopm	@nmrtn	nmrtn/nanopm	PM öncelikli iş akışı. nanopm'ın planlama hattını (denetim → strateji → yol haritası → PRD) uygulamanın akışında çalıştırır. Ürün planlamasını OpenSpec'in spesifikasyon odaklı mühendislik iş akışına köprüler. .nanopm/ dizini varsa çıktılar oradan okunur — öneri denetimi, tasarım stratejiyi ve görevler PRD kırılımını kaynak alır.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	Yetenek düzeyinde uçtan uca test çalışma kitapları. Her yetenek için değiştirilemez bir spesifikasyon, değiştirilemez bir görev şablonu ve her çalıştırma için bir zaman damgalı çalışma kaydı oluşturur. İddialar yalnızca gözlemlenebilir davranışlardır (HTTP durumu, yanıt gövdesi, kalıcı durum — asla günlük alt dizeleri değil); her çalışma başlangıç/bitiş UTC'sini, süreyi ve en iyi tahmin LLM token tüketimini kaydeder.
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	TDD disiplini ve düşmanca bir inceleme adımıyla spesifikasyon odaklı iş akışı. Akış: proposal → specs → design → review → test-plan → tasks → apply → verify. review, taze bağlamda, salt okunur bir inceleyici tarafından (mümkünse ikinci bir modelle) yazılır ve ajanın test-plan, tasks ve apply adımlarını kontrol etmesini söyleyen bir VERDICT: satırı üretir; OpenSpec yalnızca çıktıların var olup olmadığını kontrol eder, bu yüzden kontrolü kendi CI veya hook'unuzla uygulayın. test-plan, her spesifikasyon senaryosunu adlandırılmış bir teste eşler ve verify tarafından denetlenen kırmızı/yeşil bir defter görevi görür.

Topluluk şeması katkıda bulunmak ister misiniz? Deponuza bir bağlantı içeren bir sorun açın veya bu tabloya bir satır ekleyen bir PR gönderin.

---

Ayrıca Bakınız

• CLI Referansı: Şema Komutları - Tam komut belgelendirmesi