Iman Suherman — Building solutions. Delivering impact.
ENID
← Semua artikel

Artikel

Selain Gherkin: ADR, SHALL, OpenAPI, dan sisa paket spesifikasi

Gherkin hanya lapisan bukti yang bisa dijalankan. SurveyDesk juga menyimpan ADR, requirements SHALL, OpenAPI, FormSpec, cerita produk, dan prompt regenerasi — supaya Anda tidak harus menonton ulang YouTube untuk belajar arsitekturnya.

10 menit baca
ADRSpec-Driven DevelopmentSurveyDeskGherkin
Paket spesifikasi SurveyDesk — product, requirements, domain, OpenAPI, ADR, acceptance Gherkin, regenerasi

Setelah live build SurveyDesk 12 September, orang sering membuka artikel get-started, mengklik Catatan sesi, dan hanya menemukan catatan Sabtu terbaru. Lalu bertanya: di mana penjelasan dokumen selain Gherkin — terutama ADR? Jawaban singkat: dokumen itu tidak pernah dimaksudkan hanya hidup di halaman catatan. Mereka hidup di repo di bawah specs/, dan artikel ini adalah petanya yang bisa dibaca.

Gherkin adalah bukti — bukan seluruh kontrak

Dalam Spec-Driven Development, file yang berbeda menjawab pertanyaan yang berbeda. Mencampurinya membuat demo terasa seolah “hanya Gherkin yang ada.”

  • Cerita produk (specs/product) — untuk siapa, apa yang in/out of scope, perjalanan demo.
  • Requirements SHALL (specs/requirements) — aturan produk tahan lama dengan ID (SD-001 … SD-012).
  • Catatan domain (specs/domain) — kosakata survey, FormSpec, lifecycle, response, results.
  • OpenAPI (specs/api/openapi.yaml) — bentuk HTTP yang harus dihormati API (netral bahasa).
  • ADR (specs/adr) — kenapa arsitektur dipilih seperti ini supaya agent tidak “memperbaikinya” sampai hilang.
  • Gherkin (specs/acceptance) — skenario yang bisa dijalankan (Given / When / Then) yang membuktikan SHALL.
  • Regenerasi (specs/regeneration) — prompt supaya agent lain bisa membangun ulang apps/ dari kontrak.

Loading diagram…

Cerita produk yang sama, dilapis jadi kontrak. Gherkin ada di tepi bukti — bukan sendirian di tengah.

Apa itu ADR (dan kenapa itu bukan Gherkin)

Architecture Decision Record membekukan pilihan dan konsekuensinya. Gherkin membekukan perilaku yang bisa diuji. Jika hanya ada Gherkin, agent tetap bisa “membantu” memindahkan Anda ke Postgres di cloud karena tidak ada skenario yang bilang “harus tetap satu file SQLite.” ADR mengatakan itu dengan jelas.

Tur ADR SurveyDesk (baca ini dulu)

Buka https://github.com/iman-suherman/survey-desk/tree/main/specs/adr. Mulai dari sepuluh ini — masing-masing sengaja pendek.

  1. ADR-001 Monorepo — satu checkout untuk API, web, iOS, Android supaya live build sejam tetap mungkin.
  2. ADR-002 SQLite — persistensi file lokal; wipe/reset tanpa kredensial cloud.
  3. ADR-003 Publik anonim — responden tidak perlu login; kontrol abuse hanya soft.
  4. ADR-004 Mobile punya operator — phone/tablet adalah meja; browser adalah audiens.
  5. ADR-005 FormSpec JSON — form adalah data yang dipakai bersama builder mobile dan renderer web.
  6. ADR-006 Penamaan English — satu nama produk di specs, package, dan GitHub.
  7. ADR-007 Mobile native — Swift/SwiftUI dan Kotlin/Compose; Expo di luar cakupan untuk operator v1.
  8. ADR-008 Brand theme — token warna dan aset logo bersama di semua permukaan.
  9. ADR-009 Kecepatan build Android — jaga regenerasi Wave-1 dalam anggaran yang sama dengan iOS.
  10. ADR-010 API netral bahasa — OpenAPI + SQLite adalah kontrak; Python referensi, Java boleh.
markdown
# ADR-002 SQLite for persistence

## Decision
Use a single local SQLite database file for surveys and responses.

## Why
Matches “still running locally”, easy wipe/reset, no cloud credentials.

## Consequences
Not a multi-region SaaS store. Backup = copy the file.

Bentuk itu — Decision / Why / Consequences — adalah seluruh kebiasaan ADR. Biarkan membosankan. Agent lebih jarang berhalusinasi ketika file yang membosankan itu ada.

SHALL vs Gherkin (kebenaran sama, pekerjaan berbeda)

SHALL adalah aturan yang diperdebatkan manusia dan agent. Gherkin adalah skenario yang membuktikan aturan itu masih berlaku setelah seseorang meregenerasi apps/.

text
# From specs/requirements (illustrative)
SD-003: submit SHALL be rejected when the survey is closed.

# From specs/acceptance/lifecycle.feature
Scenario: Reject responses when closed
  Given a survey with status "closed"
  When a respondent submits answers to its public slug
  Then the API rejects the submission

OpenAPI dan FormSpec — kontrak yang bukan skenario

  • openapi.yaml — path, status code, payload. Implementasi di Python, Java, Go… selama bentuknya cocok.
  • FormSpec — tipe field JSON (short_text, rating_1_5, …) dipakai bersama builder iOS/Android dan renderer Next.js.

Urutan baca 20 menit (tanpa YouTube)

  1. Artikel ini — supaya petanya ada di kepala.
  2. Artikel catatan sesi 12 Sep — apa yang benar-benar dibahas live.
  3. specs/product/vision.md + demo journey — ceritanya.
  4. specs/adr/ADR-002, ADR-005, ADR-007, ADR-010 — tulang punggung arsitektur.
  5. Satu SHALL (mis. SD-003) + Gherkin-nya di lifecycle.feature.
  6. Baru setelah itu buka apps/ — atau minta agent mengimplementasi satu ID.

Bacaan terkait

Intinya: Gherkin adalah bukti. ADR adalah guardrail. SHALL adalah kebenaran produk. OpenAPI dan FormSpec adalah bentuk bersama. YouTube adalah warna opsional — paket spesifikasi adalah buku teksnya.

← Semua artikel

Selain Gherkin: ADR, SHALL, OpenAPI, dan sisa paket spesifikasi · suherman.net