การแก้ไขปัญหา

การแก้ไขปัญหาที่ชัดเจนสำหรับปัญหาที่เกิดขึ้น แต่ละรายการจะระบุอาการ สาเหตุที่เป็นไปได้ในหนึ่งประโยค และให้วิธีแก้ไข หากคุณไม่พบปัญหาของคุณที่นี่ FAQ อาจช่วยได้ และ Discord จะช่วยได้อย่างแน่นอน

การติดตั้งและการตั้งค่า

openspec: command not found

CLI ยังไม่ได้ถูกติดตั้ง หรือเชลล์ (shell) ของคุณไม่สามารถค้นหาได้ ให้ทำการติดตั้งแบบ global และตรวจสอบ:

npm install -g @fission-ai/openspec@latest
openspec --version

หากติดตั้งแล้วแต่ยังพบปัญหาอยู่ แสดงว่าไดเรกทอรี npm bin แบบ global ของคุณอาจไม่ได้อยู่ใน PATH ให้รัน npm bin -g เพื่อดูว่าไบนารีแบบ global อยู่ที่ไหน และตรวจสอบให้แน่ใจว่าเส้นทางนั้นอยู่ในโปรไฟล์เชลล์ของคุณ

"Requires Node.js 20.19.0 or higher"

OpenSpec ทำงานบน Node 20.19.0 ขึ้นไป ตรวจสอบเวอร์ชันของคุณและอัปเกรดหากจำเป็น:

node --version

หากคุณใช้ bun ในการติดตั้ง OpenSpec โปรดทราบว่า OpenSpec ยังคง ทำงาน บน Node ดังนั้นคุณจึงต้องมี Node 20.19.0+ อยู่ใน PATH ของคุณเสมอ ดู Installation

openspec init ไม่ได้ตั้งค่า AI tool ของฉัน

Init จะถามว่าจะตั้งค่าเครื่องมือใด หากคุณข้ามการตั้งค่าเครื่องมือของคุณหรือต้องการเพิ่มอีก ให้ลองรันใหม หรือใช้รูปแบบแบบไม่โต้ตอบ (non-interactive form):

openspec init --tools claude,cursor

รายการ ID เครื่องมือทั้งหมดอยู่ใน Supported Tools ใช้ --tools all สำหรับทุกอย่าง และ --tools none เพื่อข้ามการตั้งค่าเครื่องมือ

คำสั่งไม่ปรากฏขึ้น

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

1. คุณอาจจะอยู่ในตำแหน่งที่ไม่ถูกต้อง คำสั่งแบบสแลช (Slash commands) จะต้องใช้ในแชทของ AI assistant ของคุณ ไม่ใช่ในเทอร์มินัล หากคุณพิมพ์ /opsx:propose ลงในเชลล์ นั่นคือปัญหา ดู How Commands Work

2. สร้างไฟล์ขึ้นมาใหม่ จาก root project:

   openspec update

   สิ่งนี้จะเขียนทับ (rewrites) ไฟล์ skill และ command สำหรับเครื่องมือทุกตัวที่คุณได้ตั้งค่าไว้

3. รีสตาร์ท assistant ของคุณ เครื่องมือส่วนใหญ่จะสแกนหา skills และ commands เมื่อเริ่มต้นใช้งาน หน้าต่างใหม่มักจะทำเช่นนั้น

4. ยืนยันว่าไฟล์มีอยู่จริง สำหรับ Claude Code ให้ตรวจสอบว่า .claude/skills/ มีโฟลเดอร์ openspec-* อยู่หรือไม่ เครื่องมืออื่น ๆ จะใช้ไดเรกทอรีของตัวเอง ซึ่งระบุไว้ทั้งหมดใน Supported Tools

5. ยืนยันว่าคุณได้เริ่มต้นโปรเจกต์นี้แล้ว Skills ถูกเขียนขึ้นต่อโปรเจกต์ หากคุณ clone repo หรือสลับโฟลเดอร์ ให้รัน openspec init (หรือ openspec update) ที่นั่น

6. ยืนยันว่าเครื่องมือของคุณรองรับไฟล์คำสั่ง เครื่องมือบางตัว (Kimi CLI, Trae, ForgeCode, Mistral Vibe) จะไม่สร้างไฟล์คำสั่ง opsx-*; พวกเขาใช้การเรียกใช้งานแบบอิงตาม skill แทน รูปแบบจะแตกต่างกันไปในแต่ละเครื่องมือ: ดู Supported Tools และ How Commands Work

การทำงานกับความเปลี่ยนแปลง

"Change not found" (ไม่พบการเปลี่ยนแปลง)

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

openspec list                    # ดูการเปลี่ยนแปลงที่ใช้งานอยู่
/opsx:apply add-dark-mode        # ตั้งชื่อการเปลี่ยนแปลงในแชท

ให้ยืนยันด้วยว่าคุณอยู่ในไดเรกทอรีโปรเจกต์ที่ถูกต้อง

"No artifacts ready" (ไม่มีอาร์ติแฟกต์พร้อม)

อาร์ติแฟกต์แต่ละตัวจะถูกสร้างขึ้นแล้ว หรือกำลังรออยู่เพราะมี dependency ที่ค้างอยู่ ดูว่าอะไรกำลังบล็อก:

openspec status --change <name>

จากนั้นให้สร้าง dependency ที่ขาดหายไปก่อน จำลำดับไว้: proposal เปิดใช้งาน specs และ design; specs และ design ร่วมกันเปิดใช้งาน tasks

openspec validate รายงานคำเตือนหรือข้อผิดพลาด

Validation จะตรวจสอบ specs และการเปลี่ยนแปลงของคุณสำหรับปัญหาเชิงโครงสร้าง อ่านข้อความ: มันจะระบุไฟล์และปัญหา

openspec validate <name>           # ตรวจสอบรายการเดียว
openspec validate --all            # ตรวจสอบทั้งหมด
openspec validate --all --strict   # การตรวจสอบที่เข้มงวดขึ้น เหมาะสำหรับ CI

สาเหตุทั่วไปคือมีส่วนที่จำเป็นขาดหายไป (เช่น spec ที่ไม่มี scenario) หรือ delta header มีรูปแบบไม่ถูกต้อง แก้ไขไฟล์แล้วรันใหม ดู CLI reference สำหรับรูปแบบเอาต์พุต

AI สร้างอาร์ติแฟกต์ที่ไม่สมบูรณ์หรือผิดพลาด

AI ขาด้านบริบทที่เพียงพอ ตัวช่วยบางอย่างมีดังนี้:

• เพิ่มบริบทของโปรเจกต์ใน openspec/config.yaml เพื่อให้ stack และ convention ของคุณถูกฉีดเข้าไปในการร้องขอทุกครั้ง ดู Customization
• เพิ่ม rules: ต่ออาร์ติแฟกต์เพื่อเป็นแนวทางที่ใช้ได้กับ เช่น specs เท่านั้น
• ให้คำอธิบายโดยละเอียดมากขึ้นเมื่อคุณเสนอ
• ใช้ /opsx:continue ที่ขยายออกเพื่อสร้างอาร์ติแฟกต์ทีละตัวและตรวจสอบแต่ละรายการ แทนที่จะให้ /opsx:ff ทำทั้งหมดในครั้งเดียว

Archive ไม่เสร็จ หรือเตือนเกี่ยวกับงานที่ไม่สมบูรณ์

Archive จะไม่ บล็อก บนงานที่ไม่สมบูรณ์ แต่จะเตือนคุณ เนื่องจากโดยปกติแล้วการเก็บถาวรันหมายถึงงานนั้นเสร็จสิ้นแล้ว หากยังมีงานอยู่โดยเจตนา (คุณกำลังยื่นการเปลี่ยนแปลงบางส่วน) ให้ดำเนินการต่อ มิฉะนั้นให้ทำงานให้เสร็จก่อน Archive จะเสนอที่จะซิงค์ delta specs ของคุณเข้าสู่ main specs หากคุณยังไม่ได้ซิงค์ ให้ตอบว่าใช่ เว้นแต่จะมีเหตุผลที่ไม่ควรทำ

การตั้งค่า

config.yaml ของฉันไม่ถูกนำไปใช้

มีผู้ต้องสงสัยสามประการ:

1. ชื่อไฟล์ผิด ต้องเป็น openspec/config.yaml ไม่ใช่ .yml
2. YAML ไม่ถูกต้อง ให้รันผ่านตัวตรวจสอบ YAML ใด ๆ CLI ยังรายงานข้อผิดพลาดไวยากรณ์พร้อมหมายเลขบรรทัดด้วย
3. คุณคาดหวังให้มีการรีสตาร์ท คุณไม่จำเป็นต้องมี Config changes จะมีผลทันที

"Unknown artifact ID in rules: X" (ไม่พบ Artifact ID ใน rules: X)

คีย์ภายใต้ rules: ไม่ตรงกับอาร์ติแฟกต์ใด ๆ ใน schema ของคุณ สำหรับ default spec-driven schema ID ที่ถูกต้องคือ proposal, specs, design, tasks หากต้องการดู ID สำหรับ schema ใด ๆ ให้ใช้:

openspec schemas --json

"Context too large" (บริบทมีขนาดใหญ่เกินไป)

ฟิลด์ context: ถูกจำกัดไว้ที่ 50KB โดยเจตนา เนื่องจากมันถูกฉีดเข้าไปในการร้องขอทุกครั้ง สรุปเนื้อหา หรือลิงก์ออกไปยังเอกสารที่ยาวกว่าแทนการวางทั้งหมด บริบทที่กระชับยังให้ผลลัพธ์ที่ดีและเร็วขึ้นด้วย

"Schema not found" (ไม่พบ Schema)

ชื่อ schema ที่คุณอ้างถึงไม่มีอยู่ ให้แสดงรายการที่มีอยู่และตรวจสอบการสะกด:

openspec schemas                    # แสดงรายการ schema ที่มีอยู่
openspec schema which <name>        # ดูว่า schema ถูก resolve จากที่ใด
openspec schema init <name>         # สร้าง custom schema

ดู Customization

การย้ายจากเวิร์กโฟลว์เดิม (Legacy workflow)

"Legacy files detected in non-interactive mode" (ตรวจพบไฟล์เก่าในโหมดที่ไม่โต้ตอบ)

คุณอยู่ใน CI หรือเชลล์ที่ไม่โต้ตอบ และ OpenSpec พบไฟล์เก่าที่ต้องทำความสะอาดแต่ไม่สามารถแจ้งเตือนคุณได้ ให้อนุมัติโดยอัตโนมัติ:

openspec init --force

คำสั่งไม่ปรากฏขึ้นหลังจากย้ายแล้ว

รีสตาร์ท IDE ของคุณ Skills จะถูกตรวจพบเมื่อเริ่มต้นใช้งาน หากยังไม่ปรากฏ ให้รัน openspec update และตรวจสอบตำแหน่งไฟล์ใน Supported Tools

project.md เก่าของฉันไม่ได้ถูกย้าย (Migrate)

นั่นเป็นสิ่งที่ตั้งใจไว้ OpenSpec ไม่เคยลบ project.md โดยอัตโนมัติเพราะมันอาจบรรจุบริบทที่คุณเขียนไว้ ให้ย้ายส่วนที่มีประโยชน์ไปยัง context: ของ config.yaml แล้วลบไฟล์นั้นด้วยตัวเอง Migration Guide จะแนะนำกระบวนการนี้ รวมถึง prompt ที่คุณสามารถมอบให้ AI เพื่อทำการกลั่นกรองได้

ยังติดอยู่?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• จากเทอร์มินัลของคุณ: openspec feedback "what went wrong" จะเปิด issue ให้คุณ

เมื่อคุณรายงานปัญหา โปรดระบุเวอร์ชัน OpenSpec (openspec --version) เวอร์ชัน Node ของคุณ (node --version) เครื่องมือ AI และคำสั่งและเอาต์พุตที่แน่นอน การทำเช่นนี้จะช่วยให้การช่วยเหลือรวดเร็วยิ่งขึ้นมาก