OpenSpec

Glossary ​

รวมคำศัพท์ OpenSpec ทุกคำไว้ในที่เดียว อธิบายด้วยภาษาที่เข้าใจง่าย อ่านผ่านสักครั้งเดียว เอกสารส่วนที่เหลือก็จะอ่านได้เร็วขึ้น

คำศัพท์จัดกลุ่มตามหัวข้อ แล้วเรียงตัวอักษรภายในแต่ละกลุ่ม

คำนามหลัก ​

Spec. เอกสารที่อธิบายว่าส่วนหนึ่งของระบบของคุณทำงานอย่างไร Specs อยู่ใน openspec/specs/ จัดระเบียบตาม domain และประกอบด้วย requirements และ scenarios Spec คือคำตอบที่ตกลงกันไว้สำหรับคำถามว่า "ซอฟต์แวร์นี้ทำอะไร?" ดู Concepts

Source of truth. ディレクトอรี openspec/specs/ ทั้งรวมกัน เป็นที่เก็บพฤติกรรมปัจจุบันของระบบที่ตกลงกันไว้ Changes เสนอการแก้ไข; การ archive นำไปใช้

Change. หน่วยงานหนึ่งหน่วย จัดเป็นโฟลเดอร์ภายใต้ openspec/changes/<name>/ Change เก็บทุกอย่างเกี่ยวกับงานนั้น: proposal, design, tasks และ spec edits ที่นำเข้ามา One change, one feature or fix

Artifact. เอกสารภายใน change artifacts มาตรฐานคือ proposal, delta specs, design และ tasks สร้างตามลำดับ dependency และส่งต่อข้อมูลให้กัน

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

Domain. การจัดกลุ่มเชิงตรรกะสำหรับ specs เช่น auth/, payments/ หรือ ui/ คุณเลือก domain ที่ตรงกับวิธีที่คุณคิดเกี่ยวกับระบบของคุณ

ภายใน spec ​

Requirement. พฤติกรรมเดียวที่ระบบต้องมี มักเขียนด้วย keyword ของ RFC 2119: "The system SHALL expire sessions after 30 minutes." Requirements ระบุ what ไม่ใช่ how

Scenario. ตัวอย่างที่เป็นรูปธรรมและทดสอบได้ของ requirement ในการทำงาน โดยทั่วไปอยู่ในรูปแบบ Given/When/Then Scenarios ทำให้ requirement ตรวจสอบได้: คุณสามารถเขียน automated test จาก scenario หนึ่งได้

RFC 2119 keywords. คำว่า MUST, SHALL, SHOULD และ MAY ซึ่งมีความหมายมาตรฐานเกี่ยวกับความเข้มงวดของ requirement MUST และ SHALL เป็นสิ่งเด็ดขาด SHOULD แนะนำแต่มีช่องว่างสำหรับข้อยกเว้น MAY เป็นตัวเลือก ชื่อมาจากเอกสารมาตรฐานอินเทอร์เน็ตที่กำหนดคำเหล่านี้

Artifacts ​

Proposal (proposal.md). why และ what ของ change: intent, scope และแนวทางระดับสูง Artifact แรกที่คุณสร้าง

Design (design.md). how: แนวทางทางเทคนิค, architectural decisions และไฟล์ที่คุณคาดว่าจะต้องแก้ไข เป็น optional สำหรับ changes ง่ายๆ

Tasks (tasks.md). Checklist การ implement พร้อม checkboxes AI ทำงานผ่านรายการนี้ระหว่าง /opsx:apply และทำเครื่องหมายเมื่อเสร็จแต่ละรายการ

Lifecycle ​

Archive. การเสร็จสิ้น change Delta specs ของมันจะ merge เข้า main specs และโฟลเดอร์ change จะย้ายไปที่ openspec/changes/archive/YYYY-MM-DD-<name>/ หลังการ archive specs ของคุณจะอธิบายความเป็นจริงใหม่ ดู Concepts

Sync. การ merge delta specs ของ change เข้า main specs โดย ไม่ archive change โดยทั่วไปเป็นอัตโนมัติ (archive จะเสนอให้ทำ) แต่มีให้ใช้แยกต่างหากเป็น /opsx:sync สำหรับ changes ที่ใช้เวลานาน ดู Commands

Workflow และ commands ​

OPSX. Workflow มาตรฐานปัจจุบันของ OpenSpec สร้างรอบ fluid actions แทน rigid phases Slash commands ทั้งหมดเริ่มต้นด้วย /opsx: ดู OPSX Workflow

Slash command. คำสั่งที่คุณพิมพ์ใน chat ของ AI assistant เช่น /opsx:propose Slash commands ขับเคลื่อน workflow ไม่ใช่ terminal commands ดู How Commands Work

Explore (/opsx:explore). คำสั่ง thinking-partner อ่าน codebase ของคุณ เปรียบเทียบตัวเลือก และทำให้ไอเดียที่คลุมเครือชัดเจนเป็นแผนที่เป็นรูปธรรม โดยไม่สร้าง artifacts และไม่เขียนโค้ด จุดเริ่มต้นที่แนะนำเมื่อคุณมีปัญหาแต่ยังไม่มีแผน ดู Explore First

CLI. โปรแกรม openspec ที่คุณรันใน terminal ตั้งค่าโปรเจกต์, list และ validate changes, เปิด dashboard และ archive ครึ่ง terminal ของ OpenSpec ดู CLI

Skill. โฟลเดอร์คำสั่ง (.../skills/openspec-*/SKILL.md) ที่ AI assistant ของคุณ auto-detect และปฏิบัติตาม Skills เป็นมาตรฐาน cross-tool ที่กำลังเติบโตสำหรับการส่งมอบ workflow ของ OpenSpec ให้ assistant ของคุณ

Command file. ไฟล์ slash command ต่อ tool (.../commands/opsx-*) กลไกการส่งมอบแบบเก่า ยังรองรับอยู่ร่วมกับ skills คุณแทบไม่ต้องแตะไฟล์เหล่านี้โดยตรง

Profile. ชุดของ slash commands ที่ติดตั้งในโปรเจกต์ของคุณ Core (ค่าเริ่มต้น) คือ propose, explore, apply, update, sync, archive ชุด expanded เพิ่ม new, continue, ff, verify, bulk-archive, onboard เปลี่ยนด้วย openspec config profile

Delivery. ว่า OpenSpec ติดตั้ง skills, command files หรือทั้งสองอย่างสำหรับ tools ของคุณ ตั้งค่าแบบ global และใช้ด้วย openspec update

Customization ​

Schema. นิยามว่า workflow มี artifacts อะไรบ้างและ dependency ระหว่างกันอย่างไร ค่าเริ่มต้นในตัวคือ spec-driven (proposal → specs → design → tasks) คุณสามารถ fork หรือเขียนของตัวเอง ดู Customization

Template. ไฟล์ Markdown ภายใน schema ที่กำหนดรูปแบบสิ่งที่ AI สร้างสำหรับ artifact นั้นๆ การแก้ไข template เปลี่ยน output ของ AI ทันที โดยไม่ต้อง rebuild

Project config (openspec/config.yaml). การตั้งค่าต่อโปรเจกต์: schema เริ่มต้น, context: ที่ inject เข้าทุก planning request และ rules: ต่อ artifact วิธีที่ง่ายที่สุดในการสอน OpenSpec เกี่ยวกับ stack และ conventions ของคุณ ดู Customization

Context injection. การใส่ข้อมูลพื้นหลังของโปรเจกต์ในฟิลด์ context: ของ config.yaml เพื่อให้เพิ่มอัตโนมัติในทุก artifact ที่ AI สร้าง น่าเชื่อถือกว่าการหวังว่า AI จะอ่านไฟล์แยกต่างหาก

Dependency graph. Directed graph ที่เกิดจากความสัมพันธ์ requires: ของ artifacts เป็น DAG (directed acyclic graph: ลูกศรชี้ไปข้างหน้าเท่านั้น ไม่เป็น loop) และ OpenSpec ใช้เพื่อรู้ว่าอะไรที่คุณสร้างได้ถัดไป

Enablers, not gates. หลักการที่ว่า artifact dependencies แสดงว่าอะไรจะ เป็นไปได้ ถัดไป ไม่ใช่สิ่งที่ จำเป็น ถัดไป คุณสามารถกลับไปแก้ไข artifact ใดก็ได้ตลอดเวลา ดู Core Concepts at a Glance

Coordination across repos (beta) ​

คำศัพท์เหล่านี้ใช้เฉพาะเมื่อการวางแผนของคุณครอบคลุมมากกว่าหนึ่ง repo อยู่ใน beta ผู้ใช้ส่วนใหญ่สามารถละเลยได้ ดู Stores User Guide

Store. Repo อิสระที่หน้าที่ทั้งหมดคือการวางแผน มีโครงสร้าง openspec/ เดียวกันที่คุณรู้จักอยู่แล้ว (specs และ changes) บวกกับ identity file เล็กน้อย คุณลงทะเบียนบนเครื่องของคุณครั้งเดียว โดยใช้ชื่อ จากนั้นคำสั่ง OpenSpec ใดก็ได้สามารถทำงานในนั้นได้จากทุกที่

Reference. การประกาศใน openspec/config.yaml ของ code repo ว่า repo นั้นดึงข้อมูลจาก store ใด References เป็น read-only: repo ยังคง root ของตัวเอง และ openspec instructions จะได้ index ของ specs ของ store ที่อ้างอิง แต่ละอันพร้อมคำสั่งที่ถูกต้องในการ fetch

Working context. สิ่งที่ openspec context ประกอบขึ้นสำหรับ repo ปัจจุบัน: OpenSpec root ของมันบวกกับทุก store ที่อ้างอิง แต่ละอันพร้อมวิธี fetch คำตอบสำหรับคำถามว่า "ฉันกำลังทำงานกับอะไร?"

Workset. ชุดโฟลเดอร์ส่วนตัวเฉพาะเครื่องที่คุณเปิดพร้อมกัน (store ควบคู่กับ code repos ที่คุณทำงาน) สร้างอย่างชัดเจนด้วย openspec workset create; ไม่มีอะไรเกี่ยวกับ local paths เหล่านั้นที่ commit เข้า shared planning repo

ดูเพิ่มเติม ​