Spec Kit untuk Tim Golang: Onboarding dan Shared Constitution

1Masalah umum:
2- "Spec ada di dokumen Google Docs yang sudah 3 versi lama"
3- "PR review butuh waktu lama karena reviewer tidak paham konteks"
4- "Kode yang sama di-implement berbeda oleh developer berbeda"
5- "Developer baru butuh 2 minggu untuk paham codebase"
6- "Tidak jelas apakah implementasi sesuai requirement atau tidak"

 1# Sesi constitution writing (workshop, bukan individual)
 2# Libatkan: tech lead, 2-3 senior developer, product
 3
 4specify constitution
 5
 6# Prompts:
 7# - "Apa arsitektur yang kita gunakan dan mengapa?"
 8# - "Apa convention naming yang harus diikuti?"
 9# - "Apa yang tidak boleh dilakukan di codebase ini?"
10# - "Bagaimana error handling yang benar?"

 1# Constitution: Santekno Shop
 2# Version: 2.0
 3# Last reviewed: 2025-07-01
 4# Reviewed by: @budi (tech lead), @andi, @citra, @dewi
 5
 6## Prinsip Arsitektur
 7
 8### Clean Architecture
 9WAJIB ikuti layer ini (tanpa exception):
101. Domain: entity, value object, repository interface, usecase interface
112. UseCase: business logic, tidak boleh import repository implementation
123. Repository: implementasi persistence, import hanya domain package
134. Delivery: HTTP handler, import usecase interface
14
15Dependency rule: lapisan luar boleh import lapisan dalam, TIDAK sebaliknya.
16Violation contoh: usecase yang import delivery/http = PELANGGARAN SERIUS.
17
18### Error Handling
191. Repository: return (nil, nil) untuk not found, bukan error
202. UseCase: return domain error types (ErrNotFound, ErrForbidden, etc.)
213. Handler: mapping domain errors ke HTTP status + error code JSON
224. Error code format: UPPERCASE_SNAKE_CASE
235. Error wrap: selalu fmt.Errorf("context: %w", err)
24
25### Database
261. UUID untuk SEMUA primary keys
272. int64 cents untuk SEMUA monetary values (TIDAK float64)
283. Timestamps: timestamptz (bukan timestamp)
294. Soft delete: deleted_at TIMESTAMPTZ + deleted_by UUID
305. Koneksi: pgx/v5 ONLY (tidak database/sql)
316. Transaction: selalu gunakan pgx.Tx untuk operasi multi-table
32
33### API
341. REST: kebab-case untuk URL path (/cancel-order, bukan /cancelOrder)
352. HTTP verbs: GET (read), POST (create), DELETE (delete), PUT (replace), PATCH (partial update)
363. Response: JSON selalu, Content-Type: application/json
374. Pagination: cursor-based untuk list > 100 items (bukan offset)
38
39## Haram Dilakukan (Never Do)
40
41- JANGAN return error database (pgx errors) ke layer atas
42- JANGAN gunakan float64 untuk monetary values
43- JANGAN import delivery dari usecase atau repository
44- JANGAN skip error wrap (selalu fmt.Errorf("%w", err))
45- JANGAN gunakan global state atau singleton
46- JANGAN panic dalam handler (hanya untuk truly unrecoverable)
47
48## Wajib Ada di Setiap PR
49
50- Spec reference (.specify/features/*/spec.md)
51- Test coverage >= 85%
52- specify audit --feature [name] PASS
53- go test -race pass
54- Tidak ada golangci-lint warnings

 1## Developer Onboarding Checklist (Week 1)
 2
 3### Day 1: Context
 4- [ ] Baca README.md
 5- [ ] Baca CLAUDE.md (project context)
 6- [ ] Baca .specify/constitution.md (prinsip wajib)
 7- [ ] Setup development environment
 8- [ ] Run tests: go test ./...
 9
10### Day 2-3: Codebase exploration via .specify
11- [ ] Baca .specify/features/ — lihat 2-3 spec fitur yang sudah selesai
12- [ ] Baca salah satu plan.md + tasks.md lengkap
13- [ ] Trace spec ke kode: ikuti AC dari spec.md ke implementasinya
14
15### Day 4: First task
16- [ ] Ambil task kecil dari backlog
17- [ ] Run specify feature untuk task tersebut
18- [ ] Review dan approval dari senior developer
19- [ ] Implement dengan specify implement
20
21### Day 5-7: First PR
22- [ ] Selesaikan implementasi
23- [ ] Run specify audit — pastikan semua AC implemented
24- [ ] Buat PR dengan PR description dari specify pr
25- [ ] Minta review dari senior developer

 1# .speckit-config.yaml
 2
 3team:
 4  roles:
 5    product_manager:
 6      can_run: [feature, clarify]
 7      cannot_run: [implement, audit]
 8      description: "PM dapat tulis spec dan participate di clarification"
 9
10    junior_developer:
11      can_run: [feature, clarify, plan, tasks, implement, audit]
12      requires_approval: [plan, implement]
13      description: "Junior dapat semua, tapi plan dan implement butuh approval senior"
14
15    senior_developer:
16      can_run: all
17      can_approve: [plan, implement]
18      description: "Senior dapat semua dan bisa approve plan junior"
19
20    tech_lead:
21      can_run: all
22      can_approve: all
23      can_modify: [constitution, claude_md]
24      description: "Tech lead yang update constitution dan CLAUDE.md"

 1# Workflow dengan approval gate
 2
 3# Developer: tulis spec
 4specify feature
 5specify clarify
 6
 7# Buat spec review request
 8specify review-request --feature product-review --reviewers budi,dewi
 9
10# Tech lead / senior developer review:
11specify review --feature product-review
12
13# Output:
14# Review: product-review
15# Reviewer: @budi
16#
17# Checking spec quality...
18# All ACs have clear acceptance criteria (OK)
19# Edge cases are defined (OK)
20# Out of scope explicitly stated (OK)
21# AC13 ambiguous: "order yang valid" — what defines valid? PENDING? DELIVERED?
22# NFR missing: no performance requirement specified
23#
24# Decision: [approve/request-changes/reject]: request-changes
25# Comment: "Clarify AC13 and add performance NFR"
26
27# Developer update spec dan minta review lagi
28specify review-request --feature product-review --update

1# Buat template untuk tipe fitur yang sering dibuat
2specify template create --name crud-api
3# Template dibuat di: .specify/templates/crud-api.md
4
5# Gunakan template saat specify feature:
6specify feature --template crud-api
7
8# Template di-share di git dan di-update bersama
9git commit .specify/templates/ -m "spec: add crud-api template with standard ACs"

 1# Template: CRUD API
 2# Untuk: endpoint yang melakukan Create, Read, Update, Delete
 3
 4## User Stories
 5[Definisikan User Story di sini]
 6
 7## Acceptance Criteria
 8
 9### Happy Path — Create
10- AC1: POST /[resources] menerima {[required fields]}
11- AC2: System memvalidasi [validation rules]
12- AC3: System menyimpan dengan status [default status]
13- AC4: Response: 201 Created dengan [entity data]
14
15### Happy Path — Read (List)
16- AC5: GET /[resources] mengembalikan list dengan pagination
17- AC6: Response menyertakan: total count, items, next cursor
18
19### Happy Path — Read (Single)
20- AC7: GET /[resources]/:id mengembalikan single entity
21
22### Happy Path — Update
23- AC8: PUT /[resources]/:id menerima {[updateable fields]}
24- AC9: Response: 200 OK dengan updated entity
25
26### Happy Path — Delete
27- AC10: DELETE /[resources]/:id menghapus entity
28- AC11: Response: 204 No Content
29
30### Error Cases
31- AC12: Invalid input → 400 Bad Request + INVALID_[FIELD]
32- AC13: Entity tidak ditemukan → 404 NOT_FOUND
33- AC14: Unauthorized → 401 UNAUTHORIZED
34- AC15: Forbidden → 403 FORBIDDEN
35
36## Edge Cases
37- EC1: Concurrent create/update (race condition)
38- EC2: DB failure (atomic concern)
39
40## Out of Scope
41[List fitur yang TIDAK masuk PR ini]

 1# Generate team metrics dari spec history
 2specify metrics --team --since "2025-06-01" --until "2025-07-01"
 3
 4# Output:
 5# Team Metrics — June 2025
 6#
 7# Features completed: 8
 8# ACs implemented: 112/115 (97.4%)
 9#
10# Per-developer:
11# @andi:  3 features, 42 ACs, avg 89% coverage, avg spec audit 96
12# @budi:  2 features (tech lead, lower count), 28 ACs, avg 94% coverage
13# @citra: 3 features, 42 ACs, avg 87% coverage, avg spec audit 94
14#
15# Deviation stats:
16# Most common: error code case mismatch (5 times)
17# Action: Update constitution.md with stronger language
18#
19# Time metrics:
20# Avg spec phase: 45 min/feature
21# Avg implementation: 4.2 hr/feature
22# Avg review: 1.3 hr/feature
23# Total: 6 hr/feature (vs 12 hr estimate before Spec Kit)

 1# Buat RFC (Request for Constitution Change)
 2specify constitution-rfc --title "Add pgx advisory locks as preferred pattern"
 3
 4# Output: .specify/rfcs/2025-07-01-pgx-advisory-locks.md
 5
 6# Team review di GitHub (PR/issue)
 7# Voting: minimal 2 senior devs approval
 8
 9# Setelah approval:
10specify constitution-apply --rfc 2025-07-01-pgx-advisory-locks
11
12# Constitution.md ter-update dan semua developer di-notify

1# Feature spec yang butuh input dari team lain
2specify feature --feature cross-service-cancel-notification
3
4# Tag reviewer dari multiple team
5specify review-request --feature cross-service-cancel-notification \
6                       --reviewers @order-team/budi,@notification-team/eko
7
8# Cross-team review captured di clarifications.md

 1# Sebelum sprint: generate spec untuk semua stories yang akan dikerjakan
 2for ticket in SHOP-789 SHOP-790 SHOP-791; do
 3    specify feature --ticket $ticket
 4done
 5
 6# Estimasi dari tasks.md untuk semua stories
 7specify estimate --features "product-review,shipping-calc,flash-sale"
 8
 9# Output:
10# Sprint Estimation from Spec Kit:
11#
12# product-review:    14 tasks, 8.5 jam  (SHOP-789, @citra)
13# shipping-calc:     9 tasks,  5.5 jam  (SHOP-790, @andi)
14# flash-sale:        18 tasks, 11 jam   (SHOP-791, @budi+@andi)
15#
16# Total: 41 tasks, 25 jam
17# Team capacity (2 devs, 2 weeks): 40 jam
18#
19# Recommendation: Flash-sale perlu dipecah atau di-push ke sprint berikutnya

 1# Developer A menulis spec untuk payment gateway
 2specify feature --feature payment-gateway
 3
 4# Developer B review dan tidak setuju dengan AC5:
 5specify review --feature payment-gateway --reviewer andi
 6
 7# Output review @andi:
 8# AC5: "3D Secure harus selalu enabled" — saya tidak setuju
 9#    Alasan: 3D Secure menambahkan friction, business memutuskan optional
10#    Saran: "3D Secure diaktifkan berdasarkan bank requirement, bisa optional"
11# Decision: request-changes
12
13# Resolution: meeting 30 menit dengan PM → clarification baru di clarifications.md

 1# Developer A (Jakarta, 9am) tulis spec:
 2specify feature  # -> spec.md
 3
 4# Developer B (Singapore, beda timezone) review async:
 5specify review --feature payment-gateway \
 6               --async \  # submit review tanpa blocking
 7               --comments "Q1: Apakah 3D Secure wajib?"
 8
 9# Developer A (besok pagi) lihat comments:
10specify review-status --feature payment-gateway
11# -> Pending review dari @developer-b (Q1 submitted)
12
13# Jawab async:
14specify clarify --answer "Q1: 3D Secure optional, diaktifkan per bank requirement"

 1# Tes onboarding comprehension (untuk assessment):
 2specify quiz --constitution
 3
 4# Output: 10 pertanyaan berdasarkan constitution
 5# Q1: Jika repository mendapat not-found dari DB, apa yang harus di-return?
 6# A: nil, nil (bukan error)
 7#
 8# Q2: Apa format error code yang benar?
 9# A: UPPERCASE_SNAKE_CASE (PURCHASE_REQUIRED, bukan purchase_required)
10#
11# Developer baru bisa self-assess sebelum PR pertama

 1# Generate team dashboard
 2specify dashboard --team
 3
 4# Output (bisa di-export sebagai HTML):
 5#
 6# Sprint Progress
 7# 83% (10/12 features complete)
 8#
 9# Spec Compliance This Sprint
10# AC compliance: 97.4%
11# Coverage avg: 89%
12# Lint: 0 issues
13#
14# Pending Reviews
15# product-review: waiting @budi review (2 hari)
16# flash-sale spec: waiting @dewi approval (1 hari)
17#
18# Recent Merges
19# cancel-order (SHOP-456) — @andi — 2025-07-01
20# product-review (SHOP-789) — @citra — 2025-07-02

 1## Anti-Pattern 1: "Spec by Committee"
 2
 3Problem: 5 orang edit spec.md bersamaan → tidak koheren
 4Fix: Satu spec writer, satu reviewer, satu approver (RACI model)
 5
 6## Anti-Pattern 2: "Living Spec yang Tidak Pernah Di-approve"
 7
 8Problem: Spec terus di-edit setelah implement mulai → scope creep
 9Fix: Spec-lock sebelum specify plan — setelah plan, spec tidak boleh berubah
10
11## Anti-Pattern 3: "Constitution yang Tidak Pernah Di-enforce"
12
13Problem: Constitution ada tapi tidak ada konsekuensi violation
14Fix: CI check untuk constitution compliance, code review protocol yang strict
15
16## Anti-Pattern 4: "Spec Hanya untuk Junior Developer"
17
18Problem: Senior developer skip Spec Kit dan langsung coding
19Fix: Semua developer, semua level, wajib ikuti Spec Kit workflow

 1## Spec Kit Adoption Plan (4 minggu)
 2
 3### Week 1: Constitution dan Setup
 4- Workshop: tulis constitution.md bersama (half day)
 5- Setup: semua developer install specify CLI
 6- Latihan: setiap developer specify feature untuk fitur kecil yang sudah ada
 7
 8### Week 2: Pilot Feature
 9- Pilih satu fitur baru sebagai pilot
10- Jalani full workflow: specify → clarify → plan → tasks → implement
11- Retrospektif: apa yang berjalan baik, apa yang perlu disesuaikan
12
13### Week 3: Paralel Run
14- 2-3 fitur secara paralel dengan Spec Kit
15- Senior developer support untuk tiap session
16
17### Week 4: Full Adoption
18- Semua fitur baru wajib pakai Spec Kit
19- Update PR template dan CI untuk enforcement

 1# Monthly adoption metrics
 2specify metrics --adoption --month "2025-07"
 3
 4# Output:
 5# Spec Kit Adoption — July 2025
 6#
 7# Features completed: 12
 8# With Spec Kit: 10 (83.3%)
 9# Without Spec Kit: 2 (hotfixes - expected)
10#
11# Spec quality:
12# Avg ACs per feature: 9.4 (target: 8+)
13# Avg clarification Qs: 4.2 (good — thorough)
14#
15# Velocity impact:
16# Avg feature duration: 5.2 hr (vs 9.1 hr last month) -43%
17# PR review duration: 1.1 hr (vs 2.8 hr last month) -61%
18#
19# Adoption growing! Target 100% for August 2025.