speckit.clarify: Q&A Terstruktur Hilangkan Ambiguitas Spec Golang

speckit.clarify: Q&A Terstruktur untuk Perjelas Detail Spec

Perintah speckit clarify adalah tahap yang paling sering dilewati developer yang baru mulai dengan Spec Kit — dan justru inilah kesalahan terbesar yang mereka buat ketika membangun fitur Golang. Padahal aturannya sederhana: klarifikasi 10 menit setara dengan 2 jam debugging yang terhindar.

Di artikel ini kita bahas mengapa tahap ini sangat penting untuk menghilangkan ambiguitas spec golang, bagaimana AI menganalisis spec untuk menemukan celah yang tersembunyi, dan teknik menjawab pertanyaan klarifikasi yang efektif agar plan dan implementasi menjadi akurat.

07.1 Mengapa Klarifikasi Sangat Penting

Spec yang baru ditulis selalu punya gap. Bukan karena penulis tidak kompeten — tapi karena menulis spec berarti mengartikulasikan sesuatu yang belum pernah dibangun. Ada hal-hal yang “obvious” bagi penulis tapi ambigu bagi orang lain (dan AI).

Untuk membuat ini konkret, ambil satu contoh nyata di mana satu kalimat spec ternyata menyimpan beberapa pertanyaan yang belum terjawab.

1Spec: "Search hanya menampilkan produk aktif."
2
3Pertanyaan yang tidak terjawab:
4- Apa definisi "aktif"? Status ACTIVE saja, atau juga harus punya stock > 0?
5- Jika seller deactivate produk saat ada order pending — apa yang terjadi?
6- Apakah "active" bisa berubah menjadi system-calculated, atau hanya manual seller action?

Perhatikan bahwa ketiga pertanyaan di atas tidak muncul di permukaan spec — mereka baru terlihat ketika seseorang (atau AI) memeriksanya dengan teliti. Jika tidak dijawab, developer akan membuat keputusan sendiri yang mungkin berbeda dari intention bisnis, dan gap itulah yang berubah menjadi bug produksi.

07.2 Menjalankan specify clarify

Langkah pertama adalah menjalankan perintah clarify terhadap fitur yang specnya sudah ditulis. Perintah berikut menargetkan fitur product-search.

1specify clarify product-search

Setelah dijalankan, Spec Kit menganalisis spec.md dan menghasilkan sesi tanya-jawab interaktif. Transkrip berikut memperlihatkan bagaimana enam area ambigu ditemukan, ditanyakan satu per satu, lalu jawabannya langsung diterjemahkan menjadi update spec.

  1🔍 Analyzing spec: product-search
  2
  3Spec Kit found 6 areas that need clarification:
  4
  5━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  6
  7QUESTION 1 of 6: Product "Active" Definition
  8Category: Business Logic
  9
 10The spec says "only ACTIVE products appear in search."
 11However, the constitution defines product status as {ACTIVE, INACTIVE}.
 12
 13Clarification needed:
 14Should "active for search" consider stock level?
 15For example, should out-of-stock products (stock=0) still appear in search
 16but marked as "Out of Stock"?
 17
 18Options:
 19  A) Only ACTIVE status matters (stock level irrelevant for visibility)
 20  B) ACTIVE + stock > 0 required to appear in search
 21  C) ACTIVE status required, stock=0 shows as "Out of Stock" (still visible)
 22
 23Your answer (A/B/C or custom):
 24> C
 25
 26Spec updated: Products with ACTIVE status appear in search.
 27   Products with stock=0 are shown with "Out of Stock" badge.
 28   Products with INACTIVE status never appear.
 29
 30━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 31
 32QUESTION 2 of 6: Search Result Ranking
 33Category: Algorithm
 34
 35The spec says results are ranked by "relevance" but doesn't define how
 36relevance is calculated.
 37
 38Options:
 39  A) PostgreSQL full-text search score (tsvector ranking)
 40  B) Exact keyword match first, then partial match
 41  C) Based on a combination of: text match score + product popularity (order count)
 42  D) Custom scoring (please describe)
 43
 44Your answer:
 45> A — PostgreSQL full-text search score for now. We can enhance later.
 46
 47━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 48
 49QUESTION 3 of 6: Concurrent Search + Deactivate
 50Category: Race Condition
 51
 52Scenario: Customer submits search (query in flight) while seller deactivates
 53a product that would have been in the results.
 54
 55Should the deactivated product:
 56  A) Still appear in this search response (the query was already submitted)
 57  B) Be filtered from results even mid-query
 58  C) This scenario is acceptable (eventual consistency OK)
 59
 60Your answer:
 61> C — Eventual consistency is fine. 60-second index update is acceptable.
 62
 63━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 64
 65QUESTION 4 of 6: Search by SKU
 66Category: Scope
 67
 68The spec covers search by keyword (name + description).
 69Should SKU (product code, like "SKU-12345") also be searchable?
 70
 71  A) Yes, SKU search is in scope
 72  B) No, SKU search is out of scope (add to .specify/out-of-scope.md)
 73
 74Your answer:
 75> B — Out of scope. Customer doesn't know SKU. Seller can search by SKU
 76>     via a separate seller dashboard feature (SHOP-234).
 77
 78━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 79
 80QUESTION 5 of 6: Empty Category Filter
 81Category: Edge Case
 82
 83What happens when a customer selects a category that has no active products?
 84
 85  A) Return empty results with "No products in this category"
 86  B) Return empty results with general "No products found" message
 87  C) Hide empty categories from the filter options
 88
 89Your answer:
 90> A — Return empty with specific message. Frontend can hide empty categories
 91>     separately (that's a frontend concern, not API concern).
 92
 93━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 94
 95QUESTION 6 of 6: Search Cache Strategy
 96Category: Performance
 97
 98The NFR says p95 < 500ms. To achieve this, a cache layer might be needed.
 99
100  A) No cache (direct DB query each time)
101  B) Cache results by {keyword + category + sort + page} (Redis, TTL?)
102  C) Leave this decision to the technical plan
103
104Your answer:
105> C — Leave to technical plan. This is an implementation decision.
106
107━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
108
109Clarification complete!
110
111Updated spec: .specify/features/product-search/spec.md
112Clarifications saved: .specify/features/product-search/clarifications.md

Yang penting dari transkrip ini bukan sekadar pertanyaannya, tapi bahwa setiap jawaban langsung punya konsekuensi terhadap spec — jawaban “C” di pertanyaan pertama, misalnya, langsung menambahkan aturan badge “Out of Stock”. Inilah yang membedakan clarify dari sekadar diskusi: outputnya terdokumentasi dan mengikat.

07.3 Apa yang Disimpan di clarifications.md

Selain mengupdate spec, Spec Kit menyimpan seluruh keputusan ke file clarifications.md. Cuplikan berikut memperlihatkan format dokumentasinya — setiap entri berisi pertanyaan, jawaban, dan dampaknya ke spec.

 1# Clarifications: Product Search
 2# Date: 2025-07-02
 3# Spec version: v1.1 (after clarification)
 4
 5## Q1: Product "Active" Definition
 6**Question:** Should "active for search" consider stock level?
 7**Answer:** ACTIVE status required. stock=0 products still appear with "Out of Stock" badge.
 8**Impact:** Added AC2a to spec: "Products with stock=0 show 'Out of Stock' badge but appear in results"
 9
10## Q2: Search Result Ranking
11**Question:** How is "relevance" calculated?
12**Answer:** PostgreSQL full-text search score (ts_rank). Can be enhanced later.
13**Impact:** Added to spec: "Results ranked by PostgreSQL ts_rank score"
14
15## Q3: Concurrent Search + Deactivate
16**Question:** Race condition between search query and product deactivation?
17**Answer:** Eventual consistency acceptable. 60-second index update window is fine.
18**Impact:** No spec change needed. Documents expected behavior.
19
20## Q4: Search by SKU
21**Question:** Should SKU be searchable?
22**Answer:** Out of scope. Only name + description.
23**Impact:** Added explicit out-of-scope: "SKU-based search (tracked: SHOP-234)"
24
25## Q5: Empty Category Filter
26**Question:** What to show when category has no products?
27**Answer:** Return empty results with "No products in [category name]" message.
28**Impact:** Added AC6a to spec.
29
30## Q6: Cache Strategy
31**Question:** Should search results be cached?
32**Answer:** Leave to technical plan.
33**Impact:** Added note in NFR: "Caching strategy delegated to technical plan"

Kolom Impact inilah yang membuat file ini bernilai: enam bulan kemudian, ketika seseorang bertanya “kenapa produk stok 0 masih muncul di search?”, jawabannya ada di sini — bukan hilang di riwayat chat. Dokumen ini adalah institutional knowledge yang ter-version bersama kode.

07.4 Kategori Pertanyaan yang Diajukan AI

Spec Kit tidak mengajukan pertanyaan secara acak — ia mengelompokkannya ke dalam beberapa kategori yang masing-masing menyorot jenis risiko berbeda. Daftar berikut memberi satu contoh pertanyaan konkret per kategori.

Business Logic — ambiguitas dalam aturan bisnis

1"Spec says 'only available products.' Does 'available' mean:
2stock > 0, OR status = ACTIVE, OR both?"

Edge Cases — skenario yang tidak ter-cover di spec

1"What happens when a customer tries to search with only spaces?
2(empty string passes the 2-char minimum but has no semantic value)"

Race Conditions — skenario concurrency

1"If two customers add the last item to cart simultaneously,
2what should happen? First wins? Both get it?"

Scope Boundaries — klarifikasi batas fitur

1"The spec mentions 'user profile.' Does this include:
2a) Read-only view, OR b) Edit capabilities too?"

Performance Implications — keputusan dengan trade-off performa

1"Search across 1 million products: acceptable to scan all
2or must use full-text index?"

Security — edge case terkait keamanan

1"Can a customer search for products from a specific seller?
2Should seller information be filterable?"

Dengan memetakan pertanyaan ke enam kategori ini, kamu bisa langsung menilai bobot masing-masing: pertanyaan Business Logic dan Security biasanya harus dijawab sebelum plan, sementara Performance sering aman untuk ditunda. Kategorisasi ini menjadi kompas prioritas di sesi clarify yang panjang.

07.5 Teknik Menjawab Pertanyaan Klarifikasi

Kualitas spec akhir sangat bergantung pada kualitas jawabanmu. Empat teknik berikut membantu menjawab dengan concrete dan bisa ditelusuri kembali.

Teknik 1: STAR answers (Situation, Trade-off, Answer, Reasoning) — struktur ini memaksa jawaban menyertakan konteks dan alasan, bukan sekadar pilihan.

1Question: Should deactivated products show in search?
2
3STAR answer:
4S: Sometimes products are temporarily deactivated (stock replenishment)
5T: Always-hide vs show-with-badge (accessibility vs simplicity)
6A: Show with "Out of Stock" badge (Option C)
7R: Better UX — customer can wishlist or check back later

Teknik 2: Defer ke Technical Plan ketika sesuai — jangan mengunci detail teknis di tahap spec.

1Question: Should we use Redis cache for search results?
2
3Good answer: "Delegate to technical plan. This is implementation detail."
4
5Bad answer: "Yes, use Redis with TTL 5 minutes"
6(terlalu detail untuk tahap spec, bisa berubah setelah benchmarking)

Teknik 3: Jelaskan Implikasi dari Jawaban — sebutkan konsekuensi teknis agar plan bisa mengantisipasinya.

1Question: Minimum keyword length?
2
3Good answer: "2 characters. Note: single characters like 'a' would match too many
4products and create performance issues. This also matches Indonesian
53-letter abbreviations like 'HP' (Handphone)."

Teknik 4: Tambahkan Context untuk Jawaban Kualitatif — beri angka atau prioritas yang eksplisit.

1Question: How important is search speed vs accuracy?
2
3Good answer: "Speed priority. We'd rather return 95% accurate results in 200ms
4than 100% accurate results in 800ms. Users expect search to be instant."

Benang merah keempat teknik ini sama: jawaban yang baik selalu menyertakan alasan. Alasan itulah yang nanti membuat plan bisa mengambil keputusan teknis yang tepat tanpa harus menebak maksud bisnis di baliknya.

07.6 Memilih Pertanyaan Mana yang Perlu Dijawab

Tidak semua pertanyaan Spec Kit harus dijawab dengan detail panjang. Prioritaskan berdasarkan seberapa besar dampaknya ke acceptance criteria dan integritas data.

Priority 1 — WAJIB dijawab sebelum plan:

• Business logic ambiguities (berpengaruh ke AC)
• Security edge cases (berpengaruh ke validation)
• Data integrity scenarios (berpengaruh ke transaction boundary)

Priority 2 — Sebaiknya dijawab:

• Edge cases yang mungkin muncul di production
• Scope boundaries

Priority 3 — Boleh defer ke technical plan:

• Performance optimization strategy
• Caching decisions
• Infrastructure choices

Dengan skema tiga tingkat ini, kamu tidak akan terjebak menghabiskan waktu di pertanyaan infrastruktur sementara ambiguitas business logic yang benar-benar berbahaya justru terlewat.

07.7 specify clarify: Flags yang Berguna

Untuk sesi clarify yang lebih terarah, specify clarify menyediakan beberapa flag. Perintah berikut menunjukkan opsi yang paling sering dipakai dalam praktik sehari-hari.

 1# Hanya tampilkan pertanyaan priority tinggi
 2specify clarify product-search --priority=high
 3
 4# Jawab pertanyaan tertentu saja (by index)
 5specify clarify product-search --questions=1,3,5
 6
 7# Non-interactive mode (semua jawaban dari file)
 8specify clarify product-search --answers-file=clarify-answers.txt
 9
10# Tambahkan pertanyaan manual
11specify clarify product-search --add-question "Should search respect user blocklist?"
12
13# Skip pertanyaan tertentu (defer to plan)
14specify clarify product-search --skip=6

Flag --priority=high dan --answers-file sangat berguna di tim: yang pertama mempercepat review fitur besar, yang kedua memungkinkan clarify dijalankan otomatis di CI dengan jawaban yang sudah disepakati. Sesuaikan flag dengan konteks, jangan selalu jalankan mode interaktif penuh.

07.8 Clarify untuk Fitur yang Sudah Punya Kode

Kadang kamu perlu clarify spec untuk fitur yang sudah diimplementasikan sebagian. Flag --with-code membuat Spec Kit membaca kode existing dan menanyakan apakah spec sudah mencerminkannya.

1# Clarify berdasarkan kode yang sudah ada
2specify clarify product-search --with-code=internal/product/
3
4# Output akan mention: "The code already handles X, does the spec reflect this?"

Pola ini berguna untuk tiga situasi: membuat spec retroaktif untuk kode lama, menuliskan spec setelah proof-of-concept, dan menyelaraskan implementasi dengan spec yang mulai divergen. Intinya, clarify tidak hanya untuk fitur greenfield — ia juga alat rekonsiliasi antara kode dan dokumentasi.

07.9 Pertanyaan yang Sering Muncul per Domain

Seiring pengalaman, kamu akan melihat pola pertanyaan yang berulang per domain. Mengenali pola ini membantu kamu mengantisipasi jawaban bahkan sebelum Spec Kit bertanya.

Untuk fitur E-commerce:

1- Apa yang terjadi jika cart expired saat checkout?
2- Bagaimana handle concurrent order untuk produk stok 1?
3- Apakah harga bisa berubah saat item ada di cart?
4- Siapa yang bayar shipping: customer atau seller?

Untuk fitur Authentication:

1- Berapa lama JWT valid?
2- Apa yang terjadi saat refresh token expired?
3- Apakah bisa login dari multiple device?
4- Bagaimana handle password yang sama dengan yang lama?

Untuk fitur Notification:

1- Apa yang terjadi jika email bounce?
2- Berapa retry attempt untuk failed notification?
3- Apakah user bisa opt-out dari notifikasi tertentu?
4- Real-time atau delayed (batch)?

Jika kamu perhatikan, mayoritas pertanyaan ini menyangkut edge case dan concurrency — bukan happy path. Menyiapkan jawaban untuk daftar seperti ini sebelum sesi clarify akan memangkas durasi tanya-jawab secara signifikan.

07.10 Menyimpan Jawaban sebagai Institutional Knowledge

Jawaban klarifikasi adalah aset berharga yang tidak boleh hilang di chat history. Perintah berikut menunjukkan bahwa clarifications.md tersimpan otomatis dan bisa dicari lintas fitur.

1# clarifications.md secara otomatis disimpan
2cat .specify/features/product-search/clarifications.md
3
4# Untuk search yang lebih mudah ke depannya
5specify search "stock=0 visibility"
6# → Finds: product-search/clarifications.md Q1
7# → Finds: cancel-order/clarifications.md Q3

Kemampuan specify search menelusuri seluruh keputusan lintas fitur mengubah clarifications.md dari sekadar arsip menjadi basis pengetahuan yang bisa dikueri. Ini persis yang membedakan tim yang belajar dari keputusannya dengan tim yang mengulang perdebatan yang sama tiap kuartal.

07.11 Clarify sebagai Review Mechanism

Selain untuk menghilangkan ambiguitas, sesi clarify bisa dipakai sebagai mekanisme review antar developer. Cuplikan berikut membandingkan alur clarify berdua dengan diskusi ad-hoc yang tidak terstruktur.

 1# Developer A menulis spec
 2specify feature product-search
 3
 4# Developer B run clarify dan jawab pertanyaan bersama
 5specify clarify product-search
 6# (berdua di screen sharing)
 7
 8# Ini jauh lebih efektif dari:
 9# Developer B: "Ini specnya gimana edge casenya?"
10# Developer A: "Gimana maksudnya?"
11# Developer B: "Yang kalau produknya habis..."
12# [5 menit diskusi tidak produktif]

Perbedaannya jelas: pertanyaan Spec Kit sudah terstruktur dan lengkap, sehingga diskusi berdua langsung fokus ke keputusan alih-alih meraba-raba apa yang perlu didiskusikan. Clarify menjadi agenda review yang siap pakai.

07.12 Integrasi clarify dengan Jira Comments

Agar keputusan clarify terlihat oleh stakeholder non-teknis, hasilnya bisa langsung dikirim ke Jira. Perintah berikut menautkan sesi clarify ke sebuah tiket.

1# Simpan hasil klarifikasi ke Jira comment
2specify clarify product-search --jira=SHOP-123
3
4# Output: Jira comment ditambahkan:
5# "Spec clarification completed. Key decisions:
6#  - Products with stock=0 show as 'Out of Stock' but visible in search
7#  - Ranking uses PostgreSQL full-text search score
8#  - SKU search is out of scope (SHOP-234)"

Dengan integrasi ini, PM dan tech lead bisa melihat keputusan penting tanpa perlu membuka repo. Jembatan antara dokumentasi teknis dan alat manajemen proyek inilah yang menjaga semua pihak tetap sinkron.

07.13 Clarification yang Mengubah Scope

Terkadang proses klarifikasi justru mengungkap bahwa fitur perlu di-scope-ulang. Contoh berikut memperlihatkan momen ketika sebuah jawaban membuka kebutuhan yang sebelumnya terlupa.

 1Question 4: Should the search also support filtering by price range?
 2
 3Developer: "Actually yes, product manager mentioned this during planning..."
 4→ Price filter WAS in scope but forgotten during specify feature!
 5
 6Correct action:
 71. Jawab "Yes, price filter is in scope"
 82. Spec Kit menambahkan AC baru ke spec.md
 93. Note: "Scope increased from initial spec. PM approval needed."
104. Update Jira ticket dengan scope change

Jika clarify malah menunjukkan feature terlalu besar, langkah yang tepat adalah memecahnya menjadi beberapa fitur terpisah, seperti berikut.

1→ Option: Split ke dua fitur terpisah
2→ specify feature product-search/core
3→ specify feature product-search/advanced-filters

Poin pentingnya: clarify bukan hanya mempertajam spec yang ada, tapi juga berfungsi sebagai gerbang scope control. Perubahan scope yang tertangkap di sini jauh lebih murah daripada yang ketahuan saat implementasi.

07.14 Waktu Optimal untuk Clarify

Timing menentukan seberapa besar manfaat clarify. Aturan mainnya sederhana namun sering diabaikan.

Waktu terbaik: Segera setelah specify feature, sebelum specify plan.

Jangan tunda clarify karena:

• Plan yang dibuat tanpa klarifikasi akan punya asumsi yang mungkin salah
• Kode yang dihasilkan dari plan yang salah = technical debt
• Fix setelah implementation = expensive

Berapa lama harusnya?

• Spec sederhana (CRUD): 5-10 menit
• Spec dengan business logic: 10-20 menit
• Spec dengan concurrency/security: 20-30 menit

Angka durasi di atas menegaskan bahwa clarify adalah investasi menit, bukan jam — dan return-nya berlipat karena mencegah kesalahan mengalir ke plan dan kode. Jalankan clarify tepat setelah spec, jangan menunggu.

07.15 Mengukur Kualitas Clarification

Setelah sesi selesai, kamu bisa mengukur seberapa efektif clarify tersebut. Flag --report menghasilkan ringkasan kuantitatif seperti berikut.

 1# Quality report setelah clarify
 2specify clarify product-search --report
 3
 4# Output:
 5# Clarification Quality Report: product-search
 6# Questions asked: 6
 7# Questions answered: 6
 8# ACs added/modified: 3
 9# Out-of-scope items clarified: 1
10# Spec completeness: 94% (from 71% before clarify)
11# Estimated implementation risk reduced: 43%

Metrik seperti “spec completeness 94% dari 71%” mengubah nilai clarify dari klaim subjektif menjadi angka yang bisa ditunjukkan ke stakeholder. Gunakan report ini untuk membuktikan bahwa waktu yang dihabiskan di clarify memang menurunkan risiko implementasi secara terukur.

07.16 Clarify untuk Microservice Boundary

Pada arsitektur microservice, pertanyaan clarify sering menyentuh soal kepemilikan data antar service. Contoh berikut adalah pertanyaan khas untuk fitur yang melibatkan service boundary.

1Question: Who owns the canonical product data — Product Service or Search Service?
2
3A) Product Service is source of truth; Search Service reads via Kafka events
4B) Search Service maintains its own copy synchronized via Kafka
5C) Shared database (not recommended per constitution)
6
7Answer: B — Search Service maintains own optimized read model
8Impact: Plan will show Kafka consumer setup for product events

Keputusan boundary seperti ini punya efek berantai besar ke plan: memilih opsi B berarti plan harus menyiapkan konsumer Kafka dan read model terpisah. Menyelesaikannya di clarify mencegah dua tim membangun asumsi kepemilikan data yang bertabrakan.

07.17 Hasil Clarify yang Ideal

Bagaimana bentuk spec yang “matang” setelah clarify? Cuplikan berikut menunjukkan spec ideal — bertanda status CLARIFIED, dengan tabel keputusan dan AC yang sudah diperbarui.

 1## Status: CLARIFIED (ready for plan)
 2
 3## Key Decisions from Clarification (2025-07-02)
 4
 5| Decision | Choice | Rationale |
 6|----------|--------|-----------|
 7| Stock=0 visibility | Show with "Out of Stock" badge | Better UX for wishlist |
 8| Relevance ranking | PostgreSQL ts_rank | Sufficient for phase 1 |
 9| SKU search | Out of scope | Seller-only feature (SHOP-234) |
10| Cache strategy | Delegate to plan | Implementation decision |
11
12## Acceptance Criteria (Updated after Clarification)
13
14- AC1: [...original...]
15- AC2: Products with ACTIVE status appear in search
16- AC2a: Products with stock=0 display "Out of Stock" badge but still appear [NEW]
17- AC6: System shows "No products found for '[keyword]'" when no results [CLARIFIED]
18- AC6a: Empty category shows "No products in [category name]" [NEW]

Tanda [NEW] dan [CLARIFIED] pada setiap AC membuat jejak perubahan terlihat: reviewer bisa langsung tahu mana yang muncul dari clarify. Spec seperti inilah yang siap dilempar ke specify plan tanpa menyisakan asumsi tersembunyi.

07.18 Tips & Gotchas

Sebelum menutup, berikut beberapa tips praktis dan jebakan umum yang perlu kamu waspadai saat menjalankan clarify.

💡 Tip 1: Jangan skip clarify bahkan untuk “simple” features — feature yang terlihat simple sering punya edge case tersembunyi yang justru ditemukan Spec Kit.

💡 Tip 2: Jawab bersama PM dan tech lead untuk decisions penting — keputusan business logic harus di-approve PM, jangan dijawab sendirian.

💡 Tip 3: Gunakan opsi “Delegate to plan” untuk keputusan teknikal — cache strategy, database index, event schema lebih tepat ada di plan, bukan spec.

💡 Tip 4: Simpan jawaban “surprising” untuk knowledge sharing — jika ada jawaban yang mengejutkan, share di standup atau team channel.

⚠️ Gotcha 1: Clarify yang terlalu cepat = edge cases terlewat — jangan terburu-buru; luangkan waktu memikirkan setiap pertanyaan.

⚠️ Gotcha 2: Jawaban yang bertentangan dengan constitution — jika jawaban klarifikasi melanggar constitution, flag ini; mungkin constitution yang perlu diupdate.

⚠️ Gotcha 3: Tidak semua pertanyaan relevan untuk sprint ini — pertanyaan tentang fitur yang jelas di-defer sebaiknya ditandai out-of-scope.

⚠️ Gotcha 4: Clarify tidak sama dengan design session — jika clarify berubah menjadi redesign, stop dan jadwalkan design meeting terpisah.

Benang merah semua gotcha di atas: clarify adalah alat untuk menajamkan spec, bukan untuk mendesain ulang fitur atau membuat keputusan bisnis sendirian. Jaga sesi tetap fokus pada ambiguitas.

07.19 Clarify sebagai Input ke Plan

Nilai akhir clarify baru terlihat di tahap berikutnya. Perintah berikut menunjukkan bagaimana specify plan membaca spec dan clarifications sekaligus.

1specify plan product-search
2# Reads: constitution.md + spec.md (updated) + clarifications.md
3
4# Plan yang dihasilkan akan mencerminkan keputusan dari clarify:
5# - Stock=0 handling di repository layer
6# - ts_rank di SQL query
7# - Empty category message di handler

Perhatikan bahwa setiap keputusan clarify muncul kembali sebagai elemen teknis konkret di plan. Tanpa clarify, plan akan penuh asumsi yang mungkin salah; dengan clarify, plan menjadi akurat dan langsung implementable.

07.20 Ringkasan

Perintah specify clarify adalah tahap yang paling underestimated tapi paling high-value dalam siklus Spec Kit. Sepuluh sampai dua puluh menit klarifikasi menghasilkan spec yang jauh lebih complete dan plan yang jauh lebih accurate.

Apa yang dilakukan Spec Kit: menganalisis spec.md, mengidentifikasi ambiguitas berdasarkan business logic, edge case, dan concurrency scenario, lalu mengajukan pertanyaan terstruktur per kategori.

Jawaban terbaik: concrete, disertai rationale, dan tahu kapan harus defer ke technical plan.

Output: spec.md yang di-update plus clarifications.md yang mendokumentasikan semua keputusan sebagai institutional knowledge.

Jangan pernah skip tahap ini. Waktu yang dihemat dari klarifikasi selalu lebih besar dari waktu yang dihabiskan untuk menjawab pertanyaannya. Di artikel berikutnya, kita bawa spec yang sudah CLARIFIED ini ke tahap perencanaan teknis.