การกำหนดค่าโปรเจกต์

กำหนดให้เวิร์กโฟลว์วางแผนการเปลี่ยนแปลงได้ตามที่คุณต้องการด้วยโค้ดเพียงไม่กี่บรรทัดใน config.yaml

openspec/config.yaml บอกเวิร์กโฟลว์ว่าคุณต้องการให้วางแผนการเปลี่ยนแปลงอย่างไร

ตัวอย่างเช่น การกำหนดค่าต่อไปนี้จะปรับกฎการสร้างสำหรับอาร์ติแฟกต์ tasks.md:

rules:
  tasks:
    - End every task with a commit

เมื่อเอเจนต์ทำงาน มันจะดึงกฎเหล่านี้มาใช้ และทำให้แน่ใจว่าทุกทาสก์ลงท้ายด้วยขั้นตอน commit

ควรเขียนกฎให้สั้น เนื้อหาทั้งหมดนี้จะเข้าสู่บริบทของเอเจนต์ และกฎที่ยาวเหยียดอาจทำให้ผลลัพธ์แย่ลง

วิธีการทำงาน

config.yaml เก็บคำแนะนำที่เอเจนต์จะได้รับเมื่อสร้างอาร์ติแฟกต์หรือดำเนินการตามเวิร์กโฟลว์

นี่คือสิ่งที่เกิดขึ้นในทุกครั้งที่รัน:

1. คุณรันเวิร์กโฟลว์ (เช่น /openspec-propose)
2. เอเจนต์เรียกใช้คำสั่ง openspec instructions
3. คำสั่งจะอ่านบริบทและกฎของคุณจาก config.yaml
4. คำแนะนำในตัวของ OpenSpec และการปรับแต่งของคุณจะถูกรวมเข้าเป็นพรอมต์เดียวสำหรับเอเจนต์
5. เอเจนต์ทำตามพรอมต์นั้นเพื่อเขียนอาร์ติแฟกต์

ตัวอย่างเช่น เมื่อมีฟิลด์ context และกฎจากด้านบนของหน้านี้ นี่คือผลลัพธ์ที่ openspec instructions ส่งกลับสำหรับ tasks.md (ตัดทอนและใส่คำอธิบายประกอบแล้ว):

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

  <!-- มาจาก config.yaml ของคุณ: context -->
  <project_context>
    Designs and tasks must cover Windows, macOS, and Linux
    Write all artifacts in Spanish
  </project_context>

  <!-- มาจาก config.yaml ของคุณ: กฎสำหรับ tasks -->
  <rules>
    - End every task with a commit
  </rules>

  <!-- มาจาก OpenSpec: คำแนะนำในตัว -->
  <instruction>
    ...how to write a good tasks.md...
  </instruction>

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

</artifact>

config ของคุณจะมาก่อน ตามด้วยคำแนะนำในตัวและเทมเพลตของ OpenSpec กฎจะถูกเพิ่มเข้าไปในส่วนที่มีในตัวอยู่แล้วเท่านั้น ไม่เคยเข้ามาแทนที่ การแก้ไข config.yaml จะส่งผลถึงเอเจนต์ในการรันครั้งถัดไป

ฟิลด์ต่าง ๆ

ฟิลด์ทั้งสามตัวเป็นตัวกำหนดสิ่งที่เอเจนต์จะได้รับ ส่วนข้อกำหนด (contract) ที่ชัดเจนของแต่ละฟิลด์ (ชนิดข้อมูล ขีดจำกัด การตรวจสอบความถูกต้อง) มีรายละเอียดอยู่ในหน้า การกำหนดค่าโปรเจกต์ (config.yaml)

ฟิลด์	หน้าที่	ถูกแทรกเข้าไปใน
context	คำแนะนำที่เอเจนต์จะได้รับเสมอ	ทุกอย่าง: ทุกอาร์ติแฟกต์, apply, archive
rules	คำแนะนำเพิ่มเติมสำหรับอาร์ติแฟกต์เดียว	เฉพาะการสร้างอาร์ติแฟกต์นั้น
operations	แนวทางว่าจะดำเนินการแต่ละขั้นตอนของเวิร์กโฟลว์อย่างไร	เฉพาะ apply และ archive

ส่วนฟิลด์อื่น ๆ ของ config.yaml (schema, store, references) ใช้เลือกว่าโปรเจกต์จะใช้ schema ใดและ OpenSpec root ใด หน้าข้อกำหนดดังกล่าวได้อธิบายรายละเอียดของฟิลด์เหล่านี้ไว้

คอลัมน์สุดท้ายระบุไว้อย่างเป๊ะ ดังนั้นฟิลด์จะไปถึงเฉพาะขั้นตอนที่ระบุไว้ในคอลัมน์นั้นเท่านั้น โดยเฉพาะอย่างยิ่ง verify จะไม่ได้รับ rules เด็ดขาด เนื่องจากหน้าที่ของมันคือการตรวจสอบ implementation เทียบกับอาร์ติแฟกต์ตามที่เขียนไว้

context

context คือข้อมูลพื้นหลังที่เอเจนต์ได้รับเมื่อสร้างอาร์ติแฟกต์ ดำเนินการตามทาสก์ หรือจัดเก็บการเปลี่ยนแปลง (archive)

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

ใช้ context สำหรับข้อเท็จจริงและข้อจำกัดที่ควรกำหนดทิศทางของผลลัพธ์เวิร์กโฟลว์ ส่วนเอกสารประกอบโปรเจกต์ที่ใช้ถาวรให้เก็บไว้ในไฟล์เอกสารของโปรเจกต์ และไม่ต้องใส่สิ่งที่เอเจนต์รู้ได้เองจากการอ่านโค้ด

ภาษาอื่น: เนื่องจาก context เข้าถึงทุกอาร์ติแฟกต์ คุณจึงสามารถเพิ่ม Write all artifacts in Spanish. เพื่อสั่งให้เอเจนต์เขียนอาร์ติแฟกต์ proposal, spec, design และ tasks เป็นภาษาสเปนได้

rules

rules จะผูกกับอาร์ติแฟกต์เดียว โดยใช้ artifact id เป็นคีย์ แต่ละบรรทัดจะถูกเพิ่มเข้าไปในคำแนะนำในตัวของอาร์ติแฟกต์นั้น:

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

ทำให้ proposal กระชับอยู่เสมอ และ tasks.md จะวางแผนการทดสอบ browser ไว้ทุกครั้ง ส่วนอาร์ติแฟกต์อื่น ๆ จะไม่ถูกแตะต้องแต่อย่างใด

operations

operations กำหนดแนวทางว่าเอเจนต์จะดำเนินการ apply และ archive อย่างไร แทนที่จะเป็นการกำหนดว่าอาร์ติแฟกต์จะมีเนื้อหาอย่างไร:

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

ระหว่าง apply เอเจนต์จะรัน linter ไปพร้อมกับการทำทาสก์ให้เสร็จ ส่วนระหว่าง archive จะปิดท้ายด้วยการสรุปผล

เมื่อ config.yaml ไม่เพียงพอ

Config ทำหน้าที่เพิ่มคำแนะนำทับบนเวิร์กโฟลว์มาตรฐาน แต่ไม่สามารถเปลี่ยนได้ว่าจะมีอาร์ติแฟกต์ใดบ้าง หรืออาร์ติแฟกต์เหล่านั้นจะมีโครงสร้างอย่างไร เมื่อคุณต้องการการควบคุมในระดับนั้น หรือกฎไม่สามารถกำกับพฤติกรรมได้อย่างสม่ำเสมอ ให้ทำการ fork schema