เริ่มต้นใช้งาน

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

วิธีการทำงาน

OpenSpec ช่วยให้คุณและ AI ผู้ช่วยเขียนโค้ดตกลงในสิ่งที่จะสร้างก่อนที่จะเริ่มเขียนโค้ดใดๆ

เส้นทางเริ่มต้นแบบรวดเร็ว (โปรไฟล์หลัก):

/opsx:propose ──► /opsx:apply ──► /opsx:archive

เส้นทางที่ขยาย (เลือกเวิร์กโฟลว์แบบกำหนดเอง):

/opsx:new ──► /opsx:ff หรือ /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

โปรไฟล์ระดับโลกเริ่มต้นคือ core ซึ่งรวมถึง propose, explore, apply และ archive คุณสามารถเปิดใช้งานคำสั่งเวิร์กโฟลว์ที่ขยายได้ด้วย openspec config profile แล้วตามด้วย openspec update

สิ่งที่ OpenSpec สร้างขึ้น

หลังจากเรียกใช้ openspec init โปรเจกต์ของคุณจะมีโครงสร้างดังนี้:

openspec/
├── specs/              # แหล่งข้อมูลที่เชื่อถือได้ (พฤติกรรมของระบบของคุณ)
│   └── <domain>/
│       └── spec.md
├── changes/            # การอัปเดตที่เสนอ (หนึ่งโฟลเดอร์ต่อการเปลี่ยนแปลง)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta specs (สิ่งที่กำลังเปลี่ยนแปลง)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # การกำหนดค่าโปรเจกต์ (ไม่บังคับ)

สองโฟลเดอร์หลัก:

• specs/ - แหล่งข้อมูลที่เชื่อถือได้ สเปกเหล่านี้อธิบายว่าระบบของคุณทำงานอย่างไรในปัจจุบัน จัดเรียงตามโดเมน (เช่น specs/auth/, specs/payments/)

• changes/ - การแก้ไขที่เสนอ การเปลี่ยนแปลงแต่ละครั้งจะได้รับโฟลเดอร์ของตัวเองพร้อมกับสิ่งที่เกี่ยวข้องทั้งหมด เมื่อการเปลี่ยนแปลงเสร็จสมบูรณ์ สเปกของมันจะถูกรวมเข้ากับโฟลเดอร์ specs/ หลัก

การเข้าใจ Artifacts

โฟลเดอร์การเปลี่ยนแปลงแต่ละโฟลเดอร์มี artifacts ที่แนะนำการทำงาน:

Artifact	วัตถุประสงค์
proposal.md	"ทำไม" และ "อะไร" - บันทึกเจตนา ขอบเขต และวิธีการ
specs/	Delta specs แสดงข้อกำหนดที่เพิ่ม/แก้ไข/ลบ
design.md	"อย่างไร" - วิธีการทางเทคนิคและการตัดสินใจสถาปัตยกรรม
tasks.md	รายการตรวจสอบการนำไปใช้งานพร้อมช่องทำเครื่องหมาย

Artifacts สร้างต่อยอดกัน:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            อัปเดตเมื่อเรียนรู้

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

วิธีการทำงานของ Delta Specs

Delta specs เป็นแนวคิดหลักใน OpenSpec แสดงสิ่งที่กำลังเปลี่ยนแปลงเมื่อเทียบกับสเปกปัจจุบันของคุณ

รูปแบบ

Delta specs ใช้ส่วนต่างๆ เพื่อระบุประเภทของการเปลี่ยนแปลง:

# Delta สำหรับ Auth

## ข้อกำหนดที่เพิ่ม

### ข้อกำหนด: การยืนยันตัวตนสองปัจจัย
ระบบต้องกำหนดให้มีปัจจัยที่สองระหว่างการเข้าสู่ระบบ

#### สถานการณ์: ต้องใช้ OTP
- GIVEN ผู้ใช้ที่เปิดใช้งาน 2FA
- WHEN ผู้ใช้ส่งข้อมูลรับรองที่ถูกต้อง
- THEN จะแสดง OTP challenge

## ข้อกำหนดที่แก้ไข

### ข้อกำหนด: หมดเวลาเซสชัน
ระบบจะหมดอายุเซสชันหลังจากไม่มีกิจกรรม 30 นาที
(ก่อนหน้า: 60 นาที)

#### สถานการณ์: หมดเวลาเนื่องจากไม่มีกิจกรรม
- GIVEN เซสชันที่ยืนยันตัวตนแล้ว
- WHEN ผ่านไป 30 นาทีโดยไม่มีกิจกรรม
- THEN เซสชันจะถูกยกเลิก

## ข้อกำหนดที่ลบ

### ข้อกำหนด: จดจำฉัน
(เลิกใช้แล้วแทนที่ด้วย 2FA)

สิ่งที่เกิดขึ้นเมื่อเก็บถาวร

เมื่อคุณเก็บถาวรการเปลี่ยนแปลง:

1. ข้อกำหนดที่ เพิ่ม จะถูกเพิ่มต่อท้ายสเปกหลัก
2. ข้อกำหนดที่ แก้ไข จะแทนที่เวอร์ชันที่มีอยู่
3. ข้อกำหนดที่ ลบ จะถูกลบออกจากสเปกหลัก

โฟลเดอร์การเปลี่ยนแปลงจะย้ายไปที่ openspec/changes/archive/ เพื่อเก็บประวัติการตรวจสอบ

ตัวอย่าง: การเปลี่ยนแปลงครั้งแรกของคุณ

เรามาดูตัวอย่างการเพิ่มโหมดมืดให้กับแอปพลิเคชัน

1. เริ่มการเปลี่ยนแปลง (ค่าเริ่มต้น)

คุณ: /opsx:propose add-dark-mode

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

หากคุณได้เปิดใช้งานโปรไฟล์เวิร์กโฟลว์ที่ขยาย คุณยังสามารถทำได้เป็นสองขั้นตอน: /opsx:new แล้วตามด้วย /opsx:ff (หรือ /opsx:continue ทีละส่วน)

2. สิ่งที่ถูกสร้างขึ้น

proposal.md - บันทึกเจตนา:

## เจตนา
ผู้ใช้ร้องขอตัวเลือกโหมดมืดเพื่อลดอาการปวดตา
ระหว่างการใช้งานในช่วงกลางคืน

## ขอบเขต
- เพิ่มปุ่มสลับธีมในการตั้งค่า
- รองรับการตรวจจับค่าที่ต้องการของระบบ
- เก็บค่าที่ต้องการไว้ใน localStorage

## วิธีการ
ใช้ CSS custom properties สำหรับธีมด้วย React context
สำหรับการจัดการสถานะ

specs/ui/spec.md - Delta แสดงข้อกำหนดใหม่:

# Delta สำหรับ UI

## ข้อกำหนดที่เพิ่ม

### ข้อกำหนด: การเลือกธีม
ระบบจะอนุญาตให้ผู้ใช้เลือกระหว่างธีมสว่างและมืด

#### สถานการณ์: สลับด้วยตนเอง
- GIVEN ผู้ใช้บนหน้าใดก็ได้
- WHEN ผู้ใช้คลิกปุ่มสลับธีม
- THEN ธีมจะสลับทันที
- AND ค่าที่ต้องการจะคงอยู่ข้ามเซสชัน

#### สถานการณ์: ค่าที่ต้องการของระบบ
- GIVEN ผู้ใช้ที่ไม่มีค่าที่ต้องการที่บันทึกไว้
- WHEN แอปพลิเคชันโหลด
- THEN จะใช้โทนสีที่ระบบต้องการ

tasks.md - รายการตรวจสอบการนำไปใช้งาน:

# งาน

## 1. โครงสร้างพื้นฐานของธีม
- [ ] 1.1 สร้าง ThemeContext พร้อมสถานะสว่าง/มืด
- [ ] 1.2 เพิ่ม CSS custom properties สำหรับสี
- [ ] 1.3 ใช้งาน localStorage persistence

## 2. คอมโพเนนต์ UI
- [ ] 2.1 สร้างคอมโพเนนต์ ThemeToggle
- [ ] 2.2 เพิ่มปุ่มสลับไปยังหน้าตั้งค่า
- [ ] 2.3 อัปเดต Header เพื่อรวมปุ่มสลับด่วน

## 3. การจัดรูปแบบ
- [ ] 3.1 กำหนดจานสีธีมมืด
- [ ] 3.2 อัปเดตคอมโพเนนต์ให้ใช้ CSS variables

3. นำไปใช้งาน

คุณ: /opsx:apply

AI:  กำลังทำงานผ่านงานต่างๆ...
     ✓ 1.1 สร้าง ThemeContext พร้อมสถานะสว่าง/มืด
     ✓ 1.2 เพิ่ม CSS custom properties ไปยัง globals.css
     ✓ 1.3 ใช้งาน localStorage persistence
     ✓ 2.1 สร้างคอมโพเนนต์ ThemeToggle
     ...
     งานทั้งหมดเสร็จสมบูรณ์!

ระหว่างการนำไปใช้งาน หากคุณพบว่าการออกแบบต้องปรับแต่ง ให้อัปเดต artifact แล้วดำเนินการต่อ

4. เก็บถาวร

คุณ: /opsx:archive

AI:  กำลังเก็บถาวร add-dark-mode...
     ✓ รวมสเปกเข้ากับ openspec/specs/ui/spec.md
     ✓ ย้ายไปที่ openspec/changes/archive/2025-01-24-add-dark-mode/
     เสร็จแล้ว! พร้อมสำหรับฟีเจอร์ถัดไป

Delta specs ของคุณตอนนี้เป็นส่วนหนึ่งของสเปกหลัก บันทึกวิธีการทำงานของระบบของคุณ

การตรวจสอบและทบทวน

ใช้ CLI เพื่อตรวจสอบการเปลี่ยนแปลงของคุณ:

# แสดงรายการการเปลี่ยนแปลงที่ใช้งานอยู่
openspec list

# แสดงรายละเอียดการเปลี่ยนแปลง
openspec show add-dark-mode

# ตรวจสอบรูปแบบสเปก
openspec validate add-dark-mode

# แดชบอร์ดแบบโต้ตอบ
openspec view

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

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