ตัวอย่าง & สูตรการใช้งาน

การเปลี่ยนแปลงจริง ตั้งแต่ต้นจนจบ แต่ละสูตรแสดงคำสั่งที่คุณจะพิมพ์และผลลัพธ์ที่คุณจะได้เห็น เพื่อให้คุณจับคู่สถานการณ์ของคุณเข้ากับรูปแบบแล้วคัดลอกไปใช้ได้เลย ตัวอย่างเหล่านี้ใช้คำสั่ง core โดยค่าเริ่มต้น (propose, explore, apply, update, sync, archive); ในกรณีที่ชุดคำสั่งที่ขยายเพิ่มเติมช่วยได้ จะมีการระบุไว้

คำเตือนก่อนเริ่มใช้งาน: คำสั่งแบบ slash เช่น /opsx:propose จะพิมพ์ใน แชทของ AI assistant ของคุณ ส่วนคำสั่ง openspec จะพิมพ์ใน terminal ของคุณ หากสิ่งนี้เป็นเรื่องใหม่ ให้อ่าน How Commands Work ก่อน ในบันทึกการสนทนาด้านล่าง You: และ AI: คือแชท และบรรทัดที่ขึ้นต้นด้วย $ คือ terminal

ยังไม่แน่ใจว่าจะสร้างอะไร? สูตรส่วนใหญ่เหล่านี้จะได้ผลดียิ่งขึ้นหากคุณเริ่มด้วย /opsx:explore เพื่อคิดทบทวนก่อน Recipe 3 แสดงการใช้งานจริง และคู่มือ Explore First อธิบายเหตุผลทั้งหมด

สูตรที่ 1: ฟีเจอร์ขนาดเล็ก เส้นทางลัด

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

ทั้งหมดมีเพียงสามคำสั่ง Propose สร้าง แล้ว archive

You: /opsx:propose add-logout-button

AI:  Created openspec/changes/add-logout-button/
     ✓ proposal.md — why and what
     ✓ specs/      — the new requirement and its scenarios
     ✓ design.md   — technical approach
     ✓ tasks.md    — implementation checklist
     Ready for implementation. Run /opsx:apply.

ตอนนี้ให้เปิดอ่านแผน เปิด proposal และ delta spec นี่คือช่วงเวลาที่ OpenSpec ถูกสร้างขึ้นมาเพื่อ: จับความเข้าใจผิดตั้งแต่ยังเป็นเพียงหนึ่งย่อหน้า ไม่ใช่ 400 บรรทัดของโค้ด แก้ไข artifact โดยตรงหากมีอะไรไม่ถูกต้อง แล้วดำเนินการต่อ

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Add logout button to header
     ✓ 1.2 Clear session on click
     ✓ 1.3 Add confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  Archiving add-logout-button...
     ✓ Merged specs into openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
     Done. Ready for the next change.

เท่านี้เอง พฤติกรรมของการ logout ตอนนี้กลายเป็นส่วนหนึ่งของ specs แล้ว และการเปลี่ยนแปลงถูกเก็บไว้พร้อมบริบททั้งหมด

สูตรที่ 2: แก้ไขบั๊ก

เมื่อไหร่ควรใช้: มีบางอย่างเสียหายและคุณต้องการให้การแก้ไขถูกบันทึกเป็นการเปลี่ยนแปลงพฤติกรรมอย่างตั้งใจ ไม่ใช่ commit ที่ไม่มีใครเข้าใจ

การแก้ไขบั๊กทำงานเหมือนฟีเจอร์ تمامًا ความแตกต่างอยู่ที่วิธีที่คุณเขียน proposal: อธิบายพฤติกรรมที่ ถูกต้อง ไม่ใช่แค่ "แก้บั๊ก"

You: /opsx:propose fix-login-redirect-loop

AI:  Created openspec/changes/fix-login-redirect-loop/
     The proposal captures the current broken behavior and the
     intended behavior. The delta spec MODIFIES the redirect
     requirement so it's now precise and testable.
     Ready for implementation.

เนื่องจากตัวแก้ไขถูกบันทึกเป็น requirement แบบ MODIFIED พร้อม scenario ใหม่ คนถัดไป (หรือ AI session ถัดไป) จะเห็นไม่เพียงแค่ว่าคุณแก้ไขแล้ว แต่เห็นด้วยว่า "ถูกต้อง" หมายความว่าอย่างไร จากนั้นใช้ /opsx:apply และ /opsx:archive ตามปกติ

เคล็ดลับ: สำหรับการแก้ไข scenario ที่ดีคือ regression test ในรูปแบบข้อความ "GIVEN ผู้ใช้ที่ไม่ได้ล็อกอิน, WHEN ส่งข้อมูลเข้าสู่ระบบที่ถูกต้อง, THEN พวกเขาจะไปถึงหน้า dashboard และไม่ถูก redirect ซ้ำ" เขียนสิ่งนั้นไว้ แล้วการ implement ก็จะมีเป้าหมายที่ชัดเจน

สูตรที่ 3: สำรวจก่อนตัดสินใจ

เมื่อไหร่ควรใช้: คุณมีปัญหาแต่ยังไม่มีแผน คุณไม่แน่ใจว่าจะสร้างอะไร หรือแนวทางไหนถูกต้อง

เริ่มด้วย /opsx:explore มันคือคู่คิดที่ไม่มีโครงสร้างและไม่สร้าง artifact ใดๆ มันอ่าน codebase ของคุณและช่วยคุณตัดสินใจ

You: /opsx:explore

AI:  What would you like to explore?

You: Page loads feel slow but I don't know where the time goes.

AI:  Let me look... I found three likely culprits:
     1. Large unoptimized images on the product list
     2. Synchronous data fetching that blocks render
     3. Re-renders triggered by context changes
     Which should we tackle first?

You: The data fetching one.

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

AI:  Created the change, with a proposal informed by what we just
     found. Ready for implementation.

การสำรวจทำให้ความคิดของคุณชัดเจน ก่อน ที่คุณจะเสียเวลาสร้าง change เมื่อ insight ชัดเจนขึ้น ก็ propose และ AI จะนำบริบทไปต่อ

สูตรที่ 4: จัดการสองการเปลี่ยนแปลงพร้อมกัน

เมื่อไหร่ควรใช้: คุณกำลังทำฟีเจอร์อยู่แต่มีงานแก้ไขด่วนแทรกเข้ามา

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

You: I'm partway through add-dark-mode, but I need to fix a login bug now.

You: /opsx:propose fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/. Ready for implementation.

You: /opsx:apply

AI:  Implemented the fix. All tasks complete.

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect.

You: Back to dark mode.

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode. Picking up at task 2.3: Update Header...

การระบุชื่อการเปลี่ยนแปลงใน /opsx:apply add-dark-mode คือวิธีที่คุณบอก AI ให้มุ่งไปที่การเปลี่ยนแปลงเฉพาะเมื่อมีการเปลี่ยนแปลงหลายอย่างพร้อมกัน เนื่องจาก tasks ติดตามความคืบหน้าใน tasks.md AI จึงรู้ว่าหยุดไว้ตรงไหนพอดี

เมื่อมีการเปลี่ยนแปลงหลายอย่างเสร็จพร้อมกัน /opsx:bulk-archive ที่ขยายเพิ่มเติมจะเก็บรวมกันและแก้ไขความขัดแย้งของ spec โดยตรวจสอบสิ่งที่ implement จริงๆ ดู Workflows

สูตรที่ 5: Refactor โดยไม่เปลี่ยนพฤติกรรม

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

นี่คือกรณีที่น่าสนใจ เพราะการ refactor ล้วนๆ มี อะไรให้เพิ่มใน specs ของคุณเลย สัญญาพฤติกรรมไม่เปลี่ยน มีเพียงการ implement ที่เปลี่ยน ดังนั้นงานจึงอยู่ใน design และ tasks และ spec delta จะว่างหรือไม่มีอยู่

You: /opsx:propose refactor-payment-module

AI:  Created the change. The proposal states the goal (split the
     payment module, no behavior change) and the design captures
     the new structure. No spec changes, since behavior is identical.
     Ready for implementation.

ประกาศ delta ว่างอย่างชัดเจนโดยตั้ง skip_specs: true ใน .openspec.yaml ของการเปลี่ยนแปลง:

schema: spec-driven
skip_specs: true

หากไม่มี marker นี้ openspec validate จะปฏิเสธการเปลี่ยนแปลงที่มี delta ศูนย์ (ดังนั้นขั้นตอน specs ที่ลืมทำจึงยังถูกจับได้); หากมี marker นี้ validation จะผ่านและ openspec status จะแสดงว่าขั้นตอน specs ถูกข้ามอย่างชัดเจนแทนที่จะค้างอยู่ หากการ refactor ปรากฏว่าเปลี่ยนพฤติกรรมอยู่ดี ให้ลบ skip_specs ออกจาก .openspec.yaml และเขียน delta specs — validate จะถือว่า marker พร้อมไฟล์ spec เป็นความขัดแย้ง ดังนั้น marker ที่ล้าสมัยจึงไม่สามารถค้างอยู่เงียบๆ ได้

การ archive การเปลี่ยนแปลงที่มี marker ไม่ต้องใช้ flag เพิ่มเติม (ไม่มี delta ให้ merge) โดยอิสระ flag --skip-specs บอกคำสั่ง terminal ให้ข้ามขั้นตอน spec อย่างชัดเจน:

$ openspec archive refactor-payment-module --skip-specs

flag เดียวกันนี้มีประโยชน์สำหรับ tooling, CI และการเปลี่ยนแปลงเฉพาะ docs หลักการคือ: specs อธิบายพฤติกรรม ดังนั้นหากพฤติกรรมไม่เปลี่ยน spec ก็ไม่ควรเปลี่ยนเช่นกัน ดู Concepts

สูตรที่ 6: ควบคุมทีละขั้น (คำสั่งที่ขยายเพิ่มเติม)

เมื่อไหร่ควรใช้: การเปลี่ยนแปลงที่ซับซ้อนหรือมีความเสี่ยงที่คุณต้องการตรวจสอบแต่ละ artifact ก่อนดำเนินการต่อ

/opsx:propose หลักจะร่างทุกอย่างพร้อมกัน เมื่อคุณต้องการทำทีละขั้น ให้เปิดคำสั่งที่ขยายเพิ่มเติม:

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

ตอนนี้คุณสามารถ scaffold และสร้างแบบค่อยเป็นค่อยไป:

You: /opsx:new add-2fa

AI:  Created openspec/changes/add-2fa/. Ready to create: proposal.

You: /opsx:continue

AI:  Created proposal.md. Now available: specs, design.

You: /opsx:continue

AI:  Created specs/auth/spec.md. Now available: design.

ตรวจสอบแต่ละ artifact เมื่อมันถูกสร้าง แก้ไขได้ตามต้องการ และดำเนินการต่อเมื่อพอใจ เมื่อต้องการให้ร่างส่วนที่เหลือพร้อมกัน /opsx:ff จะ fast-forward ผ่าน artifact การวางแผนที่เหลือ ก่อน archive /opsx:verify จะตรวจสอบว่าการ implement ตรงกับ specs จริงๆ ดู Workflows

สูตรที่ 7: เรียนรู้วงจรทั้งหมดด้วยมือตัวเอง

เมื่อไหร่ควรใช้: คุณติดตั้ง OpenSpec แล้วและต้องการ สัมผัส workflow บนโค้ดของคุณเอง ไม่ใช่ตัวอย่างเล่นๆ

เปิดคำสั่งที่ขยายเพิ่มเติม (ดูสูตรที่ 6) จากนั้น:

You: /opsx:onboard

AI:  Welcome to OpenSpec! I'll walk you through a complete change
     using your actual codebase. Let me scan for a small, safe
     improvement we can make together...

/opsx:onboard จะค้นหาการปรับปรุงจริง (ขนาดเล็ก) สร้างการเปลี่ยนแปลงสำหรับมัน implement และ archive โดยอธิบายทุกขั้นตอน ใช้เวลา 15 ถึง 30 นาที และทิ้งการเปลี่ยนแปลงจริงให้คุณเก็บไว้หรือทิ้งก็ได้ นี่คือวิธีที่นุ่มนวลที่สุดในการเรียนรู้ ดู Commands

ตรวจสอบงานจาก terminal

ตลอดเวลา จาก terminal ของคุณ คุณสามารถตรวจสอบสถานะต่างๆ ได้:

$ openspec list                      # active changes
$ openspec show add-dark-mode        # one change in detail
$ openspec validate add-dark-mode    # check structure
$ openspec view                      # interactive dashboard

เหล่านี้คือเครื่องมือสำหรับอ่านและตรวจสอบ การ propose และสร้างยังคงทำผ่านคำสั่ง slash ในแชท รายละเอียดทั้งหมดอยู่ใน CLI reference

ไปต่อได้ที่ไหน

• Explore First: วิธีที่แนะนำในการเริ่มต้นเมื่อคุณไม่แน่ใจ
• Workflows: รูปแบบข้างต้น พร้อมคำแนะนำในการตัดสินใจว่าเมื่อไหร่ควรใช้แต่ละอย่าง
• Commands: คำสั่ง slash ทุกคำสั่งอย่างละเอียด
• Getting Started: การเดินผ่านครั้งแรกอย่างเป็นทางการ
• Concepts: ทำไมชิ้นส่วนต่างๆ จึงประกอบกันแบบนี้