สคีมา (Schemas)

เปลี่ยนแปลงสิ่งที่ OpenSpec สร้าง: อาร์ติแฟกต์ ลำดับ และเทมเพลตของพวกมัน

สคีมา (Schema) กำหนดว่าข้อเสนอเปลี่ยนแปลง (change proposal) จะผลิตอะไรออกมา: เป็นอาร์ติแฟกต์ใดบ้าง ในลำดับไหน และใช้เทมเพลตใด ตัวอย่างเช่น spec-driven ซึ่งเป็นสคีมาที่ติดตั้งมาพร้อมกับแพ็กเกจโดยค่าเริ่มต้น จะผลิตสิ่งเหล่านี้สี่อย่างตามลำดับโดยประมาณ โดยแต่ละส่วนจะต่อยอดจากส่วนก่อนหน้า:

proposal → specs → design → tasks

ให้ทำการ Fork สคีมาเมื่อคุณต้องการให้ผลลัพธ์เหล่านี้เป็นเอกสารที่แตกต่างกัน ไม่ว่าจะเป็นการลดจำนวนลง เปลี่ยนชื่อ หรือเปลี่ยนโครงสร้าง

ตำแหน่งของสคีมา

OpenSpec จะค้นหาสคีมาในสามตำแหน่งตามลำดับ และจะใช้ตำแหน่งแรกที่พบ:

1. โปรเจกต์ของคุณ: openspec/schemas/ ซึ่งคอมมิตไว้ในรีโพสิทอรีเพื่อให้ทีมทั้งหมดของคุณได้รับรู้
2. เครื่องของคุณ: ~/.local/share/openspec/schemas บน macOS และ Linux (หรือภายใต้ $XDG_DATA_HOME หากมีการตั้งค่าไว้) หรือ %LOCALAPPDATA%\openspec\schemas บน Windows สคีมาในตำแหน่งนี้จะพร้อมใช้งานในทุกโปรเจกต์ที่คุณทำงานด้วย
3. แพ็กเกจ: ส่วนที่เป็น Built-in เช่น spec-driven จะถูกบรรจุอยู่ในตัว openspec เอง

ชื่อเดียวกันสามารถมีอยู่ได้ในหลายตำแหน่ง โดยตำแหน่งที่มีความเฉพาะเจาะจงกว่าจะมีสิทธิ์เหนือกว่า คำสั่ง openspec schema which จะแสดงว่าสำเนาใดกำลังถูกใช้งานอยู่:

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

โครงสร้างภายในสคีมา

สคีมาถูกกำหนดโดยโฟลเดอร์ที่มีไฟล์ธรรมดา: ไฟล์ schema.yaml ไฟล์เดียวที่ใช้ประกาศอาร์ติแฟกต์ และเทมเพลตสำหรับอาร์ติแฟกต์แต่ละตัว นี่คือตัวอย่างของ spec-driven ที่เป็น Built-in:

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

• schema.yaml: ประกาศอาร์ติแฟกต์แต่ละตัว ไฟล์ที่จะถูกสร้างขึ้น เทมเพลตเริ่มต้น ข้อกำหนดที่ต้องมีก่อนหน้า และคำแนะนำที่ Agent ได้รับเมื่อสร้างอาร์ติแฟกต์นั้น รายละเอียดสัญญาของแต่ละฟิลด์มีอยู่ที่ schema.yaml
• templates/: โครงร่าง Markdown สำหรับอาร์ติแฟกต์แต่ละตัว ซึ่ง Agent จะนำไปเติมข้อมูล

นี่คือรายการของอาร์ติแฟกต์ tasks ใน schema.yaml ที่ตัดทอนแล้ว:

artifacts:
  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      ...what the agent is told when creating tasks.md...
    requires:
      - specs
      - design

สคีมาแบบ Built-in จะถูกบรรจุอยู่ในแพ็กเกจ openspec ดังนั้นคุณจึงไม่ต้องแก้ไขโดยตรง คุณจะได้รับสำเนาของตัวเองโดยการทำการ Fork

การสร้างสคีมาแบบกำหนดเองของคุณเอง

มีสองวิธีในการได้สคีมาของคุณเอง:

1. Fork สคีมาที่มีอยู่แล้ว แล้วแก้ไขสำเนาของคุณ เริ่มต้นที่นี่เมื่อสคีมาที่มีอยู่ใกล้เคียงกับสิ่งที่คุณต้องการ เพราะทุกอย่างในตัวมันใช้งานได้เรียบร้อยแล้ว
2. เริ่มใหม่ทั้งหมด เมื่อไม่มีอันไหนเหมาะสม โดยใช้คำสั่ง openspec schema init เพื่อสร้างโครงร่างสคีماว่างเปล่า

Fork สคีมาที่มีอยู่แล้ว

1. ทำการ Fork สคีมาที่คุณต้องการเริ่มต้น จากไดเรกทอรีรากของโปรเจกต์:

   $ openspec schema fork spec-driven
   
   Note: Schema commands are experimental and may change.
   ✔ Forked 'spec-driven' to 'spec-driven-custom'
   
   Source: .../openspec/schemas/spec-driven (package)
   Destination: /your-project/openspec/schemas/spec-driven-custom

   ส่งอาร์กิวเมนต์ที่สองเพื่อเลือกชื่อ (openspec schema fork spec-driven team-flow) ชื่อจะต้องเป็นรูปแบบ kebab-case

2. แก้ไขสำเนานั้น: schema.yaml และเทมเพลตต่างๆ การแก้ไข Fork ของคุณ อธิบายถึงสิ่งที่ต้องเปลี่ยนแปลง

3. ตรวจสอบความถูกต้อง (Validate):

   openspec schema validate spec-driven-custom

   นี่เป็นคำสั่งเดียวที่สามารถตรวจจับสคีมาที่เสียหาย (เช่น ขาดเทมเพลต, YAML ผิดพลาด, หรือวงจรการพึ่งพา) ก่อนที่คุณจะดำเนินการเปลี่ยนแปลงใดๆ

4. ชี้โปรเจกต์ของคุณไปยังสคีมานี้ใน openspec/config.yaml ขั้นตอนนี้คุณต้องทำเองเพราะคำสั่ง fork ไม่แตะต้อง config.yaml:

   schema: spec-driven-custom

5. ข้อเสนอเปลี่ยนแปลงใหม่จะปฏิบัติตามสคีมาของคุณ การเปลี่ยนแปลงที่สร้างไว้ก่อนหน้านี้จะยังคงใช้สคีมาเดิมที่มันเริ่มต้นด้วย

หากต้องการแทนที่สคีมาเริ่มต้นทุกที่โดยไม่แตะต้อง config.yaml ให้ทำการ Fork ไปยังชื่อเดิม: openspec schema fork spec-driven spec-driven สำเนาในโปรเจกต์ของคุณจะทับซ้อน (shadow) สคีมาแบบ Built-in ตามที่อธิบายไว้ใน ตำแหน่งของสคีมา

เริ่มใหม่ทั้งหมด

openspec schema init จะสร้างโครงร่างสคีมาใหม่แทนที่จะคัดลอกมาจากอันอื่น:

$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

โครงร่างที่ได้มาจะเป็นแบบพื้นฐานที่สุด อาร์ติแฟกต์มาจาก ID แบบ Built-in ทั้งสี่เท่านั้น และเทมเพลตที่ถูกสร้างขึ้นจะไม่มียังไม่มีคำแนะนำ ทำให้ Agent ได้รับคำแนะนำน้อยลงจนกว่าคุณจะเขียนคำแนะนำของคุณเอง จากนั้นขั้นตอนการ Fork ก็สามารถใช้ได้ตามปกติ: ตรวจสอบความถูกต้อง แล้วชี้ config.yaml ไปยังมัน

การแก้ไข Fork ของคุณ

Fork มีไฟล์สองประเภทที่ต้องแก้ไข:

• templates/: เปลี่ยนโครงร่างของเอกสารแต่ละชิ้น เพิ่มส่วนลงในเทมเพลต tasks และทุกไฟล์ tasks.md ใหม่จะเริ่มด้วยส่วนนั้น รักษาหัวข้อ # ไว้ในบรรทัดแรก: อาร์ติแฟกต์จะสืบทอดหัวข้อนั้น ทำให้ไฟล์ที่ถูกสร้างขึ้นทุกไฟล์เปิดขึ้นมาเป็นเอกสารที่มีหัวข้อ
• schema.yaml: เปลี่ยนแปลงเวิร์กโฟลว์เอง: มีอาร์ติแฟกต์อะไรบ้าง แต่ละตัวต้องการอะไรก่อนหน้า และคำแนะนำที่ Agent ได้รับเมื่อสร้างมัน

ตัวอย่างเช่น หากต้องการลบเอกสาร design ออกเพื่อทำให้เวิร์กโฟลว์กระชับขึ้น:

1. ลบรายการ design ออกจาก schema.yaml

2. ลบ design ออกจากรายการ requires ของ tasks

3. ตรวจสอบความถูกต้อง (Validate):

   $ openspec schema validate spec-driven-custom
   
   ✓ Schema 'spec-driven-custom' is valid

หากคุณข้ามขั้นตอนที่ 2 และการตรวจสอบความถูกต้องจะจับข้อผิดพลาดได้:

✗ Schema 'spec-driven-custom' has errors:
  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

ควรตรวจสอบความถูกต้องหลังจากแก้ไขด้วยมือทุกครั้ง มิฉะนั้นสคีมาที่เสียหายจะปรากฏขึ้นกลางคันระหว่างการเปลี่ยนแปลง เมื่อเวิร์กโฟลด์พยายามขอไฟล์ที่ไม่มีอยู่จริง เช่นเดียวกับ config.yaml การแก้ไขสคีมาจะมีผลต่อ Agent ในการรันครั้งถัดไป

Fork คือภาพSnapshot

openspec update จะอัปเดตทักษะและคำสั่งที่ติดตั้งไว้ และไม่แตะต้อง openspec/schemas/ เลย Fork ของคุณจึงทำงานได้อย่างต่อเนื่องตามที่คุณทิ้งไว้ ซึ่งหมายความว่า它也หยุดรับการพัฒนาเมื่อสคีมาแบบ Built-in มีการพัฒนาต่อไป หากต้องการรับการพัฒนาเหล่านั้นในภายหลัง ให้ทำการ Fork สคีมาแบบ Built-in อีกครั้งภายใต้ชื่อใหม่ และนำความแตกต่างเหล่านั้นมาปรับใช้

การแบ่งปันสคีมา

การแบ่งปันสคีมาหมายถึงการคัดลอกโฟลเดอร์ของมัน

• กับทีมของคุณ: คอมมิต openspec/schemas/ ทุกคนในรีโพสิทอรีจะใช้สคีมานี้
• ข้ามโปรเจกต์ของคุณ: วางโฟลเดอร์ลงในไดเรกทอรีระดับผู้ใช้จาก ตำแหน่งของสคีมา
• จากชุมชน: แคตตาล็อกชุมชน รวบรวมสคีมาที่แบ่งปันกัน คัดลอกอันหนึ่งเข้าไปใน openspec/schemas/<name> และมันจะทำงานเหมือนของคุณเอง

เรากำลังพัฒนาระบบทะเบียนสคีมา (Schema Registry) ทั้งแบบสาธารณะและส่วนตัว เพื่อให้สามารถติดตั้งสคีมาด้วยชื่อแทนที่จะต้องคัดลอกด้วยตนเอง

ใช้ OpenSpec พร้อมพลังพิเศษ

สคีมา superpowers-bridge ที่ดูแลโดยชุมชน เชื่อมต่ออาร์ติแฟกต์ของ OpenSpec กับทักษะการดำเนินการของ Superpowers โปรดอ่านบันทึกการติดตั้งและความเข้ากันได้ของ Bridge ก่อนคัดลอกมันเข้าสู่โปรเจกต์ของคุณ

Bridge นี้ได้รับการเผยแพร่ภายนอก OpenSpec OpenSpec ไม่ได้ทดสอบหรือจัดการเวอร์ชันของการผสานรวม Superpowers ของมัน