Konsep
Panduan ini menjelaskan ide-ide inti di balik OpenSpec dan bagaimana konsep-konsep tersebut saling terkait. Untuk penggunaan praktis, lihat Memulai dan Alur Kerja.
Filosofi
OpenSpec dibangun berdasarkan empat prinsip:
fluid not rigid — tanpa fase yang kaku, kerjakan apa yang masuk akal
iterative not waterfall — belajar saat membangun, sempurnakan seiring berjalan
easy not complex — pengaturan ringan, minim prosedur formal
brownfield-first — bekerja dengan basis kode yang ada, bukan hanya proyek baruMengapa Prinsip-Prinsip Ini Penting
Fluid not rigid. Sistem spesifikasi tradisional mengunci Anda ke dalam fase-fase tertentu: pertama Anda merencanakan, kemudian Anda mengimplementasikan, lalu selesai. OpenSpec lebih fleksibel — Anda dapat membuat artefak dalam urutan apa pun yang sesuai dengan pekerjaan Anda.
Iterative not waterfall. Persyaratan berubah. Pemahaman semakin mendalam. Apa yang tampak sebagai pendekatan yang baik di awal mungkin tidak bertahan setelah Anda melihat basis kode. OpenSpec menerima kenyataan ini.
Easy not complex. Beberapa kerangka kerja spesifikasi memerlukan pengaturan ekstensif, format yang kaku, atau proses yang berat. OpenSpec tidak menghalangi pekerjaan Anda. Inisialisasi dalam hitungan detik, mulai bekerja segera, sesuaikan hanya jika diperlukan.
Brownfield-first. Sebagian besar pekerjaan perangkat lunak bukanlah membangun dari nol, melainkan memodifikasi sistem yang sudah ada. Pendekatan berbasis delta pada OpenSpec memudahkan untuk menentukan perubahan terhadap perilaku yang sudah ada, bukan hanya mendeskripsikan sistem baru.
Gambaran Besar
OpenSpec mengatur pekerjaan Anda ke dalam dua area utama:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Source of truth │◄─────│ Proposed modifications │ │
│ │ How your system │ merge│ Each change = one folder │ │
│ │ currently works │ │ Contains artifacts + deltas │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specs adalah sumber kebenaran (source of truth) — mereka mendeskripsikan bagaimana sistem Anda saat ini berperilaku.
Changes adalah modifikasi yang diusulkan — mereka berada di folder terpisah sampai Anda siap untuk menggabungkannya (merge).
Pemisahan ini sangat penting. Anda dapat mengerjakan beberapa perubahan secara paralel tanpa konflik. Anda dapat meninjau sebuah perubahan sebelum memengaruhi specs utama. Dan ketika Anda mengarsipkan sebuah perubahan, delta-delta-nya akan bergabung dengan bersih ke dalam sumber kebenaran.
Specs
Specs mendeskripsikan perilaku sistem Anda menggunakan persyaratan dan skenario terstruktur.
Struktur
openspec/specs/
├── auth/
│ └── spec.md # Authentication behavior
├── payments/
│ └── spec.md # Payment processing
├── notifications/
│ └── spec.md # Notification system
└── ui/
└── spec.md # UI behavior and themesAtur specs berdasarkan domain — pengelompokan logis yang masuk akal untuk sistem Anda. Pola umum:
- Berdasarkan area fitur:
auth/,payments/,search/ - Berdasarkan komponen:
api/,frontend/,workers/ - Berdasarkan konteks terbatas (bounded context):
ordering/,fulfillment/,inventory/
Format Spec
Sebuah spec berisi persyaratan, dan setiap persyaratan memiliki skenario:
# Auth Specification
## Purpose
Authentication and session management for the application.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.
#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued
### Requirement: Session Expiration
The system MUST expire sessions after 30 minutes of inactivity.
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticateElemen kunci:
| Elemen | Tujuan |
|---|---|
## Purpose | Deskripsi tingkat tinggi dari domain spec ini |
### Requirement: | Perilaku spesifik yang harus dimiliki sistem |
#### Scenario: | Contoh konkret dari persyaratan yang sedang berjalan |
| SHALL/MUST/SHOULD | Kata kunci RFC 2119 yang menunjukkan kekuatan persyaratan |
Mengapa Menspesifikasikan Struktur Seperti Ini
Persyaratan adalah "apa" — mereka menyatakan apa yang seharusnya dilakukan sistem tanpa menentukan implementasi.
Skenario adalah "kapan" — mereka memberikan contoh konkret yang dapat diverifikasi. Skenario yang baik:
- Dapat diuji (Anda dapat menulis uji otomatis untuknya)
- Mencakup jalur sukses (happy path) dan kasus tepi (edge cases)
- Menggunakan format terstruktur seperti Given/When/Then atau serupa
Kata kunci RFC 2119 (SHALL, MUST, SHOULD, MAY) menyampaikan maksud:
- MUST/SHALL — persyaratan mutlak
- SHOULD — direkomendasikan, tetapi ada pengecualian
- MAY — opsional
Apa Itu Spec (dan Bukan Apa)
Sebuah spec adalah kontrak perilaku, bukan rencana implementasi.
Konten spec yang baik:
- Perilaku yang dapat diamati yang diandalkan oleh pengguna atau sistem turunan
- Input, output, dan kondisi kesalahan
- Kendala eksternal (keamanan, privasi, keandalan, kompatibilitas)
- Skenario yang dapat diuji atau divalidasi secara eksplisit
Hindari dalam spec:
- Nama kelas/fungsi internal
- Pilihan pustaka atau kerangka kerja
- Detail implementasi langkah demi langkah
- Rencana eksekusi terperinci (itu milik
design.mdatautasks.md)
Uji cepat:
- Jika implementasi dapat berubah tanpa mengubah perilaku yang terlihat secara eksternal, kemungkinan besar itu tidak termasuk dalam spec.
Jaga Tetap Ringan: Ketelitian Progresif
OpenSpec bertujuan menghindari birokrasi. Gunakan tingkat ketelitian teringan yang masih membuat perubahan dapat diverifikasi.
Spec Lite (default):
- Persyaratan berfokus pada perilaku yang singkat
- Ruang lingkup dan hal-hal yang bukan tujuan (non-goals) yang jelas
- Beberapa pemeriksaan penerimaan (acceptance checks) yang konkret
Spec Penuh (untuk risiko lebih tinggi):
- Perubahan lintas tim atau lintas repositori
- Perubahan API/kontrak, migrasi, masalah keamanan/privasi
- Perubahan di mana ambiguitas cenderung menyebabkan pekerjaan ulang yang mahal
Sebagian besar perubahan harus tetap dalam mode Lite.
Kolaborasi Manusia + Agen
Di banyak tim, manusia mengeksplorasi dan agen menyusun artefak. Siklus yang dimaksud adalah:
- Manusia menyediakan maksud, konteks, dan kendala.
- Agen mengubah ini menjadi persyaratan dan skenario berfokus pada perilaku.
- Agen menyimpan detail implementasi di
design.mddantasks.md, bukanspec.md. - Validasi mengkonfirmasi struktur dan kejelasan sebelum implementasi.
Ini menjaga spec agar mudah dibaca oleh manusia dan konsisten untuk agen.
Changes
Sebuah perubahan adalah modifikasi yang diusulkan untuk sistem Anda, dikemas sebagai folder dengan segala sesuatu yang diperlukan untuk memahami dan mengimplementasikannya.
Struktur Perubahan
openspec/changes/add-dark-mode/
├── proposal.md # Why and what
├── design.md # How (technical approach)
├── tasks.md # Implementation checklist
├── .openspec.yaml # Change metadata (optional): schema, created, skip_specs, retire_capabilities
└── specs/ # Delta specs
└── ui/
└── spec.md # What's changing in ui/spec.mdSetiap perubahan bersifat mandiri. Ia memiliki:
- Artefak — dokumen yang menangkap maksud, desain, dan tugas
- Delta specs — spesifikasi untuk apa yang ditambahkan, dimodifikasi, atau dihapus
- Metadata — konfigurasi opsional untuk perubahan spesifik ini
Mengapa Changes Adalah Folder
Mengemas perubahan sebagai folder memiliki beberapa manfaat:
Semua bersama. Proposal, desain, tugas, dan specs berada di satu tempat. Tidak perlu mencari-cari di lokasi berbeda.
Pekerjaan paralel. Beberapa perubahan dapat ada secara bersamaan tanpa konflik. Bekerjalah pada
add-dark-modesementarafix-auth-bugjuga sedang berlangsung.Riwayat yang bersih. Ketika diarsipkan, perubahan dipindahkan ke
changes/archive/dengan konteks penuh mereka tetap terjaga. Anda dapat melihat kembali dan memahami tidak hanya apa yang berubah, tetapi juga mengapa.Ramah peninjauan. Folder perubahan mudah ditinjau — buka, baca proposal, periksa desain, lihat delta specs.
Artefak
Artefak adalah dokumen-dokumen dalam sebuah perubahan yang mengarahkan pekerjaan.
Aliran Artefak
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
why what how steps
+ scope changes approach to takeArtefak saling membangun. Setiap artefak menyediakan konteks untuk yang berikutnya.
Jenis Artefak
Proposal (proposal.md)
Proposal menangkap maksud, ruang lingkup, dan pendekatan secara tinggi level.
# Proposal: Add Dark Mode
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.
## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage
Out of scope:
- Custom color themes (future work)
- Per-page theme overrides
## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.Kapan memperbarui proposal:
- Perubahan ruang lingkup (mempersempit atau memperluas)
- Maksud menjadi lebih jelas (pemahaman yang lebih baik tentang masalah)
- Pendekatan berubah secara fundamental
Specs (delta specs di specs/)
Delta specs mendeskripsikan apa yang berubah relatif terhadap specs saat ini. Lihat Delta Specs di bawah.
Design (design.md)
Design menangkap pendekatan teknis dan keputusan arsitektur.
# Design: Add Dark Mode
## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.
## Architecture Decisions
### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency
### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution
## Data Flow
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)Kapan memperbarui design:
- Implementasi mengungkapkan bahwa pendekatan tersebut tidak akan berhasil
- Solusi yang lebih baik ditemukan
- Ketergantungan atau kendala berubah
Tasks (tasks.md)
Tasks adalah daftar periksa implementasi — langkah-langkah konkret dengan kotak centang.
# Tasks
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
- [ ] 1.4 Add system preference detection
## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle
## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
- [ ] 3.3 Test contrast ratios for accessibilityPraktik terbaik untuk Task:
- Kelompokkan tugas-tugas terkait di bawah judul
- Gunakan penomoran hierarkis (1.1, 1.2, dll.)
- Jaga tugas tetap kecil sehingga dapat diselesaikan dalam satu sesi
- Centang tugas saat Anda menyelesaikannya
Delta Specs
Delta specs adalah konsep kunci yang membuat OpenSpec berfungsi untuk pengembangan brownfield. Mereka mendeskripsikan apa yang berubah daripada menyatakan kembali seluruh spec.
Format
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.
#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation
#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP
## MODIFIED Requirements
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated
## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)Bagian Delta
| Bagian | Arti | Apa yang Terjadi Saat Arsip |
|---|---|---|
## ADDED Requirements | Perilaku baru | Ditambahkan ke spec utama |
## MODIFIED Requirements | Perilaku yang berubah | Mengganti persyaratan yang ada |
## REMOVED Requirements | Perilaku yang ditinggalkan | Dihapus dari spec utama; menghapus persyaratan terakhir pensiun kemampuan dan menghapus file spec-nya, ketika perubahan mendeklarasikan retire_capabilities: true |
## Purpose | Untuk apa kemampuan baru sepenuhnya | Menanamkan Purpose dari spec utama yang sedang dibuat; diabaikan ketika spec sudah ada |
Mengapa Delta Alih-alih Specs Penuh
Kejelasan. Sebuah delta menunjukkan tepat apa yang berubah. Membaca spec penuh, Anda harus melakukan diff secara mental terhadap versi saat ini.
Penghindaran konflik. Dua perubahan dapat menyentuh file spec yang sama tanpa konflik, selama mereka memodifikasi persyaratan yang berbeda.
Efisiensi peninjauan. Peninjau melihat perubahan, bukan konteks yang tidak berubah. Fokus pada apa yang penting.
Cocok untuk Brownfield. Sebagian besar pekerjaan memodifikasi perilaku yang ada. Delta membuat modifikasi menjadi prioritas utama, bukan sekadar pikiran tambahan.
Skema
Skema mendefinisikan jenis artefak dan dependensinya untuk sebuah alur kerja.
Cara Kerja Skema
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # Tidak ada dependensi, dapat dibuat pertama kali
- id: specs
generates: specs/**/*.md
requires: [proposal] # Memerlukan proposal sebelum dibuat
- id: design
generates: design.md
requires: [proposal] # Dapat dibuat secara paralel dengan specs
- id: tasks
generates: tasks.md
requires: [specs, design] # Memerlukan kedua-duanya (specs dan design) terlebih dahuluArtefak membentuk grafik dependensi:
proposal
(node akar)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(memerlukan: (memerlukan:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(memerlukan:
specs, design)Dependensi adalah pemicu, bukan gerbang. Dependensi menunjukkan apa yang memungkinkan untuk dibuat, bukan apa yang harus Anda buat selanjutnya. Anda dapat melewati tahap design jika tidak diperlukan. Anda dapat membuat specs sebelum atau sesudah design — keduanya hanya bergantung pada proposal.
Skema Bawaan
spec-driven (bawaan)
Alur kerja standar untuk pengembangan berbasis spesifikasi:
proposal → specs → design → tasks → implementCocok untuk: Sebagian besar pekerjaan fitur di mana Anda ingin menyepakati spesifikasi sebelum implementasi.
Skema Kustom
Buat skema kustom sesuai alur kerja tim Anda:
# Buat dari awal
openspec schema init research-first
# Atau fork yang sudah ada
openspec schema fork spec-driven research-firstContoh skema kustom:
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # Lakukan riset terlebih dahulu
- id: proposal
generates: proposal.md
requires: [research] # Proposal yang dipengaruhi oleh riset
- id: tasks
generates: tasks.md
requires: [proposal] # Lewati specs/design, langsung ke tasksLihat Kustomisasi untuk detail lengkap tentang cara membuat dan menggunakan skema kustom.
Arsip
Pengarsipan menyelesaikan sebuah perubahan dengan menggabungkan delta spesifikasinya ke dalam spesifikasi utama dan melestarikan perubahan tersebut untuk riwayat.
Apa yang Terjadi Saat Anda Mengarsipkan
Sebelum diarsipkan:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ gabung
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
Setelah diarsipkan:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Sekarang mencakup persyaratan 2FA
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Disimpan untuk riwayat
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdProses Pengarsipan
Gabungkan delta. Setiap bagian delta spesifik (ADDED/MODIFIED/REMOVED) diterapkan ke spesifikasi utama yang bersesuaian.
Pindahkan ke arsip. Folder perubahan dipindahkan ke
changes/archive/dengan awalan tanggal untuk pengurutan kronologis.Pelestarian konteks. Semua artefak tetap utuh di dalam arsip. Anda selalu dapat melihat kembali untuk memahami alasan di balik suatu perubahan.
Mengapa Pengarsipan Penting
Keadaan bersih. Perubahan aktif (changes/) hanya menampilkan pekerjaan yang sedang berlangsung. Pekerjaan yang selesai dipindahkan keluar dari jalur utama.
Jejak audit. Arsip melestarikan konteks lengkap setiap perubahan — bukan hanya apa yang berubah, tetapi juga proposal yang menjelaskan alasannya, design yang menjelaskan caranya, dan tasks yang menunjukkan pekerjaan yang dilakukan.
Evolusi spesifikasi. Spesifikasi berkembang secara organik seiring arsip perubahan. Setiap pengarsipan menggabungkan delta-delta-nya, membangun spesifikasi komprehensif seiring waktu.
Bagaimana Semuanya Berpadu
┌──────────────────────────────────────────────────────────────────────────────┐
│ ALUR OPENSPEC │
│ │
│ ┌────────────────┐ │
│ │ 1. MULAI │ /opsx:propose (inti) atau /opsx:new (diperluas) │
│ │ PERUBAHAN │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. BUAT │ /opsx:ff atau /opsx:continue (alur kerja diperluas) │
│ │ ARTEFAK │ Membuat proposal → specs → design → tasks │
│ │ │ (berdasarkan dependensi skema) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. IMPLEMENTASI│ /opsx:apply │
│ │ TASKS │ Kerjakan tasks, centang satu per satu │
│ │ │◄──── Perbarui artefak saat belajar │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. VERIFIKASI │ /opsx:verify (opsional) │
│ │ PEKERJAAN │ Periksa apakah implementasi sesuai dengan spesifikasi │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARSIPKAN │────►│ Delta spesifikasi digabung ke spesifikasi │ │
│ │ PERUBAHAN │ │ folder perubahan dipindahkan ke arsip/ │ │
│ └────────────────┘ │ Spesifikasi sekarang menjadi sumber kebenaran│ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘Siklus positif:
- Spesifikasi menggambarkan perilaku saat ini
- Perubahan mengusulkan modifikasi (sebagai delta)
- Implementasi mewujudkan perubahan tersebut
- Pengarsipan menggabungkan delta ke dalam spesifikasi
- Spesifikasi kini menggambarkan perilaku baru
- Perubahan berikutnya dibangun berdasarkan spesifikasi yang telah diperbarui
Glosarium
| Istilah | Definisi |
|---|---|
| Artefak | Dokumen di dalam sebuah perubahan (proposal, design, tasks, atau delta specs) |
| Arsip | Proses penyelesaian perubahan dan penggabungan delta-nya ke dalam spesifikasi utama |
| Perubahan | Modifikasi yang diusulkan terhadap sistem, dikemas sebagai folder berisi artefak |
| Delta spesifik | Spesifikasi yang menggambarkan perubahan (ADDED/MODIFIED/REMOVED) relatif terhadap spesifikasi saat ini |
| Domain | Pengelompokan logis untuk spesifikasi (misalnya, auth/, payments/) |
| Persyaratan | Perilaku spesifik yang harus dimiliki sistem |
| Skenario | Contoh konkret dari sebuah persyaratan, biasanya dalam format Given/When/Then |
| Skema | Definisi jenis artefak dan dependensinya |
| Spesifikasi | Deskripsi perilaku sistem, berisi persyaratan dan skenario |
| Sumber kebenaran | Direktori openspec/specs/, berisi perilaku yang telah disepakati saat ini |
Langkah Selanjutnya
- Memulai - Langkah praktis pertama
- Alur Kerja - Pola umum dan kapan menggunakannya
- Perintah - Referensi perintah lengkap
- Kustomisasi - Buat skema kustom dan konfigurasikan proyek Anda