Branching Strategy Spec Kit Golang: Satu Fitur Satu Branch

Branching Strategy: Setiap Fitur = Satu Branch, Satu Spec

Menerapkan branching strategy Spec Kit Golang yang konsisten adalah salah satu keputusan paling berdampak dalam SDD workflow. Prinsipnya sederhana tapi powerful: setiap fitur punya satu branch dan satu spec yang saling terikat. Ini bukan sekadar Git hygiene — ini soal membangun audit trail yang lengkap dan memungkinkan tim bekerja paralel tanpa saling menabrak.

Di artikel ini kita bedah cara menata branch, spec, dan Git workflow agar setiap unit kerja tetap traceable dari spesifikasi hingga kode yang di-merge ke main.

12.1 Prinsip: One Feature, One Branch, One Spec

Fondasi strategi ini adalah struktur direktori yang mengikat spec ke branch fiturnya. Diagram berikut menunjukkan bagaimana satu feature branch membungkus spec, plan, tasks, dan kode implementasi dalam satu tempat.

1feature/SHOP-789-product-review
2├── .specify/features/product-review/spec.md
3├── .specify/features/product-review/plan.md
4├── .specify/features/product-review/tasks.md
5└── [implementation files]

Ketika branch ini di-merge ke main:

• Semua spec, plan, dan tasks masuk bersama kode
• Git history branch = history implementasi yang dapat di-trace
• Reviewer bisa lihat spec → plan → tasks → kode dalam satu PR

Dengan pola ini, tidak ada lagi spec yang “hidup terpisah” dari kodenya — keduanya versioned bersama dan bisa ditelusuri kapan saja.

12.2 Branch Naming Convention dengan Spec Kit

Konvensi penamaan yang seragam membuat navigasi antar branch jauh lebih mudah, apalagi saat ada banyak fitur paralel. Contoh berikut memperlihatkan format yang direkomendasikan beserta variannya untuk spec-only dan hotfix.

 1# Format yang direkomendasikan
 2feature/{jira-ticket}-{kebab-case-feature-name}
 3spec/{jira-ticket}-{kebab-case-feature-name}  # hanya untuk spec review
 4
 5# Contoh:
 6feature/SHOP-789-product-review
 7feature/SHOP-456-cancel-order
 8spec/SHOP-900-flash-sale-pricing  # branch spec saja, belum implementasi
 9
10# Untuk hotfix (tidak perlu full Spec Kit workflow):
11hotfix/SHOP-901-fix-review-rating-calculation

Nama branch yang menyertakan ticket dan deskripsi kebab-case membuat tiap branch self-explanatory — kamu tahu isinya tanpa perlu membukanya.

12.3 Workflow Branch dengan Spec Kit

Setelah konvensi jelas, mari lihat alur kerja penuh dari membuat branch hingga PR siap review. Rangkaian perintah berikut memetakan tiga fase — spec, plan/tasks, dan implementasi — dalam satu branch fitur.

 1# Mulai fitur baru
 2git checkout -b feature/SHOP-789-product-review
 3
 4# Phase 1: Spec (bisa di-push untuk early review)
 5specify feature
 6specify clarify
 7git push origin feature/SHOP-789-product-review
 8# → PR draft dengan spec saja untuk early feedback
 9
10# Phase 2: Plan dan Tasks
11specify plan
12specify tasks
13git push  # update PR draft
14
15# Phase 3: Implementation
16specify implement
17# → 14 commits, satu per task
18
19# Finalize
20git push
21# → PR siap untuk full review

Perhatikan bahwa PR bisa dibuka sejak fase spec — feedback tidak perlu menunggu implementasi selesai, sehingga koreksi arah bisa terjadi lebih awal dan lebih murah.

12.4 Spec Branch: Review Spec Sebelum Implementasi

Untuk fitur besar, memisahkan review spec dari implementasi menghemat banyak rework. Alur berikut membuat branch khusus spec lebih dulu, lalu menurunkan feature branch dari spec yang sudah disetujui.

 1# Branch untuk spec review saja
 2git checkout -b spec/SHOP-789-product-review
 3
 4specify feature
 5specify clarify
 6
 7git push origin spec/SHOP-789-product-review
 8# Buat PR: "spec: add product review specification [SHOP-789]"
 9# Label: spec-review, NOT READY TO IMPLEMENT
10
11# Setelah spec approved:
12git checkout -b feature/SHOP-789-product-review spec/SHOP-789-product-review
13# Branch feature dari spec branch yang sudah approved
14
15specify plan
16specify tasks
17specify implement

Pemisahan ini memungkinkan tech lead dan PM me-review spec sebelum developer mulai coding — sebuah feedback loop lebih awal yang tidak memblokir siapa pun.

12.5 Integrasi Spec Kit dengan Git Config

Spec Kit bisa mengetahui preferensi Git tim lewat file konfigurasi, sehingga penamaan branch dan pesan commit konsisten otomatis. Konfigurasi berikut mengatur format branch, auto-create, auto-push, dan template commit message.

 1# .speckit-config.yaml — git section
 2
 3git:
 4  # Format branch name yang di-suggest
 5  branch_format: "feature/{ticket}-{feature_name}"
 6
 7  # Auto-create branch saat specify feature
 8  auto_create_branch: true
 9
10  # Branch name saat auto-create
11  auto_branch_prefix: "feature/"
12
13  # Auto-push setelah setiap speckit command
14  auto_push: false  # default false, set true untuk continuous visibility
15
16  # Commit message format
17  commit_message_template: |
18    {type}({scope}): {description}
19
20    Implements: {spec_reference}
21    Task: {task_number} from {tasks_file}

Dengan template ini, setiap commit otomatis menautkan diri ke spec dan task tertentu — commit history berubah menjadi audit trail yang bisa dibaca mesin maupun manusia.

12.6 Branch Protection Rules untuk Spec-Driven Projects

Agar disiplin spec-first tidak bergantung pada niat baik developer, ia perlu ditegakkan di level branch protection. Aturan berikut mewajibkan PR, reviewer, dan status check yang menyertakan spec compliance sebelum merge ke main.

 1# GitHub Branch Protection (via Terraform atau manual)
 2
 3# main branch
 4rules:
 5  - require_pull_request: true
 6  - required_reviewers: 1
 7  - required_status_checks:
 8      - "Spec Compliance Check"  # CI yang run specify audit
 9      - "Build"
10      - "Test"
11  - dismiss_stale_reviews: true
12  - include_admin: false
13
14# Spec Check: enforce spec link in PR description
15spec_compliance:
16  - check_type: "spec_link_required"
17    pattern: "Spec.*: .specify/features/"
18    error_message: "PR must include a spec reference from .specify/features/"

Aturan spec_link_required inilah gerbang terakhir: tidak ada kode yang masuk ke main tanpa referensi spec yang jelas, mencegah “kode tanpa dokumentasi” merembes ke production.

12.7 Parallel Features: Dua Fitur Bersamaan

Salah satu keuntungan terbesar model ini muncul saat beberapa developer bekerja serentak. Contoh berikut menunjukkan dua fitur dikerjakan paralel tanpa saling mengganggu karena masing-masing punya branch dan folder spec sendiri.

 1# Developer A: product review
 2git checkout -b feature/SHOP-789-product-review
 3specify feature  # spec di .specify/features/product-review/
 4specify implement
 5
 6# Developer B: shipping calculator (bersamaan)
 7git checkout -b feature/SHOP-790-shipping-calculator
 8specify feature  # spec di .specify/features/shipping-calculator/
 9specify implement
10
11# Tidak ada konflik karena:
12# - Branch berbeda
13# - Spec folder berbeda (.specify/features/product-review/ vs /shipping-calculator/)
14# - Implementation files berbeda (biasanya)

Isolasi per-folder di .specify/features/ inilah yang membuat konflik spec nyaris tidak pernah terjadi — tiap fitur hidup di ruangnya sendiri.

12.8 Handling Merge Conflicts di .specify/

Meski jarang, konflik tetap bisa muncul di file yang shared seperti constitution.md. Cuplikan berikut menunjukkan cara meresolusi konflik constitution dengan aman sambil mempertahankan perubahan dari branch kamu.

 1# Jika ada conflict di .specify/ saat merge:
 2git merge main
 3# CONFLICT (.specify/constitution.md)
 4
 5# Constitution conflict: siapa yang benar?
 6git diff .specify/constitution.md
 7
 8# Biasanya karena ada update constitution di main
 9# Resolve: ambil versi main + pertahankan tambahan dari branch kamu
10git checkout --theirs .specify/constitution.md  # ambil versi main
11# Lalu manually add perubahan dari branch kamu
12
13# Feature spec files: tidak seharusnya conflict
14# Karena setiap fitur punya folder sendiri di .specify/features/

Kuncinya: file spec per-fitur hampir tidak pernah bentrok, jadi konflik yang perlu perhatian ekstra biasanya hanya di file bersama seperti constitution.

12.9 Long-Running Feature Branches

Fitur yang dikembangkan lebih dari seminggu berisiko drift dari main. Perintah berikut menjaga branch tetap sinkron lewat rebase reguler dan mencatat perubahan spec yang muncul dari feedback.

 1# Rebase secara regular untuk tetap sync dengan main
 2git fetch origin
 3git rebase origin/main
 4
 5# Jika ada update spec selama development (dari feedback):
 6git add .specify/features/product-review/spec.md
 7git commit -m "spec: update product review spec based on review feedback
 8
 9- AC14: clarified to include soft-deleted reviews in uniqueness check
10- NFR: added response time requirement (p95 < 200ms)"

Rebase rutin memastikan branch panjang tidak menumpuk konflik besar di akhir, dan commit spec terpisah membuat evolusi requirement tetap terdokumentasi.

12.10 Squash vs Preserve Commits

Tim perlu memutuskan bagaimana commit di-merge ke main. Blok pertama menunjukkan strategi preserve yang mempertahankan setiap commit per task.

1# Merge dengan semua commit dari branch
2git merge --no-ff feature/SHOP-789-product-review
3
4# Hasil: 14 individual commits di main
5# Benefit: bisa trace setiap task ke commit-nya
6# Tradeoff: git log lebih panjang

Preserve unggul untuk traceability: setiap task punya jejak commit sendiri. Sebagai perbandingan, blok berikut memperlihatkan strategi squash yang meringkas semuanya menjadi satu commit.

1# Squash semua ke satu commit
2git merge --squash feature/SHOP-789-product-review
3
4# Hasil: satu commit di main
5# Benefit: git log bersih
6# Tradeoff: kehilangan granular history per task

Squash menghasilkan git log yang lebih rapi dengan mengorbankan granularitas. Rekomendasi Spec Kit: preserve commits untuk traceability maksimal, tapi squash tetap acceptable jika tim lebih menghargai git log yang bersih.

12.11 Branch Lifecycle dengan Spec Kit

Agar setiap orang paham di fase mana sebuah branch berada, siklus hidupnya perlu eksplisit. Diagram berikut memetakan lima fase dari spec hingga archive.

 11. SPEC PHASE (branch: spec/SHOP-789-*)
 2   specify feature
 3   specify clarify
 4   [spec review dan approval]
 5
 62. PLANNING PHASE (masih di spec branch atau pindah ke feature branch)
 7   specify plan
 8   specify tasks
 9   [plan review dan approval]
10
113. IMPLEMENTATION PHASE (branch: feature/SHOP-789-*)
12   specify implement → 14 commits
13
144. REVIEW PHASE (PR ke main)
15   [code review oleh tim]
16   [CI: spec compliance check]
17   [Approval dan merge]
18
195. ARCHIVE PHASE (setelah merge)
20   specify tasks --archive --feature product-review
21   Delete feature branch (spec tetap ada di main via .specify/)

Perhatikan bahwa spec tetap tinggal di main bahkan setelah branch dihapus — branch bersifat sementara, tapi dokumentasi spec-nya permanen.

12.12 Template PR untuk Branch dengan Spec Kit

Template PR yang terstruktur memaksa setiap kontributor menautkan spec, mencatat compliance, dan melampirkan coverage. Template berikut bisa langsung dipakai sebagai pull_request_template.md.

 1## PR Template (.github/pull_request_template.md)
 2
 3## Feature Summary
 4[Deskripsi singkat]
 5
 6## Spec Reference
 7- **Spec**: .specify/features/[feature]/spec.md
 8- **Spec version**: v[x.x]
 9- **Spec status**: APPROVED by [reviewer] on [date]
10
11## Spec Compliance
12| AC/EC | Status | Notes |
13|-------|--------|-------|
14| AC1-AC5 | ✅ | |
15| AC6-AC10 | ✅ | |
16| EC1 | ✅ | UNIQUE INDEX handles |
17| EC2 | ✅ | Atomic transaction |
18
19## Tasks Completed
20| Task | Status | Duration | Notes |
21|------|--------|----------|-------|
22| 01: Domain Entity | ✅ | 35 min | |
23| 02: Migration | ✅ | 20 min | |
24| ... | | | |
25
26## Test Coverage
27[Paste output dari: go test -cover ./...]
28
29## Branch Cleanup
30- [ ] Feature branch akan di-delete setelah merge
31- [ ] Spec files tetap ada di .specify/features/ di main

Template ini membuat reviewer punya seluruh konteks dalam satu tempat — spec, status AC/EC, dan tasks — sehingga review jadi lebih cepat dan objektif.

12.13 Hotfix vs Feature: Workflow yang Berbeda

Tidak semua perubahan pantas melewati full Spec Kit workflow. Panduan berikut memilah kapan sebuah perubahan butuh feature branch dan kapan cukup hotfix branch:

Gunakan Spec Kit (feature branch):

• Fitur baru yang butuh spec
• Enhancement yang significant (>2 jam)
• Perubahan yang butuh approval PM/business

Tidak perlu Spec Kit (hotfix branch):

• Bug fix urgent yang jelas scope-nya (<30 menit)
• Typo fix atau minor copy change
• Config update
• Dependency security update

Untuk kasus hotfix, alurnya jauh lebih ringkas seperti contoh berikut yang melewati tahap specify sepenuhnya.

1# Hotfix: bypass Spec Kit
2git checkout -b hotfix/SHOP-901-fix-rating-precision
3# Fix langsung, tidak perlu specify feature/clarify/plan/tasks
4git push
5# PR dengan label: hotfix, bukan: spec-review

Membedakan dua jalur ini mencegah over-process: perbaikan kecil tetap cepat, sementara fitur bernilai tinggi tetap melewati disiplin spec-first.

12.14 Spec Kit + Gitflow: Compatibility

Spec Kit tidak memaksakan satu branching model — ia menempel di atas strategi apa pun yang sudah dipakai tim. Tiga diagram berikut menunjukkan penerapannya di GitHub Flow, Gitflow, dan trunk-based development.

1main ← feature branches (direct PR ke main)

GitHub Flow adalah yang paling natural karena feature branch langsung PR ke main. Untuk tim yang memakai staging terpisah, Gitflow menambahkan lapisan develop seperti berikut.

1main ← develop ← feature branches
2specify feature berjalan di feature branch

Di Gitflow, specify feature tetap berjalan di feature branch sebelum naik ke develop. Sementara untuk tim yang mengutamakan integrasi cepat, trunk-based development memakai branch berumur pendek seperti ini.

1main ← short-lived feature branches (< 2 hari)
2specify feature untuk fitur yang lebih besar, implement per-commit langsung

Intinya, Spec Kit fleksibel terhadap ketiganya — tapi GitHub Flow memberikan friksi paling kecil untuk SDD workflow.

12.15 CI Check untuk Branch dengan Spec Kit

Enforcement otomatis memastikan setiap feature branch benar-benar punya spec sebelum boleh di-merge. Workflow GitHub Actions berikut memeriksa keberadaan file spec berdasarkan nama branch.

 1# .github/workflows/spec-branch-check.yml
 2name: Spec Branch Check
 3
 4on:
 5  pull_request:
 6    branches: [main]
 7
 8jobs:
 9  check-spec-present:
10    runs-on: ubuntu-latest
11    steps:
12      - uses: actions/checkout@v4
13
14      - name: Check for spec file in PR
15        run: |
16          # Extract feature name dari branch name
17          BRANCH="${GITHUB_HEAD_REF}"
18
19          # Jika feature branch, cek ada spec-nya
20          if [[ "$BRANCH" == feature/* ]]; then
21            FEATURE=$(echo "$BRANCH" | sed 's/feature\/[A-Z0-9-]*-//')
22            SPEC_FILE=".specify/features/$FEATURE/spec.md"
23
24            if [ ! -f "$SPEC_FILE" ]; then
25              echo "❌ No spec found for feature branch: $BRANCH"
26              echo "   Expected: $SPEC_FILE"
27              exit 1
28            fi
29
30            echo "✅ Spec found: $SPEC_FILE"
31          fi

Check sederhana ini mengubah “setiap fitur harus punya spec” dari harapan menjadi aturan yang ditegakkan mesin di setiap PR.

12.16 Monorepo: Satu Spec Kit untuk Banyak Service

Di monorepo dengan banyak service, constitution bisa di-share sementara tiap service punya konfigurasinya sendiri. Struktur direktori berikut memperlihatkan pembagian antara constitution shared dan config per-service.

 1santekno-shop/
 2├── .specify/           ← shared constitution
 3│   ├── constitution.md
 4│   └── features/       ← feature specs (cross-service)
 5├── order-service/
 6│   ├── .speckit-config.yaml  ← service-specific config
 7│   └── .specify/             ← service-specific features (optional)
 8├── product-service/
 9│   └── .speckit-config.yaml
10└── notification-service/
11    └── .speckit-config.yaml

Dengan struktur ini, specify feature bisa dijalankan dari direktori service mana pun sambil tetap membaca constitution bersama seperti contoh berikut.

1# Run specify dari directory service tertentu:
2cd order-service
3specify feature --context "../.specify/constitution.md"
4
5# Atau dari root dengan flag:
6specify feature --service order-service

Pola ini menjaga konsistensi aturan lintas service (via constitution shared) tanpa mengorbankan otonomi tiap service dalam mengatur fiturnya sendiri.

12.17 Branch Audit: Cek Orphan Spec

Seiring waktu, sebagian spec bisa “yatim” — branch-nya sudah dihapus tapi spec masih menggantung. Perintah berikut memindai spec tanpa feature branch yang cocok dan menandainya untuk ditindaklanjuti.

 1# List semua spec yang tidak ada matching feature branch
 2specify audit --orphan-specs
 3
 4# Output:
 5# ⚠️  Orphan specs found:
 6# .specify/features/payment-gateway/ — no feature/SHOP-800-* branch exists
 7# .specify/features/loyalty-points/  — no feature/SHOP-750-* branch exists
 8#
 9# These specs may be:
10# 1. Implemented and merged (check git log)
11# 2. Abandoned (archive or delete)
12# 3. Waiting for implementation (keep and track)

Audit orphan spec ini penting untuk kebersihan repo jangka panjang: ia memaksa kamu memutuskan apakah tiap spec sudah selesai, ditinggalkan, atau masih menunggu implementasi.

12.18 Tips & Gotchas

Beberapa kebiasaan kecil membuat branching strategy ini berjalan mulus. Tip pertama menyangkut urutan: buat branch dulu, baru specify feature.

1git checkout -b feature/SHOP-789-product-review
2specify feature
3# Spec langsung ter-associate ke branch yang tepat

Dengan urutan ini, spec langsung terikat ke branch yang benar sejak awal — tidak ada spec nyasar di branch keliru.

💡 Tip 2: Push spec branch untuk early feedback — tidak perlu menunggu implementasi selesai. Push spec branch dulu, buat draft PR, dan minta review spec dari PM serta tech lead.

💡 Tip 3: Gunakan branch name yang deskriptif — feature/SHOP-789-product-review jauh lebih informatif dari feature/789 atau feature/review, memudahkan navigasi saat banyak fitur paralel.

💡 Tip 4: Archive branch setelah merge, jangan delete spec — branch boleh dihapus, tapi .specify/features/product-review/ di main tetap ada sebagai dokumentasi permanen.

⚠️ Gotcha 1: Spec di branch lama bisa outdated — jika feature branch lama tidak di-update, spec-nya mungkin sudah tidak relevan; rebase dengan main dan perbarui spec bila perlu.

⚠️ Gotcha 2: Constitution conflict saat merge bisa tricky — jika dua branch sama-sama meng-update constitution.md, resolusi perlu manual dan hati-hati; koordinasikan sebelum mengubah constitution.

⚠️ Gotcha 3: Auto-create branch bisa bikin branch orphan — jika auto_create_branch: true, branch ter-create otomatis saat specify feature; pastikan kamu memang mau branch baru sebelum menjalankannya.

⚠️ Gotcha 4: Jangan merge spec branch ke feature branch tanpa rebase. Bandingkan pendekatan yang salah dan yang benar pada cuplikan berikut.

1# ❌ Jangan:
2git checkout feature/SHOP-789
3git merge spec/SHOP-789  # bisa ada weird merge commits
4
5# ✅ Lakukan:
6git checkout feature/SHOP-789
7git rebase spec/SHOP-789  # clean history

Memakai rebase alih-alih merge di sini menjaga history tetap linear dan bersih, menghindari merge commit aneh yang mengaburkan jejak per-task.

12.19 Branch Strategy untuk Release Cycle

Untuk tim dengan siklus rilis berbasis staging, Spec Kit menyatu mulus dengan alur promote dari develop ke main. Contoh berikut menunjukkan feature branch yang naik ke staging lalu ke production, ditutup dengan audit rilis.

 1# Release-based workflow dengan Spec Kit
 2
 3# Feature development di feature branch
 4git checkout -b feature/SHOP-789-product-review
 5specify implement
 6
 7# Merge ke develop dulu (staging)
 8git checkout develop
 9git merge feature/SHOP-789-product-review
10
11# Setelah testing di staging pass:
12git checkout main
13git merge develop  # atau release branch
14
15# Spec Kit audit di release:
16specify audit --branch main --vs develop
17# Cek: apakah ada spec di develop yang belum di-implement di main?

Audit main vs develop di akhir memastikan tidak ada spec yang tertinggal saat promote — gerbang rilis yang menjaga production selalu selaras dengan yang sudah lolos staging.

12.20 Ringkasan

Branching strategy “satu fitur, satu branch, satu spec” bukan hanya Git hygiene — ini adalah cara menjaga SDD workflow tetap terikat ke unit kerja yang jelas dan dapat di-audit.

Feature branch = unit of work yang punya spec, plan, tasks, dan implementasi yang saling terhubung.

Spec branch berguna untuk review spec sebelum implementasi dimulai — memungkinkan feedback loop lebih awal tanpa blocker.

CI enforcement memastikan setiap PR ke main punya spec reference — mencegah kode masuk tanpa dokumentasi yang proper.

Di artikel berikutnya, kita bahas Git workflow lebih dalam: auto-commit dan PR generation dari Spec Kit — bagaimana commit history yang bersih dan PR description yang komprehensif di-generate secara otomatis.