แนวคิดหลักโดยสังเขป

OpenSpec คือชั้นการตกลงที่เบา (lightweight agreement layer) ระหว่างคุณกับ AI ของคุณ คุณเขียนสิ่งที่การเปลี่ยนแปลงควรทำ AI จะร่างรายละเอียดออกไป ทั้งสองฝ่ายจะดูแผนเดียวกัน และเมื่อถึงตอนนั้นจึงจะมีการเขียนโค้ด หน้านี้คือแบบจำลองทางความคิดทั้งหมดในหน้าจอเดียว หากคุณต้องการฉบับเต็ม Concepts มีไว้ให้

นี่คือแนวคิดทั้งหมดในห้าคำ: ตกลงก่อน แล้วจึงสร้างได้อย่างมั่นใจ

แนวคิดทั้งห้า

ทุกสิ่งใน OpenSpec สร้างขึ้นจากแนวคิดทั้งห้า เรียนรู้สิ่งเหล่านี้ แล้วส่วนที่เหลือจะเป็นรายละเอียด

1. Specs คือความจริง Spec อธิบายว่าระบบของคุณทำงานอย่างไร ณ ตอนนี้ มันอาศัยอยู่ใน openspec/specs/ จัดเรียงตามโดเมน (auth/, payments/, ui/) Specs ประกอบด้วยข้อกำหนด (requirements) ("the system SHALL expire sessions after 30 minutes") และสถานการณ์ (scenarios) ตัวอย่าง given/when/then ลองคิดว่า specs คือคำตอบเดียวที่ตกลงร่วมกันสำหรับคำถามที่ว่า "ซอฟต์แวร์นี้ทำอะไร?"

2. การเปลี่ยนแปลงคือหน่วยงานหนึ่งหน่วย เมื่อคุณต้องการเพิ่ม แก้ไข หรือลบพฤติกรรม คุณจะสร้างการเปลี่ยนแปลง (change) ซึ่งเป็นโฟลเดอร์ใน openspec/changes/ ที่บรรจุทุกสิ่งเกี่ยวกับงานนั้นไว้ในที่เดียว ได้แก่ proposal, design, task list และ spec edits การเปลี่ยนแปลงหนึ่งครั้ง โฟลเดอร์หนึ่งอัน ฟีเจอร์หนึ่งอย่าง

3. Delta specs อธิบายสิ่งที่กำลังเปลี่ยน ไม่ใช่โลกทั้งใบ ภายในการเปลี่ยนแปลง คุณไม่จำเป็นต้องเขียน spec ทั้งหมดใหม่ แต่คุณจะเขียน delta เล็กๆ: ADDED ข้อกำหนดนี้, MODIFIED อันนั้น, REMOVED อีกอัน นี่คือเคล็ดลับที่ทำให้ OpenSpec เก่งในการแก้ไขระบบที่มีอยู่ ไม่ใช่แค่ระบบที่สร้างขึ้นใหม่เท่านั้น คุณอธิบายความแตกต่าง (diff) ไม่ใช่อธิบายปลายทาง

4. Artifacts สร้างต่อกัน การเปลี่ยนแปลงประกอบด้วยเอกสารบางส่วน ซึ่งถูกสร้างตามลำดับที่เป็นธรรมชาติ โดยแต่ละส่วนจะป้อนข้อมูลให้กับส่วนถัดไป:

proposal ──► specs ──► design ──► tasks ──► implement
   why        what       how       steps      do it

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

5. การเก็บถาว (Archiving) จะรวมการเปลี่ยนแปลงกลับเข้ากับความจริง เมื่องานเสร็จสิ้น คุณจะทำการเก็บถาว (archive) การเปลี่ยนแปลง Delta specs ของมันจะถูกผสานเข้ากับ specs หลัก และโฟลเดอร์การเปลี่ยนแปลงจะย้ายไปยัง changes/archive/ พร้อมกับการประทับวันที่ ตอนนี้ specs ของคุณจึงอธิบายความเป็นจริงใหม่ และคุณก็พร้อมสำหรับการเปลี่ยนแปลงครั้งต่อไป วงจรได้ปิดลง

ภาพรวม

┌─────────────────────────────────────────────────────────────────┐
│                          openspec/                              │
│                                                                 │
│   ┌──────────────────┐         ┌──────────────────────────┐    │
│   │     specs/       │         │        changes/          │    │
│   │                  │ ◄─────  │                          │    │
│   │ source of truth  │  merge  │ one folder per change    │    │
│   │ how things work  │  on     │ proposal · design ·      │    │
│   │ today            │ archive │ tasks · delta specs      │    │
│   └──────────────────┘         └──────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

สองโฟลเดอร์ specs/ คือสิ่งที่จริง changes/ คือสิ่งที่คุณกำลังเสนอ การเก็บถาว (Archiving) จะย้ายข้อเสนอให้กลายเป็นความจริง

ลูปที่คุณจะใช้งานจริง

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

/opsx:explore                   →  (optional) think it through with the AI first
/opsx:propose add-dark-mode     →  AI drafts proposal, specs, design, tasks
        (you read and adjust the plan)
/opsx:apply                     →  AI builds it, checking off tasks
/opsx:archive                   →  specs updated, change archived

เมื่อสงสัย ให้เริ่มต้นด้วยการสำรวจ (exploring) /opsx:explore เป็นคู่คิดในการคิดที่ไม่มีความเสี่ยงาน: มันจะอ่านโค้ดของคุณ วางทางเลือก และเปลี่ยนแนวคิดที่ไม่ชัดเจนให้กลายเป็นแผนที่เป็นรูปธรรมก่อนที่จะมี artifact ใดๆ เกิดขึ้น นี่คือยาแก้พิษที่ดีที่สุดสำหรับ AI ที่อาจสร้าง บางสิ่ง จาก prompt ที่คลุมเครือ คุณรู้แล้วว่าต้องการอะไรอย่างแน่นอนหรือไม่? ข้ามไปที่ /opsx:propose ได้เลย ไม่ว่าจะด้วยวิธีใด การสำรวจก็ยังคงอยู่ในโปรไฟล์เริ่มต้น ดังนั้นมันจึงมีอยู่เสมอ ดู Explore guide

สิ่งเหล่านี้คือคำสั่งสแลช (slash commands) ที่พิมพ์ในแชทของ AI assistant การตั้งค่า (openspec init) เกิดขึ้นในเทอร์มินัลของคุณ หากการแยกส่วนนี้เป็นเรื่องใหม่สำหรับคุณ โปรดอ่าน How Commands Work ก่อน เพราะเป็นจุดที่สร้างความสับสนมากที่สุด

"ตัวช่วยให้เกิดการทำงาน ไม่ใช่สิ่งกีดขวาง"

วลีนี้ปรากฏอยู่ทุกที่ใน OpenSpec ดังนั้นนี่คือความหมายของมันในแง่ที่เข้าใจง่าย

กระบวนการกำหนดสเปคแบบดั้งเดิมเป็นเหมือนน้ำตก: จบการวางแผน แล้วจึง ได้รับอนุญาตให้ดำเนินการ และการย้อนกลับนั้นเจ็บปวด OpenSpec ปฏิเสธสิ่งนี้ ลำดับ proposal → specs → design → tasks แสดงให้เห็นว่าอะไรที่ เป็นไปได้ ต่อไป ไม่ใช่สิ่งที่คุณ ถูกบังคับ ให้ทำต่อไป

ค้นพบระหว่างการดำเนินการว่าดีไซน์ผิดพลาดหรือไม่? แก้ไข design.md และทำต่อไป ตระหนักว่าขอบเขตควรเล็กลงหรือไม่? อัปเดต proposal สิ่งใดก็ไม่ถูกล็อก ความสัมพันธ์ (dependencies) มีอยู่เพื่อให้ AI มีบริบทที่จำเป็นเท่านั้น (คุณไม่สามารถเขียนงานที่ดีได้หากไม่มี specs เป็นพื้นฐาน) ไม่ใช่เพื่อจำกัดคุณ

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

ทำไม่อย่างไรจึงคุ้มค่ากับภาระที่เพิ่มขึ้นเล็กน้อยนี้

ความจริงที่ตรงไปตรงมา: OpenSpec เพิ่มขั้นตอน คุณเขียนแผนสั้นๆ ก่อนการสร้าง แล้วคุณจะได้อะไรจากมัน?

• คุณจะจับได้ว่ามีทิศทางที่ผิดก่อนที่จะทำให้คุณเสียค่าใช้จ่าย การแก้ไขความเข้าใจผิดใน proposal หนึ่งย่อหน้านั้นไม่มีค่าใช้จ่าย แต่การแก้ไขหลังจากที่ AI เขียนไปแล้ว 400 บรรทัดนั้นไม่ใช่
• แผนและโค้ดยังคงอยู่ใน repository เดียวกัน หกเดือนต่อมา specs จะบอกคุณ (และเซสชัน AI ถัดไป) ว่าทำไมาระบบจึงทำงานแบบที่เป็นอยู่
• การเปลี่ยนแปลงสามารถตรวจสอบได้ โฟลเดอร์การเปลี่ยนแปลงคือแพ็คเกจที่เรียบร้อย: อ่าน proposal กวาดดู delta ตรวจสอบ tasks ไม่ต้องขุดค้นจากประวัติแชท
• มันเข้ากันได้กับ codebase ที่มีอยู่ Deltas หมายความว่าคุณสามารถระบุการเปลี่ยนแปลงสำหรับแอปพลิเคชัน 50,000 บรรทัดโดยไม่ต้องจัดทำเอกสารทั้งหมดก่อน

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

จะไปต่อที่ไหน

• เพิ่งเริ่มต้น? Getting Started อธิบายการเปลี่ยนแปลงแรกแบบเต็มรูปแบบ
• ยังไม่แน่ใจว่าจะสร้างอะไรดี? Explore First คือจุดเริ่มต้น
• สับสนว่าคำสั่งทำงานที่ใด? How Commands Work
• ต้องการฉบับเจาะลึกของทุกสิ่งที่กล่าวมาข้างต้นหรือไม่? Concepts
• เรียนรู้จากตัวอย่าง? Examples & Recipes
• ต้องการนิยามคำศัพท์ใดๆ หรือไม่? Glossary