SDD di Tim Golang: Versioning Spec, Onboarding, Code Review
Cara menerapkan SDD secara efektif di tim Golang: versioning spec, onboarding developer baru, code review process, dan workflow kolaboratif dengan Claude Code.
SDD di Tim: Versioning Spec, Onboarding, Code Review
SDD di tim Golang menuntut disiplin yang berbeda dari SDD seorang diri. Dikerjakan sendiri, prosesnya relatif sederhana: kamu tulis spec, kamu implement, kamu review sendiri. SDD di tim adalah tantangan yang berbeda — bagaimana memastikan setiap anggota tim mengikuti proses yang sama, spec tetap up-to-date, dan Claude Code digunakan secara konsisten?
Di artikel ini, kita bahas praktik-praktik konkret untuk membuat SDD bekerja di level tim: versioning spec, onboarding developer baru, dan code review yang berfokus pada spec compliance.
18.1 Tim Menghadapi Masalah Berbeda dari Individual
Sebelum masuk ke praktik, penting menyadari bahwa masalah tim secara fundamental berbeda dari masalah individual.
Di level individual:
- Kamu ingat context setiap spec
- Kamu tahu kenapa keputusan tertentu dibuat
- Perubahan spec mudah di-track karena kamu yang buat
Di level tim:
- Developer baru tidak punya context historical
- Keputusan yang “obvious” bagi satu orang tidak obvious bagi yang lain
- Spec bisa di-update oleh siapapun, perlu governance
- Claude Code perlu di-setup konsisten untuk semua anggota tim
Perbedaan ini menjelaskan seluruh isi artikel: setiap praktik di bawah dirancang untuk memindahkan context dari kepala satu orang ke artefak yang bisa diakses seluruh tim.
18.2 Versioning Spec: Lebih dari Sekadar Git
Spec di git otomatis ter-version, tapi version di git saja tidak cukup memberikan context. Lihat contoh git log berikut untuk memahami keterbatasannya.
1git log specs/order/cancel-order.md
2abc123 - "Update spec" (tidak informatif)
3def456 - "Fix typo"
4ghi789 - "Add EC"Dari log seperti ini kita tidak bisa tahu apa yang berubah, kenapa, dan siapa yang memutuskan — informasi yang justru paling dibutuhkan tim. Solusinya adalah menuliskan metadata dan changelog di dalam spec itu sendiri, seperti berikut.
1# specs/order/cancel-order.md
2
3## Metadata
4- **Spec Version:** v1.3
5- **Status:** ACTIVE (in production)
6- **Created:** 2025-05-01
7- **Authors:** @budi (lead), @andi (contributor)
8- **Last Updated:** 2025-07-01
9
10## Changelog
11
12### v1.3 (2025-07-01)
13**Changed:**
14- AC4: Cancellation window changed from 15 → 30 minutes
15 Reason: User research showed 15 menit tidak cukup untuk banyak user
16 Decision maker: @budi (Product) + @andi (Tech)
17 Consumers notified: 2025-06-28
18
19### v1.2 (2025-06-15)
20**Added:**
21- EC3: Explicit DB timeout handling
22 Background: Ditemukan dari load test (JIRA-456)
23
24### v1.1 (2025-06-01)
25**Changed:**
26- NFR-P2: Target latency diperketat dari 500ms → 300ms
27 Background: Baseline measurement menunjukkan kita sudah di 120ms p95
28
29### v1.0 (2025-05-01)
30Initial spec.Changelog seperti ini menyimpan “kenapa” di sebelah “apa” — sesuatu yang git log biasa tidak pernah bisa berikan, dan yang menyelamatkan tim dari pertanyaan “kok begini?” berbulan-bulan kemudian.
18.3 Spec Status Lifecycle
Selain versi, setiap spec perlu status yang jelas agar tim tahu boleh tidaknya spec itu diimplementasikan. Diagram lifecycle berikut mendefinisikan enam status baku.
1## Spec Status Lifecycle
2
3DRAFT → Spec sedang ditulis, belum di-review
4REVIEW → Spec sudah di-submit untuk review tim
5APPROVED → Spec di-approve, siap untuk implementasi
6ACTIVE → Spec dalam production, kode sudah di-deploy
7DEPRECATED → Spec sudah digantikan oleh versi baru
8ARCHIVED → Spec sudah tidak digunakan (feature removed atau replaced)Status ini mencegah kesalahan fatal seperti mengimplementasikan spec yang masih DRAFT. Di header spec, status ditulis eksplisit beserta siapa yang meng-approve, seperti contoh berikut.
1## Status: APPROVED
2**Approved by:** @budi (Tech Lead), @maya (Product Manager)
3**Approval date:** 2025-07-01
4**Target implementation:** Sprint 23 (2025-07-15)Dengan status dan approver tertulis di kepala spec, siapa pun yang membuka file langsung tahu apakah spec ini aman dikerjakan — tanpa perlu bertanya di chat.
18.4 Spec Ownership dan Review Process
Agar spec tidak menjadi “milik semua orang sekaligus tidak ada yang bertanggung jawab”, governance perlu didefinisikan. Dokumen berikut menetapkan peran, syarat review, dan timeline-nya.
1## Spec Governance
2
3### Roles
4**Spec Author:** Developer yang menulis spec (biasanya yang implement)
5**Spec Reviewer:** Tech lead + 1 developer senior
6**Spec Approver:** Tech lead (untuk tech spec) + PM (untuk business spec)
7
8### Review Requirements
9- Setiap spec BARU butuh minimal 2 reviewer (1 tech, 1 business/PM)
10- Perubahan MINOR (typo, clarification): 1 reviewer cukup
11- Perubahan MAJOR (behavior change, breaking change): semua reviewer wajib
12
13### Review Timeline
14- DRAFT → REVIEW: Author submit PR dengan label "spec-review"
15- REVIEW → APPROVED: Minimal 48 jam review window
16- APPROVED → ACTIVE: Setelah implementasi di-merge ke productionAturan yang membedakan perubahan MINOR dan MAJOR inilah kuncinya: ia mencegah proses menjadi bottleneck untuk typo, sekaligus memastikan perubahan behavior mendapat pengawasan penuh.
18.5 Onboarding Developer Baru ke SDD
Developer baru perlu memahami spec structure, workflow, CLAUDE.md, dan ekspektasi code review. Onboarding kit berikut memandu mereka hari demi hari, dari membaca spec sampai menulis spec pertama.
1# Onboarding: SDD Workflow di Santekno Shop
2
3## Hari 1-2: Pahami Spec
4
5Baca spec-spec berikut secara berurutan:
61. specs/_templates/feature-spec.md → template yang digunakan
72. specs/order/create-order.md → contoh spec yang lengkap
83. specs/order/cancel-order.md → contoh spec yang sudah production
9
10Untuk setiap spec, trace ke implementasinya:
11→ specs/order/cancel-order.md → lihat internal/usecase/order/cancel_order.go
12
13## Hari 3: Pahami CLAUDE.md
14
15Baca CLAUDE.md di root proyek.
16Test Claude Code dengan probe prompts yang ada di onboarding guide.
17
18## Hari 4-5: Shadow Review
19
20Ikut code review seseorang yang sudah experienced di SDD.
21Perhatikan bagaimana reviewer check spec compliance.
22
23## Minggu 2: First Spec
24
25Pilih task kecil dari backlog.
26Tulis spec-nya sendiri, minta review dari senior.
27Lakukan implementasi berdasarkan spec.Urutan ini sengaja menempatkan “baca dan trace spec” sebelum “tulis spec”: developer baru belajar SDD paling cepat dengan melihat spec matang lalu menelusuri kodenya, bukan dari teori. Untuk menutup onboarding, berikan satu latihan implementasi utuh seperti berikut.
1## Onboarding Task: Get Order by Order Number
2
3Sebagai exercise onboarding, implementasikan endpoint:
4GET /api/v1/orders/number/{order_number}
5
6Steps:
71. Tulis spec di specs/order/get-order-by-number.md
8 Gunakan template di specs/_templates/feature-spec.md
9
102. Review spec dengan senior
11
123. Setelah approved:
13 a. Plan Mode di Claude Code
14 b. Task breakdown
15 c. Implementasi per task
16 d. Unit test dari spec
17
184. Submit PR dengan spec link di description
19
20Ini akan membantu kamu familiar dengan seluruh SDD workflow
21sebelum mengerjakan task yang lebih complex.Latihan end-to-end pada task kecil ini memberi developer baru pengalaman utuh siklus SDD dengan risiko rendah — jauh lebih efektif daripada workshop teoretis.
18.6 CLAUDE.md yang Kondusif untuk Tim
CLAUDE.md versi tim perlu memuat lebih dari sekadar arsitektur: ia juga mengatur proses, konvensi, dan spec yang sedang aktif. Contoh berikut adalah CLAUDE.md edisi tim untuk Santekno Shop.
1# CLAUDE.md — Santekno Shop (Team Edition)
2
3## Spec Process
4
5Setiap fitur baru WAJIB mengikuti proses ini:
61. Tulis spec di specs/domain/[feature].md
72. Submit untuk review (label: spec-review di PR)
83. Dapatkan approval sebelum mulai implementasi
94. Implement berdasarkan approved spec
105. Referensikan spec di setiap PR
11
12Jika tidak ada spec:
13> "Fitur ini belum ada spec-nya. Apakah kamu sudah tulis spec di specs/ folder?
14> Jika belum, mari buat dulu. Link ke template: specs/_templates/feature-spec.md"
15
16## Team Conventions
17
18### Timezone
19Team timezone: WIB (Asia/Jakarta, UTC+7)
20Semua timestamp di log dan event: UTC
21
22### Code Review
23- Minimum 1 approver sebelum merge
24- Tech lead approval wajib untuk: arch changes, interface changes, security changes
25- PR harus include link ke spec yang diimplementasikan
26
27### Branching
28- Feature: feature/{jira-ticket-number}-{short-description}
29- Spec: spec/{jira-ticket-number}-{feature-name}
30- Hotfix: hotfix/{jira-ticket-number}-{short-description}
31
32## Current Active Specs
33
34Sprint 23 specs yang sedang dalam implementasi:
35- specs/order/cancel-order.md v1.3 (assignee: @andi)
36- specs/product/update-stock.md v1.0 (assignee: @citra)
37- specs/user/update-address.md v1.1 (assignee: @budi)Bagian Current Active Specs membuat CLAUDE.md menjadi dokumen hidup: dengan menyebut spec dan assignee sprint berjalan, Claude Code langsung punya konteks siapa mengerjakan apa tanpa perlu dijelaskan ulang tiap sesi.
18.7 Spec-First Code Review
Code review di tim SDD berbeda dari review biasa karena spec compliance diperiksa lebih dulu, baru kualitas kode. Panduan reviewer berikut memecah proses menjadi empat langkah dengan alokasi waktu jelas.
1## SDD Code Review Guide
2
3### Step 1: Verify Spec Link (30 detik)
4- Apakah PR description menyebutkan spec yang diimplementasikan?
5- Apakah spec versi yang benar?
6- Apakah spec status sudah APPROVED?
7
8### Step 2: Spec Compliance Check (5-10 menit)
9Buka spec di satu window, kode di window lain:
10- Setiap AC → apakah ter-implement?
11- HTTP status codes sesuai spec?
12- Error codes exact match dengan spec?
13- Response format sesuai spec?
14
15### Step 3: Test Coverage Check (5 menit)
16- Setiap AC punya test?
17- Setiap high-priority EC punya test?
18- Test names reference AC/EC dari spec?
19- Coverage command: `go test -cover ./...`
20
21### Step 4: Standard Code Review (15-20 menit)
22- Go idioms
23- Error handling
24- Performance concerns
25- Security considerations
26
27### Review Comment Template
28
29#### Spec compliance issue:
30"Spec [cancel-order.md v1.3 AC9] mengatakan error_code harus 'ORDER_NOT_CANCELLABLE',
31tapi kode menggunakan 'NOT_CANCELLABLE'. Tolong sesuaikan."
32
33#### Missing test:
34"EC1 (concurrent cancel) tidak ada test yang cover-nya.
35Ini high-risk scenario yang butuh test sebelum merge."
36
37#### Acknowledgment:
38"✅ Semua AC dan EC sudah ter-cover.
39Spec compliance check: PASSED.
40Lanjut ke code quality review."Urutan langkahnya disengaja: memverifikasi spec compliance lebih dulu mencegah reviewer membuang waktu mengomentari gaya kode pada implementasi yang ternyata salah spec sejak awal.
18.8 PR Template yang Mendorong SDD
Agar spec compliance tidak bergantung ingatan, jadikan ia bagian dari PR template. Template berikut memaksa author melakukan self-review terhadap setiap AC/EC sebelum meminta review.
1# Pull Request
2
3## Summary
4[Deskripsi singkat apa yang di-implementasikan]
5
6## Spec Reference
7- **Spec file:** specs/order/cancel-order.md
8- **Spec version:** v1.3
9- **Spec status:** APPROVED (approved by @budi, 2025-07-01)
10
11## Spec Compliance Self-Review
12Saya telah memverifikasi implementasi terhadap spec:
13
14| AC/EC | Status | Notes |
15|-------|--------|-------|
16| AC1-AC6 (happy path) | ✅ Implemented | |
17| AC7 (not found) | ✅ Implemented | |
18| AC8 (not owner) | ✅ Implemented | |
19| AC9 (non-PENDING) | ✅ Implemented | |
20| AC10 (window expired) | ✅ Implemented | |
21| EC1 (concurrent) | ✅ Implemented | Via SELECT FOR UPDATE in repo |
22| EC2 (Kafka failure) | ✅ Implemented | Best effort + log warning |
23| EC3 (DB timeout) | ⚠️ Partial | Context deadline from middleware covers this. Tracked: JIRA-789 |
24
25## AI Spec Review
26[Optional: paste output dari AI spec compliance review]
27
28## Implementation Plan Reference
29[Link ke implementation plan jika ada]
30
31## Test Coverage
32go test -cover ./internal/usecase/order/...
33coverage: 91.2% of statements
34
35## Checklist
36- [ ] Spec compliance self-review done
37- [ ] All high-priority AC/EC have tests
38- [ ] Error codes match spec exactly
39- [ ] HTTP status codes match spec
40- [ ] No sensitive data in logs
41- [ ] Migration added if DB schema changedTabel self-review inilah nilai utamanya: author dipaksa memetakan tiap AC/EC ke statusnya, sehingga gap seperti EC3 yang “partial” terlihat jujur di depan mata reviewer, bukan tersembunyi.
18.9 Spec di Jira/Linear: Menghubungkan Ticket dan Spec
Ticket di Jira/Linear dan spec di git harus terhubung tanpa saling menduplikasi. Template ticket berikut menempatkan AC bisnis di ticket dan AC teknis di spec, dengan tautan yang jelas di antara keduanya.
1## Jira/Linear Ticket Template untuk SDD
2
3### Story Title
4[Jira Story] Cancel Order Feature
5
6### Acceptance Criteria (Business Level)
7- Customer bisa cancel order yang masih PENDING
8- Customer mendapat email konfirmasi setelah cancel
9- Stok produk kembali tersedia setelah cancel
10
11### Technical Spec
12→ Link ke: specs/order/cancel-order.md v1.3
13
14### Implementation Status
15- [ ] Spec: DRAFT
16- [ ] Spec: REVIEW
17- [ ] Spec: APPROVED
18- [ ] Implementation: IN PROGRESS
19- [ ] Implementation: PR OPEN
20- [ ] Implementation: MERGED
21- [ ] Spec: ACTIVE (closed setelah production deploy)
22
23### Notes
24Business-level AC di ticket ini adalah source untuk Product.
25Technical AC/EC ada di spec file. Jangan duplikasi AC di ticket jika
26sudah ada di spec.Pembagian ini menghindari sumber kebenaran ganda: Product membaca AC bisnis di ticket, engineer membaca AC teknis di spec, dan tidak ada AC yang perlu disinkronkan manual di dua tempat.
18.10 Tim Workflow: Sprint dengan SDD
SDD paling efektif ketika menyatu dengan ritme sprint yang sudah ada. Alur berikut memetakan aktivitas SDD ke setiap upacara sprint, dari planning sampai retrospective.
1## SDD Sprint Workflow
2
3### Sprint Planning (Senin)
41. Review spec yang akan di-implementasikan
5 - Tech lead verify semua spec sudah APPROVED
6 - Developer yang assign ke task: baca spec sebelum planning
7
82. Task breakdown (berdasarkan spec)
9 - Estimasi berdasarkan spec complexity, bukan feeling
10
113. CLAUDE.md update jika ada convention baru
12 - Update "Current Active Specs" section
13
14### Daily Standup
15- "Kemarin saya implement AC1-AC3 dari cancel-order.md"
16- "Hari ini saya akan implement EC1 dan test untuk AC7-AC10"
17- "Blocker: EC1 membutuhkan index yang belum ada, perlu diskusi dengan DBA"
18
19### Mid-Sprint (Rabu)
20- Spec compliance check untuk in-progress features
21- Flag issues early sebelum PR
22
23### Sprint Review (Jumat)
24- Demo diverifikasi terhadap spec
25- "Spec cancel-order.md v1.3 semua AC ter-implementasi dan tested"
26
27### Sprint Retrospective
28- "Apakah ada spec drift yang ditemukan?"
29- "Apakah proses spec review sudah efisien?"
30- "Ada yang perlu di-update di CLAUDE.md?"Yang menarik dari alur ini, spec menjadi bahasa bersama di setiap upacara — bahkan standup pun mereferensikan AC, sehingga progress diukur terhadap spesifikasi, bukan perasaan.
18.11 Conflict Resolution: Ketika Tim Tidak Setuju dengan Spec
Perdebatan tentang implementasi tak terhindarkan, tapi harus punya jalur penyelesaian yang menghasilkan dokumen. Skenario dan proses berikut menunjukkan cara menyelesaikan ketidaksepakatan tanpa berakhir di interpretasi masing-masing.
1Scenario: Developer A dan B tidak setuju tentang implementasi AC9.
2
3Developer A: "Kita harus return 404 untuk keamanan (tidak reveal order existence)"
4Developer B: "Spec bilang 409, kita ikut spec"
5
6Resolusi process:
71. Cek apakah spec eksplisit (jika iya, follow spec)
82. Jika spec ambigu, raise sebagai spec issue
93. Bawa ke tech lead + PM untuk decision
104. Update spec dengan keputusan dan reasoning
115. Implement berdasarkan spec yang sudah di-update
12
13JANGAN: implement berdasarkan interpretasi masing-masing.
14JANGAN: diskusi panjang tanpa output dokumen.Inti proses ini: setiap perdebatan wajib berakhir sebagai keputusan yang tertulis di spec, sehingga konflik yang sama tidak muncul lagi enam bulan kemudian. Untuk membantu memecah kebuntuan, Claude Code bisa dimintai perspektif ketiga yang netral.
1Developer A dan B tidak setuju tentang return value untuk AC9.
2Perspektif A: return 404 (security, tidak reveal existence)
3Perspektif B: return 409 (sesuai spec literal)
4
5Berikan analisis:
61. Apa trade-off dari masing-masing approach?
72. Apa yang biasanya dipakai di industry untuk case ini?
83. Apakah ada cara untuk menyatukan keduanya?
94. Rekomendasi dengan justifikasi?
10
11Context: e-commerce B2C, customer bisa tau order ID mereka sendiri via frontend.Perspektif AI di sini bukan pengambil keputusan akhir, melainkan input netral yang memperkaya diskusi — keputusan tetap di tangan tech lead dan PM, lalu dituangkan ke spec.
18.12 Sharing Claude Code Setup di Tim
Agar output AI konsisten, semua anggota tim harus memakai setup Claude Code yang sama. Dokumen setup berikut memandu instalasi sampai probe test untuk memverifikasi CLAUDE.md benar-benar terbaca.
1# docs/claude-code-setup.md
2
3## Setup Claude Code untuk Tim Santekno Shop
4
5### 1. Install Claude Code
6npm install -g @anthropic-ai/claude-code
7
8### 2. Configure API Key
9export ANTHROPIC_API_KEY=sk-ant-... (tanya ke tech lead)
10
11### 3. Verifikasi CLAUDE.md
12cd /path/to/santekno-shop
13claude # CLAUDE.md seharusnya otomatis terbaca
14
15### 4. Probe Test
16Jalankan probe test ini untuk verify setup:
17
18> "Saya mau tambahkan business logic langsung di handler untuk validasi user"
19
20Expected response:
21"Berdasarkan architecture rules di proyek ini, business logic tidak boleh ada di handler.
22Validasi ini seharusnya di usecase layer."
23
24Jika response berbeda dari expected, CLAUDE.md mungkin tidak terbaca.
25Cek: ls -la CLAUDE.md (harus ada di root proyek)
26
27### 5. Best Practices
28- Mulai setiap session dengan menyebutkan spec yang dikerjakan
29- Gunakan Plan Mode sebelum implementasi besar
30- Commit setelah setiap task breakdown selesai
31- Jika session panjang (>50 pesan), mulai session baruProbe test di langkah 4 adalah trik verifikasi yang cerdas: jika Claude menolak menaruh business logic di handler, berarti CLAUDE.md sudah aktif — cara cepat memastikan seluruh tim benar-benar berangkat dari aturan yang sama.
18.13 Spec as Knowledge Base
Di tim yang berkembang, spec berevolusi menjadi knowledge base yang bisa dicari. Dokumen berikut menunjukkan cara memanfaatkan Claude Code untuk menelusuri keputusan lama sekaligus struktur index yang memudahkan navigasi.
1## Specs sebagai Knowledge Base
2
3### Mencari Informasi dengan Claude Code
4
5"Di spec mana saya bisa menemukan bagaimana kita handle concurrent access?"
6→ Claude akan search di specs/ folder
7
8"Apa keputusan kita tentang error codes untuk cancel order?"
9→ Claude akan lihat specs/order/cancel-order.md AC9-AC10
10
11"Bagaimana kita handle Kafka failure di usecase?"
12→ Claude akan lihat EC2 di berbagai spec
13
14### Index Spec
15
16Buat index untuk navigasi yang lebih mudah:
17
18specs/
19├── README.md ← index semua spec
20├── _templates/ ← template untuk spec baru
21├── order/
22│ ├── README.md ← index spec order domain
23│ ├── create-order.md
24│ ├── cancel-order.md
25│ └── get-order.md
26└── product/
27 ├── README.md
28 └── update-stock.mdKetika spec terorganisir dan bisa dicari seperti ini, pertanyaan “kenapa dulu kita putuskan begini?” bisa dijawab dalam hitungan detik oleh siapa pun — pengetahuan tim berhenti bergantung pada ingatan individu.
18.14 Mengukur SDD Maturity di Tim
Untuk tahu apakah adopsi SDD berkembang, tim butuh tolok ukur. Assessment berbasis level berikut memetakan kematangan SDD dari basic sampai expert beserta ciri-cirinya.
1## SDD Maturity Assessment
2
3### Level 1: Basic (0-3 bulan)
4- [ ] Semua feature baru punya spec
5- [ ] Spec di-review sebelum implementasi
6- [ ] Code review mencek spec link
7
8### Level 2: Intermediate (3-6 bulan)
9- [ ] Spec punya versioning dan changelog
10- [ ] Test names reference AC/EC dari spec
11- [ ] AI spec compliance review dilakukan per PR
12- [ ] Spec coverage ≥ 80% untuk fitur baru
13
14### Level 3: Advanced (6-12 bulan)
15- [ ] Spec drift detection otomatis di CI
16- [ ] CLAUDE.md selalu up-to-date dengan conventions terbaru
17- [ ] Onboarding developer baru < 1 minggu untuk paham SDD workflow
18- [ ] Consumer-driven contract testing untuk inter-service communication
19
20### Level 4: Expert (> 12 bulan)
21- [ ] SDD menjadi default mode, bukan extra overhead
22- [ ] Tim bisa onboard AI tools baru tanpa hilang context
23- [ ] Spec menjadi source of truth yang dipercaya semua stakeholder
24- [ ] Regression dari spec drift praktis nol di productionAssessment ini berguna sebagai roadmap, bukan rapor: ia menunjukkan langkah konkret berikutnya untuk naik level, sehingga tim punya arah perbaikan yang jelas alih-alih target abstrak “lebih baik”.
18.15 Retrospective Khusus untuk SDD Process
Sekali per kuartal, proses SDD itu sendiri layak diretrospeksi secara mendalam. Agenda 90 menit berikut menstrukturkan diskusi dari metrik sampai action item.
1## SDD Quarterly Retrospective Agenda (90 menit)
2
3### Part 1: Metrics Review (20 menit)
4- Berapa persen fitur yang punya spec di quarter ini?
5- Rata-rata spec coverage (AC/EC covered by tests)?
6- Berapa kali spec drift ditemukan dan di mana?
7- Berapa lama rata-rata dari spec ditulis ke implementasi selesai?
8
9### Part 2: What Worked (20 menit)
10- Spec mana yang paling membantu selama implementasi?
11- Aspek SDD mana yang sudah terasa natural?
12- Contoh di mana spec mencegah bug atau miscommunication?
13
14### Part 3: What Didn't Work (20 menit)
15- Di mana kita bypass spec process dan kenapa?
16- Spec mana yang terlalu detail atau terlalu abstrak?
17- Pain point dalam workflow saat ini?
18
19### Part 4: Action Items (30 menit)
20- 3-5 concrete improvements untuk quarter berikutnya
21- Owner dan timeline untuk setiap improvement
22- Update CLAUDE.md dan spec templates jika diperlukanBagian metrics di awal membuat retrospective ini berbasis data, bukan opini: keputusan perbaikan berangkat dari angka coverage dan frekuensi drift nyata, sehingga action item-nya lebih tajam.
18.16 Scaling SDD: Ketika Tim Bertumbuh
Praktik SDD yang cocok untuk lima orang bisa runtuh di dua puluh orang. Panduan berikut menunjukkan bagaimana governance dan tooling perlu berevolusi seiring ukuran tim.
1Tim kecil (2-5 orang):
2→ Satu CLAUDE.md untuk semua
3→ Tech lead review semua spec
4→ Informal process OK
5
6Tim menengah (5-15 orang):
7→ CLAUDE.md per domain (order, product, user)
8→ Domain tech lead review spec dalam domain mereka
9→ PR-based spec review process
10
11Tim besar (15+ orang):
12→ Spec governance dengan dedicated spec owner per domain
13→ Spec review committee untuk cross-domain changes
14→ Automated tooling: spec linter, contract testing, drift detection CI
15→ Spec versioning platform (bisa pakai Confluence + git dual-track)Polanya jelas: semakin besar tim, semakin banyak proses informal yang harus digantikan otomasi dan ownership eksplisit — karena koordinasi via percakapan langsung tidak lagi skalabel.
18.17 Common Team Anti-Patterns dalam SDD
Sama pentingnya dengan mengetahui praktik baik adalah mengenali anti-pattern yang menggerogoti SDD. Empat berikut adalah yang paling sering muncul di tim.
Anti-pattern pertama adalah menganggap spec sebagai opsional untuk task “kecil”.
1"Ini task kecil, gausah spec dulu lah."
2→ Semua task terasa kecil, tapi yang sering drift justru task "kecil"Bahayanya, hampir semua task terasa kecil di awal, sehingga budaya “spec optional” pelan-pelan menghapus SDD sama sekali. Anti-pattern kedua adalah membalik urutan: menulis spec setelah kode selesai.
1"Saya akan nulis spec SETELAH implementasi untuk dokumentasi."
2→ Ini bukan SDD, ini dokumentasi retrospektifSpec yang ditulis belakangan hanya mendokumentasikan apa yang sudah ada, bukan memandu apa yang seharusnya dibangun — nilai utama SDD hilang. Anti-pattern ketiga adalah reviewer yang tidak membaca spec sebelum review.
1"Code review biasanya saya langsung lihat kode-nya, spec belakangan."
2→ Spec review harus sebelum atau bersamaan dengan code reviewTanpa membaca spec lebih dulu, reviewer tidak punya tolok ukur untuk menilai apakah kode benar — ia hanya menilai gaya, bukan kebenaran. Anti-pattern keempat adalah membiarkan CLAUDE.md usang.
1CLAUDE.md ditulis di awal project, tidak pernah di-update.
2Konvensi sudah berubah tapi CLAUDE.md masih bilang konvensi lama.
3→ CLAUDE.md harus di-review dan di-update setiap sprint.CLAUDE.md yang usang lebih buruk daripada tidak ada, karena ia mengarahkan AI dan developer baru ke konvensi yang sudah ditinggalkan.
18.18 Tips & Gotchas
💡 Tip 1: Spec review dan code review adalah dua activity terpisah
Reviewer yang berbeda bisa lebih efektif: business analyst / PM review spec, senior developer review code. Pisahkan PR untuk spec dan untuk kode jika perlu.
💡 Tip 2: Onboarding via “read spec, find implementation” exercise
Developer baru diminta: pilih spec yang sudah ACTIVE, trace ke implementasinya, dan presentasikan findings. Ini cara terbaik belajar SDD workflow.
💡 Tip 3: Celebrate spec quality, bukan hanya delivery speed
Tim yang hanya di-recognize atas kecepatan delivery akan skip spec untuk mengejar velocity. Recognise dan appreciate spec yang ditulis dengan baik.
💡 Tip 4: CLAUDE.md as living document, review di setiap sprint
Dedikasikan 15 menit di sprint planning untuk review CLAUDE.md: apakah ada yang perlu ditambah, diubah, atau dihapus?
⚠️ Gotcha 1: SDD overhead nyata tapi ROI juga nyata
SDD menambah ~20% waktu di awal. ROI terasa di: lebih sedikit bug production, onboarding lebih cepat, code review lebih efisien. Komunikasikan ini ke stakeholder yang menanyakan velocity.
⚠️ Gotcha 2: AI inconsistency antar developer
Developer A dan B dengan CLAUDE.md yang sama bisa mendapat output yang berbeda dari Claude. Ini normal — AI tidak deterministic. Yang penting: constraint dari CLAUDE.md ter-enforce.
⚠️ Gotcha 3: Spec yang terlalu demokratis bisa melambat
Jika setiap perubahan spec butuh approval dari semua, proses akan lambat. Delegasikan: minor changes cukup 1 reviewer, major changes butuh lebih banyak.
⚠️ Gotcha 4: Jangan paksakan SDD untuk semua task
Hotfix production yang butuh 5 menit tidak perlu full spec process. Emergency response mode berbeda dari normal development mode. Dokumentasikan retroaktif.
18.19 Spec Repository Structure yang Direkomendasikan
Semua praktik di atas bermuara pada satu struktur repository yang rapi dan bisa di-scan. Struktur direktori berikut menata spec, template, arsip, dan dokumentasi pendukung untuk tim.
1santekno-shop/
2├── CLAUDE.md ← shared AI context
3├── specs/
4│ ├── README.md ← index + governance doc
5│ ├── _templates/
6│ │ ├── feature-spec.md ← template untuk feature spec
7│ │ └── contract-spec.md ← template untuk API contract
8│ ├── _archive/ ← deprecated/removed specs
9│ ├── order/
10│ │ ├── README.md ← order domain index
11│ │ ├── create-order.md ← v1.2 (ACTIVE)
12│ │ ├── cancel-order.md ← v1.3 (ACTIVE)
13│ │ └── get-order.md ← v1.0 (ACTIVE)
14│ ├── product/
15│ │ └── update-stock.md ← v1.0 (REVIEW)
16│ └── contracts/
17│ ├── order-events.md ← Kafka event contracts
18│ └── order-product-sync.md ← sync API contracts
19├── api/
20│ └── openapi.yaml ← OpenAPI spec (extends feature specs)
21└── docs/
22 ├── claude-code-setup.md ← setup guide untuk tim
23 └── sdd-workflow.md ← workflow guideStruktur ini menempatkan spec, kode, dan dokumentasi proses dalam satu repo yang sama — sehingga spec ter-version bersama implementasinya dan setiap developer baru bisa menemukan semua yang mereka butuhkan dari satu titik masuk.
18.20 Ringkasan
SDD di tim bukan hanya tentang tools — ini tentang establishing shared mental model tentang “bagaimana kita membangun software.”
Versioning spec yang baik mencakup status lifecycle, changelog dengan context keputusan, dan ownership yang jelas. Git versioning tidak cukup tanpa narrative yang menyertainya.
Onboarding yang efektif untuk SDD: baca spec, trace ke implementasi, shadow review, first spec exercise. Bukan workshop atau training formal.
PR process yang mendorong SDD: PR template dengan spec link, reviewer checklist yang mencakup spec compliance, dan AI review sebagai sanity check sebelum human review.
Culture beats tools: CLAUDE.md bisa di-setup dalam satu jam. Yang butuh berbulan-bulan adalah membangun culture di mana setiap developer naturally menanyakan “di mana spec-nya?” sebelum mulai coding.
Di artikel berikutnya, kita akan melihat semua yang sudah dipelajari dalam action: studi kasus lengkap dari spec ke merge untuk Order Service e-commerce.