ตัวอย่างและสูตรปฏิบัติ

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

ข้อควรจำก่อนเริ่มต้น: คำสั่ง Slash เช่น /opsx:propose ใช้ใน แชทผู้ช่วย AI ของคุณ และคำสั่ง openspec ใช้ใน เทอร์มินัล ของคุณ หากคุณยังไม่เคยใช้ ให้อ่าน วิธีทำงานของคำสั่ง ก่อน ในบันทึกบทสนทนาต่อไปนี้ You: และ AI: เป็นส่วนของแชท และบรรทัดที่ขึ้นต้นด้วย $ เป็นส่วนของเทอร์มินัล

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

สูตรปฏิบัติ 1: ฟีเจอร์ขนาดเล็ก เส้นทางเร็ว

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

ทั้งหมดมีเพียง 3 คำสั่ง: propose (เสนอ) build (สร้าง) และ archive (เก็บถาวร)

You: /opsx:propose add-logout-button

AI:  สร้าง openspec/changes/add-logout-button/ เรียบร้อย
     ✓ proposal.md — เหตุผลและรายละเอียด
     ✓ specs/      — ความต้องการใหม่และสถานการณ์ที่เกี่ยวข้อง
     ✓ design.md   — แนวทางทางเทคนิค
     ✓ tasks.md    — รายการตรวจสอบการนำไปปฏิบัติใช้
     พร้อมสำหรับการนำไปปฏิบัติใช้แล้ว รัน /opsx:apply.

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

You: /opsx:apply

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

You: /opsx:archive

AI:  กำลังเก็บถาวร add-logout-button...
     ✓ ผนวกข้อกำหนดเข้าไปยัง openspec/specs/auth/spec.md
     ✓ ย้ายไปยัง openspec/changes/archive/2026-06-22-add-logout-button/
     เสร็จสมบูรณ์ พร้อมสำหรับการเปลี่ยนแปลงถัดไป

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

สูตรปฏิบัติ 2: แก้ไขบั๊ก

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

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

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

AI:  สร้าง openspec/changes/fix-login-redirect-loop/ เรียบร้อย
     ข้อเสนอบันทึกพฤติกรรมที่เสียหายปัจจุบันและพฤติกรรมที่กำหนดไว้เรียบร้อย
     delta spec ทำการแก้ไข (MODIFIES) ความต้องการเกี่ยวกับการเปลี่ยนเส้นทาง (redirect) เพื่อให้มีความแม่นยำและสามารถทดสอบได้
     พร้อมสำหรับการนำไปปฏิบัติใช้แล้ว

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

เคล็ดลับ: สำหรับการแก้ไข สถานการณ์ที่ดีคือการทดสอบการถดถอย (regression test) ในรูปแบบข้อความ "กำหนดให้ ผู้ใช้ที่ออกจากระบบแล้ว เมื่อ ผู้ใช้ส่งข้อมูลประจำตัวที่ถูกต้อง แล้ว ผู้ใช้จะเข้าสู่หน้าแดชบอร์ดและไม่ถูกเปลี่ยนเส้นทางอีก" เขียนสิ่งนี้ไว้ และการนำไปปฏิบัติใช้จะมีเป้าหมายที่ชัดเจน

สูตรปฏิบัติ 3: สำรวจก่อนเริ่มดำเนินการ

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

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

You: /opsx:explore

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

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

AI:  ให้ฉันดูสิ... ฉันพบสาเหตุที่เป็นไปได้ 3 รายการ:
     1. ภาพขนาดใหญ่ที่ไม่ได้รับการปรับแต่งบนรายการสินค้า
     2. การดึงข้อมูลแบบซิงโครนัสที่บล็อกการเรนเดอร์
     3. การเรนเดอร์ซ้ำที่เกิดจากการเปลี่ยนแปลงของคอนเท็กซ์ (context)
     ควรจัดการอันไหนก่อน?

You: The data fetching one.

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

AI:  สร้างการเปลี่ยนแปลงนี้เรียบร้อย พร้อมข้อเสนอที่ได้รับข้อมูลจากสิ่งที่เราพบเมื่อก่อน
     พร้อมสำหรับการนำไปปฏิบัติใช้แล้ว

การสำรวจช่วยให้ความคิดของคุณชัดเจน ก่อน ที่คุณจะใช้การเปลี่ยนแปลงกับมัน เมื่อความเข้าใจเป็นรูปธรรมแล้ว เสนอการเปลี่ยนแปลง และ 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:  สร้าง openspec/changes/fix-login-redirect/ เรียบร้อย พร้อมสำหรับการนำไปปฏิบัติใช้.

You: /opsx:apply

AI:  นำการแก้ไขไปปฏิบัติใช้เรียบร้อย งานทั้งหมดเสร็จสมบูรณ์.

You: /opsx:archive

AI:  ✓ เก็บถาวร fix-login-redirect เรียบร้อย.

You: Back to dark mode.

You: /opsx:apply add-dark-mode

AI:  กำลังดำเนินการ add-dark-mode ต่อ เริ่มจากงาน 2.3: อัปเดตส่วนหัว...

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

เมื่อมีการเปลี่ยนแปลงหลายรายการเสร็จพร้อมกัน คำสั่งขยาย /opsx:bulk-archive จะเก็บถาวรทั้งหมดไว้ด้วยกัน และแก้ไขข้อขัดแย้งของข้อกำหนดโดยตรวจสอบสิ่งที่ถูกนำไปปฏิบัติใช้จริง ดูเพิ่มเติมที่ เวิร์กโฟลว์

สูตรปฏิบัติ 5: รีแฟกเตอร์โดยไม่มีการเปลี่ยนแปลงพฤติกรรม

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

นี่เป็นกรณีที่น่าสนใจ เพราะการรีแฟกเตอร์ที่ไม่มีการเปลี่ยนแปลงพฤติกรรมเลย ไม่มีอะไรให้เพิ่มเข้าไปในข้อกำหนดของคุณ สัญญาพฤติกรรมไม่เปลี่ยนแปลง ใช้เฉพาะส่วนของการนำไปปฏิบัติใช้ที่เปลี่ยนเท่านั้น ดังนั้นงานทั้งหมดอยู่ในส่วนของ design และ tasks และส่วนต่างของข้อกำหนด (spec delta) จึงว่างเปล่าหรือไม่มีอยู่

You: /opsx:propose refactor-payment-module

AI:  สร้างการเปลี่ยนแปลงนี้เรียบร้อย ข้อเสนอระบุเป้าหมาย (แยกโมดูลการชำระเงิน ไม่มีการเปลี่ยนแปลงพฤติกรรม) และ design จับโครงสร้างใหม่ไว้ ไม่มีการเปลี่ยนแปลงข้อกำหนดใดๆ เพราะพฤติกรรมคงไม่เปลี่ยนแปลง พร้อมสำหรับการนำไปปฏิบัติใช้แล้ว

ระบุว่าส่วนต่างของข้อกำหนดว่างเปล่าโดยตรงโดยตั้งค่า skip_specs: true ในไฟล์ .openspec.yaml ของการเปลี่ยนแปลง:

schema: spec-driven
skip_specs: true

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

การเก็บถาวรการเปลี่ยนแปลงที่มีเครื่องหมายนี้ไม่ต้องการแฟล็กเพิ่มเติม (เนื่องจากไม่มีส่วนต่างให้ผนวก) แยกกันจากนี้ แฟล็ก --skip-specs จะบอกคำสั่งในเทอร์มินัลให้ข้ามขั้นตอนของข้อกำหนดโดยชัดเจน:

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

แฟล็กนี้มีประโยชน์สำหรับเครื่องมือ CI และการเปลี่ยนแปลงที่เกี่ยวกับเอกสารเพียงอย่างเดียว หลักการคือ: ข้อกำหนดอธิบายพฤติกรรม ดังนั้นหากพฤติกรรมไม่เปลี่ยนแปลง ข้อกำหนดก็ไม่ควรเปลี่ยนแปลงด้วย ดูเพิ่มเติมที่ แนวคิดพื้นฐาน

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

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

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

$ openspec config profile      # เลือกเวิร์กโฟลว์ขยาย
$ openspec update              # นำไปใช้กับโปรเจกต์นี้

ตอนนี้คุณสามารถสร้างโครงสร้างพื้นฐานและสร้างเพิ่มเติมทีละขั้นได้:

You: /opsx:new add-2fa

AI:  สร้าง openspec/changes/add-2fa/ เรียบร้อย พร้อมสร้าง: proposal.

You: /opsx:continue

AI:  สร้าง proposal.md เรียบร้อย พร้อมใช้งาน: specs, design.

You: /opsx:continue

AI:  สร้าง specs/auth/spec.md เรียบร้อย พร้อมใช้งาน: design.

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

สูตรปฏิบัติ 7: เรียนรู้เวิร์กโฟลว์ทั้งหมดด้วยการปฏิบัติเอง

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

เปิดใช้งานคำสั่งขยาย (ดูสูตรปฏิบัติ 6) แล้ว:

You: /opsx:onboard

AI:  ยินดีต้อนรับสู่ OpenSpec! ฉันจะนำคุณผ่านการเปลี่ยนแปลงทั้งหมด
     โดยใช้โค้ดเบสจริงของคุณ ฉันจะสแกนหาการปรับปรุงขนาดเล็กและปลอดภัย
     ที่เราสามารถทำร่วมกัน...

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

ตรวจสอบงานของคุณจากเทอร์มินัล

ทุกเมื่อ จากเทอร์มินัลของคุณ คุณสามารถตรวจสอบสถานะของทุกอย่างได้:

$ openspec list                      # การเปลี่ยนแปลงที่ใช้งานอยู่
$ openspec show add-dark-mode        # รายละเอียดของการเปลี่ยนแปลงหนึ่งรายการ
$ openspec validate add-dark-mode    # ตรวจสอบโครงสร้าง
$ openspec view                      # แดชบอร์ดแบบโต้ตอบ

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

สิ่งที่ควรทำต่อไป

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