Workflows

คู่มือนี้ครอบคลุมรูปแบบเวิร์กโฟลว์ทั่วไปสำหรับ OpenSpec และวิธีการใช้งานแต่ละแบบ สำหรับการตั้งค่าพื้นฐาน โปรดดูที่ Getting Started สำหรับข้อมูลอ้างอิงคำสั่ง โปรดดูที่ Commands

ปรัชญา: การกระทำ (Actions) ไม่ใช่ขั้นตอน (Phases)

เวิร์กโฟลว์แบบดั้งเดิมจะบังคับให้คุณผ่านขั้นตอนต่างๆ: การวางแผน จากนั้นการนำไปใช้ และสุดท้ายคือเสร็จสิ้น แต่งานจริงไม่ได้ลงตัวอยู่ในกล่องอย่างเรียบร้อย

OPSX มีแนวทางที่แตกต่างออกไป:

Traditional (phase-locked):

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "Can't go back"  │
      └────────────────────┘

OPSX (fluid actions):

  proposal ──► specs ──► design ──► tasks ──► implement

หลักการสำคัญ:

• การกระทำ (Actions) ไม่ใช่ขั้นตอน (Phases) - คำสั่งคือสิ่งที่คุณสามารถทำได้ ไม่ใช่สถานะที่คุณติดอยู่
• Dependencies คือตัวเปิดใช้งาน (Enablers) - พวกมันแสดงสิ่งที่สามารถทำได้ ไม่ใช่สิ่งที่จำเป็นต้องทำต่อไป

การปรับแต่ง (Customization): เวิร์กโฟลว์ของ OPSX ถูกขับเคลื่อนโดยสคีมา (schemas) ที่กำหนดลำดับของอาร์ติแฟกต์ (artifact sequences) ดู Customization สำหรับรายละเอียดเกี่ยวกับการสร้างสคีมาแบบกำหนดเอง

สองโหมดการทำงาน (Two Modes)

เส้นทางด่วนเริ่มต้น (core profile)

การติดตั้งใหม่จะตั้งค่าเป็น core ซึ่งมีสิ่งต่อไปนี้:

• /opsx:explore
• /opsx:propose
• /opsx:apply
• /opsx:sync
• /opsx:archive

ขั้นตอนการทำงานโดยทั่วไป:

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (ทางเลือก)

เริ่มต้นด้วยการสำรวจ (สิ่งที่ควรสร้างนิสัย)

/opsx:explore เป็นส่วนหนึ่งของโปรไฟล์เริ่มต้น ไม่ใช่ส่วนเสริมขั้นสูง นี่คือขั้นตอนที่ต้องทำเมื่อคุณมีปัญหาแต่ยังไม่มีแผน ซึ่งโดยปกติแล้วมักจะเป็นเช่นนั้น ด้วยผู้ช่วย AI

You: /opsx:explore

AI:  คุณต้องการสำรวจอะไร?

You: ผลการค้นหาของเราดูเก่า ฉันไม่แน่ใจว่าเป็นเพราะ caching, indexing หรือที่ตัว query เอง

AI:  ให้ฉันตรวจสอบดู... [อ่านบริการค้นหาและชั้นแคช]
     เป็นปัญหาที่ index: มันจะสร้างใหม่ทุกคืน ดังนั้นการแก้ไขจึงไม่ปรากฏจนกว่าวันถัดไป มีสองทางเลือก: rebuild on write (ง่าย แต่โหลดงานเยอะ) หรือ short-TTL cache invalidation (มีส่วนประกอบมากขึ้น โหลดงานน้อยลง) เนื่องจากปริมาณการเขียนของคุณต่ำ การทำ rebuild-on-write จึงเป็นการแก้ไขที่สะอาดกว่า ต้องการกำหนดขอบเขตไหม?

You: ใช่

You: /opsx:propose rebuild-search-index-on-write

Explore ไม่ได้สร้าง artifact ใด ๆ และไม่ได้เขียนโค้ดใด ๆ นี่คือการสนทนาแบบไร้ความเสี่ยงานที่เปลี่ยนความกังวลที่ไม่ชัดเจนให้เป็นการเปลี่ยนแปลงที่แม่นยำ ดังนั้นข้อเสนอที่ตามมาจึงมีความคมชัด หากคุณรู้ว่าต้องการอะไรอย่างแน่นอนแล้ว ให้ข้ามไปและตรงไปยัง /opsx:propose คู่มือฉบับเต็ม: Explore First

ขั้นตอนการทำงานแบบขยาย/ฉบับเต็ม (custom selection)

หากคุณต้องการคำสั่ง scaffold-and-build ที่ชัดเจน (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard) ให้เปิดใช้งานโดยใช้:

openspec config profile
openspec update

รูปแบบขั้นตอนการทำงาน (Expanded Mode)

ฟีเจอร์ด่วน (Quick Feature)

เมื่อคุณรู้ว่าต้องการสร้างอะไรและเพียงแค่ต้องดำเนินการ:

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

ตัวอย่างการสนทนา:

You: /opsx:new add-logout-button

AI:  สร้าง openspec/changes/add-logout-button/ แล้ว
     พร้อมที่จะสร้าง: proposal

You: /opsx:ff

AI:  กำลังสร้าง artifact การวางแผนทั้งหมด...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     พร้อมสำหรับการนำไปใช้งาน!

You: /opsx:apply

AI:  ดำเนินการตามงานที่ได้รับมอบหมาย...
     ✓ เพิ่มปุ่มออกจากระบบในส่วนหัว (header)
     ✓ ใช้งานการล้างเซสชัน
     ✓ เพิ่มกล่องโต้ตอบยืนยัน
     งานทั้งหมดเสร็จสมบูรณ์!

You: /opsx:archive

AI:  ✓ ผสานรวม specs
     ✓ เก็บถาวรการเปลี่ยนแปลง

เหมาะสำหรับ: ฟีเจอร์ขนาดเล็กถึงกลาง การแก้ไขบั๊ก การเปลี่ยนแปลงที่ตรงไปตรงมา

แบบสำรวจ (Exploratory)

เมื่อข้อกำหนดไม่ชัดเจนหรือคุณจำเป็นต้องตรวจสอบก่อน:

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

ตัวอย่างการสนทนา:

You: /opsx:explore

AI:  คุณต้องการสำรวจอะไร?

You: ฉันต้องการปรับปรุงประสิทธิภาพการโหลดหน้าเว็บ แต่ไม่แน่ใจว่าคอขวดอยู่ที่ไหน

AI:  ให้ฉันช่วยตรวจสอบ...
     [วิเคราะห์ขนาด bundle ระบุ query ที่ช้า ตรวจสอบรูปแบบการเรนเดอร์ของ component]

     ฉันพบสามจุดที่เป็นปัญหาหลัก:
     1. รูปภาพขนาดใหญ่ที่ไม่ได้ปรับปรุงให้เหมาะสม
     2. การดึงข้อมูลแบบ Synchronous ใน ProductList
     3. การ Re-render จากการเปลี่ยนแปลง context

     คุณต้องการจัดการเรื่องใดก่อน?

You: มาจัดการปัญหาการดึงข้อมูลกันเถอะ

You: /opsx:new optimize-product-list-fetching

AI:  สร้าง change แล้ว พร้อมที่จะสร้าง: proposal

You: /opsx:continue

AI:  กำลังสร้าง proposal ตามผลการสำรวจของเรา...
     [เขียน proposal โดยรวมข้อมูลเชิงลึกจากการตรวจสอบ]

     พร้อมที่จะสร้าง: specs, design
     คุณต้องการทำอะไรต่อไป?

You: /opsx:continue

AI:  กำลังสร้าง specs...

เหมาะสำหรับ: การปรับปรุงประสิทธิภาพ การดีบัก การตัดสินใจด้านสถาปัตยกรรม ข้อกำหนดที่ไม่ชัดเจน

การเปลี่ยนแปลงแบบขนาน (Parallel Changes)

ทำงานกับการเปลี่ยนแปลงหลายอย่างพร้อมกัน:

Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (กำลังดำเนินการ)
                                         │
                                    context switch
                                         │
Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

ตัวอย่างการสนทนา:

You: ฉันกำลังทำงาน add-dark-mode แต่ถูกดึงไปแก้บั๊ก

You: /opsx:new fix-login-redirect

AI:  สร้าง openspec/changes/fix-login-redirect/ แล้ว

You: /opsx:ff

AI:  ✓ สร้าง artifact การวางแผน

You: /opsx:apply

AI:  กำลังดำเนินการแก้ไข fix-login-redirect...
     [นำการแก้ไขไปใช้]
     งานทั้งหมดเสร็จสมบูรณ์!

You: /opsx:archive

AI:  ✓ เก็บถาวร fix-login-redirect

You: กลับมาที่ dark mode กันเถอะ

You: /opsx:apply add-dark-mode

AI:  ดำเนินการต่อ add-dark-mode...
     กลับมาที่งาน 2.3: อัปเดต Header...

เหมาะสำหรับ: กระแสงานแบบขนาน การขัดจังหวะเร่งด่วน การทำงานร่วมกันของทีม

เมื่อคุณมีการเปลี่ยนแปลงที่เสร็จสมบูรณ์หลายรายการ ให้ใช้ /opsx:bulk-archive:

You: /opsx:bulk-archive

AI:  พบการเปลี่ยนแปลงที่เสร็จสมบูรณ์ 3 รายการ:
     - add-dark-mode (งานทั้งหมดเสร็จ)
     - fix-login-redirect (งานทั้งหมดเสร็จ)
     - update-footer (งานทั้งหมดเสร็จ)

     กำลังตรวจสอบความขัดแย้งของ specs...
     ⚠ add-dark-mode และ update-footer ต่างก็แตะต้อง specs/ui/ ทั้งคู่

     กำลังตรวจสอบ codebase เพื่อแก้ไข...
     การเปลี่ยนแปลงทั้งสองถูกนำไปใช้แล้ว จะทำการ apply ตามลำดับเวลา

     ต้องการเก็บถาวรทั้งหมด 3 รายการหรือไม่?

You: ใช่

AI:  ✓ เก็บถาวร add-dark-mode
     ✓ เก็บถาวร fix-login-redirect
     ✓ เก็บถาวร update-footer
     Specs ถูกผสานรวมตามลำดับ: add-dark-mode → update-footer

Bulk archive ตรวจจับเมื่อการเปลี่ยนแปลงหลายรายการแตะต้อง specs เดียวกันและแก้ไขความขัดแย้งโดยการตรวจสอบว่าอะไรถูกนำไปใช้จริง

การทำให้การเปลี่ยนแปลงเสร็จสมบูรณ์ (Completing a Change)

ขั้นตอนที่แนะนำสำหรับการทำให้เสร็จสมบูรณ์:

/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              ตรวจสอบความถูกต้อง          แจ้งเตือนให้ซิงค์
              การนำไปใช้     หากจำเป็น

Verify: ตรวจสอบงานของคุณ (Check Your Work)

/opsx:verify จะตรวจสอบการนำไปใช้เทียบกับ artifact ของคุณในสามมิติ:

You: /opsx:verify

AI:  กำลังตรวจสอบ add-auth...

     ความสมบูรณ์ (COMPLETENESS)
     ✓ งานทั้ง 12 รายการใน tasks.md ถูกตรวจสอบแล้ว
     ✓ ข้อกำหนดทั้งหมดใน specs มีโค้ดที่เกี่ยวข้อง
     ⚠ สถานการณ์ "เซสชันหมดอายุหลังจากการไม่มีกิจกรรม" ยังไม่ถูกทดสอบ

     ความถูกต้อง (CORRECTNESS)
     ✓ การนำไปใช้ตรงตามเจตนาของ spec
     ✓ จัดการกับกรณีขอบเขต (Edge cases) จากสถานการณ์แล้ว
     ✓ สถานะתข้อผิดพลาดตรงตามคำจำกัดความใน spec

     ความสอดคล้อง (COHERENCE)
     ✓ การตัดสินใจด้านการออกแบบสะท้อนอยู่ในโครงสร้างโค้ด
     ✓ ข้อตกลงด้านชื่อสอดคล้องกับ design.md
     ⚠ การออกแบบกล่าวถึง "event-driven" แต่การนำไปใช้กลับใช้ polling

     สรุป (SUMMARY)
     ─────────────────────────────
     ปัญหาสำคัญ: 0
     คำเตือน: 2
     พร้อมที่จะเก็บถาวร: ใช่ (พร้อมคำเตือน)

     ข้อเสนอแนะ:
     1. เพิ่มการทดสอบสำหรับสถานการณ์เซสชันหมดอายุ
     2. พิจารณา Refactoring ให้เป็น event-driven ตามที่ออกแบบไว้ หรืออัปเดต design.md

สิ่งที่ Verify ตรวจสอบ:

มิติ	สิ่งที่ตรวจสอบ
ความสมบูรณ์ (Completeness)	งานทั้งหมดเสร็จ, ข้อกำหนดทั้งหมดถูกนำไปใช้, ครอบคลุมสถานการณ์แล้ว
ความถูกต้อง (Correctness)	การนำไปใช้ตรงตามเจตนาของ spec, จัดการกับกรณีขอบเขตแล้ว
ความสอดคล้อง (Coherence)	การตัดสินใจด้านการออกแบบสะท้อนอยู่ในโค้ด, รูปแบบสอดคล้องกัน

Verify จะไม่บล็อก Archive แต่จะแสดงปัญหาที่คุณอาจต้องการแก้ไขก่อน

Archive: สรุปการเปลี่ยนแปลง (Finalize the Change)

/opsx:archive ทำให้การเปลี่ยนแปลงเสร็จสมบูรณ์และย้ายไปยังที่เก็บถาวร:

You: /opsx:archive

AI:  กำลังเก็บถาวร add-auth...

     สถานะของ Artifact:
     ✓ proposal.md มีอยู่
     ✓ specs/ มีอยู่
     ✓ design.md มีอยู่
     ✓ tasks.md มีอยู่ (12/12 งานเสร็จสมบูรณ์)

     Delta specs: ยังไม่ได้ซิงค์ไปยัง main
     → ต้องการให้ซิงค์ตอนนี้หรือไม่?

You: Yes

AI:  ✓ ซิงค์ specs ไปยัง openspec/specs/auth/spec.md
     ✓ ย้ายไปที่ openspec/changes/archive/2025-01-24-add-auth/

     เก็บถาวรการเปลี่ยนแปลงสำเร็จแล้ว

Archive จะแจ้งเตือนหาก specs ยังไม่ได้ซิงค์ มันจะไม่บล็อกเนื่องจากงานที่ไม่สมบูรณ์ แต่จะเตือนคุณ

เมื่อไหร่ควรใช้สิ่งใด (When to Use What)

/opsx:ff เทียบกับ /opsx:continue

สถานการณ์	ใช้
ข้อกำหนดชัดเจน พร้อมที่จะสร้าง	/opsx:ff
กำลังสำรวจ ต้องการทบทวนแต่ละขั้นตอน	/opsx:continue
ต้องการทำซ้ำ (iterate) บน proposal ก่อน specs	/opsx:continue
มีแรงกดดันด้านเวลา ต้องดำเนินการอย่างรวดเร็ว	/opsx:ff
การเปลี่ยนแปลงที่ซับซ้อน ต้องการการควบคุม	/opsx:continue

กฎง่าย ๆ: หากคุณสามารถอธิบายขอบเขตทั้งหมดได้ตั้งแต่ต้น ให้ใช้ /opsx:ff หากคุณกำลังค้นหาคำตอบไปพร้อม ๆ กับการทำงาน ให้ใช้ /opsx:continue

เมื่อไหร่ควร Update เทียบกับ Start Fresh

คำถามทั่วไป: เมื่อใดที่การอัปเดตการเปลี่ยนแปลงที่มีอยู่แล้วถือว่าโอเค และเมื่อใดที่ควรเริ่มต้นใหม่?

ให้ทำการอัปเดตการเปลี่ยนแปลงที่มีอยู่เมื่อ:

• เจตนาเดียวกัน แต่มีการปรับปรุงวิธีการดำเนินการ
• ขอบเขตแคบลง (MVP ก่อน ส่วนที่เหลือทีหลัง)
• การแก้ไขที่ขับเคลื่อนด้วยการเรียนรู้ (โค้ดเบสไม่ได้เป็นอย่างที่คุณคาดไว้)
• การปรับแต่งการออกแบบตามสิ่งที่ค้นพบจากการนำไปใช้

ให้เริ่มต้นการเปลี่ยนแปลงใหม่เมื่อ:

• เจตนาเปลี่ยนไปโดยพื้นฐาน
• ขอบเขตขยายตัวจนกลายเป็นงานที่แตกต่างออกไปโดยสิ้นเชิง
• การเปลี่ยนแปลงเดิมสามารถถูกทำเครื่องหมายว่า "เสร็จสมบูรณ์" ได้ด้วยตัวเอง
• แพทช์จะสร้างความสับสนมากกว่าที่จะทำให้ชัดเจนขึ้น

                     ┌─────────────────────────────────────┐
                     │     นี่คืองานเดียวกันหรือไม่?          │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          เจตนาเดียวกัน?      >50% ทับซ้อน?      สามารถทำให้การเปลี่ยนแปลงเดิมเป็น "เสร็จสมบูรณ์" ได้โดยไม่ต้องมีสิ่งเหล่านี้หรือไม่?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      ใช่           ไม่ ใช่    ใช่         ไม่  ไม่              ใช่
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    อัปเดต        ใหม่  อัปเดต       ใหม่  อัปเดต          ใหม่

ตัวอย่าง: "เพิ่ม dark mode"

• "จำเป็นต้องรองรับธีมแบบกำหนดเองด้วย" → การเปลี่ยนแปลงใหม่ (ขอบเขตขยาย)
• "การตรวจจับความชอบของระบบยากกว่าที่คาดไว้" → อัปเดต (เจตนาเดียวกัน)
• "มาปล่อย toggle ก่อน แล้วค่อยเพิ่ม preferences ทีหลัง" → อัปเดตแล้วเก็บถาวร จากนั้นสร้างการเปลี่ยนแปลงใหม่

แนวทางปฏิบัติที่ดีที่สุด (Best Practices)

ให้การเปลี่ยนแปลงมีความเฉพาะเจาะจง (Keep Changes Focused)

ให้เป็นหน่วยงานเชิงตรรกะหนึ่งชุดต่อการเปลี่ยนแปลง หากคุณกำลังทำ "เพิ่มฟีเจอร์ X และ Refactor Y ด้วย" ให้พิจารณาเป็นการเปลี่ยนแปลงแยกกันสองรายการ

เหตุผลที่สำคัญ:

• ง่ายต่อการตรวจสอบและทำความเข้าใจ
• ประวัติการเก็บถาวรที่สะอาดกว่า
• สามารถปล่อยออกไปได้โดยอิสระ
• การ Rollback ที่ง่ายขึ้นหากจำเป็น

ใช้ /opsx:explore สำหรับข้อกำหนดที่ไม่ชัดเจน

ก่อนที่จะผูกมัดกับการเปลี่ยนแปลง ให้สำรวจพื้นที่ปัญหา:

You: /opsx:explore

AI:  คุณต้องการสำรวจอะไร?

You: เราควรจัดการเรื่อง rate limiting สำหรับ API ของเราอย่างไรดี?

AI:  ให้ฉันตรวจสอบการตั้งค่าและตัวเลือกปัจจุบันของคุณ...
     [ค้นคว้า codebase พิจารณารูปแบบ]

     ฉันเห็นสามแนวทางที่เราสามารถทำได้:
     1. Middleware-based (ง่าย ต่อ endpoint)
     2. Redis-backed (ปรับขนาดได้ มีสถานะร่วมกัน)
     3. Token bucket per user (ยุติธรรม ซับซ้อน)

     Stack ปัจจุบันของคุณแนะนำ #1 หรือ #2 คุณมีสเกลแค่ไหน?

การสำรวจช่วยให้ความคิดชัดเจนขึ้นก่อนที่คุณจะสร้าง artifact ใด ๆ

ตรวจสอบก่อนเก็บถาวร (Verify Before Archiving)

ใช้ /opsx:verify เพื่อตรวจสอบว่าการนำไปใช้นั้นตรงกับ artifacts หรือไม่:

You: /opsx:verify

AI:  กำลังตรวจสอบ add-dark-mode...

     ✓ งานทั้งหมดใน tasks.md ถูกตรวจสอบแล้ว
     ✓ ข้อกำหนดใน specs มีโค้ดที่เกี่ยวข้อง
     ✓ การตัดสินใจด้านการออกแบบสะท้อนอยู่ใน implementation

     พร้อมที่จะเก็บถาวร!

ตรวจจับความไม่ตรงกันก่อนที่คุณจะปิดการเปลี่ยนแปลงนั้น

ตั้งชื่อการเปลี่ยนแปลงให้ชัดเจน (Name Changes Clearly)

ชื่อที่ดีทำให้ openspec list มีประโยชน์:

ดี:                          ควรหลีกเลี่ยง:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

สรุปคำสั่งอย่างรวดเร็ว

สำหรับรายละเอียดและตัวเลือกของคำสั่งทั้งหมด โปรดดูที่ Commands

Command	วัตถุประสงค์	สถานการณ์การใช้งาน
/opsx:propose	สร้างการเปลี่ยนแปลงและสิ่งของประกอบการวางแผน	เส้นทางเริ่มต้นที่รวดเร็ว (โปรไฟล์ core)
/opsx:explore	คิดวิเคราะห์แนวคิดร่วมกับ AI	เริ่มต้นที่นี่เมื่อไม่แน่ใจ: ข้อกำหนดที่ไม่ชัดเจน การสืบสวน หรือการเปรียบเทียบตัวเลือก
/opsx:new	สร้างโครงร่างการเปลี่ยนแปลง (change scaffold)	โหมดขยาย, ควบคุมสิ่งของประกอบอย่างชัดเจน
/opsx:continue	สร้างสิ่งของประกอบถัดไป	โหมดขยาย, การสร้างสิ่งของประกอบแบบทีละขั้นตอน
/opsx:ff	สร้างสิ่งของประกอบการวางแผนทั้งหมด	โหมดขยาย, ขอบเขตที่ชัดเจน
/opsx:apply	ดำเนินการตามงาน (Implement tasks)	พร้อมที่จะเขียนโค้ด
/opsx:verify	ตรวจสอบความถูกต้องของการดำเนินการ	โหมดขยาย, ก่อนการจัดเก็บถาว (archiving)
/opsx:sync	รวมสเปคที่เปลี่ยนแปลง (Merge delta specs)	โหมดขยาย, เป็นทางเลือก
/opsx:archive	สิ้นสุดการเปลี่ยนแปลง	เมื่อทำงานเสร็จสิ้นทั้งหมด
/opsx:bulk-archive	จัดเก็บการเปลี่ยนแปลงหลายรายการ	โหมดขยาย, การทำงานแบบคู่ขนาน (parallel work)

ขั้นตอนถัดไป

• Commands - เอกสารอ้างอิงคำสั่งฉบับเต็มพร้อมตัวเลือก
• Concepts - เจาะลึกเกี่ยวกับสเปค สิ่งของประกอบ และโครงสร้างข้อมูล (schemas)
• Customization - สร้างเวิร์กโฟลว์แบบกำหนดเอง