แนวคิด
คู่มือนี้อธิบายแนวคิดหลักเบื้องหลัง OpenSpec และวิธีที่แนวคิดเหล่านี้เชื่อมต่อกัน สำหรับการใช้งานจริง โปรดดูที่ เริ่มต้นใช้งาน และ ขั้นตอนการทำงาน
ปรัชญา
OpenSpec สร้างขึ้นจากหลักการสี่ประการ:
fluid not rigid — ไม่มีประตูแบ่งขั้นตอน ทำงานในสิ่งที่สมเหตุสมผล
iterative not waterfall — เรียนรู้ในขณะที่สร้าง ปรับปรุงไปเรื่อยๆ
easy not complex — การตั้งค่าเบาบาง พิธีการน้อยที่สุด
brownfield-first — ทำงานร่วมกับโค้ดที่มีอยู่แล้ว ไม่ใช่แค่โปรเจกต์ใหม่ทำไมหลักการเหล่านี้จึงสำคัญ
Fluid not rigid. ระบบสเปกแบบดั้งเดิมบังคับให้คุณเข้าสู่ขั้นตอนต่างๆ: ขั้นแรกคุณวางแผน จากนั้นคุณดำเนินการ แล้วคุณก็เสร็จสิ้น OpenSpec มีความยืดหยุ่นมากกว่า — คุณสามารถสร้างชิ้นงานได้ตามลำดับที่สมเหตุสมผลสำหรับงานของคุณ
Iterative not waterfall. ความต้องการเปลี่ยนแปลง ความเข้าใจลึกซึ้งขึ้น สิ่งที่ดูเหมือนเป็นวิธีที่ดีในตอนแรกอาจไม่คงอยู่หลังจากที่คุณเห็นโค้ดแล้ว OpenSpec ยอมรับความเป็นจริงนี้
Easy not complex. บางกรอบงานสเปกต้องการการตั้งค่าที่กว้างขวาง รูปแบบที่เข้มงวด หรือกระบวนการที่หนักหน่วง OpenSpec ไม่ขวางทางคุณ เริ่มต้นได้ภายในไม่กี่วินาที เริ่มทำงานได้ทันที และปรับแต่งเฉพาะเมื่อคุณต้องการเท่านั้น
Brownfield-first. งานซอฟต์แวร์ส่วนใหญ่ไม่ได้สร้างจากศูนย์ — แต่เป็นการแก้ไขระบบที่มีอยู่แล้ว วิธีการแบบเดลต้าของ OpenSpec ทำให้ง่ายต่อการระบุการเปลี่ยนแปลงต่อพฤติกรรมที่มีอยู่ ไม่ใช่แค่การอธิบายระบบใหม่
ภาพรวม
OpenSpec จัดระเบียบงานของคุณออกเป็นสองส่วนหลัก:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ แหล่งข้อมูลจริง │◄─────│ การแก้ไขที่เสนอ │ │
│ │ วิธีการทำงาน │ merge│ การเปลี่ยนแปลงแต่ละรายการ │ │
│ │ ปัจจุบันของระบบ │ │ = หนึ่งโฟลเดอร์ │ │
│ │ │ │ มีไฟล์ประกอบ + ข้อมูลต่าง │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specs คือแหล่งข้อมูลจริง — มันอธิบายว่าระบบของคุณทำงานอย่างไรในปัจจุบัน
Changes คือการแก้ไขที่เสนอ — มันอยู่ในโฟลเดอร์แยกต่างหากจนกว่าคุณจะพร้อมที่จะรวมเข้าด้วยกัน
การแยกส่วนนี้เป็นกุญแจสำคัญ คุณสามารถทำงานกับการเปลี่ยนแปลงหลายรายการพร้อมกันได้โดยไม่มีความขัดแย้ง คุณสามารถตรวจสอบการเปลี่ยนแปลงก่อนที่จะมีผลต่อ specs หลัก และเมื่อคุณเก็บถาวรการเปลี่ยนแปลง ข้อมูลต่างของมันจะรวมเข้ากับแหล่งข้อมูลจริงได้อย่างราบรื่น
Specs
Specs อธิบายพฤติกรรมของระบบของคุณโดยใช้ข้อกำหนดและสถานการณ์ที่มีโครงสร้าง
โครงสร้าง
openspec/specs/
├── auth/
│ └── spec.md # พฤติกรรมการยืนยันตัวตน
├── payments/
│ └── spec.md # การประมวลผลการชำระเงิน
├── notifications/
│ └── spec.md # ระบบการแจ้งเตือน
└── ui/
└── spec.md # พฤติกรรม UI และธีมจัดระเบียบ specs ตามโดเมน — กลุ่มตรรกะที่สมเหตุสมผลสำหรับระบบของคุณ รูปแบบทั่วไป:
- ตามพื้นที่ฟีเจอร์:
auth/,payments/,search/ - ตามองค์ประกอบ:
api/,frontend/,workers/ - ตามขอบเขต:
ordering/,fulfillment/,inventory/
รูปแบบ Spec
Spec ประกอบด้วยข้อกำหนด และข้อกำหนดแต่ละรายการมีสถานการณ์:
markdown
# สเปคการยืนยันตัวตน
## วัตถุประสงค์
การยืนยันตัวตนและการจัดการเซสชันสำหรับแอปพลิเคชัน
## ข้อกำหนด
### ข้อกำหนด: การยืนยันตัวตนของผู้ใช้
ระบบ SHALL ออก JWT token เมื่อเข้าสู่ระบบสำเร็จ
#### สถานการณ์: ข้อมูลรับรองที่ถูกต้อง
- GIVEN ผู้ใช้ที่มีข้อมูลรับรองที่ถูกต้อง
- WHEN ผู้ใช้ส่งแบบฟอร์มเข้าสู่ระบบ
- THEN จะมีการคืน JWT token
- AND ผู้ใช้จะถูกเปลี่ยนเส้นทางไปยังแดชบอร์ด
#### สถานการณ์: ข้อมูลรับรองที่ไม่ถูกต้อง
- GIVEN ข้อมูลรับรองที่ไม่ถูกต้อง
- WHEN ผู้ใช้ส่งแบบฟอร์มเข้าสู่ระบบ
- THEN จะแสดงข้อความแสดงข้อผิดพลาด
- AND ไม่มีการออก tokenองค์ประกอบสำคัญ:
| องค์ประกอบ | วัตถุประสงค์ |
|---|---|
## วัตถุประสงค์ | คำอธิบายระดับสูงของโดเมน spec นี้ |
### ข้อกำหนด: | พฤติกรรมเฉพาะที่ระบบต้องมี |
#### สถานการณ์: | ตัวอย่างที่เป็นรูปธรรมของข้อกำหนดในการทำงาน |
| SHALL/MUST/SHOULD | คีย์เวิร์ด RFC 2119 ที่บ่งบอกความเข้มข้นของข้อกำหนด |
ทำไมต้องจัดโครงสร้าง Specs แบบนี้
ข้อกำหนดคือ "อะไร" — มันระบุว่าระบบควรทำอะไรโดยไม่ระบุการใช้งาน
สถานการณ์คือ "เมื่อไหร่" — มันให้ตัวอย่างที่เป็นรูปธรรมที่สามารถตรวจสอบได้ สถานการณ์ที่ดี:
- สามารถทดสอบได้ (คุณสามารถเขียนการทดสอบอัตโนมัติสำหรับมันได้)
- ครอบคลุมทั้งเส้นทางที่ราบรื่นและกรณีขอบ
- ใช้รูปแบบที่มีโครงสร้างเช่น Given/When/Then หรือรูปแบบที่คล้ายกัน
คีย์เวิร์ด RFC 2119 (SHALL, MUST, SHOULD, MAY) สื่อสารเจตนา:
- MUST/SHALL — ข้อกำหนดที่เด็ดขาด
- SHOULD — แนะนำ แต่มีข้อยกเว้น
- MAY — เป็นทางเลือก
สิ่งที่ Spec คือ (และไม่ใช่)
Spec คือ สัญญาณพฤติกรรม ไม่ใช่แผนการใช้งาน
เนื้อหา spec ที่ดี:
- พฤติกรรมที่สังเกตได้ซึ่งผู้ใช้หรือระบบล่างพึ่งพา
- ข้อมูลเข้า ข้อมูลออก และเงื่อนไขข้อผิดพลาด
- ข้อจำกัดภายนอก (ความปลอดภัย ความเป็นส่วนตัว ความน่าเชื่อถือ ความเข้ากันได้)
- สถานการณ์ที่สามารถทดสอบหรือตรวจสอบได้อย่างชัดเจน
สิ่งที่ควรหลีกเลี่ยงใน specs:
- ชื่อคลาส/ฟังก์ชันภายใน
- การเลือกใช้ไลบรารีหรีอเฟรมเวิร์ก
- รายละเอียดการใช้งานทีละขั้นตอน
- แผนการดำเนินงานโดยละเอียด (สิ่งเหล่านี้ควรอยู่ใน
design.mdหรือtasks.md)
การทดสอบอย่างรวดเร็ว:
- หากการใช้งานสามารถเปลี่ยนแปลงได้โดยไม่เปลี่ยนพฤติกรรมที่มองเห็นได้ภายนอก มันก็ไม่ควรอยู่ใน spec
รักษาความเบา: ความเข้มข้นแบบก้าวหน้า
OpenSpec มุ่งหวังที่จะหลีกเลี่ยงระบบราชการ ใช้ระดับที่เบาที่สุดที่ยังทำให้การเปลี่ยนแปลงสามารถตรวจสอบได้
สเปคแบบเบา (ค่าเริ่มต้น):
- ข้อกำหนดที่สั้นและเน้นพฤติกรรม
- ขอบเขตและเป้าหมายที่ไม่ใช่ที่ชัดเจน
- การตรวจสอบการยอมรับที่เป็นรูปธรรมไม่กี่รายการ
สเปคแบบเต็ม (สำหรับความเสี่ยงที่สูงขึ้น):
- การเปลี่ยนแปลงข้ามทีมหรือข้าม repo
- การเปลี่ยนแปลง API/สัญญาณ การย้ายข้อมูล ความกังวลด้านความปลอดภัย/ความเป็นส่วนตัว
- การเปลี่ยนแปลงที่ความคลุมเครืออาจทำให้ต้องแก้ไขซ้ำที่มีค่าใช้จ่ายสูง
การเปลี่ยนแปลงส่วนใหญ่ควรอยู่ในโหมดเบา
การทำงานร่วมกันของมนุษย์ + ตัวแทน
ในหลายทีม มนุษย์สำรวจและตัวแทนร่างไฟล์ประกอบ ลูปที่ตั้งใจไว้คือ:
- มนุษย์ให้เจตนา บริบท และข้อจำกัด
- ตัวแทนแปลงสิ่งนี้เป็นข้อกำหนดที่เน้นพฤติกรรมและสถานการณ์
- ตัวแทนเก็บรายละเอียดการใช้งานไว้ใน
design.mdและtasks.mdไม่ใช่spec.md - การตรวจสอบยืนยันโครงสร้างและความชัดเจนก่อนการใช้งาน
สิ่งนี้ทำให้ specs อ่านง่ายสำหรับมนุษย์และสอดคล้องกันสำหรับตัวแทน
Changes
Change คือการแก้ไขที่เสนอให้กับระบบของคุณ บรรจุในรูปแบบโฟลเดอร์ที่มีทุกสิ่งที่จำเป็นเพื่อเข้าใจและนำไปใช้
โครงสร้าง Change
openspec/changes/add-dark-mode/
├── proposal.md # ทำไมและอะไร
├── design.md # อย่างไร (แนวทางทางเทคนิค)
├── tasks.md # รายการตรวจสอบการใช้งาน
├── .openspec.yaml # ข้อมูลเมตาของ Change (ไม่บังคับ)
└── specs/ # สเปคข้อมูลต่าง
└── ui/
└── spec.md # สิ่งที่กำลังเปลี่ยนแปลงใน ui/spec.mdChange แต่ละรายการเป็นอิสระ มันมี:
- ไฟล์ประกอบ — เอกสารที่บันทึกเจตนา การออกแบบ และงาน
- สเปคข้อมูลต่าง — ข้อกำหนดสำหรับสิ่งที่กำลังถูกเพิ่ม แก้ไข หรือลบ
- ข้อมูลเมตา — การกำหนดค่าที่ไม่บังคับสำหรับ change นี้โดยเฉพาะ
ทำไม Changes ถึงเป็นโฟลเดอร์
การบรรจุ change เป็นโฟลเดอร์มีประโยชน์หลายประการ:
ทุกอย่างอยู่ด้วยกัน ข้อเสนอ การออกแบบ งาน และ specs อยู่ในที่เดียว ไม่ต้องค้นหาในตำแหน่งต่างๆ
การทำงานแบบคู่ขนาน Change หลายรายการสามารถอยู่ร่วมกันได้โดยไม่ขัดแย้ง ทำงานกับ
add-dark-modeในขณะที่fix-auth-bugก็กำลังดำเนินการอยู่ประวัติที่สะอาด เมื่อเก็บถาวร change จะย้ายไปที่
changes/archive/พร้อมบริบทที่สมบูรณ์ คุณสามารถย้อนกลับและเข้าใจไม่เพียงว่ามีอะไรเปลี่ยนแปลง แต่ทำไมเป็นมิตรกับการตรวจสอบ โฟลเดอร์ change ตรวจสอบได้ง่าย — เปิดมัน อ่านข้อเสนอ ตรวจสอบการออกแบบ ดูสเปคข้อมูลต่าง
ไฟล์ประกอบ
ไฟล์ประกอบคือเอกสารภายใน change ที่ชี้นำงาน
กระแสไฟล์ประกอบ
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
ทำไม อะไร อย่างไร ขั้นตอน
+ ขอบเขต การเปลี่ยนแปลง แนวทาง ที่จะทำไฟล์ประกอบสร้างขึ้นบนกันและกัน ไฟล์ประกอบแต่ละตัวให้บริบทสำหรับถัดไป
ประเภทไฟล์ประกอบ
ข้อเสนอ (proposal.md)
ข้อเสนอบันทึก เจตนา ขอบเขต และ แนวทาง ในระดับสูง
markdown
# ข้อเสนอ: เพิ่มโหมดมืด
## เจตนา
ผู้ใช้ได้ร้องขอตัวเลือกโหมดมืดเพื่อลดอาการปวดตา
ในช่วงเวลาใช้งานตอนกลางคืนและให้เข้ากับค่าตั้งต้นของระบบ
## ขอบเขต
อยู่ในขอบเขต:
- การสลับธีมในการตั้งค่า
- การตรวจจับค่าตั้งต้นของระบบ
- การเก็บรักษาค่าตั้งต้นใน localStorage
ไม่อยู่ในขอบเขต:
- ธีมสีที่กำหนดเอง (งานในอนาคต)
- การเขียนทับธีมต่อหน้า
## แนวทาง
ใช้ CSS custom properties สำหรับธีมโดยใช้ React context
สำหรับการจัดการสถานะ ตรวจจับค่าตั้งต้นของระบบเมื่อโหลดครั้งแรก
อนุญาตให้เขียนทับด้วยตนเองเมื่อใดควรอัปเดตข้อเสนอ:
- ขอบเขตเปลี่ยนแปลง (แคบลงหรือขยายออก)
- เจตนาชัดเจนขึ้น (เข้าใจปัญหาได้ดีขึ้น)
- แนวทางเปลี่ยนแปลงอย่างมีนัยสำคัญ
สเปค (สเปคข้อมูลต่างใน specs/)
สเปคข้อมูลต่างอธิบาย สิ่งที่กำลังเปลี่ยนแปลง เมื่อเทียบกับสเปคปัจจุบัน ดู สเปคข้อมูลต่าง ด้านล่าง
การออกแบบ (design.md)
การออกแบบบันทึก แนวทางทางเทคนิค และ การตัดสินใจสถาปัตยกรรม
markdown
# การออกแบบ: เพิ่มโหมดมืด
## แนวทางทางเทคนิค
สถานะธีมจัดการผ่าน React Context เพื่อหลีกเลี่ยง prop drilling
CSS custom properties ช่วยให้สลับได้ในเวลาทำงานโดยไม่ต้องสลับคลาส
## การตัดสินใจทางสถาปัตยกรรม
### การตัดสินใจ: Context แทน Redux
ใช้ React Context สำหรับสถานะธีมเนื่องจาก:
- สถานะแบบง่ายสองสถานะ (สว่าง/มืด)
- ไม่มีการเปลี่ยนสถานะที่ซับซ้อน
- หลีกเลี่ยงการเพิ่ม dependency ของ Redux
### การตัดสินใจ: CSS Custom Properties
ใช้ CSS variables แทน CSS-in-JS เนื่องจาก:
- ทำงานร่วมกับ stylesheets ที่มีอยู่ได้
- ไม่มีค่าใช้จ่ายในการรันไทม์
- เป็นโซลูชันแบบ native ของเบราว์เซอร์
## การไหลของข้อมูล
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## การเปลี่ยนแปลงไฟล์
- `src/contexts/ThemeContext.tsx` (ใหม่)
- `src/components/ThemeToggle.tsx` (ใหม่)
- `src/styles/globals.css` (แก้ไข)เมื่อใดควรอัปเดตการออกแบบ:
- การนำไปใช้งานเปิดเผยว่าแนวทางนี้ไม่ได้ผล
- พบวิธีแก้ไขที่ดีกว่า
- ความต้องการหรือข้อจำกัดเปลี่ยนไป
งาน (tasks.md)
งานคือ รายการตรวจสอบการนำไปใช้งาน — ขั้นตอนที่เป็นรูปธรรมพร้อมช่องทำเครื่องหมาย
markdown
# งาน
## 1. โครงสร้างพื้นฐานของธีม
- [ ] 1.1 สร้าง ThemeContext พร้อมสถานะสว่าง/มืด
- [ ] 1.2 เพิ่ม CSS custom properties สำหรับสี
- [ ] 1.3 ใช้งาน localStorage persistence
- [ ] 1.4 เพิ่มการตรวจจับความต้องการของระบบ
## 2. องค์ประกอบ UI
- [ ] 2.1 สร้างองค์ประกอบ ThemeToggle
- [ ] 2.2 เพิ่มสวิตช์ไปยังหน้าตั้งค่า
- [ ] 2.3 อัปเดต Header เพื่อรวมสวิตช์ด่วน
## 3. การจัดรูปแบบ
- [ ] 3.1 กำหนดจานสีธีมมืด
- [ ] 3.2 อัปเดตองค์ประกอบให้ใช้ CSS variables
- [ ] 3.3 ทดสอบอัตราส่วนความคมชัดสำหรับการเข้าถึงแนวทางปฏิบัติที่ดีสำหรับงาน:
- จัดกลุ่มงานที่เกี่ยวข้องกันภายใต้หัวข้อ
- ใช้หมายเลขลำดับชั้น (1.1, 1.2 ฯลฯ)
- รักษาขนาดงานให้เล็กพอที่จะทำให้เสร็จในเซสชันเดียว
- ทำเครื่องหมายในช่องเมื่อคุณทำเสร็จ
Delta Specs
Delta specs เป็นแนวคิดหลักที่ทำให้ OpenSpec ทำงานได้สำหรับการพัฒนา brownfield พวกเขาอธิบาย สิ่งที่กำลังเปลี่ยนแปลง แทนที่จะระบุ spec ทั้งหมดใหม่
รูปแบบ
markdown
# Delta สำหรับ Auth
## ข้อกำหนดที่เพิ่มเข้ามา
### ข้อกำหนด: การยืนยันตัวตนแบบสองปัจจัย
ระบบต้องรองรับการยืนยันตัวตนแบบสองปัจจัยที่ใช้ TOTP
#### สถานการณ์: การลงทะเบียน 2FA
- GIVEN ผู้ใช้ที่ไม่ได้เปิดใช้งาน 2FA
- WHEN ผู้ใช้เปิดใช้งาน 2FA ในการตั้งค่า
- THEN แสดง QR code สำหรับการตั้งค่าแอปยืนยันตัวตน
- AND ผู้ใช้ต้องยืนยันด้วยรหัสก่อนเปิดใช้งาน
#### สถานการณ์: การเข้าสู่ระบบ 2FA
- GIVEN ผู้ใช้ที่เปิดใช้งาน 2FA
- WHEN ผู้ใช้ส่งข้อมูลรับรองที่ถูกต้อง
- THEN แสดง OTP challenge
- AND การเข้าสู่ระบบจะเสร็จสมบูรณ์เฉพาะหลังจากได้รับ OTP ที่ถูกต้อง
## ข้อกำหนดที่แก้ไข
### ข้อกำหนด: หมดอายุเซสชัน
ระบบต้องให้เซสชันหมดอายุหลังจากไม่มีกิจกรรม 15 นาที
(ก่อนหน้านี้: 30 นาที)
#### สถานการณ์: หมดเวลาว่าง
- GIVEN เซสชันที่ยืนยันตัวตนแล้ว
- WHEN ผ่านไป 15 นาทีโดยไม่มีกิจกรรม
- THEN เซสชันจะถูกยกเลิก
## ข้อกำหนดที่ลบออก
### ข้อกำหนด: จดจำฉัน
(เลิกใช้แล้วแทนที่ด้วย 2FA ผู้ใช้ควรยืนยันตัวตนใหม่ในทุกเซสชัน)ส่วนของ Delta
| ส่วน | ความหมาย | สิ่งที่เกิดขึ้นเมื่อเก็บถาวร |
|---|---|---|
## ข้อกำหนดที่เพิ่มเข้ามา | พฤติกรรมใหม่ | เพิ่มเข้าไปใน spec หลัก |
## ข้อกำหนดที่แก้ไข | พฤติกรรมที่เปลี่ยนแปลง | แทนที่ข้อกำหนดที่มีอยู่ |
## ข้อกำหนดที่ลบออก | พฤติกรรมที่เลิกใช้ | ลบออกจาก spec หลัก |
ทำไมต้องใช้ Delta แทน Full Specs
ความชัดเจน Delta แสดงให้เห็นอย่างชัดเจนว่ามีการเปลี่ยนแปลงอะไรบ้าง การอ่าน spec ทั้งหมด คุณจะต้องเปรียบเทียบในใจกับเวอร์ชันปัจจุบัน
การหลีกเลี่ยงความขัดแย้ง การเปลี่ยนแปลงสองอย่างสามารถสัมผัสไฟล์ spec เดียวกันได้โดยไม่ขัดแย้งกัน ตราบใดที่พวกเขาแก้ไขข้อกำหนดที่แตกต่างกัน
ประสิทธิภาพการตรวจสอบ ผู้ตรวจสอบจะเห็นการเปลี่ยนแปลง ไม่ใช่บริบทที่ไม่ได้เปลี่ยนแปลง มุ่งเน้นไปที่สิ่งที่สำคัญ
ความเหมาะสมกับ Brownfield งานส่วนใหญ่จะแก้ไขพฤติกรรมที่มีอยู่ Delta ทำให้การแก้ไขเป็นสิ่งสำคัญ ไม่ใช่เป็นเพียงสิ่งที่ตามมา
Schemas
Schemas กำหนดประเภทของ artifact และความเชื่อมโยงของพวกเขาสำหรับเวิร์กโฟลว์
วิธีการทำงานของ Schemas
yaml
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # ไม่มีความเชื่อมโยง สามารถสร้างได้ก่อน
- id: specs
generates: specs/**/*.md
requires: [proposal] # ต้องการ proposal ก่อนสร้าง
- id: design
generates: design.md
requires: [proposal] # สามารถสร้างพร้อมกับ specs ได้
- id: tasks
generates: tasks.md
requires: [specs, design] # ต้องการทั้ง specs และ design ก่อนArtifacts สร้างแผนผังความเชื่อมโยง:
proposal
(โหนดราก)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(ต้องการ: (ต้องการ:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(ต้องการ:
specs, design)ความเชื่อมโยงเป็นตัวอำนวยความสะดวก ไม่ใช่ประตูกั้น พวกเขาแสดงสิ่งที่สามารถสร้างได้ ไม่ใช่สิ่งที่คุณต้องสร้างต่อไป คุณสามารถข้าม design ได้หากคุณไม่ต้องการ คุณสามารถสร้าง specs ก่อนหรือหลัง design — ทั้งคู่ขึ้นอยู่กับ proposal เท่านั้น
Schemas ที่มีอยู่แล้ว
spec-driven (ค่าเริ่มต้น)
เวิร์กโฟลว์มาตรฐานสำหรับการพัฒนาแบบ spec-driven:
proposal → specs → design → tasks → implementเหมาะสำหรับ: งานฟีเจอร์ส่วนใหญ่ที่คุณต้องการตกลงเกี่ยวกับ specs ก่อนการนำไปใช้งาน
Schemas ที่กำหนดเอง
สร้าง schemas ที่กำหนดเองสำหรับเวิร์กโฟลว์ของทีมคุณ:
bash
# สร้างจากศูนย์
openspec schema init research-first
# หรือ fork จากที่มีอยู่
openspec schema fork spec-driven research-firstตัวอย่าง schema ที่กำหนดเอง:
yaml
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # ทำวิจัยก่อน
- id: proposal
generates: proposal.md
requires: [research] # Proposal ได้รับข้อมูลจากงานวิจัย
- id: tasks
generates: tasks.md
requires: [proposal] # ข้าม specs/design ไปที่ tasks โดยตรงดู การปรับแต่ง สำหรับรายละเอียดทั้งหมดเกี่ยวกับการสร้างและใช้งาน schemas ที่กำหนดเอง
การเก็บถาวร
การเก็บถาวรจะทำให้การเปลี่ยนแปลงเสร็จสมบูรณ์โดยการรวม delta specs เข้ากับ specs หลักและเก็บรักษาการเปลี่ยนแปลงไว้สำหรับประวัติศาสตร์
สิ่งที่เกิดขึ้นเมื่อคุณเก็บถาวร
ก่อนเก็บถาวร:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ รวม
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
หลังเก็บถาวร:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # ตอนนี้รวมข้อกำหนด 2FA แล้ว
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # เก็บรักษาไว้สำหรับประวัติศาสตร์
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdกระบวนการเก็บถาวร
รวม deltas ส่วนของ delta spec แต่ละส่วน (ADDED/MODIFIED/REMOVED) จะถูกนำไปใช้กับ spec หลักที่สอดคล้องกัน
ย้ายไปเก็บถาวร โฟลเดอร์การเปลี่ยนแปลงจะย้ายไปที่
changes/archive/พร้อมคำนำหน้าวันที่สำหรับการจัดเรียงตามลำดับเวลารักษาบริบท Artifacts ทั้งหมดยังคงอยู่ครบถ้วนในที่เก็บถาวร คุณสามารถย้อนกลับไปดูเพื่อเข้าใจว่าทำไมการเปลี่ยนแปลงจึงเกิดขึ้น
ทำไมการเก็บถาวรจึงสำคัญ
สถานะที่สะอาด การเปลี่ยนแปลงที่ใช้งานอยู่ (changes/) แสดงเฉพาะงานที่กำลังดำเนินการ งานที่เสร็จสมบูรณ์จะย้ายออกไป
ร่องรอยการตรวจสอบ ที่เก็บถาวรเก็บรักษาบริบททั้งหมดของการเปลี่ยนแปลงทุกครั้ง — ไม่ใช่แค่สิ่งที่เปลี่ยนแปลง แต่รวมถึง proposal ที่อธิบายว่าทำไม, design ที่อธิบายว่าอย่างไร และ tasks ที่แสดงงานที่ทำเสร็จแล้ว
วิวัฒนาการของ Spec Specs เติบโตอย่างเป็นธรรมชาติเมื่อมีการเก็บถาวรการเปลี่ยนแปลง การเก็บถาวรแต่ละครั้งจะรวม deltas ของมัน สร้าง spec ที่ครอบคลุมขึ้นเรื่อยๆ ตามกาลเวลา
วิธีที่ทุกอย่างเชื่อมต่อกัน
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC FLOW │
│ │
│ ┌────────────────┐ │
│ │ 1. เริ่มต้น │ /opsx:propose (core) หรือ /opsx:new (expanded) │
│ │ การเปลี่ยนแปลง│ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. สร้าง │ /opsx:ff หรือ /opsx:continue (expanded workflow) │
│ │ Artifacts │ สร้าง proposal → specs → design → tasks │
│ │ │ (ตามความเชื่อมโยงของ schema) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. นำไปใช้ │ /opsx:apply │
│ │ งาน │ ทำตาม tasks ทีละขั้นตอน ทำเครื่องหมายเมื่อเสร็จ │
│ │ │◄──── อัปเดต artifacts ตามที่คุณเรียนรู้ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. ตรวจสอบ │ /opsx:verify (ไม่บังคับ) │
│ │ งาน │ ตรวจสอบว่าการนำไปใช้งานตรงกับ specs │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. เก็บถาวร │────►│ Delta specs รวมเข้ากับ specs หลัก │ │
│ │ การเปลี่ยนแปลง│ │ โฟลเดอร์การเปลี่ยนแปลงย้ายไป archive/ │ │
│ └────────────────┘ │ Specs ตอนนี้เป็นแหล่งข้อมูลที่อัปเดตแล้ว │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘วงจรแห่งความดี:
- Specs อธิบายพฤติกรรมปัจจุบัน
- การเปลี่ยนแปลงเสนอการแก้ไข (ในรูปแบบ deltas)
- การนำไปใช้งานทำให้การเปลี่ยนแปลงเป็นจริง
- การเก็บถาวรรวม deltas เข้ากับ specs
- Specs ตอนนี้อธิบายพฤติกรรมใหม่
- การเปลี่ยนแปลงถัดไปสร้างบน specs ที่อัปเดตแล้ว
คำศัพท์
| คำศัพท์ | คำจำกัดความ |
|---|---|
| Artifact | เอกสารภายในชุดการเปลี่ยนแปลง (ข้อเสนอ, แบบแปลน, งาน หรือสเปกชุดย่อย) |
| Archive | กระบวนการเสร็จสิ้นการเปลี่ยนแปลงและรวมสเปกชุดย่อยเข้ากับสเปกหลัก |
| Change | การแก้ไขที่เสนอต่อระบบ จัดอยู่ในรูปแบบโฟลเดอร์ที่มีเอกสารประกอบ |
| Delta spec | สเปกที่อธิบายการเปลี่ยนแปลง (เพิ่ม/แก้ไข/ลบ) เมื่อเทียบกับสเปกปัจจุบัน |
| Domain | การจัดกลุ่มเชิงตรรกะสำหรับสเปก (เช่น auth/, payments/) |
| Requirement | พฤติกรรมเฉพาะที่ระบบต้องมี |
| Scenario | ตัวอย่างที่เป็นรูปธรรมของข้อกำหนด มักอยู่ในรูปแบบ Given/When/Then |
| Schema | คำจำกัดความของประเภทเอกสารและความเชื่อมโยงระหว่างกัน |
| Spec | ข้อกำหนดที่อธิบายพฤติกรรมของระบบ ประกอบด้วยข้อกำหนดและสถานการณ์ |
| Source of truth | ไดเรกทอรี openspec/specs/ ที่มีพฤติกรรมที่ตกลงร่วมกันในปัจจุบัน |
ขั้นตอนถัดไป
- เริ่มต้นใช้งาน - ขั้นตอนแรกที่เป็นประโยชน์
- เวิร์กโฟลว์ - รูปแบบทั่วไปและเวลาที่ควรใช้แต่ละแบบ
- คำสั่ง - คำอ้างอิงคำสั่งฉบับเต็ม
- การปรับแต่ง - สร้างสคีมาที่กำหนดเองและกำหนดค่าโปรเจกต์ของคุณ