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

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

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

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

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

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

ลูปทั้งหมด โดยระบุขั้นตอนด้วยสถานที่ที่ดำเนินการ:

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

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

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

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

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

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

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (ทางเลือก)

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

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

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

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

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

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

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

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

อาร์ติแฟกต์สร้างบนกัน:

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

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

Delta Specs ทำงานอย่างไร

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

รูปแบบ

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

# Delta สำหรับ Auth

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

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

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

## ข้อกำหนดที่ถูกแก้ไข (MODIFIED Requirements)

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

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

## ข้อกำหนดที่ถูกลบ (REMOVED Requirements)

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

เกิดอะไรขึ้นเมื่อทำการเก็บถาวร (Archive)

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

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

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

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

มาดูขั้นตอนการเพิ่ม dark mode ให้กับแอปพลิเคชันกัน

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 - บันทึกเจตนา:

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

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

## ขอบเขต
- เพิ่มสวิตช์ธีมในการตั้งค่า
- รองรับการตรวจจับการตั้งค่าระบบ
- บันทึกการตั้งค่าใน localStorage

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

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

# Delta สำหรับ UI

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

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

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

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

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

# งาน

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

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

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

3. นำไปใช้ (Implement)

คุณ: /opsx:apply

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

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

4. จัดเก็บถาวร (Archive)

คุณ: /opsx:archive

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

Delta specs ของคุณเป็นส่วนหนึ่งของ main specs ซึ่งบันทึกว่าระบบของคุณทำงานอย่างไร

การตรวจสอบและรีวิว

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

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

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

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

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

ขั้นตอนต่อไป

• Explore First - ใช้ /opsx:explore เพื่อคิดเกี่ยวกับแนวคิดก่อนที่คุณจะยืนยัน
• Using OpenSpec in an Existing Project - เริ่มต้นในโค้ดเบส brownfield ขนาดใหญ่
• Editing & Iterating on a Change - อัปเดตอาร์ติแฟกต์ ย้อนกลับ และกระทบยอดการแก้ไขด้วยตนเอง
• Core Concepts at a Glance - โมเดลความคิดทั้งหมดในหน้าเดียว
• Examples & Recipes - การเปลี่ยนแปลงจริง ตั้งแต่ต้นจนจบ
• Workflows - รูปแบบทั่วไปและเมื่อใดที่ควรใช้แต่ละคำสั่ง
• Commands - เอกสารอ้างอิงฉบับเต็มสำหรับทุกสแลชคอมมานด์
• Concepts - ความเข้าใจเชิงลึกเกี่ยวกับ specs, changes และ schemas
• Customization - ทำให้ OpenSpec ทำงานตามที่คุณต้องการ
• Stores - การวางแผนที่ครอบคลุมรีโพซิทอรีหรือทีม? เก็บไว้ในรีโพซิทอรีของตัวเอง (เบต้า)
• FAQ และ Troubleshooting - เมื่อคุณติดปัญหา