Spec-Driven Development: tulis kontrak sebelum agent menulis kode

Coding agent itu cepat. Mereka juga pelupa. Chat Sabtu yang menghasilkan dasbor sudah hilang pada Senin — agent berikutnya tidak tahu apa artinya “selesai”, SQL mana yang dilarang, atau kenapa penurunan APAC adalah cerita demo. Spec-Driven Development (SDD) ada supaya kontrak hidup lebih lama daripada sesi chat.

Prompt vs spesifikasi

Vibe coding terasa produktif karena agent selalu bergerak. Biayanya muncul belakangan: arsitektur yang bergeser diam-diam, perilaku “hampir benar” yang tidak bisa diuji, dan produk yang hanya chat asli yang bisa membuat ulang. Spesifikasi lebih lambat di awal, lebih murah untuk dilanjutkan.

• Prompt: “Buat copilot analitik yang menjawab pertanyaan.”
• Spesifikasi: agent SHALL menghasilkan QueryPlan; SHALL NOT mengeksekusi SQL sembarang; SHALL mengembalikan jawaban, bukti, visualisasi, dan rencana itu sendiri.
• Prompt mati bersama tab. Spesifikasi berversi di git, bisa direview, dan bisa dipakai ulang oleh agent berikutnya.
• Prompt berharap model mengingat batasan. Spesifikasi membuat batasan bisa dijalankan lewat tes dan jejak runtime.

Loop yang benar-benar kami jalankan

Di Analytica Copilot (demo SDD Analytics Copilot di https://analytica-demo.suherman.net) setiap kapabilitas utama bernomor SDD-001 … SDD-013. Pohon spesifikasi adalah otoritasnya — bukan README yang ditulis setelah UI terlihat bagus.

1. 01Visi produk, persona, dan perjalanan demo berbahasa Indonesia.
2. 02Persyaratan SHALL SDD-001 … SDD-013 (workspace, dataset, copilot, tata kelola, dasbor, tenancy, locale, ops).
3. 03Kontrak domain, OpenAPI, dan tool agent — QueryPlan, model semantik, DSL dasbor.
4. 04Implementasi di src/ sesuai kontrak itu.
5. 05Tes penerimaan + Gherkin. Lalu jejak runtime di UI produk (Jejak).

Ketertelusuran adalah intinya. Jika suatu perilaku ada di UI, Anda harus bisa menunjuk ID persyaratan, kontrak, tes, dan jejak runtime. Jika tidak bisa, itu belum terspesifikasi — itu kecelakaan prototype.

Spesifikasi konkret: SDD-004

Analitik percakapan adalah hero flow: “Kenapa pendapatan turun bulan lalu?” Spesifikasinya tidak bilang “pakai LLM untuk query database.” Ia mengunci rel keamanan lebih dulu.

# SDD-004 Conversational Analytics

The system SHALL allow a user to ask an analytical
question using natural language.

The agent SHALL resolve metrics against the semantic model.
The agent SHALL generate a QueryPlan.
The agent SHALL NOT directly execute arbitrary SQL.
The engine SHALL validate the QueryPlan before execution.

The system SHALL return:
  answer, result data, evidence,
  visualisation recommendation, QueryPlan.

Penerimaan memakai Gherkin, bukan vibe check. Satu skenario dari file yang sama:

Scenario: Ask for monthly revenue
  Given the commerce semantic model is loaded
  And the SQLite demo database contains order data
  When the user asks "What was revenue last month?"
  Then the agent resolves the "revenue" metric
  And creates a governed QueryPlan
  And the analytics engine executes the query
  And the answer contains the resulting revenue
  And the evidence shows the metric definition
  And the execution trace is persisted

Tata kelola adalah produknya

Tanpa SDD, agent analitik akhirnya akan mengeluarkan SQL. Itu nyaman di demo dan tidak bisa diterima di tenant. QueryPlan adalah kontraknya: model mengusulkan rencana, engine memvalidasinya terhadap model semantik, lalu mengompilasi SQL. LLM tidak pernah bicara ke SQLite secara langsung. Aturan itu hidup di SDD-004, SDD-005, dan ADR — jadi agent regenerasi tidak bisa “membantu” dengan melewatkannya.

Spesifikasi sebagai kit regenerasi

Tes SDD yang paling kuat terasa tidak nyaman: hapus src/, simpan specs/, lalu minta coding agent membangun ulang. Analytica Copilot ditulis agar itu mungkin. specs/regeneration/ menyimpan blueprint dan prompt copy-paste. Invarian yang tidak boleh dilanggar ada di atas: tidak ada SQL sembarang, dasbor adalah spesifikasi JSON (bukan pohon React yang digenerate), monolit Next.js + SQLite, jam demo 2026-09-05, multi-tenancy lunak, UI Bahasa Indonesia.

Cara mulai di repo Anda sendiri

Anda tidak butuh tiga belas persyaratan di hari pertama. Anda butuh kontrak bernomor yang tidak bisa diabaikan agent belakangan.

1. Beri setiap perilaku sebuah ID (PROJ-001 …). Satu file per ID di specs/requirements/.
2. Tulis SHALL dan SHALL NOT di file yang sama. Batasan berada di samping fitur, bukan di thread Slack.
3. Tambah satu skenario Gherkin yang akan gagal jika agent “hanya mengirim UI”.
4. Kunci kontrak yang harus ditaati model: OpenAPI, skema tool, metrik semantik, ADR.
5. Arahkan coding agent ke ID spesifikasi — bukan ke paragraf di chat. Implementasi adalah diff terhadap kontrak.
6. Simpan prompt regenerasi di samping spesifikasi. Jika src/ hilang besok, prompt itu adalah bootstrap-nya.

Apa yang bukan SDD

• Bukan waterfall. Spesifikasi tetap kecil, bernomor, dan bisa direvisi. Kami menyetujuinya; kami tidak membekukan novel 40 halaman.
• Bukan “tulis docs setelah demo.” Jika spesifikasi diubah supaya cocok dengan kode, kodenya yang menang. Balik itu.
• Bukan pengganti merge oleh manusia. Agent menyiapkan; orang tetap memutuskan FINAL_REVIEW. Itu rel yang sama dengan Agent On Rails.

Di mana ini hidup di suherman.net

Kami sudah memakai loop ini secara live di sesi berbagi dengan SDD Analitik Kopilot: pertanyaan bahasa alami → QueryPlan terkendali → bukti → dasbor. Spesifikasi yang sama dibaca coding agent saat meregenerasi aplikasi.

• Prototipe live: https://analytica-demo.suherman.net
• Situs produk: https://analytica.suherman.net
• Repo referensi: https://github.com/iman-suherman/sdd-analytics-copilot
• Indeks spesifikasi: specs/README.md di repo itu (SDD-001 … SDD-013).
• Microsoft Spec Kit (bacaan latar): https://developer.microsoft.com/blog/spec-driven-development-spec-kit/
• Artikel terkait: https://suherman.net/articles/agent-on-rails-escalation-watchdog

Intinya: Spec-Driven Development adalah cara menjaga coding agent tetap di jalur tanpa mengawasi setiap prompt. Tulis kontrak dulu. Biarkan agent mengimplementasi. Simpan tes dan jejak sebagai bukti. Ketika chat sudah hilang, spesifikasi masih ada — dan itu satu-satunya artefak yang bisa dipercaya agent lain, atau Sabtu berikutnya.