speckit.specify: Cara Menulis Kebutuhan Fitur Golang Tanpa Tech Stack
Panduan lengkap menggunakan speckit.specify untuk menulis spesifikasi fitur Golang yang bersih: user story, business rules, dan scope definition yang efektif tanpa menyebut tech stack.
speckit.specify: Tulis Kebutuhan Tanpa Sebut Tech Stack
Perintah specify feature (atau speckit.specify) adalah titik masuk untuk menulis feature specification Golang dan menjadi perintah yang paling sering dijalankan dalam workflow sehari-hari. Setiap fitur baru dimulai dari sini — dan kunci keberhasilannya adalah satu prinsip sederhana: tuliskan apa yang user butuhkan, bukan bagaimana cara membangunnya.
Di artikel ini, kita bahas teknik untuk mendapatkan spec.md yang terbaik dari specify feature, lengkap dengan contoh dan checklist review.
06.1 Filosofi: Feature Spec yang Bebas Tech
Spec yang baik bisa dibaca oleh:
- Business analyst yang tidak tahu Go
- Frontend developer yang tidak tahu PostgreSQL
- Product manager yang tidak tahu apa itu goroutine
Jika spec kamu penuh dengan pgx.Pool, echo.Context, atau kafka.Producer, itu bukan spec — itu adalah catatan implementasi awal.
Spec yang baik menjawab: siapa yang butuh apa, dan apa aturan bisnisnya?
Spec yang buruk menjawab: bagaimana cara implement menggunakan library X?
06.2 Menjalankan specify feature
Untuk membuat spec baru, jalankan perintah dengan nama fitur sebagai argumen seperti berikut.
1specify feature product-searchSetelah perintah dijalankan, Spec Kit akan memandu kamu lewat sesi tanya-jawab interaktif. Transkrip berikut menunjukkan pertanyaan yang diajukan beserta contoh jawabannya.
1📋 Creating Feature Specification: product-search
2
31. Describe this feature in 2-3 sentences:
4> Customers can search for products using keywords.
5> Results are ranked by relevance and filtered by category.
6> Search includes product name and description.
7
82. Who will use this feature?
9> Customer (searching for products to buy)
10> System (indexing products when they're created/updated)
11
123. What MUST users be able to do?
13> Search products by keyword (partial match OK)
14> Filter search results by category
15> Sort results (relevance, newest, price low-high, price high-low)
16> See "no results" message when nothing matches
17
184. What MUST NOT happen?
19> Deactivated products must not appear in search results
20> Search must not expose seller information to customers
21> Empty keyword search should not be allowed (minimum 2 chars)
22
235. Business rules and constraints?
24> Minimum keyword length: 2 characters
25> Maximum results per page: 50
26> Search indexes: product name and description only (not internal notes)
27> Category filter is optional
28
296. What is explicitly OUT OF SCOPE for this feature?
30> Autocomplete/typeahead suggestions
31> Search analytics and tracking
32> Personalized search results based on user history
33> Price range filter (separate ticket)Dari transkrip di atas, semua jawaban berpusat pada perilaku user dan aturan bisnis — tidak ada satu pun yang menyebut library atau schema. Hasil akhirnya disimpan otomatis di .specify/features/product-search/spec.md.
06.3 Anatomy spec.md yang Dihasilkan
Dari jawaban interaktif tadi, Spec Kit menyusun dokumen spec yang terstruktur. Contoh berikut adalah spec.md lengkap dengan user story, acceptance criteria, dan business rules.
1# Feature Specification: Product Search
2
3## Status: DRAFT
4## Created: 2025-07-02
5## Feature Code: SHOP-123
6
7---
8
9## Context
10
11The product search feature enables customers to find relevant products
12on Santekno Shop quickly and accurately. Without this feature, customers
13must scroll through all products — unacceptable at catalog scale.
14
15---
16
17## User Stories
18
19### Primary: Customer Searching for Products
20
21**As a customer** browsing Santekno Shop,
22**I want to** search for products using keywords
23**so that** I can find specific products without scrolling through the entire catalog.
24
25**Acceptance Criteria:**
26
27- AC1: Customer can type keywords in search box and see matching products
28- AC2: Results show only ACTIVE products (deactivated products never appear)
29- AC3: Search matches keywords in product name and description
30- AC4: Customer can filter results by product category
31- AC5: Customer can sort results by: Relevance | Newest | Price Low-High | Price High-Low
32- AC6: System shows "No products found" when no results match
33- AC7: Empty search (< 2 characters) is rejected with descriptive error message
34- AC8: Results are paginated (default 20 per page, max 50)
35
36### Secondary: Catalog Freshness
37
38**As the system**,
39**I want to** index new and updated products automatically
40**so that** search results always reflect the current product catalog.
41
42- AC9: When a product is created, it becomes searchable within 60 seconds
43- AC10: When a product is deactivated, it stops appearing in search within 60 seconds
44
45---
46
47## Business Rules
48
491. **Minimum query length:** 2 characters. One-character searches are invalid.
502. **Active products only:** Status = ACTIVE. Deactivated products are invisible to customers.
513. **Search fields:** Product name and description only. Seller notes not searchable.
524. **Category filter:** Optional. When set, AND with keyword filter.
535. **Sort options:** relevance | newest | price_asc | price_desc
546. **Pagination:** Default page size 20, maximum 50 per request.
557. **No empty results page without context:** Show "No products found for '[keyword]'"
56
57---
58
59## What This Feature Is NOT (Out of Scope)
60
61- ❌ Autocomplete/typeahead (tracked: SHOP-124)
62- ❌ Search analytics (tracked: SHOP-125)
63- ❌ Personalized results (tracked: SHOP-126)
64- ❌ Price range filter (tracked: SHOP-127)
65- ❌ Saved searches
66
67---
68
69## Success Criteria
70
71The feature is considered complete when:
721. A customer can type "laptop" and see relevant active products
732. A customer can filter by "Electronics" category
743. Deactivated products do NOT appear in any search result
754. Response time is acceptable (this will be defined in NFR section)Perhatikan struktur di atas: setiap AC diberi nomor sehingga bisa langsung dipetakan ke test, dan bagian out-of-scope ditulis eksplisit dengan referensi tiket — dua ciri spec yang siap di-review.
06.4 Teknik untuk Spec yang Lebih Baik
Teknik 1: User Story dengan Role Spesifik
Perbandingan berikut menunjukkan perbedaan antara user story yang generik dan yang spesifik.
1❌ Terlalu generik:
2"As a user, I want to search products"
3
4✅ Role spesifik:
5"As a customer shopping on Santekno Shop,
6I want to find products using keywords,
7so that I can quickly locate what I'm looking for"Role yang spesifik memberi konteks siapa yang benar-benar terlayani, sehingga AI dan reviewer bisa menilai apakah kebutuhannya sudah terpenuhi.
Teknik 2: Business Rules yang Measurable
Aturan bisnis harus bisa diukur, bukan sekadar aspirasi. Bandingkan dua versi berikut.
1❌ Ambigu:
2"Search results should be relevant"
3
4✅ Measurable:
5"Search matches keywords in product name and description.
6Results are ranked by text similarity score (higher = first)"Versi measurable bisa langsung diterjemahkan menjadi kriteria pengujian, sedangkan versi ambigu akan memicu interpretasi yang berbeda-beda antar developer.
Teknik 3: Out of Scope yang Explicit
Selalu sertakan explicit “out of scope” section dengan Jira/Linear ticket reference. Ini mencegah scope creep dan membuat keputusan sadar tentang apa yang tidak dibangun.
Teknik 4: Success Criteria yang Concrete
Success criteria yang baik menyebutkan hasil yang bisa diverifikasi, seperti contoh berikut.
1✅ Concrete success criteria:
2"Feature complete when:
31. curl test returns active products matching 'laptop' keyword
42. Deactivated products never in search results (automated test)
53. Category filter reduces result set correctly"Dengan success criteria yang konkret seperti ini, tidak ada ambiguitas kapan sebuah fitur dianggap “selesai”.
06.5 Spec untuk Fitur Internal (Service-to-Service)
Tidak semua fitur adalah user-facing. Untuk fitur internal seperti API antar service, perintahnya tetap sama seperti berikut.
1specify feature stock-deduction-apiSesi tanya-jawab untuk fitur internal berfokus pada kontrak antar service dan jaminan konsistensi data, seperti terlihat pada transkrip berikut.
11. Describe this feature:
2> Internal API for Order Service to atomically reduce product stock
3> when an order is confirmed. Must prevent overselling.
4
52. Who uses this?
6> Order Service (internal, service-to-service only)
7> Not customer-facing
8
93. What MUST happen?
10> Stock deduction must be atomic across multiple products in one transaction
11> Must return which specific products failed (insufficient stock)
12> Must be idempotent: same request twice = same result (no double deduction)
13
144. What MUST NOT happen?
15> Stock must never go negative
16> Operation must not partially succeed (all or nothing)Spec untuk internal API sama pentingnya dengan spec user-facing — bahkan mungkin lebih penting, karena kegagalannya bisa menyebabkan data corruption seperti overselling stok.
06.6 Flag dan Options untuk specify feature
Selain mode interaktif, specify feature menyediakan sejumlah flag untuk otomasi dan kustomisasi. Kumpulan perintah berikut merangkum opsi yang paling sering dipakai.
1# Buat spec dari input file (berguna dari Jira description)
2specify feature product-search --input=ticket.txt
3
4# Override output directory
5specify feature product-search --output=.specify/features/v2/
6
7# Gunakan custom template
8specify feature product-search --template=api-feature-template
9
10# Non-interactive mode (dengan semua jawaban via flags)
11specify feature product-search \
12 --description="Customer product search with keyword and category filter" \
13 --users="Customer" \
14 --capabilities="Search by keyword, filter by category, paginate results" \
15 --rules="Min 2 chars, active products only, max 50 per page" \
16 --out-of-scope="Autocomplete, personalization, price filter"
17
18# Dry run (preview spec tanpa save)
19specify feature product-search --dry-runMode non-interaktif (--description, --users, dst.) sangat berguna untuk otomasi CI atau membuat spec massal dari daftar tiket, sementara --dry-run membantu kamu meninjau hasil sebelum menyimpannya.
06.7 Iterasi spec.md
Setelah spec dibuat, kamu bisa iterasi sebelum di-approve. Perintah berikut mencakup edit manual, regenerate, penambahan AC, hingga update status.
1# Buka spec untuk edit manual
2vim .specify/features/product-search/spec.md
3
4# Atau regenerate dengan prompt yang berbeda
5specify feature product-search --regenerate
6
7# Tambahkan AC yang terlewat
8specify feature product-search --add-ac "AC11: Search results show product thumbnail"
9
10# Update status
11specify feature product-search --status=APPROVEDAlur iterasi ini menegaskan bahwa spec adalah dokumen hidup — kamu tidak perlu menunggu sempurna di percobaan pertama, cukup perbaiki bertahap sampai statusnya APPROVED.
06.8 Spec Review: Pertanyaan Reviewer
Saat spec di-submit untuk review, reviewer perlu panduan konkret. Checklist berikut memandu pengecekan kualitas user story, AC, business rules, dan scope.
1🔍 Spec Review Checklist
2
3User Story Quality:
4✅ Role spesifik (bukan "user")?
5✅ Benefit (so that...) jelas dan valuable?
6✅ Story bisa dipahami non-technical stakeholder?
7
8Acceptance Criteria:
9✅ Setiap AC bisa jadi satu test function?
10✅ AC tidak menyebutkan implementasi detail?
11✅ Error cases ter-cover?
12✅ Happy path ter-cover?
13
14Business Rules:
15✅ Semua rules measurable?
16✅ Tidak ada ambiguity?
17✅ Consistent dengan rules di fitur lain?
18
19Out of Scope:
20✅ Explicit tentang apa yang TIDAK dibangun?
21✅ Ticket reference untuk out-of-scope items?Menjadikan checklist ini sebagai gate review memastikan spec yang lolos benar-benar bebas ambiguitas dan siap dijadikan kontrak implementasi.
06.9 Spec dan Non-Functional Requirements
Spec.md dari specify feature adalah untuk functional requirements. Non-functional requirements (NFR) ditambahkan sebagai section terpisah, seperti contoh berikut.
1## Non-Functional Requirements
2
3### Performance
4- Search endpoint: < 500ms p95 at 100 concurrent users
5- Search index update: < 60 seconds from product creation/update
6
7### Availability
8- Must be available when product listing is available
9- Graceful degradation: if search index unavailable, return error (not empty results)
10
11### Security
12- Search results must never expose seller internal data
13- Rate limit: 60 searches per minute per userUntuk fitur yang performance-critical, selalu tambahkan NFR section seperti ini. Angka-angka di dalamnya akan dijadikan target teknis oleh specify plan di tahap berikutnya.
06.10 Spec untuk API yang Sudah Ada (Retroactive)
Jika kamu perlu membuat spec untuk fitur yang sudah terlanjur diimplementasikan, Spec Kit bisa meng-infer spec dari kode. Perintahnya seperti berikut.
1# Mode retroactive: analyze existing code and generate spec
2specify feature product-list --from-code=internal/product/handler/
3
4# Output: spec yang di-infer dari kode existing
5# Tandai dengan [INFERRED] untuk bagian yang di-generate otomatisMode retroactive ini berguna untuk mendokumentasikan fitur lama, membuat baseline sebelum refactoring besar, atau menyediakan audit trail bagi fitur yang belum punya spec.
06.11 Spec Quality Score
Spec Kit bisa menilai kualitas spec secara otomatis. Perintah berikut menghasilkan laporan skor per kategori.
1# Run quality check pada spec
2specify spec quality product-search
3
4# Output:
5# 📊 Spec Quality Report: product-search
6#
7# User Stories: ✅ 2/2 stories have clear role and benefit
8# Acceptance Criteria: ⚠️ 10/11 ACs are testable (AC5 is ambiguous)
9# Business Rules: ✅ 4/4 rules are measurable
10# Out of Scope: ✅ Explicit section with ticket references
11# NFR: ⚠️ No performance targets defined
12#
13# Overall Score: 82/100
14# Recommendation: Add performance targets and clarify AC5Laporan seperti ini menunjukkan secara spesifik bagian mana yang masih lemah (di sini AC5 dan NFR), sehingga perbaikan bisa terarah alih-alih menebak-nebak.
06.12 Berbagai Jenis Spec yang Didukung
Spec Kit mendukung berbagai tipe fitur, bukan hanya REST API. Daftar perintah berikut menunjukkan variasi tipe yang bisa di-generate.
1# REST API feature
2specify feature order-cancellation
3
4# Background job
5specify feature cleanup-expired-carts
6
7# Event consumer
8specify feature order-notification-consumer
9
10# Kafka event producer
11specify feature order-created-event
12
13# Internal API (service-to-service)
14specify feature stock-reservation-api
15
16# Scheduled task
17specify feature daily-sales-report
18
19# Database migration (schema change)
20specify feature add-product-variantsFormat spec.md sedikit berbeda untuk setiap tipe, tapi filosofinya tetap sama: deskripsikan behavior, bukan implementasi.
06.13 Spec Versioning
Spec yang berubah seiring waktu perlu changelog agar setiap revisi bisa dilacak. Contoh berikut menunjukkan blok versi di header spec.
1# Feature: Product Search
2# Spec Version: v1.3
3# Status: APPROVED
4# Changelog:
5# v1.3 (2025-07-05): Added AC11 - search history display
6# v1.2 (2025-07-03): Clarified AC2 - deactivated product exclusion
7# v1.1 (2025-07-02): Added NFR section
8# v1.0 (2025-07-01): Initial draftVersi spec kemudian harus direferensikan langsung di kode implementasi, seperti komentar berikut.
1// product_search_usecase.go
2// Implements: .specify/features/product-search/spec.md v1.3
3// AC1-AC8: customer search (implemented here)
4// AC9-AC10: indexing (implemented in product_indexer.go)Dengan menautkan versi spec ke file kode seperti ini, siapa pun yang membaca implementasi bisa langsung menelusuri kembali ke kebutuhan asli beserta AC yang di-cover.
06.14 Collaboration: Spec sebagai Kontrak
Spec.md yang sudah di-approve adalah kontrak antara:
- Engineering dan Product: “inilah yang akan kita build”
- Backend dan Frontend: “inilah API yang akan ada”
- Tim dan AI: “inilah context untuk generate kode”
Ketika ada pertanyaan “apakah kita harus handle edge case X?”, jawabannya ada di spec. Jika tidak ada di spec, itu out of scope dan harus dibuat ticket baru.
06.15 Spec sebagai Test Plan
Setiap AC di spec seharusnya menjadi satu test case. Pemetaan berikut menunjukkan hubungan langsung antara AC dan nama test function.
1AC1 → TestProductSearch_WithKeyword_ReturnsMatchingProducts
2AC2 → TestProductSearch_DeactivatedProduct_NotInResults
3AC3 → TestProductSearch_MatchesNameAndDescription
4AC4 → TestProductSearch_WithCategoryFilter_FiltersCorrectly
5AC5 → TestProductSearch_SortByPrice_OrderCorrect
6AC6 → TestProductSearch_NoResults_ReturnsEmptyWithMessage
7AC7 → TestProductSearch_ShortKeyword_ReturnsValidationError
8AC8 → TestProductSearch_Pagination_ReturnsCorrectPagePemetaan satu-AC-satu-test inilah “spec-to-test” mapping yang kita bahas di Topik #1 — dan menjadi alasan mengapa AC harus ditulis measurable sejak awal.
06.16 Integrating Existing Specs dari Topik #1
Jika kamu sudah punya specs dalam format Topik #1 (folder specs/), Spec Kit bisa mengimpornya. Perintah berikut mengonversi spec lama ke format .specify/features/.
1# Import existing spec ke Spec Kit format
2specify feature product-search --import-from=specs/product/search.md
3
4# Spec Kit akan convert ke format .specify/features/ dan
5# menambahkan missing sections (out-of-scope, quality score)Fitur impor ini memuluskan migrasi dari manual SDD ke Spec Kit tanpa harus menulis ulang spec dari nol, sekaligus melengkapi bagian yang sebelumnya belum ada.
06.17 Spec Workshop: Teknik untuk Tim
Cara terbaik menulis spec dalam konteks tim adalah lewat workshop terstruktur. Alur berikut menunjukkan pembagian peran dari PM hingga engineering.
11. Product Manager menulis user story dan acceptance criteria
22. Tech Lead review untuk technical feasibility
33. QA menambahkan edge cases yang terlewat
44. Semua review "out of scope" section
55. Tech Lead approve spec
66. Spec masuk ke Jira sebagai "Spec Approved"
77. Engineering mulai implementationAlur peran di atas memastikan setiap sudut pandang — bisnis, teknis, dan QA — ikut membentuk spec sebelum implementasi dimulai. Workshop ini bisa diintegrasikan langsung dengan specify feature seperti berikut.
1# Mode collaborative: output ke shared doc untuk comment
2specify feature product-search --output-format=google-docsDengan output ke shared doc, seluruh peserta workshop bisa memberi komentar secara paralel sebelum spec difinalisasi.
06.18 Tips & Gotchas
💡 Tip 1: Mulai dari “apa yang user mau,” bukan “apa yang bisa kita build”
Developer cenderung memikirkan implementasi saat menulis spec. Paksa diri untuk hanya memikirkan user behavior.
💡 Tip 2: Out of scope sama pentingnya dengan in scope
Explicit out-of-scope mencegah scope creep dan memberikan ruang untuk berkata “ini bukan bagian dari ticket ini.”
💡 Tip 3: Gunakan angka konkret untuk business rules
“Min 2 chars” lebih baik dari “minimal beberapa karakter.”
💡 Tip 4: Acceptance criteria harus bisa jadi test
Sebelum submit spec, coba tulis nama test function untuk setiap AC. Jika susah ditulis, AC terlalu ambigu.
⚠️ Gotcha 1: “Obvious” requirements sering tidak ditulis
Developer sering skip obvious things seperti “hanya active products yang muncul.” Tulis semuanya.
⚠️ Gotcha 2: Spec yang terlalu panjang tidak dibaca
Target 1-2 halaman. Jika lebih, pecah menjadi multiple features.
⚠️ Gotcha 3: Jangan tulis spec tanpa tahu user journey-nya
Spec yang ditulis tanpa pemahaman user journey sering miss edge cases penting.
⚠️ Gotcha 4: Jangan tunggu perfect spec
“Good enough spec + clarify” lebih baik dari “perfect spec yang memakan waktu 3 hari.”
06.19 Multi-Feature Spec: Ketika Satu Ticket Terlalu Besar
Jika satu ticket terlalu besar untuk satu spec, pecah menjadi parent dan child specs. Perintah berikut membuat hierarki fitur.
1# Buat parent spec (high-level)
2specify feature product-management
3
4# Buat child specs (detail)
5specify feature product-management/create
6specify feature product-management/update
7specify feature product-management/search
8specify feature product-management/deactivatePerintah di atas menghasilkan struktur folder berjenjang, di mana parent spec berperan sebagai overview dan setiap child menyimpan detailnya sendiri.
1.specify/features/
2└── product-management/
3 ├── spec.md ← Parent spec (overview)
4 ├── create/
5 │ └── spec.md
6 ├── update/
7 │ └── spec.md
8 └── search/
9 └── spec.mdStruktur hierarkis ini menjaga fitur besar tetap terkelola: satu overview di level atas, detail terpisah di setiap sub-fitur yang bisa dikerjakan mandiri.
06.20 Ringkasan
specify feature adalah pintu masuk ke siklus SDD dengan Spec Kit. Kuncinya adalah menulis apa yang user butuhkan, bukan bagaimana cara mengimplementasikannya.
Format yang efektif: User story dengan role spesifik + numbered acceptance criteria + explicit business rules + concrete out-of-scope section.
Jangan: menyebut tech stack, library, SQL, atau implementation detail apapun.
Quality signal: Jika PM bisa membaca dan mengerti spec kamu, kamu on the right track.
Iterasi adalah wajar: Spec v1 jarang langsung sempurna. Gunakan specify clarify di artikel berikutnya untuk mengisi gap yang tersisa.