Konfigurasi proyek

Buat alur kerja merencanakan perubahan sesuai keinginan Anda hanya dengan beberapa baris di config.yaml.

openspec/config.yaml memberi tahu alur kerja bagaimana Anda ingin perubahan direncanakan.

Sebagai contoh, konfigurasi berikut memperbarui aturan pembuatan untuk artefak tasks.md:

rules:
  tasks:
    - End every task with a commit

Saat agen berjalan, ia mengambil dari aturan-aturan ini dan memastikan setiap tugas diakhiri dengan langkah commit.

Jaga aturan tetap singkat. Semua yang ada di sini masuk ke konteks agen, dan aturan yang bertele-tele dapat memperburuk keluaran.

Cara kerjanya

config.yaml berisi instruksi yang diterima agen saat membuat artefak atau menjalankan alur kerja.

Berikut yang terjadi pada setiap eksekusi:

1. Anda menjalankan alur kerja (mis. /openspec-propose).
2. Agen memanggil perintah openspec instructions.
3. Perintah tersebut membaca konteks dan aturan Anda dari config.yaml.
4. Instruksi bawaan OpenSpec dan kustomisasi Anda digabungkan menjadi satu prompt untuk agen.
5. Agen mengikuti prompt tersebut untuk menulis artefak.

Sebagai contoh, dengan bidang context dan aturan dari bagian atas halaman ini, berikut yang dikembalikan openspec instructions untuk tasks.md (dipangkas dan diberi anotasi):

<artifact id="tasks" change="add-dark-mode" schema="spec-driven">

  <!-- Dari config.yaml Anda: context -->
  <project_context>
    Designs and tasks must cover Windows, macOS, and Linux
    Write all artifacts in Spanish
  </project_context>

  <!-- Dari config.yaml Anda: aturan untuk tasks -->
  <rules>
    - End every task with a commit
  </rules>

  <!-- Dari OpenSpec: panduan bawaan -->
  <instruction>
    ...how to write a good tasks.md...
  </instruction>

  <template>
    ...the tasks.md structure to fill in...
  </template>

</artifact>

Konfigurasi Anda datang lebih dulu, lalu instruksi dan templat bawaan OpenSpec. Aturan ditambahkan ke panduan bawaan dan tidak pernah menggantikannya. Perubahan pada config.yaml sampai ke agen pada eksekusi berikutnya.

Bidang-bidang

Tiga bidang membentuk apa yang diterima agen. Kontrak persis setiap bidang (tipe, batas, validasi) ada di Konfigurasi proyek (config.yaml).

Bidang	Fungsinya	Dimasukkan ke
context	Instruksi yang selalu diterima agen	Semuanya: setiap artefak, apply, archive
rules	Instruksi tambahan untuk satu artefak	Hanya saat pembuatan artefak tersebut
operations	Panduan untuk cara sebuah langkah alur kerja dijalankan	Hanya apply dan archive

Bidang lain dalam config.yaml (schema, store, references) memilih schema dan root OpenSpec mana yang digunakan suatu proyek. Halaman kontrak membahasnya.

Kolom terakhir bersifat persis, sehingga suatu bidang hanya diterima oleh langkah-langkah yang tercantum di sana. Secara khusus, verify tidak pernah menerima rules. Langkah ini memeriksa implementasi terhadap artefak sebagaimana tertulis.

context

context adalah latar belakang yang diterima agen saat membuat artefak, menerapkan tugas, atau mengarsipkan perubahan.

context: |
  We ship cross-platform. Designs and tasks must cover Windows, macOS, and Linux
  Write all artifacts in Spanish

Gunakan context untuk fakta dan batasan yang seharusnya membentuk keluaran alur kerja. Simpan dokumentasi proyek yang tahan lama dalam berkas dokumentasi proyek, dan jangan sertakan apa pun yang dapat dipelajari agen dengan membaca kode.

Bahasa lain: karena context menjangkau setiap artefak, Anda dapat menambahkan Write all artifacts in Spanish. untuk menginstruksikan agen agar menulis artefak proposal, spec, design, dan tasks dalam bahasa Spanyol.

rules

rules melekat pada satu artefak, dengan kunci berupa id artefak. Setiap baris ditambahkan ke panduan bawaan artefak tersebut:

rules:
  proposal:
    - Keep proposals under 500 words
  tasks:
    - Every UI task includes a Playwright test

Proposal kini tetap singkat dan tasks.md selalu merencanakan pengujian browser. Setiap artefak lainnya tidak terpengaruh.

operations

operations memandu bagaimana agen menjalankan apply dan archive, bukan tentang apa yang dikatakan artefak:

operations:
  apply:
    guidance:
      - Run the linter before marking a task complete
  archive:
    guidance:
      - Summarize what shipped before archiving

Selama apply, agen menjalankan lint saat menyelesaikan tugas. Selama archive, agen menutup dengan ringkasan.

Saat config.yaml tidak cukup

Konfigurasi menambahkan instruksi di atas alur kerja standar, tetapi tidak dapat mengubah artefak mana yang ada atau bagaimana strukturnya. Saat Anda menginginkan tingkat kendali tersebut, atau aturan tidak mengarahkan perilaku secara konsisten, lakukan fork pada schema.