Kustomisasi

OpenSpec menyediakan tiga tingkat kustomisasi:

Tingkat	Fungsinya	Cocok untuk
Konfigurasi Proyek	Mengatur nilai default, menyuntikkan konteks/aturan	Sebagian besar tim
Skema Kustom	Mendefinisikan artefak alur kerja Anda sendiri	Tim dengan proses unik
Override Global	Berbagi skema di semua proyek	Pengguna lanjutan

---

Konfigurasi Proyek

File openspec/config.yaml adalah cara termudah untuk mengustomisasi OpenSpec untuk tim Anda. File ini memungkinkan Anda:

• Mengatur skema default - Lewati --schema di setiap perintah
• Menyuntikkan konteks proyek - AI melihat stack teknologi, konvensi, dll. Anda
• Menambahkan aturan per-artefak - Aturan khusus untuk artefak tertentu
• Menambahkan panduan per-operasi - Preferensi konsultatif untuk pekerjaan apply dan archive
• Mengingat pilihan integrasi - misalnya opt-in untuk GitHub Copilot cloud coding agent

Pengaturan Cepat

openspec init

Perintah ini akan memandu Anda membuat konfigurasi secara interaktif. Atau buat secara manual:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

Cara Kerjanya

Skema default:

# Tanpa konfigurasi
openspec new change my-feature --schema spec-driven

# Dengan konfigurasi - skema otomatis
openspec new change my-feature

Penyuntikan konteks dan aturan:

Saat menghasilkan artefak apa pun, konteks dan aturan Anda disuntikkan ke dalam prompt AI:

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

• Konteks muncul di SEMUA artefak
• Aturan HANYA muncul untuk artefak yang sesuai

Panduan operasi:

operations.apply.guidance dan operations.archive.guidance adalah array opsional berisi instruksi konsultatif tentang bagaimana agen harus melakukan operasi tersebut. Keduanya terpisah dari rules: panduan operasi tidak membatasi konten artefak, dan aturan artefak tidak pernah diberi label ulang sebagai panduan operasi.

Apply dan archive mengambil input ini pada saat eksekusi:

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

Kedua permukaan ini mengembalikan context proyek saat ini dan operationGuidance yang sesuai sebagai field opsional terpisah. Setiap pemanggilan membaca snapshot segar dari root yang teresolusi. Ketika --store <id> dipilih, change, context, dan guidance semuanya berasal dari store tersebut, bukan dari repositori saat ini. Perintah instruksi archive bersifat read-only: tidak memeriksa atau menggabungkan delta specs, menulis main specs, memindahkan change, atau menjalankan alur kerja archive statis.

Konteks proyek adalah input tingkat prompt yang wajib. Alur kerja yang dihasilkan membacanya dan menerapkan fakta proyek, konvensi, dan batasan yang relevan. Panduan operasi adalah saran tambahan opsional: alur kerja mempertimbangkan setiap entri dan mengikuti entri yang berlaku dan kompatibel dengan alur kerja bawaan.

Kedua field tetap terpisah dari status yang dikendalikan CLI, path yang teresolusi, langkah bawaan, pilihan eksplisit pengguna, dan aturan artefak. Alur kerja melaporkan konflik konteks sambil mempertahankan nilai pengendali. Alur kerja tidak mengikuti panduan yang tidak berlaku atau bertentangan dan menjelaskan alasannya. Tidak ada field yang merupakan pemeriksaan yang dapat dipaksakan, dan alur kerja tidak menyalin teksnya ke file implementasi, specs, artefak change, atau ringkasan kecuali pengguna secara terpisah meminta konten tersebut.

Keamanan input archive dan spec-sync:

Archive, bulk archive, dan sync mandiri menggunakan artifactPaths.specs.existingOutputPaths dari openspec status --json sebagai sumber delta-spec satu-satunya. Skema tanpa artefak specs, atau change yang daftar output konkretnya kosong, tidak memiliki apa pun untuk di-sync; artefak lain tidak digunakan untuk menyimpulkan delta specs.

Sebelum semantic merge menulis main spec, alur kerja mengonsumsi output saat ini dari openspec instructions specs --change <name> --json. Aturan specs yang dikembalikan hanya membatasi main specs yang dihasilkan oleh merge tersebut. Single archive meneruskan snapshot tersebut ke inline sync, standalone sync mengambilnya secara langsung, dan bulk archive memperoleh setiap snapshot yang dibutuhkan sebelum penulisan spec pertamanya. Respons instruksi archive/specs JSON yang non-zero atau tidak valid adalah kegagalan lookup, bukan input kosong: alur kerja berhenti sebelum penulisan spec atau pemindahan change yang terdampak (untuk bulk archive, sebelum penulisan atau pemindahan batch apa pun).

Konfigurasi ini tidak mengubah fase eksekusi archive, prompt pengguna, operasi sistem file, kepemilikan semantic merge, perintah openspec archive langsung, atau struktur dan output aturan artefak.

Urutan Resolusi Skema

Ketika OpenSpec membutuhkan skema, ia memeriksa dalam urutan berikut:

1. CLI flag: --schema <name>
2. Metadata change (.openspec.yaml di folder change)
3. Konfigurasi proyek (openspec/config.yaml)
4. Default (spec-driven)

---

Skema Kustom

Ketika konfigurasi proyek tidak mencukupi, buat skema Anda sendiri dengan alur kerja yang sepenuhnya kustom. Skema kustom disimpan di direktori openspec/schemas/ proyek Anda dan dikontrol versi bersama kode.

your-project/
├── openspec/
│   ├── config.yaml        # Konfigurasi proyek
│   ├── schemas/           # Skema kustom disimpan di sini
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Perubahan Anda
└── src/

Fork dari Skema yang Ada

Cara tercepat untuk menyesuaikan adalah dengan melakukan fork dari skema bawaan:

openspec schema fork spec-driven my-workflow

Ini menyalin seluruh skema spec-driven ke openspec/schemas/my-workflow/ di mana Anda dapat mengeditnya secara bebas.

Apa yang Anda dapatkan:

openspec/schemas/my-workflow/
├── schema.yaml           # Definisi alur kerja
└── templates/
    ├── proposal.md       # Template untuk artefak proposal
    ├── spec.md           # Template untuk spesifikasi
    ├── design.md         # Template untuk desain
    └── tasks.md          # Template untuk tugas

Sekarang edit schema.yaml untuk mengubah alur kerja, atau edit template untuk mengubah apa yang dihasilkan AI.

Buat Skema dari Nol

Untuk alur kerja yang benar-benar baru:

# Interaktif
openspec schema init research-first

# Non-interaktif
openspec schema init rapid \
  --description "Alur kerja iterasi cepat" \
  --artifacts "proposal,tasks" \
  --default

Struktur Skema

Skema mendefinisikan artefak dalam alur kerja Anda dan bagaimana ketergantungannya satu sama lain:

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: Alur kerja kustom tim saya

artifacts:
  - id: proposal
    generates: proposal.md
    description: Dokumen proposal awal
    template: proposal.md
    instruction: |
      Buat proposal yang menjelaskan MENGAPA perubahan ini diperlukan.
      Fokus pada masalah, bukan solusi.
    requires: []

  - id: design
    generates: design.md
    description: Desain teknis
    template: design.md
    instruction: |
      Buat dokumen desain yang menjelaskan CARA mengimplementasikan.
    requires:
      - proposal    # Tidak dapat membuat desain sebelum proposal ada

  - id: tasks
    generates: tasks.md
    description: Daftar periksa implementasi
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

Field kunci:

Field	Tujuan
id	Identifier unik, digunakan dalam perintah dan aturan
generates	Nama file keluaran (mendukung glob seperti specs/**/*.md)
template	File template di direktori templates/
instruction	Instruksi AI untuk membuat artefak ini
requires	Ketergantungan - artefak mana yang harus ada terlebih dahulu

Daftarkan artefak sesuai urutan yang Anda inginkan untuk ditulis. requires menentukan apa yang mungkin; urutan daftar artifacts: menentukan apa yang didahulukan ketika beberapa artefak siap sekaligus.

Template

Template adalah file markdown yang memandu AI. Template disuntikkan ke dalam prompt saat membuat artefak tersebut.

<!-- templates/proposal.md -->
## Mengapa

<!-- Jelaskan motivasi untuk perubahan ini. Masalah apa yang diselesaikan? -->

## Perubahan Apa

<!-- Jelaskan apa yang akan berubah. Spesifik tentang kemampuan baru atau modifikasi. -->

## Dampak

<!-- Kode, API, dependensi, sistem yang terpengaruh -->

Template dapat mencakup:

• Header bagian yang harus diisi AI
• Komentar HTML dengan panduan untuk AI
• Format contoh yang menunjukkan struktur yang diharapkan

Validasi Skema Anda

Sebelum menggunakan skema kustom, validasi:

openspec schema validate my-workflow

Ini memeriksa:

• Sintaks schema.yaml benar
• Semua template yang dirujuk ada
• Tidak ada ketergantungan sirkular
• ID artefak valid

Gunakan Skema Kustom Anda

Setelah dibuat, gunakan skema Anda dengan:

# Tentukan di perintah
openspec new change feature --schema my-workflow

# Atau tetapkan sebagai default di config.yaml
schema: my-workflow

Debug Resolusi Skema

Tidak yakin skema mana yang digunakan? Periksa dengan:

# Lihat dari mana suatu skema spesifik diselesaikan
openspec schema which my-workflow

# Tampilkan semua skema yang tersedia
openspec schema which --all

Output menunjukkan apakah berasal dari proyek Anda, direktori pengguna, atau paket:

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

Catatan: OpenSpec juga mendukung skema tingkat pengguna di ~/.local/share/openspec/schemas/ untuk berbagi antar proyek, tetapi skema tingkat proyek di openspec/schemas/ disarankan karena dikontrol versi bersama kode Anda.

---

Contoh

Alur Kerja Iterasi Cepat

Alur kerja minimal untuk iterasi cepat:

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Iterasi cepat dengan overhead minimal

artifacts:
  - id: proposal
    generates: proposal.md
    description: Proposal cepat
    template: proposal.md
    instruction: |
      Buat proposal singkat untuk perubahan ini.
      Fokus pada apa dan mengapa, lewati spesifikasi detail.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Daftar periksa implementasi
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

Menambahkan Artefak Tinjauan

Fork default dan tambahkan langkah tinjauan:

openspec schema fork spec-driven with-review

Kemudian edit schema.yaml untuk menambahkan:

  - id: review
    generates: review.md
    description: Daftar periksa tinjauan pra-implementasi
    template: review.md
    instruction: |
      Buat daftar periksa tinjauan berdasarkan desain.
      Sertakan pertimbangan keamanan, kinerja, dan pengujian.
    requires:
      - design

  - id: tasks
    # ... konfigurasi tasks yang ada ...
    requires:
      - specs
      - design
      - review    # Sekarang tasks juga memerlukan review

---

Skema Komunitas

OpenSpec juga mendukung skema yang dikelola komunitas dan didistribusikan melalui repositori mandiri. Ini menyediakan alur kerja opini yang mengintegrasikan OpenSpec dengan alat atau sistem lain, mirip dengan cara kerja katalog ekstensi komunitas github/spec-kit untuk spec-kit.

Skema komunitas tidak disertakan dalam inti OpenSpec — mereka tinggal di repositori mereka sendiri dengan siklus rilis sendiri. Untuk menggunakannya, salin bundel skema ke direktori openspec/schemas/<schema-name>/ proyek Anda (README setiap repo memiliki petunjuk instalasi).

Skema	Pemelihara	Repositori	Deskripsi
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	Menangkap maksud perubahan, perilaku yang dapat diamati, desain teknis, dan keputusan arsitektur yang tahan lama sebelum implementasi. Menambahkan manifes tinjauan ADR lokal-perubahan dan menulis keputusan jangka panjang yang layak sebagai ADR yang tidak dapat diubah, dapat digantikan.
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	Mengintegrasikan tata kelola artefak OpenSpec dengan keterampilan eksekusi obra/superpowers (brainstorming, writing-plans, TDD via subagents, code review, finishing). Menambahkan artefak retrospective berbasis bukti yang mengisi celah yang tidak secara native dicakup oleh Superpowers.
nanopm	@nmrtn	nmrtn/nanopm	Alur kerja yang mengutamakan PM. Menjalankan pipeline perencanaan nanopm (audit → strategi → roadmap → PRD) di hulu implementasi. Menjembatani perencanaan produk ke alur kerja rekayasa berbasis spesifikasi OpenSpec. Artefak dibaca dari .nanopm/ jika ada — proposal bersumber dari audit, desain dari strategi, dan tugas dari rincian PRD.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	Runbook pengujian end-to-end tingkat kapabilitas. Setiap kapabilitas mendapatkan spesifikasi yang tidak dapat diubah, template tugas yang tidak dapat diubah, dan satu rekaman eksekusi bertanda waktu per eksekusi. Asersi hanya berdasarkan perilaku yang dapat diamati (status HTTP, body respons, state yang persisten — tidak pernah substring log); setiap eksekusi mencatat waktu mulai/berakhir UTC, durasi, dan estimasi konsumsi token LLM.
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	Alur kerja berbasis spesifikasi dengan disiplin TDD dan langkah tinjauan adversarial. Alur: proposal → specs → design → review → test-plan → tasks → apply → verify. review ditulis oleh peninjau read-only dengan konteks baru (model kedua jika tersedia) dan mengeluarkan baris VERDICT: yang memberitahu agen untuk mengunci test-plan, tasks, dan apply; OpenSpec hanya memeriksa keberadaan artefak, jadi tegakkan pembatasan dengan CI atau hook Anda sendiri. test-plan memetakan setiap skenario spesifikasi ke tes bernama dan berfungsi ganda sebagai buku besar merah/hijau yang diaudit oleh verify.

Ingin berkontribusi skema komunitas? Buka issue dengan tautan ke repositori Anda, atau kirim PR yang menambahkan baris ke tabel ini.

---

Lihat Juga

• Referensi CLI: Perintah Skema - Dokumentasi perintah lengkap