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

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

ฉันพิมพ์คำสั่งเหล่านี้ที่ไหน? มีสองที่ และการสลับที่กันคือข้อผิดพลาดที่พบบ่อยที่สุดในช่วงต้น

• คำสั่ง openspec ... (เช่น openspec init) รันใน เทอร์มินัล ของคุณ
• คำสั่ง /opsx:... (เช่น /opsx:propose) รันใน แชทของ AI assistant ซึ่งก็คือกล่องสนทนาเดียวกับที่คุณใช้ขอให้เขียนโค้ด

ไม่มี "โหมดโต้ตอบ" แยกต่างหากให้เริ่ม เพียงพิมพ์คำสั่ง slash ในแชท แล้วผู้ช่วยของคุณจะจัดการต่อจากนั้น คำอธิบายเต็ม: How Commands Work

ห้านาทีแรกของคุณ

วงจรทั้งหมด พร้อมป้ายบอกว่าแต่ละขั้นตอนเกิดขึ้นที่ไหน:

เทอร์มินัล   $ npm install -g @fission-ai/openspec@latest
เทอร์มินัล   $ cd your-project && openspec init
แชท AI      /opsx:explore                    (ไม่บังคับ: คิดให้ดีก่อน)
แชท AI      /opsx:propose add-dark-mode      (AI ร่างแผน; คุณตรวจสอบ)
แชท AI      /opsx:apply                      (AI สร้างโค้ด)
แชท AI      /opsx:archive                    (specs อัปเดต, เก็บการเปลี่ยนแปลง)

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

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

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

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

OpenSpec ช่วยให้คุณและ AI coding assistant ของคุณตกลงกันได้ว่าจะสร้างอะไรก่อนจะเขียนโค้ดใดๆ

เส้นทางด่วนค่าเริ่มต้น (core profile):

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (ไม่บังคับ)

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

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

/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

โพรไฟล์ส่วนกลางเริ่มต้นคือ core ซึ่งรวม propose, explore, apply, update, sync, และ 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/ - แหล่งความจริง (source of truth) สเปคเหล่านี้อธิบายว่าระบบของคุณทำงานอย่างไรในปัจจุบัน จัดกลุ่มตามโดเมน (เช่น specs/auth/, specs/payments/)

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

ทำความเข้าใจอาร์ติแฟกต์

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

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

อาร์ติแฟกต์ต่อยอดซึ่งกันและกัน:

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

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

การทำงานของ Delta Specs

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

รูปแบบ

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

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

เกิดอะไรขึ้นเมื่อ Archive

เมื่อคุณ archive การเปลี่ยนแปลง:

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

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

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

มาลองเพิ่ม dark mode ให้กับแอปพลิเคชันกัน

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

You: /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 - จับเจตนา:

# ข้อเสนอ: เพิ่ม Dark Mode

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

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

## แนวทาง
ใช้ CSS custom properties สำหรับธีมร่วมกับ React context
สำหรับการจัดการสถานะ (state management)

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

# Delta สำหรับ UI

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

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

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

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

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

# งาน

## 1. โครงสร้างพื้นฐานของธีม
- [ ] 1.1 สร้าง ThemeContext พร้อม state light/dark
- [ ] 1.2 เพิ่ม CSS custom properties สำหรับสี
- [ ] 1.3 ทำให้เก็บข้อมูลถาวรใน localStorage

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

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

3. นำไปใช้

You: /opsx:apply

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

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

4. จัดเก็บ (Archive)

You: /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

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

• สำรวจก่อน - ใช้ /opsx:explore เพื่อคิดไอเดียให้ถี่ถ้วนก่อนลงมือทำ
• การทบทวนการเปลี่ยนแปลง - สิ่งที่ควรตรวจสอบในแผนที่ AI ร่าง ก่อนมีโค้ดใดๆ
• การเขียนสเปคที่ดี - ข้อกำหนดและสถานการณ์ที่แข็งแกร่งควรเป็นอย่างไร
• การใช้งาน OpenSpec ในโปรเจกต์ที่มีอยู่แล้ว - เริ่มต้นกับโค้ดเบสขนาดใหญ่แบบ brownfield
• การแก้ไขและวนซ้ำการเปลี่ยนแปลง - อัปเดตอาร์ติแฟกต์ ย้อนกลับ ปรับแก้ไขด้วยตนเองให้สอดคล้อง
• แนวคิดหลักโดยสังเขป - โมเดลทางความคิดทั้งหมดในหน้าเดียว
• ตัวอย่างและเทคนิค - การเปลี่ยนแปลงจริง ตั้งแต่ต้นจนจบ
• เวิร์กโฟลว์ - รูปแบบที่พบบ่อย และเมื่อใดควรใช้แต่ละคำสั่ง
• คำสั่ง - คู่มืออ้างอิงทั้งหมดของคำสั่ง slash
• แนวคิด - ความเข้าใจเชิงลึกเกี่ยวกับสเปค การเปลี่ยนแปลง และสกีมา
• การปรับแต่ง - ทำให้ OpenSpec ทำงานในแบบของคุณ
• Stores - การวางแผนที่ครอบคลุมหลาย repo หรือทีม? เก็บมันไว้ใน repo ของตัวเอง (เบต้า)
• คำถามที่พบบ่อย และ การแก้ไขปัญหา - เมื่อคุณติดขัด