OpenSpec

FAQ ​

คำตอบสั้น ๆ สำหรับคำถามที่คนถามบ่อยที่สุด หากคำถามของคุณเป็นประเภท "อะไรพัง" การแก้ปัญหา เป็นหน้าที่เหมาะสมกว่า หากต้องการนิยามศัพท์ ดูที่ พจนานุกรม

พื้นฐาน ​

OpenSpec คืออะไรในประโยคเดียว? ​

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

ทำไมฉันถึงต้องการสิ่งนี้? ​

เพราะ AI assistants มีความมั่นใจแม้เมื่อมันผิด เมื่อข้อกำหนดมีอยู่เพียงในแชท AI จะเติมช่องว่างด้วยการเดา และคุณจะรู้ก็ต่อเมื่อโค้ดถูกสร้างแล้ว OpenSpec ย้ายการตกลงไปก่อนหน้า ซึ่งการแก้ไขข้อผิดพลาดมีราคาถูกกว่า ดู Core Concepts at a Glance สำหรับเหตุผลทั้งหมด

ฉันจำเป็นต้องใช้กับทุกอย่างหรือไม่? ​

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

ใช้กับ codebase ใหญ่ที่มีอยู่แล้วได้ไหม หรือเฉพาะโปรเจกต์ใหม่? ​

Codebase ที่มีอยู่แล้วคือเป้าหมายหลัก OpenSpec เป็น brownfield-first: คุณไม่ต้องเขียนเอกสารทั้งแอปตั้งแต่ต้น คุณเขียน specs เฉพาะสิ่งที่แต่ละการเปลี่ยนแปลงแตะถึง และ specs จะเติมเต็มตามเวลาโดยรอบงานที่คุณทำจริง มีคู่มือเฉพาะ: Using OpenSpec in an Existing Project

ผูกกับ AI tool ตัวเดียวไหม? ​

ไม่ OpenSpec ทำงานกับ assistants 30+ ตัว รวมถึง Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex และอื่น ๆ รายการเต็มและรายละเอียดแต่ละเครื่องมืออยู่ใน Supported Tools

การรันคำสั่ง ​

พิมพ์ /opsx:propose ที่ไหน? ​

ในแชทของ AI assistant ของคุณ ไม่ใช่ใน terminal นี่คือจุดที่ทำให้สับสนบ่อยที่สุด จึงมีหน้าของตัวเอง: How Commands Work สรุปสั้น ๆ: openspec ... รันใน terminal, /opsx:... รันในแชท

จะ "เริ่ม interactive mode" ยังไง? ​

ไม่มีโหมดแยกที่ต้องเริ่ม คุณเปิด AI assistant ตามปกติแล้วพิมพ์ slash command ลงในแชทของมัน Slash command คือวิธีที่คุณ "เข้า" OpenSpec (ฟีเจอร์ terminal ที่ interactive จริง ๆ มีเพียง openspec view ซึ่งเป็น dashboard สำหรับดู specs และ changes) คำอธิบายเต็มอยู่ใน How Commands Work

พิมพ์ slash command แล้วไม่มีอะไรเกิดขึ้น ทำไม? ​

มีแนวโน้มสูงว่าคุณพิมพ์ใน terminal แทนที่จะเป็น AI chat, ใช้การสะกดที่เครื่องมือของคุณไม่รองรับ, หรือคำสั่งยังไม่ได้ติดตั้ง หากไฟล์หายไป — หรือคุณไม่เคยตั้งค่าเครื่องมือ — รัน openspec init; openspec update รีเฟรชเฉพาะไฟล์ที่มีอยู่แล้ว จากนั้นรีสตาร์ท assistant ของคุณแล้วใช้รูปแบบที่พิมพ์ใต้ "Getting started" — ดู How To Invoke Troubleshooting มี checklist เต็ม

ทำไม syntax เป็น /opsx:propose ในเครื่องมือหนึ่งและ /opsx-propose ในอีกเครื่องมือ? ​

แต่ละ AI tool แสดง custom commands ต่างกันเล็กน้อย และ OpenSpec เขียนตามวิธีที่เครื่องมือของคุณโหลดไฟล์ที่มันเขียน ไฟล์คำสั่งชื่อ opsx-propose.md พิมพ์เป็น /opsx-propose; ไฟล์ที่อยู่ใน commands/opsx/ พิมพ์เป็น /opsx:propose เครื่องมือที่ใช้ skills แทน commands ใช้ชื่อ skill — Codex ต้องใช้ $openspec-propose, Kimi Code ใช้ /skill:openspec-propose บรรทัด "Getting started" ของ openspec init พิมพ์รูปแบบที่ถูกต้องสำหรับเครื่องมือที่คุณเลือกแล้ว; ตารางเต็มอยู่ใน How To Invoke

ความแตกต่างระหว่าง skill กับ command คืออะไร? ​

ทั้งสองเป็นไฟล์ที่ OpenSpec เขียนเพื่อให้ assistant ของคุณรัน workflow ได้ Skills (.../skills/openspec-*/SKILL.md) เป็นมาตรฐานข้ามเครื่องมือที่ใหม่กว่า; commands (.../commands/opsx-*) เป็นไฟล์ slash แบบ per-tool ที่เก่ากว่า คุณไม่จำเป็นต้องเลือก เพียงพิมพ์ slash command แล้ว OpenSpec จะติดตั้งแบบที่เครื่องมือของคุณใช้

Workflow ​

ควรเริ่มจากไหนถ้าไม่แน่ใจว่าจะสร้างอะไร? ​

เริ่มจาก /opsx:explore เป็น thinking partner ที่ไม่มีความเสี่ยง อ่าน codebase ของคุณ วางตัวเลือก และเปลี่ยนปัญหาที่คลุมเครือให้เป็นแผนที่เป็นรูปธรรม ทั้งหมดก่อนมีการเปลี่ยนแปลงหรือโค้ดใด ๆ อยู่ใน default profile จึงพร้อมใช้เสมอ เมื่อแผนชัดเจน จะส่งต่อให้ /opsx:propose นี่คือนิสัยที่ดีที่สุดที่จะสร้าง เพราะมันหยุด AI ที่กระตือรือร้นจากการสร้างสิ่งที่ผิดอย่างมั่นใจ ดู Explore First

Flow ที่ง่ายที่สุดคืออะไร? ​

text
/opsx:explore (optional)   then   /opsx:propose <what you want>   then   /opsx:apply   then   /opsx:archive

Explore เพื่อคิดให้รอบคอบ, propose เพื่อร่างแผน, apply เพื่อสร้าง, archive เพื่อเก็บไว้ ข้าม explore ได้เมื่อคุณรู้ชัดเจนอยู่แล้วว่าต้องการอะไร

ความแตกต่างระหว่าง /opsx:propose กับ /opsx:new คืออะไร? ​

/opsx:propose เป็นคำสั่ง one-step โดยค่าเริ่มต้น: สร้าง change และร่าง planning artifacts ทั้งหมดในครั้งเดียว /opsx:new เป็นส่วนหนึ่งของชุดคำสั่งที่ขยาย เพิ่มเฉพาะการ scaffold change ว่างเปล่า แล้วให้คุณสร้าง artifacts ทีละชิ้นด้วย /opsx:continue (หรือทั้งหมดพร้อมกันด้วย /opsx:ff) ใช้ propose เว้นแต่คุณต้องการควบคุมทีละขั้น ดู Commands

core และ expanded profiles คืออะไร? ​

Profile กำหนดว่า slash commands ใดจะถูกติดตั้ง Core (ค่าเริ่มต้น) ให้ propose, explore, apply, update, sync, archive ชุด expanded เพิ่ม new, continue, ff, verify, bulk-archive, และ onboard สำหรับควบคุมละเอียดขึ้น สลับด้วย openspec config profile แล้ว apply ด้วย openspec update

จำเป็นต้องรัน /opsx:sync ไหม? ​

โดยทั่วไปไม่จำเป็น Sync รวม delta specs ของ change เข้ากับ specs หลักของคุณ และ /opsx:archive จะเสนอให้ทำแทนคุณ รัน sync ด้วยตนเองเฉพาะเมื่อต้องการให้ specs ถูกรวมก่อน archive เช่น ใน change ที่ใช้เวลานาน ดู Commands

จะแก้ไข proposal, spec, หรือ task หลังเริ่มแล้วอย่างไร? ​

แก้ไขไฟล์ได้เลย ทุก artifact เป็น Markdown ธรรมดาใน openspec/changes/<name>/ และไม่มี locked phase หรือ special edit mode แก้ไขด้วยตนเอง หรือขอให้ AI แก้ไข ("update the design to use a queue") แล้วดำเนินการต่อ AI จะทำงานจากเนื้อหาไฟล์ปัจจุบันเสมอ คู่มือเต็ม: Editing & Iterating on a Change

สามารถกลับไปเปลี่ยนแผนหลัง implement บางส่วนแล้วได้ไหม? ​

ได้ ทุกเมื่อ Workflow เป็นแบบยืดหยุ่น ดังนั้นการ review และแก้ไขไม่ใช่เฟสที่คุณถูกล็อกออก แก้ไข artifact แล้วดำเนินการต่อ หากต้องการตรวจสอบเชิงโครงสร้างว่าโค้ดยังตรงกับแผน รัน /opsx:verify ดู Editing & Iterating on a Change

แก้ไขโค้ดด้วยตนเองแล้ว จะ reconcile กับ spec ยังไง? ​

ทำให้สอดคล้องกันก่อน archive เพราะ archive ทำให้ specs ของคุณเป็น record of truth หากโค้ดถูกต้องแล้ว อัปเดต delta spec ให้ตรงกับสิ่งที่ส่งมอบ; หาก spec ถูกต้อง สร้างต่อจนโค้ดตรงกัน /opsx:verify จะแสดงจุดที่ไม่ตรงกัน ดู Editing & Iterating on a Change

ควรอัปเดต change ที่มีอยู่หรือเริ่มใหม่เมื่อไหร่? ​

อัปเดตเมื่อเป็นงานเดียวกันที่ปรับปรุง เริ่มใหม่เมื่อเจตนาเปลี่ยนไปอย่างพื้นฐานหรือขอบเขตขยายออกเป็นงานที่ต่างไป มี decision flowchart และตัวอย่างใน Workflows

ถ้า session หมด context หรือ requirements เปลี่ยนระหว่าง implement จะทำอย่างไร? ​

นี่คือจุดที่ specs แสดงคุณค่า เพราะแผนอยู่ในไฟล์ (ไม่ใช่แค่ในแชท) คุณสามารถล้าง context, เริ่ม AI session ใหม่ และต่อด้วย /opsx:apply; มันอ่าน artifacts และเริ่มจาก task ที่ยังไม่ถูกติ๊กแรก หาก requirements เปลี่ยน แก้ไข artifacts ให้ตรงกับความเป็นจริงใหม่แล้วดำเนินการต่อ การคง context window สะอาดยังให้ผลลัพธ์ที่ดีขึ้น; ล้างก่อน implement

ควร commit โฟลเดอร์ openspec/ เข้า git ไหม? ​

ใช่ Specs, active changes, และ archive ของคุณเป็นส่วนหนึ่งของประวัติโปรเจกต์ Commit เหมือน source อื่น Archive โดยเฉพาะกลายเป็นบันทึกถาวรว่าทำไมระบบของคุณทำงานแบบนี้

Specs และ changes ​

อะไรอยู่ใน spec เทียบกับ design? ​

Spec อธิบายพฤติกรรมที่สังเกตได้: ระบบทำอะไร, inputs, outputs, และ error conditions Design อธิบายว่าจะสร้างอย่างไร: technical approach, architecture decisions, file changes หาก implementation สามารถเปลี่ยนได้โดยไม่เปลี่ยนพฤติกรรมภายนอก มันอยู่ใน design ไม่ใช่ spec Concepts อธิบายลึกกว่า

Delta spec คืออะไร? ​

Spec ที่อธิบายเฉพาะสิ่งที่เปลี่ยน โดยใช้ sections ADDED, MODIFIED, และ REMOVED แทนที่จะเขียนซ้ำทั้ง spec นี่คือวิธีที่ OpenSpec จัดการการแก้ไขระบบที่มีอยู่อย่างสะอาด ดู Concepts

Archived changes ไปที่ไหน? ​

ไปที่ openspec/changes/archive/YYYY-MM-DD-<name>/ พร้อม artifacts ทั้งหมดของ change Change จะออกจาก active list ของคุณ Change ที่ประกาศ retire_capabilities: true อย่างชัดเจนสามารถลบ main capability spec ได้เมื่อลบ requirement สุดท้ายของ capability นั้น

การตั้งค่าและการปรับแต่ง ​

จะบอก AI เกี่ยวกับ tech stack ยังไง? ​

ใส่ใน openspec/config.yaml ใต้ context: ข้อความนั้นจะถูก inject เข้าทุก planning request ทำให้ AI รู้ stack และ conventions ของคุณเสมอ ดู Customization

สร้าง specs เป็นภาษาอื่นที่ไม่ใช่ภาษาอังกฤษได้ไหม? ​

ได้ เพิ่ม language instruction ใน context: ของ config Multi-Language มี snippets สำหรับคัดลอกวางหลายภาษา

เปลี่ยน workflow เองได้ไหม? ​

ได้ ด้วย custom schemas Schema กำหนดว่า artifacts ใดมีอยู่และขึ้นต่อกันอย่างไร Fork default ด้วย openspec schema fork spec-driven my-workflow แล้วแก้ไข ดู Customization

Models, privacy, และ upgrades ​

ควรใช้ AI model ตัวไหน? ​

OpenSpec ทำงานได้ดีที่สุดกับ high-reasoning models README แนะนำ models เช่น Codex 5.5 และ Opus 4.7 สำหรับทั้ง planning และ implementation นอกจากนี้คง context window สะอาด: ล้างก่อน implement สำหรับผลลัพธ์ที่ดีที่สุด

OpenSpec เก็บข้อมูลไหม? ​

เก็บ anonymous usage stats: ชื่อคำสั่งและ version เท่านั้น ไม่มี arguments, paths, content, หรือข้อมูลส่วนตัว และปิดอัตโนมัติใน CI Opt out ด้วย export OPENSPEC_TELEMETRY=0 หรือ export DO_NOT_TRACK=1

อัปเดตยังไง? ​

สองขั้น อัปเดต package (npm install -g @fission-ai/openspec@latest) แล้วรัน openspec update ในแต่ละโปรเจกต์เพื่อรีเฟรช generated skills และ commands

ถอด OpenSpec ออกยังไง? ​

ไม่มีคำสั่ง uninstall เพราะเป็นเพียง global package พร้อมไฟล์ในโปรเจกต์ของคุณ ลบ package (npm uninstall -g @fission-ai/openspec) และเลือกลบโฟลเดอร์ openspec/ และ generated tool files ขั้นตอนทีละขั้น รวมถึงสิ่งที่ปลอดภัยที่จะเก็บ อยู่ใน Installation: Uninstalling

การขอความช่วยเหลือ ​

ถามคำถามหรือรายงาน bugs ที่ไหน? ​

เอกสารเหล่านี้ผิดหรือสับสน จะทำอย่างไร? ​

บอกเรา หรือแก้ไขเอง Documentation PRs ยินดีและให้ค่า เปิด issue หรือส่ง pull request