Yazılım geliştirme tarihinin büyük bölümünde, fikirden ürüne giden yol hep aynı tıkanıklıkla karşılaştı: geliştiricinin kafasındaki fikir, ürün sahibinin kafasındaki fikir ve son kullanıcının beklentisi hiçbir zaman aynı değildi. Belgeler yazılırdı, ama okunmazdı. Toplantılar yapılırdı, ama çoğu şey yine de kaybolurdu. Sonunda yazılan kod, başlangıçta isteneni ancak kısmen karşılardı.

Spec-driven development bu çıkmaza yeni bir çözüm sunuyor; LLM tabanlı sistemler çağında bu çözümün önemi artıyor.

Spec nedir, dokümandan farkı ne?

Klasik yazılım belgesi pasiftir. Okunabilir, referans alınabilir, ama bir sistem tarafından doğrudan tüketilemez. Spec ise farklıdır: hem insan hem de makine tarafından okunabilir yapılandırılmış bir sözleşmedir.

İyi yazılmış bir spec şunları içerir: bir özelliğin ne yapacağını ve ne yapmayacağını, girdi/çıktı formatlarını, kenar durumları (edge cases), kabul kriterlerini ve hata davranışlarını. Bu içerik, hem bir geliştiricinin kodu yazmasını hem de bir LLM agent'ının görevi doğru yorumlamasını mümkün kılar.

"Spec, fikirle kod arasındaki çeviri kaybını ortadan kaldırır."

Vibe coding ile kesişim

Andrej Karpathy'nin tanımladığı vibe coding akışında geliştirici, kodun her satırını yazmak yerine ne istediğini ifade eder, model üretir, geliştirici yönlendirir. Bu akış hızlıdır, yaratıcıdır, ama kontrolsüz bırakıldığında tutarsız çıktılara yol açar.

Spec-driven yaklaşım tam da bu noktada vibe coding'i disipline eder. Geliştirici önce spec'i yazar, bu hem düşüncesini netleştirir hem de modele verilecek bağlamı oluşturur. Model spec'i okur, bunu kabul kriterleri olarak yorumlar, çıktısını buna göre şekillendirir.

Neden verimi artırır?

  • Belirsizlik azalır: Spec yazılan özelliklerde yanlış anlama oranı düşer. Model daha isabetli kod üretir, revizyon sayısı azalır.
  • Test otomatikleşir: Spec'teki kabul kriterleri otomatik test senaryolarına dönüşür. Test yazmak, bir spec çevirme işine dönüşür.
  • Bilgi kaybolmaz: Özelliğin neden o şekilde davrandığı spec'te yazılıdır. Aylar sonra dönen geliştirici kodu okumak yerine spec'i okur.
  • Agent sistemlere hazır: Spec'ler, çok aktörlü agentic sistemlerin görevleri devralıp devredeceği yapılandırılmış bağlamlardır.
Spec yazmak yavaşlatmaz. Spec yazmadan ilerlemek yavaşlatır, sadece bunu hissedene kadar zaman geçer.

Q/NORMA: spec'i sürecin merkezine taşımak

Qhira'nın geliştirdiği Q/NORMA platformu, spec-driven metodolojisini yazılım geliştirme sürecinin omurgasına yerleştiriyor. Fikir aşamasından üretime kadar her adım, Q/NORMA'nın ürettiği spec standartları etrafında şekilleniyor.

Q/NORMA yalnızca bir belgeleme aracı değildir. Bir süreç orkestrasyon platformudur: agentic sistemlerin anlayabileceği spec'ler üretir, bunları geliştirme ekipleri ve agent'lar arasında paylaşır, uyumsuzlukları tespit eder.

Spec disiplininde ilk haftalar yavaş hissettirir. Kazanç, ekip soru sormak ve toplantı yapmak yerine spec'e bakmayı alışkanlık haline getirdikçe görünür olur.

Başlamak için ne lazım?

Spec-driven development bir araç değil, bir disiplindir. Başlamak için Q/NORMA'ya ihtiyacınız yok: bir metin dosyası, tutarlı bir format ve ekipte kısa bir anlayış birliği yeterlidir.

Qhira olarak önerdiğimiz başlangıç formatı şu üç soruyu yanıtlaması: Bu özellik ne yapar? Ne yapmaz? Başarısı nasıl ölçülür? Bu üç soruyu yanıtlayan her doküman, spec'in minimumunu karşılar.

Geri kalanı ölçekle gelir.

Kurumunuz için benzer bir çalışmayı konuşmak isterseniz: System Architecture · İletişim

Throughout most of software development history, the path from idea to product always hit the same bottleneck: the idea in the developer's head, the product owner's vision, and the end user's expectation were never quite the same. Documents were written but not read. Meetings were held but things still got lost. The code that emerged only partially matched what was originally wanted.

Spec-driven development offers a new answer to this impasse, and in the age of LLM-based systems, that answer matters more than ever.

What is a spec, and how is it different from documentation?

Classical software documentation is passive. It can be read and referenced, but it cannot be consumed directly by a system. A spec is different: it is a structured contract readable by both humans and machines.

A well-written spec includes: what a feature will and won't do, input/output formats, edge cases, acceptance criteria, and error behavior. This content makes it possible both for a developer to write code and for an LLM agent to correctly interpret a task.

"A spec eliminates the lost translation between idea and code."

The intersection with vibe coding

In the vibe coding flow described by Andrej Karpathy, the developer expresses what they want rather than writing every line of code, the model produces, the developer steers. This flow is fast and creative, but left unchecked it leads to inconsistent outputs.

The spec-driven approach is precisely what disciplines vibe coding. The developer writes the spec first, this clarifies their thinking and creates the context to give the model. The model reads the spec, interprets it as acceptance criteria, and shapes its output accordingly.

Why does it raise productivity?

  • Ambiguity decreases: With spec'd features, misunderstanding drops. The model produces more accurate code and fewer revisions are needed.
  • Testing becomes automated: Acceptance criteria in the spec become automated test scenarios. Writing tests becomes a spec translation exercise.
  • Knowledge doesn't get lost: Why a feature behaves a certain way is written in the spec. A developer returning a month later reads the spec, not the code.
  • Ready for agentic systems: Specs are the structured contexts in which multi-actor agentic systems hand off and receive tasks.
Writing specs doesn't slow you down. Moving without specs slows you down, it just takes a while before you feel it.

Q/NORMA: putting spec at the center of the process

Q/NORMA, the platform developed by Qhira, places spec-driven methodology at the backbone of the software development process. From ideation to production, every step is shaped around the spec standards Q/NORMA produces.

Q/NORMA is not just a documentation tool. It is a process orchestration platform: it produces specs that agentic systems can understand, shares them between development teams and agents, and detects inconsistencies.

With spec discipline, the first weeks feel slow. The gain becomes visible as the team makes checking the spec, rather than asking around or holding meetings, a habit.

What do you need to start?

Spec-driven development is a discipline, not a tool. You don't need Q/NORMA to start: a text file, a consistent format, and brief alignment within your team is enough.

The starting format Qhira recommends answers three questions: What does this feature do? What doesn't it do? How is success measured? Any document that answers these three meets the minimum of a spec.

The rest comes with scale.

If you would like to discuss similar work for your organization: System Architecture · Contact