แนวคิด
คู่มือนี้อธิบายแนวคิดหลักของ OpenSpec และวิธีการทำงานร่วมกัน สำหรับการใช้งานเชิงปฏิบัติ โปรดดูที่ เริ่มต้นใช้งาน และ เวิร์กโฟลว์
ปรัชญา
OpenSpec ถูกสร้างขึ้นโดยยึดหลักการสำคัญ 4 ประการ:
ยืดหยุ่น ไม่แข็งทื่อ — ไม่มีขั้นตอนบังคับ (phase gates) ทำงานในสิ่งที่สมเหตุสมผล
แบบวนซ้ำ ไม่ใช่สายน้ำ — เรียนรู้ขณะสร้าง ปรับปรุงไปเรื่อยๆ
เรียบง่าย ไม่ซับซ้อน — การตั้งค่าที่เบาบาง พิธีกรรมน้อยที่สุด
เน้นระบบที่มีอยู่ก่อนแล้ว — ทำงานร่วมกับโค้ดเบสเดิมได้ ไม่ใช่แค่โครงการใหม่ทั้งหมดเหตุผลที่หลักการเหล่านี้สำคัญ
ยืดหยุ่น ไม่แข็งทื่อ. ระบบสเปคแบบดั้งเดิมล็อกคุณไว้ในขั้นตอนต่างๆ: คุณต้องวางแผนก่อน แล้วจึงดำเนินการพัฒนา และเมื่อเสร็จก็จบงาน OpenSpec ยืดหยุ่นกว่า — คุณสามารถสร้างอาร์ติแฟกต์ใดๆ ก็ได้ตามลำดับที่เหมาะสมกับงานของคุณ
แบบวนซ้ำ ไม่ใช่สายน้ำ. ข้อกำหนดอาจเปลี่ยนแปลง ความเข้าใจอาจลึกซึ้งขึ้น สิ่งที่เคยดูเหมือนแนวทางที่ดีในตอนแรก อาจไม่เหมาะสมอีกต่อไปหลังจากที่คุณได้เห็นโค้ดเบสแล้ว OpenSpec ยอมรับความเป็นจริงนี้
เรียบง่าย ไม่ซับซ้อน. กรอบงานสเปคบางแห่งต้องการการตั้งค่าอย่างละเอียด รูปแบบที่ตายตัว หรือกระบวนการที่หนักหน่วง OpenSpec จะไม่ขัดขวางการทำงานของคุณ เริ่มต้นได้ในไม่กี่วินาที เริ่มทำงานได้ทันที ปรับแต่งเฉพาะเมื่อจำเป็นเท่านั้น
เน้นระบบที่มีอยู่ก่อนแล้ว. งานซอฟต์แวร์ส่วนใหญ่ไม่ใช่การสร้างใหม่ทั้งหมด แต่เป็นการปรับเปลี่ยนระบบที่มีอยู่แล้ว วิธีการแบบ Delta ของ OpenSpec ทำให้การระบุการเปลี่ยนแปลงต่อพฤติกรรมเดิมเป็นเรื่องง่าย ไม่ใช่เพียงการอธิบายระบบใหม่
ภาพรวมทั้งหมด
OpenSpec จัดระเบียบงานของคุณออกเป็นสองส่วนหลัก:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Source of truth │◄─────│ Proposed modifications │ │
│ │ How your system │ merge│ Each change = one folder │ │
│ │ currently works │ │ Contains artifacts + deltas │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specs คือแหล่งความจริงเดียว (source of truth) — อธิบายพฤติกรรมปัจจุบันของระบบคุณ
Changes คือการแก้ไขที่เสนอไว้ — จะอยู่ในโฟลเดอร์แยกจนกว่าคุณจะพร้อมที่จะ merge เข้าไป
การแยกส่วนนี้เป็นสิ่งสำคัญ คุณสามารถทำงานกับ changes หลายรายการได้พร้อมกันโดยไม่เกิดความขัดแย้ง คุณสามารถตรวจสอบ review การเปลี่ยนแปลงก่อนที่จะส่งผลกระทบต่อ main specs ได้ และเมื่อคุณ archive การเปลี่ยนแปลงแล้ว delta ของมันจะ merge เข้ากับ source of truth ได้อย่างเรียบร้อย
Specs
Specs อธิบายพฤติกรรมของระบบโดยใช้ข้อกำหนดและสถานการณ์ที่เป็นโครงสร้าง
โครงสร้าง
openspec/specs/
├── auth/
│ └── spec.md # พฤติกรรมการยืนยันตัวตน
├── payments/
│ └── spec.md # การประมวลผลการชำระเงิน
├── notifications/
│ └── spec.md # ระบบแจ้งเตือน
└── ui/
└── spec.md # พฤติกรรม UI และธีมจัดระเบียบ specs ตามโดเมน — การจัดกลุ่มเชิงตรรกะที่มีความหมายสำหรับระบบของคุณ รูปแบบทั่วไป ได้แก่:
- ตามพื้นที่ฟีเจอร์:
auth/,payments/,search/ - ตามคอมโพเนนต์:
api/,frontend/,workers/ - ตาม bounded context:
ordering/,fulfillment/,inventory/
รูปแบบ Spec
Spec ประกอบด้วย requirements และแต่ละ requirement จะมี scenarios ดังนี้:
# Auth Specification
## Purpose
Authentication and session management for the application.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.
#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued
### Requirement: Session Expiration
The system MUST expire sessions after 30 minutes of inactivity.
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticateองค์ประกอบสำคัญ:
| องค์ประกอบ | จุดประสงค์ |
|---|---|
## Purpose | คำอธิบายระดับสูงของโดเมนใน spec นี้ |
### Requirement: | พฤติกรรมเฉพาะที่ระบบต้องมี |
#### Scenario: | ตัวอย่างที่เป็นรูปธรรมของ requirement ที่กำลังทำงานอยู่ |
| SHALL/MUST/SHOULD | คำศัพท์ RFC 2119 ที่บ่งชี้ความเข้มงวดของ requirement |
เหตุผลในการจัดโครงสร้าง Specs แบบนี้
Requirements คือ "อะไร" — บอกระบบควรทำอะไร โดยไม่ระบุวิธีการนำไปปฏิบัติ
Scenarios คือ "เมื่อไหร่" — ให้ตัวอย่างที่เป็นรูปธรรมที่สามารถตรวจสอบได้ Scenarios ที่ดีควรมีลักษณะดังนี้:
- สามารถทดสอบได้ (คุณสามารถเขียน automated test สำหรับพวกเขาได้)
- ครอบคลุมทั้งกรณีปกติ (happy path) และกรณีขอบเขต (edge cases)
- ใช้รูปแบบที่มีโครงสร้างเช่น Given/When/Then หรือคล้ายกัน
คำศัพท์ RFC 2119 (SHALL, MUST, SHOULD, MAY) สื่อความตั้งใจ:
- MUST/SHALL — ข้อกำหนดที่เด็ดขาด
- SHOULD — แนะนำ แต่มีข้อยกเว้น
- MAY — เป็นทางเลือก
Spec คืออะไร (และไม่ใช่)
Spec คือ สัญญาพฤติกรรม ไม่ใช่แผนการนำไปปฏิบัติ
เนื้อหา Spec ที่ดี:
- พฤติกรรมที่สังเกตได้ซึ่งผู้ใช้หรือระบบ downstream พึ่งพา
- อินพุต เอาต์พุต และเงื่อนไขข้อผิดพลาด
- ข้อจำกัดภายนอก (ความปลอดภัย, ความเป็นส่วนตัว, ความน่าเชื่อถือ, ความเข้ากันได้)
- Scenarios ที่สามารถทดสอบหรือตรวจสอบได้อย่างชัดเจน
สิ่งที่ควรหลีกเลี่ยงใน Specs:
- ชื่อคลาส/ฟังก์ชันภายใน
- การเลือกไลบรารีหรือเฟรมเวิร์ก
- รายละเอียดขั้นตอนการนำไปปฏิบัติ
- แผนการทำงานโดยละเอียด (สิ่งเหล่านี้ควรอยู่ใน
design.mdหรือtasks.md)
การทดสอบอย่างรวดเร็ว:
- หากการนำไปปฏิบัติสามารถเปลี่ยนแปลงได้โดยไม่เปลี่ยนพฤติกรรมที่มองเห็นภายนอก มันน่าจะไม่ได้เป็นส่วนหนึ่งของ spec
รักษาให้เบาบาง: ความเข้มงวดแบบก้าวหน้า
OpenSpec มุ่งหลีกเลี่ยง бюрократี (ความ birocratic) ใช้ระดับความเข้มงวดที่เบาที่สุดที่ยังทำให้การเปลี่ยนแปลงนั้นตรวจสอบได้
Lite spec (ค่าเริ่มต้น):
- Requirements ที่เน้นพฤติกรรมก่อน
- ขอบเขตและสิ่งที่อยู่นอกขอบเขตที่ชัดเจน
- การตรวจสอบการยอมรับที่เป็นรูปธรรมจำนวนหนึ่ง
Full spec (สำหรับความเสี่ยงที่สูงขึ้น):
- การเปลี่ยนแปลงข้ามทีมหรือข้าม repo
- การเปลี่ยนแปลง API/contract, migrations, ความกังวลด้านความปลอดภัย/ความเป็นส่วนตัว
- การเปลี่ยนแปลงที่ความคลุมเครืออาจทำให้เกิดการทำงานซ้ำที่มีค่าใช้จ่ายสูง
การเปลี่ยนแปลงส่วนใหญ่ควรอยู่ในโหมด Lite
การทำงานร่วมกันระหว่างมนุษย์และ Agent
ในหลายทีม มนุษย์สำรวจและ Agent ร่างเอกสาร The intended loop คือ:
- มนุษย์ให้ความตั้งใจ บริบท และข้อจำกัด
- Agent แปลงสิ่งเหล่านี้เป็น requirements และ scenarios ที่เน้นพฤติกรรม
- Agent เก็บรายละเอียดการนำไปปฏิบัติไว้ใน
design.mdและtasks.mdไม่ใช่spec.md - การตรวจสอบยืนยันโครงสร้างและความชัดเจนก่อนการนำไปปฏิบัติ
สิ่งนี้ทำให้ specs อ่านง่ายสำหรับมนุษย์และสอดคล้องสำหรับ agents
Changes
Change คือการแก้ไขที่เสนอต่อระบบของคุณ แพ็กเกจเป็นโฟลเดอร์ที่มีทุกอย่างที่จำเป็นต่อการทำความเข้าใจและการนำไปปฏิบัติ
โครงสร้าง Change
openspec/changes/add-dark-mode/
├── proposal.md # ทำไมและอะไร
├── design.md # อย่างไร (แนวทางทางเทคนิค)
├── tasks.md # รายการตรวจสอบการนำไปปฏิบัติ
├── .openspec.yaml # Metadata ของการเปลี่ยนแปลง (ตัวเลือก): schema, created, skip_specs, retire_capabilities
└── specs/ # Delta specs
└── ui/
└── spec.md # สิ่งที่เปลี่ยนแปลงใน ui/spec.mdแต่ละ change มีความสมบูรณ์ในตัวเอง มี:
- Artifacts — เอกสารที่จับความตั้งใจ การออกแบบ และงาน
- Delta specs — specifications สำหรับสิ่งที่กำลังเพิ่ม แก้ไข หรือลบออก
- Metadata — การกำหนดค่าเพิ่มเติมสำหรับการเปลี่ยนแปลงเฉพาะนี้
เหตุใด Changes จึงเป็นโฟลเดอร์
การแพ็กเกจ change เป็นโฟลเดอร์มีประโยชน์หลายประการ:
ทุกอย่างอยู่ด้วยกัน Proposal, design, tasks และ specs อยู่ในที่เดียวกัน ไม่ต้องค้นหาในตำแหน่งต่างๆ
ทำงานขนานกันได้ Changes หลายรายการสามารถดำรงอยู่ได้พร้อมกันโดยไม่มีความขัดแย้ง ทำงานบน
add-dark-modeในขณะที่fix-auth-bugก็กำลังดำเนินการอยู่เช่นกันประวัติที่สะอาด เมื่อ archive แล้ว changes จะย้ายไปยัง
changes/archive/พร้อมบริบทเต็มรูปแบบที่คุณสามารถย้อนกลับไปดูและเข้าใจได้ว่าไม่เพียงแต่มีการเปลี่ยนแปลงอะไร แต่ยังรวมถึงเหตุผลด้วยเหมาะสำหรับการ review โฟลเดอร์ change ง่ายต่อการ review — เปิดมันอ่าน proposal ตรวจสอบ design ดู delta specs
Artifacts
Artifacts คือเอกสารภายใน change ที่ชี้งาน
กระบวนการไหลของ Artifact
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
why what how steps
+ scope changes approach to takeArtifacts สร้างต่อกัน แต่ละ artifact ให้บริบทสำหรับ artifact ถัดไป
ประเภทของ Artifact
Proposal (proposal.md)
Proposal จับ ความตั้งใจ, ขอบเขต และ แนวทาง ในระดับสูง
# Proposal: Add Dark Mode
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.
## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage
Out of scope:
- Custom color themes (future work)
- Per-page theme overrides
## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.เมื่อควรอัปเดต proposal:
- ขอบเขตเปลี่ยนแปลง (แคบลงหรือขยายออก)
- ความตั้งใจชัดเจนขึ้น (ความเข้าใจที่ดีขึ้นเกี่ยวกับปัญหา)
- แนวทางเปลี่ยนแปลงพื้นฐาน
Specs (delta specs ใน specs/)
Delta specs อธิบาย สิ่งที่กำลังเปลี่ยนแปลง เทียบกับ specs ปัจจุบัน ดู Delta Specs ด้านล่าง
Design (design.md)
Design จับ แนวทางทางเทคนิค และ การตัดสินใจด้านสถาปัตยกรรม
# Design: Add Dark Mode
## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.
## Architecture Decisions
### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency
### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution
## Data Flow
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)เมื่อควรอัปเดต design:
- การนำไปปฏิบัติเปิดเผยว่าแนวทางนั้นใช้ไม่ได้
- พบวิธีแก้ปัญหาที่ดีกว่า
- Dependencies หรือข้อจำกัดเปลี่ยนแปลง
Tasks (tasks.md)
Tasks คือ รายการตรวจสอบการนำไปปฏิบัติ — ขั้นตอนที่เป็นรูปธรรมพร้อมช่องทำเครื่องหมาย
# Tasks
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
- [ ] 1.4 Add system preference detection
## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle
## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
- [ ] 3.3 Test contrast ratios for accessibilityแนวปฏิบัติที่ดีที่สุดสำหรับ Tasks:
- จัดกลุ่ม tasks ที่เกี่ยวข้องภายใต้หัวข้อ
- ใช้หมายเลขลำดับชั้น (1.1, 1.2, ฯลฯ)
- รักษา tasks ให้เล็กพอที่จะเสร็จสิ้นในหนึ่งเซสชัน
- ทำเครื่องหมาย tasks เมื่อเสร็จสิ้น
Delta Specs
Delta specs คือแนวคิดหลักที่ทำให้ OpenSpec ทำงานได้ดีกับการพัฒนา brownfield (การปรับปรุงระบบเดิม) พวกมันอธิบาย สิ่งที่กำลังเปลี่ยนแปลง แทนที่จะกล่าวซ้ำทั้ง spec
รูปแบบ
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.
#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation
#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP
## MODIFIED Requirements
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated
## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)ส่วนของ Delta
| ส่วน | ความหมาย | เกิดอะไรขึ้นเมื่อ Archive |
|---|---|---|
## ADDED Requirements | พฤติกรรมใหม่ | เพิ่มเข้าไปใน main spec |
## MODIFIED Requirements | พฤติกรรมที่เปลี่ยนแปลง | แทนที่ requirement ที่มีอยู่ |
## REMOVED Requirements | พฤติกรรมที่ถูกเลิกใช้งาน | ลบออกจาก main spec; การลบ requirement สุดท้ายจะทำให้ capability นั้นหมดอายุและลบไฟล์ spec เมื่อการเปลี่ยนแปลงประกาศ retire_capabilities: true |
## Purpose | สิ่งใหม่ที่ capabilities ใหม่ใช้เพื่ออะไร | เป็นเมล็ดพันธุ์ของ Purpose ใน main spec ที่กำลังถูกสร้าง; ถูกเพิกเฉยเมื่อ spec มีอยู่แล้ว |
เหตุใดจึงใช้ Deltas แทน Full Specs
ความชัดเจน Delta แสดงให้เห็นอย่างชัดเจนว่ากำลังเปลี่ยนแปลงอะไร เมื่ออ่าน full spec คุณต้อง diff它在ใจเทียบกับเวอร์ชันปัจจุบัน
หลีกเลี่ยงความขัดแย้ง Changes สองรายการสามารถแตะไฟล์ spec เดียวกันได้โดยไม่มีความขัดแย้ง ตราบใดที่พวกมันแก้ไข requirements ต่างกัน
ประสิทธิภาพในการ review Reviewers เห็นการเปลี่ยนแปลง ไม่ใช่บริบทที่ไม่เปลี่ยนแปลง มุ่งเน้นไปที่สิ่งที่สำคัญ
เหมาะกับ Brownfield งานส่วนใหญ่เป็นการแก้ไขพฤติกรรมที่มีอยู่ Deltas ทำให้การแก้ไขเป็นเรื่องหลัก ไม่ใช่เรื่องรอง
Schemas
Schemas กำหนดประเภทของ artifacts และ dependencies ของพวกมันสำหรับ workflow
วิธีทำงานของ Schemas
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # ไม่มี dependencies สามารถสร้างก่อนได้
- id: specs
generates: specs/**/*.md
requires: [proposal] # ต้องมี proposal ก่อนจึงจะสร้างได้
- id: design
generates: design.md
requires: [proposal] # สามารถสร้างพร้อมกันกับ specs ได้
- id: tasks
generates: tasks.md
requires: [specs, design] # ต้องมีทั้ง specs และ design ก่อนArtifacts สร้างเป็น dependency graph:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)Dependencies คือตัวเปิดโอกาส ไม่ใช่ตัวกั้นทาง แสดงให้เห็นว่าอะไรสามารถสร้างได้ ไม่ใช่สิ่งที่ต้องสร้างต่อไป คุณสามารถข้าม design ได้ถ้าไม่ต้องการ คุณสามารถสร้าง specs ก่อนหรือหลัง design ได้ — ทั้งคู่ขึ้นอยู่กับ proposal เท่านั้น
Schemas ในตัว
spec-driven (ค่าเริ่มต้น)
Workflow มาตรฐานสำหรับการพัฒนาแบบ spec-driven:
proposal → specs → design → tasks → implementเหมาะกับ: งาน feature ส่วนใหญ่ที่ต้องการตกลง specs ก่อนการ implement
Custom Schemas
สร้าง custom schemas สำหรับ workflow ของทีมคุณ:
# สร้างใหม่ตั้งแต่ต้น
openspec schema init research-first
# หรือ fork จากที่มีอยู่
openspec schema fork spec-driven research-firstตัวอย่าง custom schema:
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # ทำ research ก่อน
- id: proposal
generates: proposal.md
requires: [research] # Proposal ที่ได้รับข้อมูลจาก research
- id: tasks
generates: tasks.md
requires: [proposal] # ข้าม specs/design ไปที่ tasks โดยตรงดู Customization สำหรับรายละเอียดทั้งหมดเกี่ยวกับการสร้างและใช้งาน custom schemas
Archive
การ Archive จะทำให้การเปลี่ยนแปลงเสร็จสมบูรณ์โดยการรวม delta specs เข้ากับ main specs และเก็บรักษาการเปลี่ยนแปลงไว้เพื่อประวัติ
สิ่งที่เกิดขึ้นเมื่อคุณ Archive
Before archive:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ merge
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
After archive:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Now includes 2FA requirements
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Preserved for history
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdกระบวนการ Archive
รวม deltas. แต่ละส่วน delta spec (ADDED/MODIFIED/REMOVED) จะถูกนำไปใช้กับ main spec ที่เกี่ยวข้อง
ย้ายไปยัง archive. โฟลเดอร์การเปลี่ยนแปลงจะถูกย้ายไปยัง
changes/archive/พร้อม prefix วันที่สำหรับการเรียงลำดับตามเวลาเก็บรักษาสภาพแวดล้อม. ทุก artifacts จะยังคงอยู่ครบถ้วนใน archive คุณสามารถย้อนดูได้เสมอเพื่อทำความเข้าใจว่าทำไมการเปลี่ยนแปลงจึงเกิดขึ้น
ทำไม Archive จึงสำคัญ
สถานะที่สะอาด. Active changes (changes/) แสดงเฉพาะงานที่กำลังดำเนินการ งานที่เสร็จสมบูรณ์จะถูกย้ายออกไป
ร่องรอยการตรวจสอบ. Archive เก็บรักษาสภาพแวดล้อมทั้งหมดของการเปลี่ยนแปลงทุกครั้ง — ไม่ใช่แค่สิ่งที่เปลี่ยน แต่รวมถึง proposal ที่อธิบายว่าทำไม, design ที่อธิบายว่าอย่างไร, และ tasks ที่แสดงงานที่ทำ
วิวัฒนาการของ Specs. Specs เติบโตอย่างเป็นธรรมชาติเมื่อมีการ archive การเปลี่ยนแปลง แต่ละ archive จะรวม deltas ของมัน สร้างข้อกำหนดที่ครอบคลุมมากขึ้นตามเวลา
ทุกอย่างทำงานร่วมกันอย่างไร
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC FLOW │
│ │
│ ┌────────────────┐ │
│ │ 1. START │ /opsx:propose (core) or /opsx:new (expanded) │
│ │ CHANGE │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. CREATE │ /opsx:ff or /opsx:continue (expanded workflow) │
│ │ ARTIFACTS │ Creates proposal → specs → design → tasks │
│ │ │ (based on schema dependencies) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. IMPLEMENT │ /opsx:apply │
│ │ TASKS │ Work through tasks, checking them off │
│ │ │◄──── Update artifacts as you learn │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. VERIFY │ /opsx:verify (optional) │
│ │ WORK │ Check implementation matches specs │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARCHIVE │────►│ Delta specs merge into main specs │ │
│ │ CHANGE │ │ Change folder moves to archive/ │ │
│ └────────────────┘ │ Specs are now the updated source of truth │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘วงจรที่ดี:
- Specs อธิบายพฤติกรรมปัจจุบัน
- Changes เสนอการแก้ไข (ในรูป deltas)
- Implementation ทำให้การเปลี่ยนแปลงเป็นจริง
- Archive รวม deltas เข้ากับ specs
- Specs อธิบายพฤติกรรมใหม่แล้ว
- การเปลี่ยนแปลงถัดไปสร้างบน specs ที่อัปเดตแล้ว
คำศัพท์
| คำศัพท์ | นิยาม |
|---|---|
| Artifact | เอกสารภายในการเปลี่ยนแปลง (proposal, design, tasks, หรือ delta specs) |
| Archive | กระบวนการทำให้การเปลี่ยนแปลงเสร็จสมบูรณ์และรวม deltas เข้ากับ main specs |
| Change | การแก้ไขที่เสนอต่อระบบ จัดเป็นโฟลเดอร์พร้อม artifacts |
| Delta spec | Spec ที่อธิบายการเปลี่ยนแปลง (ADDED/MODIFIED/REMOVED) เทียบกับ specs ปัจจุบัน |
| Domain | การจัดกลุ่มเชิงตรรกะสำหรับ specs (เช่น auth/, payments/) |
| Requirement | พฤติกรรมเฉพาะที่ระบบต้องมี |
| Scenario | ตัวอย่างที่เป็นรูปธรรมของ requirement โดยทั่วไปอยู่ในรูปแบบ Given/When/Then |
| Schema | นิยามของประเภท artifacts และ dependencies ของพวกมัน |
| Spec | ข้อกำหนดที่อธิบายพฤติกรรมของระบบ ประกอบด้วย requirements และ scenarios |
| Source of truth | โฟลเดอร์ openspec/specs/ ที่เก็บพฤติกรรมที่ตกลงกันไว้ปัจจุบัน |
ขั้นตอนถัดไป
- Getting Started - ขั้นตอนแรกเชิงปฏิบัติ
- Workflows - รูปแบบทั่วไปและเมื่อใดควรใช้แต่ละรูปแบบ
- Commands - คำสั่งอ้างอิงทั้งหมด
- Customization - สร้าง custom schemas และกำหนดค่าโปรเจกต์ของคุณ