Skip to content
Santekno.com | Level Up Your Engineering Skills
ID
📖 0%

OpenSpec Multi-Repo: Implementasi SDD di Microservices dengan Submodule + Worktree

· 17 mnt baca ·Ihsan Arif

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 explore sampai archive
  • 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 submodule dan worktree)
  • 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

text
 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 changes

Cara 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:explore di 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

OpsiRumah specKelebihanKekurangan
OpenSpec per repoDi tiap serviceSederhana, mandiri per timFitur lintas service terpecah, explore berulang, TRD digabung manual
Stores + Worksets (resmi)Repo planning terpisahDidukung langsung oleh OpenSpecMasih beta, perintah dan format file bisa berubah antar rilis
Repo payung + submodule + worktreeDi repo payungGit biasa, stabil, satu explore untuk semua serviceTim 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.

text
 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
BagianIsiAturan
openspec/Spec semua service + change lintas serviceCapability diberi prefix nama service: order-service/orders
services/<service>/Submodule, checkout utama tiap serviceSelalu menunjuk commit yang sudah di-merge di service itu
services/worktree/<change>/<service>/Worktree per change per serviceDipakai 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.

bash
 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 true

Anggota tim lain cukup clone dengan satu perintah:

bash
1git clone --recurse-submodules https://github.com/<org>/platform.git

2. 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.

yaml
 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.'
md
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:

text
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

text
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:

text
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. Review

Contoh delta spec untuk pricing-service:

md
 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>.

bash
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-service

Kenapa 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:

text
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

bash
 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 --fill

8. Membersihkan worktree

bash
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
4done

Contoh 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:

go
 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

AturanAlasan
Satu change = satu branch dengan nama sama di setiap servicePR di order-service dan pricing-service mudah dilacak lewat nama change
Merge service dulu, baru repo payungPointer submodule hanya boleh menunjuk commit yang sudah ada di main service
Perubahan API harus backward compatible, urutan merge ditulis di design.mdService di-deploy terpisah, tidak ada deploy atomik lintas repo
Archive di repo payung setelah semua PR service mergeSpec utama hanya menggambarkan yang benar-benar sudah jalan
services/worktree/ di-gitignore dan dihapus setelah selesaiWorktree hanya alat kerja, bukan bagian riwayat repo payung

Tips & gotchas

GejalaSolusi
Folder services/order-service kosong setelah clonegit submodule update --init --recursive
Submodule dalam keadaan detached HEADNormal untuk submodule. Kerja di worktree feat/<change>, atau git -C services/order-service switch main
fatal: 'feat/x' is already checked outBranch 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 context di config.yaml seperti onboarding engineer baru. Sebutkan bahasa, tanggung jawab tiap service, dan siapa memanggil siapa. Kualitas explore sangat 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:

  1. 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.
  2. 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 .
  3. Tidak ada atomicity lintas repo. Spec-nya satu change, tapi merge dan deploy-nya tetap terpisah per service. Kalau PR pricing-service sudah merge sementara PR order-service tertahan review, sistem berada di kondisi setengah jadi dan change belum bisa di-archive.
  4. 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.
  5. Biaya context dan token. Menjalankan explore di root berarti agent membaca banyak service sekaligus. Pada puluhan service, sesi jadi mahal dan kualitas analisisnya bisa turun kalau context di config.yaml tidak mengarahkan agent ke service yang relevan.
  6. 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.
  7. Spec bukan pengganti contract test. Menulis “backward compatible” di design.md tidak memaksa apa pun saat runtime. Kontrak antar service tetap perlu dijaga dengan contract testing dan CI di tiap service.
  8. 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:

Referensi resmi: dokumentasi OpenSpec dan repo Fission-AI/OpenSpec .

IH
Ihsan Arif
Backend engineer & penulis di Santekno. Aktif menulis tentang Go, Laravel, dan arsitektur backend modern.
Follow

💬 Komentar