Hızlı Başlangıç

İlk değişikliğiniz, fikirden arşivlenmeye, yeni veya mevcut bir projede.

Başlamadan önce, makinenizde CLI'a ihtiyacınız var (Kurulum) ve projenizde OpenSpec'in başlatılması gerekir (Projenizi Ayarlayın).

Boş Bir Projeden Başlama

Seçilmiş bir yığına veya tam bir mimariye sahip olmadan başlayabilirsiniz. OpenSpec'i proje klasörünüzde başlatın, ardından ajanınıza seçenekleri sizinle birlikte keşfetmesini isteyin. Yapay zeka sohbetinizde:

Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.

İlk değişikliğin ne gerektirdiğine karar verin ve sonraki mimari seçimleri açık bırakın. Ajanınıza yalnızca tek bir değişikliği önermesini isteyin, ardından aşağıdaki adımları izleyin. Proje büyüdükçe mimariyi yeniden gözden geçirebilirsiniz.

Döngüye Bir Bakış

Her değişiklik aynı beş adımdan geçer: fikri ajanınızla birlikte düşünürsünüz, bir plan taslağı oluşturur, hiçbir kod mevcut olmadan planı düzeltirsiniz, ajan ondan derler ve arşivleme, teslim edilenlerle spec'lerinizi günceller.

flowchart LR
    explore["1 · Keşfet<br/>birlikte düşünün"] --> propose["2 · Öner<br/>ajan planı taslağını oluşturur"]
    propose --> review["3 · Gözden Geçir<br/>planı düzeltirsiniz"]
    review --> apply["4 · Uygula<br/>ajan görev görev derler"]
    apply --> archive["5 · Arşivle<br/>spec'ler değişikliği özler"]
    archive -. "sonraki değişiklik" .-> explore

Aşağıdaki her istem, kod istediğiniz yerle aynı yer olan yapay zeka sohbetinize gider. Örnekler araçlar arasında çalışması için sade bir dil kullanır. Bir beceriyi doğrudan da çağırabilirsiniz; sözdizimi araca göre değişir (desteklenen araçlar).

Adım 1: Keşfet

Bir plan istemeden önce fikri ajanınızla birlikte düşünün. Yapay zeka sohbetinizde:

Help me explore how rate limiting should work in this app.

Keşfet bir düşünme modudur. Ajan kod tabanınızı araştırır, önemli soruları sorar, seçenekleri tasvir eder ve varsayımlara meydan okur. Asla kod yazmaz. Karar verdiğiniz şeyi kaydetmesini istediğinizde veya teklif ettiğinde evet dediğinizde başka hiçbir şey yazmaz. Çıktı keskinleştirilmiş bir fikirdir.

Problem ihtiyaç duyduğu sürece burada kalın. Şekil doğru hissettirdiğinde, devredin:

Propose the change we just discussed.

Bu satır, üzerinde anlaştığınız her şeyi taşıyarak sizin için önerme adımını başlatır. 2. adımdaki ilk istemi atlayın.

Adım 2: Öner

Önerme, fikri gözden geçirilebilir bir plana dönüştürür. Keşiften gelindiğinde, zaten çalışıyor olur. Serin başlangıçta, değişiklik kafanızda net olduğunda, doğrudan isteyin. Yapay zeka sohbetinizde:

Propose a change to add rate limiting.

Ajan ihtiyaç duyduğu soruları sorar, ardından bir değişiklik klasörü yazar:

openspec/changes/add-rate-limiting/
├── proposal.md    neden ve ne değişiyor
├── specs/         "bitmiş" ne demektir, test edilebilir gereksinimler olarak
├── design.md      teknik kararlar (yalnızca değişiklik gerektirdiğinde)
└── tasks.md       uygulama kontrol listesi

Henüz kod yok. Önerme planda durur.

Adım 3: Planı Gözden Geçirme ve Düzeltme

Planı hâlâ kelimelerden ibaretken ve henüz hiçbir şey derlenmemişken düzeltin. Şu sırayla okuyun:

• proposal.md: bu doğru problem mi, doğru boyutta mı?
• specs/: en yüksek değerli okuma. Bu gereksinimleri tamamlanmış olarak kabul eder miydiniz?
• tasks.md: görevler spec'leri kapsıyor mu ve fazlası yok mu?

Bir şeyi düzeltmek için her ikisi de işe yarar:

• Dosyayı kendiniz düzenleyin. Artifact'lar sade markdown'dır ve dosyalar plandır.
• Ajanınıza neyin yanlış olduğunu söyleyin ("spec, kimlik doğrulamasız durumu eksik"). Artifact'ları revize eder.

Adım 4: Uygula

Uygulama, planı koda dönüştürür. Temiz bir bağlam penceresinde uygulama daha iyi gideceği için yeni bir sohbet oturumu açın. Yapay zeka sohbetinizde:

Apply the add-rate-limiting change.

Ajan değişiklik klasörünü okur, ardından tasks.md üzerinden çalışır ve her görevi tamamladıkça işaretler.

• Kesildi veya bağlam doldu mu? Yeni bir oturum açın ve tekrar uygulamasını isteyin. İşaretlenmemiş ilk görevden devam eder.
• Plan yanlış çıktı mı? Artifact'ları düzeltin (3. adımdaki her iki yolla), ardından uygulamaya devam edin.
• İlerleme, tasks.md onay kutularında yaşar. Gizli bir durum yoktur.

Adım 5: Arşivle

Arşivleme iki şey yapar: ana spec'lerinizi değişikliğin gereksinimleriyle günceller ve değişiklik klasörünü arşiv klasörüne taşır (/openspec/changes/archive/* içinde).

tasks.md içindeki her kutu işaretlendiğinde, yapay zeka sohbetinizde:

Archive the add-rate-limiting change.

Arşivlemenin yaptıklarını adım adım inceleyin:

## Bitmiş Değişiklik
> Uygulama tamamlandı. Delta spec (bu değişikliğin eklediği şey) hâlâ değişiklik klasörünün içinde duruyor; specs/ henüz rate limiting hakkında bir şey bilmiyor.
  openspec/
  ├── specs/                                   (henüz rate-limiting spec'i yok)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         her kutu işaretli
          └── specs/
              └── rate-limiting/
                  └── spec.md                  delta: EKLENEN gereksinimler

## Gereksinimler specs/'e yerleşir
> Deltadaki her gereksinim ana spec'e yerleşir: eklenenler eklenir, değiştirilenler eski sürümlerini değiştirir. Yeni bir yetenek yeni bir spec dosyası alır.
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          "Requirement: Rate limiting" kazanır
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  delta, birleştirmenin kaynağı

## Klasör archive/'e taşınır
> Tüm değişiklik klasörü, delta dahil, tarih öneki altında arşive taşınır. Hiçbir şey silinmez.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## Spec'ler sistemi derlenmiş haliyle tanımlar
> changes/ sonraki değişiklik için boş. specs/ sistemin ne yaptığının doğruluk kaynağıdır; archive/ nasıl oraya ulaştığının geçmişidir.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          derlenmiş haliyle spec
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Git ayrı bir konudur. Değişiklik klasörünü kodla birlikte commit edin ve iş akışınızla ilgili başka hiçbir şey değişmez.

Arşivlenmiş Değişiklikleri Koruma veya Budama

openspec/changes/archive/, her bitmiş değişiklik için proposal, design, tasks ve delta saklar. Yukarıdaki arşiv akışında, delta zaten openspec/specs/'i güncelledi.

• Tüm değişiklik klasörünü koruyun mevcut checkout'ta kendi kendine yeten bir kayıt istediğinizde.
• Arşivlenmiş bir değişikliğin specs/ klasörünü kaldırın Git sizin spec geçmişiniz olduğunda. Önce arşivi commit edin, ardından openspec/changes/archive/<change>/specs/ silin. Proposal, design ve tasks checkout'ta kalır. openspec validate --archived hâlâ çalışır çünkü uygulanan deltaları değil, görev tamamlanmasını kontrol eder.
• Tüm değişiklik klasörünü yalnızca proposal, design veya görev geçmişine checkout'ta artık ihtiyacınız olmadığında kaldırın. Mevcut spec'ler değişmez, ancak openspec validate --archived ve checkout aramaları artık o değişikliği içermez.

WARNING

Git'in silinen dosyaları saklamasını istiyorsanız, arşiv commit'ini depo geçmişinizde tutun. Arşiv ve temizlik commit'lerini birlikte sıkıştırmak, bu ara anlık görüntüsünü kaldırır.

OpenSpec, arşivlenmiş değişiklikleri otomatik olarak budamaz veya bir saklama ayarı sağlamaz.

Daha İlerisine Gitmek

• Delta spec'ler: delta spec'inde davranış değişikliklerini nasıl yazarsınız.
• Profiller: çekirdek setin ötesinde isteğe bağlı iş akışları (arşivlemeden önce doğrulama, artımlı planlama).

Gelişmiş Rehberler

Henüz yazılmadı; eklemeyi planladığımız rehberler:

• Önce prototip: Herhangi bir spec'ten önce kodda bir sınama yapın, ardından prototipin size öğrettiklerinden proposal'ı doldurun.
• Yinelemeli olarak derleme: tek büyük bir proposal yerine küçük değişiklikler dizisi.
• Uygulanmış bir değişikliği revize etme: plan, uygulamadan sonra tekrar hareket etmeli, ancak değişiklik henüz birleştirilmedi veya arşivlenmedi.