Product Manager datang membawa satu fitur baru: kode diskon di checkout. Kedengarannya sederhana, sampai kita sadar fitur itu menyentuh order-service, pricing-service, dan mungkin notification-service. Tiga service, tiga repo, tiga tim reviewer. Pertanyaannya: spec-nya ditaruh di mana?
Itu persis masalah yang saya hadapi waktu pertama kali menerapkan OpenSpec multi-repo di lingkungan microservices. Artikel ini adalah catatan pengalaman pribadi: pendekatan pertama yang ternyata melelahkan, lalu pola yang akhirnya saya pakai sampai sekarang, yaitu satu repo payung + git submodule + git worktree, sehingga satu fitur dari PM cukup jadi satu proposal yang bisa dikerjakan paralel di banyak service.
Catatan: pola di artikel ini adalah rekomendasi pribadi dari pengalaman di tim microservices, bukan fitur resmi OpenSpec. Fitur resmi untuk multi-repo adalah Stores dan Worksets, yang saat artikel ini ditulis masih berstatus beta. Contoh diuji dengan OpenSpec CLI v1.16.x dan service Go 1.23+.
Apa yang akan kita pelajari
- Konsep singkat Spec-Driven Development (SDD) dan kenapa relevan di era AI coding agent
- Apa itu OpenSpec dan bagaimana siklus kerjanya
- Kenapa SDD jadi rumit begitu service kita tersebar di banyak repo
- Arsitektur repo payung + submodule + worktree
- Workflow end-to-end satu change lintas service, dari
exploresampaiarchive - Aturan main, jebakan, dan kekurangan SDD untuk microservices
Prasyarat
- Node.js 22.12+ dan OpenSpec CLI (
npm install -g @fission-ai/openspec@latest) - Git 2.30+ (butuh
submoduledanworktree) - AI coding tool yang didukung OpenSpec. Contoh di sini memakai Claude Code
- GitHub CLI (
gh) untuk membuat PR dari terminal - Paham dasar microservices. Kalau belum, baca dulu SDD untuk microservice Golang
Apa itu Spec-Driven Development (SDD)?
Spec-Driven Development (SDD) adalah cara kerja di mana kita dan AI agent menyepakati apa yang akan dibangun dalam bentuk spesifikasi tertulis, baru kemudian AI menulis bagaimana-nya. Spesifikasi disimpan di Git, direview seperti kode, dan dibaca ulang oleh agent di sesi berikutnya.
Kenapa ini penting? AI agent itu sangat cepat, tapi juga sangat literal. Kalau kebutuhan hanya hidup di riwayat chat, hasilnya sering “jalan” tapi meleset dari maksud. Begitu sesi ditutup, konteksnya hilang.
flowchart LR
subgraph Vibe["Vibe coding"]
V1["Prompt in chat"] --> V2["AI writes code"]
V2 --> V3["Works, but is it what we meant?"]
V3 -->|"re-prompt"| V1
end
subgraph SDD["Spec-Driven Development"]
S1["Agree on the spec"] --> S2["Human reviews the spec"]
S2 --> S3["AI implements against the spec"]
S3 --> S4["Spec stays in Git as the source of truth"]
end
style S1 fill:#f0f4ff,stroke:#4f6ef7
style S4 fill:#f0f4ff,stroke:#4f6ef7
Diagram 1: vibe coding berputar di chat, sedangkan SDD menaruh kesepakatan di file yang bisa direview.
Analogi yang paling pas buat saya: SDD itu seperti menulis kontrak API sebelum menulis handler. Kita tidak debat di level kode, kita debat di level perilaku.
Apa itu OpenSpec?
OpenSpec adalah tool SDD open source yang ringan. Ia menaruh spesifikasi di folder openspec/ di dalam repo, dan setiap perubahan ditulis sebagai change yang berisi proposal, delta spec, design, dan daftar task.
Tiga hal yang bikin OpenSpec cocok untuk sistem yang sudah berjalan:
- Dibuat untuk brownfield. Kita tidak perlu menulis spec seluruh sistem di awal. Kita hanya menulis spec untuk bagian yang akan diubah, dan
openspec/specs/tumbuh bertahap. - Delta spec. Sebuah change hanya berisi apa yang ditambah (
ADDED), diubah (MODIFIED), atau dihapus (REMOVED). Saat change diarsipkan, delta digabung ke spec utama. - Lintas tool. Perintahnya berjalan di banyak AI coding tool, jadi tim tidak dikunci ke satu editor.
Struktur folder OpenSpec
1openspec/
2├── config.yaml # project context + rules for the AI
3├── specs/ # main specs: what the system does today
4│ └── orders/spec.md
5└── changes/
6 ├── add-order-discount/ # one active change
7 │ ├── proposal.md # why and what
8 │ ├── specs/ # delta specs
9 │ ├── design.md # how (only when needed)
10 │ └── tasks.md # checklist the agent works through
11 └── archive/ # finished changesCara kerja OpenSpec: lima langkah
flowchart LR
E["explore
discuss, no code"] --> P["propose
create the change folder"]
P --> R{"human review
approved?"}
R -->|"revise"| P
R -->|"yes"| A["apply
AI works through tasks.md"]
A --> AR["archive
merge deltas into specs"]
style P fill:#f0f4ff,stroke:#4f6ef7
style A fill:#f0f4ff,stroke:#4f6ef7
style AR fill:#f0f4ff,stroke:#4f6ef7
Diagram 2: siklus OpenSpec. Manusia memegang gerbang review sebelum satu baris kode ditulis.
Satu jebakan pemula yang perlu diingat: perintah openspec ... dijalankan di terminal, sedangkan /opsx:... dijalankan di chat AI.
Kenapa OpenSpec multi-repo di microservices itu rumit?
OpenSpec secara default berpusat pada satu root project. Di monolith atau monorepo ini tidak masalah. Di microservices, setiap service punya repo, CI, dan PR sendiri, dan di situlah ceritanya mulai.
Pendekatan pertama saya: satu OpenSpec per repo
Awalnya saya menerapkan cara yang paling lurus: setiap repo service punya folder openspec/ masing-masing, dengan proposal masing-masing. Untuk bahan diskusi, saya membuat Technical Requirement Document (TRD) dengan melihat tiap service satu per satu, lalu menggabungkannya menjadi satu dokumen yang bisa dipresentasikan ke anggota tim dan lead.
Cara ini berjalan, tapi sangat melelahkan:
- Saya harus membuka repo tiap service dan menjalankan
/opsx:exploredi masing-masing repo hanya untuk memahami kondisi service itu. - Planning fitur baru juga dilakukan per service, lalu saya sendiri yang jadi “lem” antar dokumen.
- Begitu PM membawa fitur yang keterkaitannya lebih dari dua service, assessment-nya harus diulang di tiap service secara terpisah. Waktunya habis di situ, bukan di desain.
flowchart TD
PM["PM: one new feature"] --> A1["Open order-service
run explore"]
PM --> A2["Open pricing-service
run explore"]
PM --> A3["Open notification-service
run explore"]
A1 --> D1["Proposal in order-service"]
A2 --> D2["Proposal in pricing-service"]
A3 --> D3["Proposal in notification-service"]
D1 --> M["Manually merge into one TRD"]
D2 --> M
D3 --> M
M --> T["Present to team and lead"]
style M fill:#fff4e5,stroke:#f59e0b
Diagram 3: pendekatan per repo. Node kuning adalah pekerjaan manual yang paling menguras waktu.
Ide yang mengubah cara kerja saya
Dari situ muncul idenya: satu fitur dari PM seharusnya jadi satu proposal OpenSpec, walaupun implementasinya tersebar di banyak repo. Saya cukup menjalankan /opsx:explore di satu root folder, lalu AI yang membantu menelusuri semua service yang terkait dengan fitur tersebut. Hasilnya satu proposal (atau beberapa proposal) yang bisa dikerjakan paralel di tiap microservice.
Manfaatnya makin terasa ketika jumlah service sudah banyak dan saling terikat satu sama lain.
Tiga opsi dan trade-off-nya
| Opsi | Rumah spec | Kelebihan | Kekurangan |
|---|---|---|---|
| OpenSpec per repo | Di tiap service | Sederhana, mandiri per tim | Fitur lintas service terpecah, explore berulang, TRD digabung manual |
| Stores + Worksets (resmi) | Repo planning terpisah | Didukung langsung oleh OpenSpec | Masih beta, perintah dan format file bisa berubah antar rilis |
| Repo payung + submodule + worktree | Di repo payung | Git biasa, stabil, satu explore untuk semua service | Tim harus disiplin dengan submodule |
Saya memilih opsi ketiga karena hanya bergantung pada Git yang sudah dipahami semua orang.
Arsitektur: repo payung + submodule + worktree
Idenya: satu repo payung (umbrella) menyimpan spec dan menunjuk ke repo service lewat submodule. Spec dan change hidup di root, kode tetap hidup di repo service masing-masing. Worktree dipakai ketika beberapa change dikerjakan paralel.
graph TD
U["platform (umbrella repo)"] --> O["openspec/
specs + changes for all services"]
U --> S1["services/order-service
git submodule"]
U --> S2["services/pricing-service
git submodule"]
U --> W["services/worktree/
git-ignored"]
W --> C1["add-order-discount/order-service
branch feat/add-order-discount"]
W --> C2["add-order-discount/pricing-service
branch feat/add-order-discount"]
S1 -.->|"worktree of"| C1
S2 -.->|"worktree of"| C2
style U fill:#f0f4ff,stroke:#4f6ef7
style O fill:#f0f4ff,stroke:#4f6ef7
Diagram 4: repo payung hanya berisi spec dan pointer. Kode tetap milik repo service.
1platform/ # umbrella repo: specs + pointers
2├── openspec/
3│ ├── config.yaml
4│ ├── specs/
5│ │ ├── order-service/orders/spec.md
6│ │ └── pricing-service/discounts/spec.md
7│ └── changes/
8│ └── add-order-discount/ # deltas for BOTH services
9├── services/
10│ ├── order-service/ # git submodule (own repo, CI, PRs)
11│ ├── pricing-service/ # git submodule
12│ └── worktree/ # git-ignored, only for parallel changes
13│ └── add-order-discount/
14│ ├── order-service/ # worktree on feat/add-order-discount
15│ └── pricing-service/ # worktree on feat/add-order-discount
16├── .gitmodules
17├── .gitignore # contains: services/worktree/
18└── CLAUDE.md| Bagian | Isi | Aturan |
|---|---|---|
openspec/ | Spec semua service + change lintas service | Capability diberi prefix nama service: order-service/orders |
services/<service>/ | Submodule, checkout utama tiap service | Selalu menunjuk commit yang sudah di-merge di service itu |
services/worktree/<change>/<service>/ | Worktree per change per service | Dipakai saat lebih dari satu change jalan bersamaan, dihapus setelah merge |
Workflow satu change lintas service
Sebelum masuk ke perintah, lihat dulu gambaran besarnya.
flowchart TD
X["/opsx:explore at the umbrella root
AI scans every related service"] --> P["/opsx:propose
one change, deltas per service"]
P --> R{"Review and merge proposal
to umbrella main"}
R --> W["Create one worktree
per touched service"]
W --> A["/opsx:apply
agent edits only this change's worktrees"]
A --> PR["One PR per service repo
same branch name"]
PR --> M["Merge services
backward compatible one first"]
M --> U["Umbrella PR
bump submodule pointers + archive"]
U --> C["Remove worktrees"]
style X fill:#f0f4ff,stroke:#4f6ef7
style P fill:#f0f4ff,stroke:#4f6ef7
style R fill:#f0f4ff,stroke:#4f6ef7
style U fill:#f0f4ff,stroke:#4f6ef7
Diagram 5: node biru terjadi di repo payung, sisanya terjadi di repo service.
sequenceDiagram
participant Dev as Developer
participant Agent as AI Agent
participant Umbrella as Umbrella Repo
participant Pricing as pricing-service Repo
participant Order as order-service Repo
Dev->>Agent: /opsx:explore add order discount
Agent->>Umbrella: Read openspec/ and services/*
Agent-->>Dev: Affected services and options
Dev->>Agent: /opsx:propose add-order-discount
Agent->>Umbrella: Write proposal, delta specs, design, tasks
Dev->>Umbrella: Review and merge proposal PR
Dev->>Agent: /opsx:apply add-order-discount
Agent->>Pricing: Commit on feat/add-order-discount
Agent->>Order: Commit on feat/add-order-discount
Dev->>Pricing: Merge PR first
Dev->>Order: Merge PR second
Dev->>Umbrella: Bump submodule pointers and archive
Diagram 6: urutan interaksi developer, agent, repo payung, dan repo service untuk satu change.
Implementasi step-by-step
1. Menyiapkan repo payung dan submodule
Langkah ini cukup sekali per platform.
1mkdir platform && cd platform && git init -b main
2
3# Register each service as a submodule tracking its main branch
4git submodule add -b main https://github.com/<org>/order-service.git services/order-service
5git submodule add -b main https://github.com/<org>/pricing-service.git services/pricing-service
6
7# Worktrees are a working tool, never part of the umbrella history
8echo "services/worktree/" >> .gitignore
9
10openspec init --tools claude
11git add -A && git commit -m "chore: umbrella repo with service submodules"
12
13# Make git pull/switch update submodules too
14git config submodule.recurse trueAnggota tim lain cukup clone dengan satu perintah:
1git clone --recurse-submodules https://github.com/<org>/platform.git2. Mengajari agent tentang layout multi-repo
Agent tidak tahu bahwa services/ berisi repo lain kecuali kita beri tahu. Dua file yang jadi kuncinya: openspec/config.yaml dan CLAUDE.md.
1# openspec/config.yaml
2schema: spec-driven
3
4context: |
5 Umbrella repo. Specs live in openspec/; code lives in git submodules under services/:
6 services/order-service (Go, orders API), services/pricing-service (Go, pricing API).
7 One change may touch several services. Capabilities are named <service>/<area>,
8 e.g. order-service/orders. Each service has its own repo, CI, and PR.
9
10rules:
11 design:
12 - 'File change paths start with services/<service>/. Add a "Merge order" section:
13 which service merges first, and why that order stays backward compatible.'
14 tasks:
15 - 'Group tasks per service: "## 1. pricing-service", "## 2. order-service",
16 then Tests and Review. Every task names its service.'1<!-- CLAUDE.md -->
2## Multi-repo rules
3
4- Code for a change lives in services/worktree/<change>/<service>/ when that folder exists,
5 otherwise in services/<service>/. Never edit another change's worktree.
6- Commit and push inside each service; each service gets its own PR on feat/<change>.
7- The umbrella only commits openspec/ and submodule pointers. Never commit inside
8 services/worktree/ from the umbrella.Rule Merge order di design.md kelihatannya sepele, padahal ini yang menyelamatkan kita dari deploy yang saling menunggu.
3. Menjalankan explore dari root repo payung
Inilah bagian yang menggantikan ritual “buka repo satu per satu”. Dari root repo payung:
1/opsx:explore
2PM wants discount codes at checkout. Which services are affected,
3what contracts change, and what is the smallest safe increment?Karena semua service ada di bawah services/, agent bisa membaca handler di order-service, aturan harga di pricing-service, dan spec yang sudah ada di openspec/specs/ dalam satu sesi. explore tidak menulis file apa pun. Hasilnya adalah pemahaman dan opsi, yang sekaligus jadi bahan presentasi ke tim dan lead tanpa perlu menjahit dokumen dari tiga repo.
4. Membuat satu proposal untuk beberapa service
1/opsx:propose add-order-discount
2Orders (order-service) accept a discount code; pricing (pricing-service) validates it.
3Deltas on order-service/orders and pricing-service/discounts.
4Keep both APIs backward compatible.Hasilnya satu folder change yang memuat delta untuk kedua service:
1openspec/changes/add-order-discount/
2├── proposal.md
3├── specs/order-service/orders/spec.md # MODIFIED: create order accepts discountCode
4├── specs/pricing-service/discounts/spec.md # ADDED: validate discount code
5├── design.md # file changes per service + Merge order
6└── tasks.md # 1. pricing-service 2. order-service 3. Tests 4. ReviewContoh delta spec untuk pricing-service:
1## ADDED Requirements
2
3### Requirement: Validate discount code
4The pricing service SHALL validate a discount code against an order subtotal
5and return the discount amount.
6
7#### Scenario: Valid code
8- **WHEN** a request contains an active code and a subtotal above the minimum spend
9- **THEN** the service returns the discount amount and HTTP 200
10
11#### Scenario: Expired code
12- **WHEN** a request contains a code past its expiry date
13- **THEN** the service returns HTTP 422 with reason `DISCOUNT_EXPIRED`Merge proposal ke main repo payung lebih dulu sebagai PR kecil yang hanya berisi openspec/. Dengan begitu review spec terjadi sebelum ada kode, dan change lain bisa berjalan paralel di atasnya.
5. Membuat worktree per change
Buat satu worktree untuk setiap service yang disentuh change ini. Nama branch-nya sama di semua service: feat/<change>.
1C=add-order-discount
2for s in order-service pricing-service; do
3 git -C services/$s fetch origin
4 # New branch feat/$C from origin/main, checked out in its own folder
5 git -C services/$s worktree add -b feat/$C ../worktree/$C/$s origin/main
6done
7
8ls services/worktree/$C # order-service pricing-serviceKenapa worktree, bukan langsung checkout branch di submodule? Karena begitu ada dua change berjalan bersamaan, dua sesi agent akan berebut working directory yang sama. Dengan worktree, setiap change punya foldernya sendiri dan tidak saling menimpa.
6. Menjalankan apply
Jalankan dari root repo payung, satu sesi agent per change:
1/opsx:apply add-order-discount
2Code for this change lives only in services/worktree/add-order-discount/.
3Follow the Merge order in design.md.7. PR per service, urutan merge, dan pointer submodule
1C=add-order-discount
2
3# Follow the Merge order from design.md: pricing-service first
4for s in pricing-service order-service; do
5 git -C services/worktree/$C/$s push -u origin feat/$C
6 (cd services/worktree/$C/$s && gh pr create --fill --title "feat: $C")
7done
8
9# After BOTH service PRs are merged:
10git -C services/order-service pull origin main
11git -C services/pricing-service pull origin main
12
13git switch -c chore/archive-$C
14openspec archive $C --yes
15git add openspec services/order-service services/pricing-service # new submodule pointers
16git commit -m "chore: archive $C and bump order-service, pricing-service"
17gh pr create --fill8. Membersihkan worktree
1for s in order-service pricing-service; do
2 git -C services/$s worktree remove ../worktree/$C/$s
3 git -C services/$s branch -d feat/$C
4doneContoh nyata: fitur kode diskon di Santekno Shop
Mari lihat kenapa urutan merge itu penting. order-service akan memanggil endpoint baru di pricing-service. Kalau order-service di-deploy lebih dulu, ia memanggil endpoint yang belum ada.
Jadi design.md menulis: pricing-service merge dulu (endpoint baru bersifat aditif, tidak ada consumer yang rusak), baru order-service. Di sisi order-service, field baru dibuat opsional supaya client lama tetap jalan:
1package order
2
3// CreateOrderRequest is the payload for POST /orders.
4// DiscountCode is optional so existing clients keep working unchanged.
5type CreateOrderRequest struct {
6 UserID string `json:"userId"`
7 Items []OrderItem `json:"items"`
8 DiscountCode *string `json:"discountCode,omitempty"`
9}
10
11// OrderItem is a single product line in an order.
12type OrderItem struct {
13 ProductID string `json:"productId"`
14 Quantity int `json:"quantity"`
15}
16
17// HasDiscount reports whether the client sent a non-empty discount code.
18func (r CreateOrderRequest) HasDiscount() bool {
19 return r.DiscountCode != nil && *r.DiscountCode != ""
20}Siklus hidup change-nya terlihat seperti ini:
stateDiagram-v2
[*] --> Explored: /opsx explore at umbrella root
Explored --> Proposed: /opsx propose
Proposed --> Approved: proposal PR merged to umbrella main
Approved --> InProgress: worktrees created, /opsx apply
InProgress --> PricingMerged: pricing-service PR merged
PricingMerged --> OrderMerged: order-service PR merged
OrderMerged --> Archived: bump pointers, openspec archive
Archived --> [*]
Diagram 7: state sebuah change lintas service. Archive baru boleh terjadi setelah semua PR service merge.
Sementara itu, kalau PM membawa fitur kedua, misalnya add-shipping-estimate, kita tinggal membuat set worktree baru di services/worktree/add-shipping-estimate/ dan menjalankan sesi agent kedua. Dua change, dua set folder, tidak ada yang saling injak.
Aturan main
| Aturan | Alasan |
|---|---|
| Satu change = satu branch dengan nama sama di setiap service | PR di order-service dan pricing-service mudah dilacak lewat nama change |
| Merge service dulu, baru repo payung | Pointer submodule hanya boleh menunjuk commit yang sudah ada di main service |
Perubahan API harus backward compatible, urutan merge ditulis di design.md | Service di-deploy terpisah, tidak ada deploy atomik lintas repo |
| Archive di repo payung setelah semua PR service merge | Spec utama hanya menggambarkan yang benar-benar sudah jalan |
services/worktree/ di-gitignore dan dihapus setelah selesai | Worktree hanya alat kerja, bukan bagian riwayat repo payung |
Tips & gotchas
| Gejala | Solusi |
|---|---|
Folder services/order-service kosong setelah clone | git submodule update --init --recursive |
| Submodule dalam keadaan detached HEAD | Normal untuk submodule. Kerja di worktree feat/<change>, atau git -C services/order-service switch main |
fatal: 'feat/x' is already checked out | Branch itu dipakai worktree lain. Cek dengan git -C services/order-service worktree list |
git status payung menampilkan modified: services/order-service (new commits) | Pointer berubah. Commit hanya setelah PR service merge |
Beberapa hal lain yang saya pelajari di lapangan:
- Jangan commit pointer submodule ke commit yang belum merge. Begitu branch service di-rebase atau di-squash, pointer di repo payung menunjuk commit yang sudah tidak ada.
- Pin versi OpenSpec CLI di dokumentasi tim dan CI. OpenSpec rilis sangat sering. Upgrade dengan sengaja, bukan karena kebetulan.
- Tulis
contextdiconfig.yamlseperti onboarding engineer baru. Sebutkan bahasa, tanggung jawab tiap service, dan siapa memanggil siapa. Kualitasexploresangat bergantung pada bagian ini. - Proposal kecil lebih cepat disetujui. Kalau satu fitur terlalu besar, pecah jadi beberapa change yang bisa dikerjakan paralel.
Kapan pola ini tidak cocok
- Sudah monorepo. OpenSpec bawaan sudah cukup, tidak perlu repo payung.
- Hanya satu atau dua service yang jarang bersinggungan. Overhead submodule tidak sebanding. OpenSpec per repo masih masuk akal.
- Fitur yang memanggil sistem milik tim lain. Di situ yang dibutuhkan adalah kontrak antar tim, bukan akses ke kode mereka. Lihat pendekatan contract-first di SDD untuk microservice Golang .
- Tim belum nyaman dengan submodule. Luangkan waktu untuk membiasakan diri dulu, atau evaluasi Stores dan Worksets begitu keluar dari beta.
Kekurangan SDD untuk microservices
Supaya adil, pola ini bukan tanpa biaya. Beberapa kekurangan SDD di lingkungan microservices yang perlu kita sadari sebelum mengadopsinya:
- Overhead untuk perubahan kecil. Proposal, delta spec, design, dan tasks terasa berlebihan untuk bug fix satu baris atau perubahan config. Tanpa kesepakatan “perubahan seperti apa yang wajib lewat spec”, tim cepat merasa prosesnya memperlambat.
- Spec drift tetap bisa terjadi. Hotfix yang langsung masuk ke repo service tidak lewat repo payung, sehingga spec utama diam-diam tertinggal dari kode. Semakin banyak service, semakin banyak pintu untuk drift. Butuh disiplin atau pengecekan otomatis, lihat spec drift detection .
- Tidak ada atomicity lintas repo. Spec-nya satu change, tapi merge dan deploy-nya tetap terpisah per service. Kalau PR
pricing-servicesudah merge sementara PRorder-servicetertahan review, sistem berada di kondisi setengah jadi dan change belum bisa di-archive. - Review jadi bottleneck baru. Proposal lintas service perlu dibaca owner tiap service. AI juga mudah menghasilkan dokumen yang panjang, dan spec yang disetujui tanpa benar-benar dibaca lebih berbahaya daripada tidak punya spec, karena memberi rasa aman palsu.
- Biaya context dan token. Menjalankan
exploredi root berarti agent membaca banyak service sekaligus. Pada puluhan service, sesi jadi mahal dan kualitas analisisnya bisa turun kalaucontextdiconfig.yamltidak mengarahkan agent ke service yang relevan. - Akses dan ownership. Repo payung menuntut akses baca ke semua repo service. Di organisasi dengan batas akses antar tim, ini belum tentu boleh. Harus jelas juga siapa pemilik repo payung dan siapa yang berhak meng-approve proposal.
- Spec bukan pengganti contract test. Menulis “backward compatible” di
design.mdtidak memaksa apa pun saat runtime. Kontrak antar service tetap perlu dijaga dengan contract testing dan CI di tiap service. - Tooling masih bergerak cepat. OpenSpec rilis sangat sering dan fitur multi-repo resminya masih beta. Pola submodule + worktree ini pun menambah gesekan Git yang harus dipelajari seluruh anggota tim.
Tidak satu pun dari poin ini membatalkan manfaatnya, tapi semuanya nyata. Buat saya aturan praktisnya: pakai SDD untuk perubahan yang mengubah perilaku atau kontrak antar service, dan biarkan perubahan kecil lewat jalur PR biasa.
Kesimpulan
Menerapkan OpenSpec multi-repo di microservices bukan soal tool tambahan, tapi soal menentukan rumah yang tepat untuk spec. Dengan repo payung, submodule, dan worktree, satu fitur dari PM menjadi satu proposal, /opsx:explore cukup dijalankan sekali dari root, dan implementasinya bisa berjalan paralel di tiap service dengan PR dan CI masing-masing.
Bagi saya, perubahan terbesarnya ada di fase awal: waktu yang tadinya habis untuk membuka repo satu per satu dan menjahit dokumen, sekarang dipakai untuk mendiskusikan desain.
Bacaan lanjutan di Santekno:
- SDD untuk microservice Golang: API contract antar service untuk memahami kontrak antar service
- Ekosistem tools SDD 2026 untuk membandingkan OpenSpec dengan tool lain
- Spec drift detection supaya spec dan kode tidak diam-diam berpisah jalan
- SDD di tim untuk alur review spec bersama anggota tim
Referensi resmi: dokumentasi OpenSpec dan repo Fission-AI/OpenSpec .