#OpenSpec: การใช้งานในการสร้างระบบด้วย Spec-Driven Development

ปัจจุบัน AI Coding Assistant เช่น Claude Code, Codex, Cursor, GitHub Copilot และ Gemini CLI สามารถช่วยสร้างระบบได้อย่างรวดเร็ว แต่ปัญหาที่พบบ่อยคือ เมื่อเราสั่ง AI ด้วย Prompt เพียงไม่กี่ประโยค AI อาจตีความ Requirement ไม่ตรงกับสิ่งที่ต้องการ และเริ่มเขียนโค้ดก่อนที่ Requirement, Architecture และ Acceptance Criteria จะชัดเจน

OpenSpec เป็นเครื่องมือที่เข้ามาช่วยแก้ปัญหานี้ด้วยแนวคิด Spec-Driven Development (SDD) หรือการพัฒนาซอฟต์แวร์โดยเริ่มจาก Specification ก่อน Implementation

แทนที่จะเป็น

Prompt
   ↓
AI
   ↓
Code

OpenSpec เปลี่ยน workflow ให้เป็น

Requirement
    ↓
Explore
    ↓
Proposal
    ↓
Specification
    ↓
Design
    ↓
Tasks
    ↓
Implementation
    ↓
Verification
    ↓
Archive

ผลลัพธ์คือมนุษย์และ AI มีเอกสารชุดเดียวกันสำหรับตอบคำถามว่า

เรากำลังสร้างอะไร ระบบต้องทำงานอย่างไร และงานใดต้องทำให้เสร็จ

บทความนี้อธิบายการติดตั้งและใช้งาน OpenSpec ตั้งแต่เริ่มต้น พร้อมตัวอย่างการนำไปใช้สร้าง REST API ในโครงการจริง

#OpenSpec คืออะไร

OpenSpec เป็นเครื่องมือสำหรับจัดการกระบวนการ Spec-Driven Development สำหรับ AI Coding Assistant

แนวคิดสำคัญคือ ก่อนให้ AI เขียน Source Code เราจะสร้าง Artifact สำหรับอธิบาย Change ก่อน เช่น

proposal.md
spec.md
design.md
tasks.md

จากนั้น AI จึงนำ Artifact เหล่านี้ไปใช้เป็น Context ในการเขียนระบบ

ตัวอย่างโครงสร้าง

openspec/
├── config.yaml
├── specs/
└── changes/
    ├── add-authentication/
    │   ├── proposal.md
    │   ├── design.md
    │   ├── tasks.md
    │   └── specs/
    │       └── authentication/
    │           └── spec.md
    └── archive/

openspec/specs/ ทำหน้าที่เก็บ Specification ปัจจุบันของระบบ

ส่วน

openspec/changes/

ใช้เก็บ Change ที่กำลังพัฒนา

เมื่อ Change เสร็จแล้วจะถูกย้ายไปที่

openspec/changes/archive/

ทำให้สามารถตรวจสอบประวัติการเปลี่ยนแปลงย้อนหลังได้

#ทำไมต้องใช้ OpenSpec

#ปัญหาของ Prompt-Driven Development

ลองพิจารณา Prompt ต่อไปนี้

Create authentication API using JWT.

AI อาจต้องตัดสินใจเองว่า

  • ใช้ Access Token อย่างเดียวหรือไม่
  • ต้องมี Refresh Token หรือไม่
  • Token หมดอายุเมื่อไร
  • Password Hashing ใช้อะไร
  • Failed Login ต้อง Lock Account หรือไม่
  • Logout ต้อง invalidate token หรือไม่
  • API Error Response เป็นรูปแบบใด
  • Authentication Test ต้องครอบคลุมอะไรบ้าง

ถ้า Requirement เหล่านี้ไม่ได้ระบุไว้ AI จะต้อง เดา

ผลลัพธ์ที่อาจเกิดขึ้นคือ

Requirement ไม่ชัด
        ↓
AI ตีความเอง
        ↓
Code ถูกสร้าง
        ↓
พบว่า Behavior ไม่ตรง
        ↓
แก้ Code
        ↓
เกิด Regression

OpenSpec ช่วยให้เราย้ายการตัดสินใจเหล่านี้มาอยู่ใน Specification ก่อนเขียน Code

Requirement
        ↓
Specification
        ↓
Human Review
        ↓
Implementation

#Workflow หลักของ OpenSpec

Workflow แบบทั่วไปสามารถสรุปได้ดังนี้

flowchart LR
    A[Explore] --> B[Propose]
    B --> C[Review]
    C --> D[Apply]
    D --> E[Verify / Validate]
    E --> F[Sync]
    F --> G[Archive]
    G -. Next Change .-> A

คำสั่งที่ใช้บ่อยใน Default Workflow ได้แก่

/opsx:explore
/opsx:propose
/opsx:apply
/opsx:update
/opsx:sync
/opsx:archive

สำหรับ Workflow แบบละเอียด OpenSpec ยังมีคำสั่งเพิ่มเติม เช่น

/opsx:new
/opsx:continue
/opsx:ff
/opsx:verify
/opsx:bulk-archive
/opsx:onboard

#จุดสำคัญ: Terminal Command กับ AI Command เป็นคนละชุด

OpenSpec มีคำสั่งสองประเภท

#คำสั่งที่ใช้ใน Terminal

ตัวอย่าง

openspec init
openspec list
openspec view
openspec validate
openspec status
openspec update

#คำสั่งที่ใช้ใน AI Coding Assistant

ตัวอย่าง

/opsx:explore
/opsx:propose
/opsx:apply
/opsx:archive

ดังนั้นคำสั่งต่อไปนี้

/opsx:propose add-authentication

ไม่ได้พิมพ์ใน Shell แต่ต้องพิมพ์ใน Chat ของ AI Coding Assistant

ตัวอย่างแนวคิด

Terminal                        AI Coding Assistant

openspec init
      │
      └──────────────► /opsx:propose
                       /opsx:apply
                       /opsx:archive

ชื่อคำสั่งจริงอาจแตกต่างกันตาม AI Tool เช่น

Canonical
/opsx:propose

Cursor / GitHub Copilot
/opsx-propose

Codex
$openspec-propose

หลังจาก openspec init ควรดูข้อความที่ CLI แสดงว่า Tool ที่เราเลือกต้องเรียกคำสั่งในรูปแบบใด

#การติดตั้ง OpenSpec

#Requirement

OpenSpec เป็น Node.js CLI และเอกสารปัจจุบันกำหนด

Node.js >= 20.19.0

ตรวจสอบ Version

node --version

ตัวอย่าง

v22.20.0

#ติดตั้ง OpenSpec ด้วย npm

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

ตรวจสอบ

openspec --version

OpenSpec ยังสามารถติดตั้งด้วย package manager อื่น เช่น pnpm, Bun หรือ Yarn 1.x ได้ แต่ตัว Runtime ของ OpenSpec ยังคงต้องมี Node.js ตาม Version ที่กำหนด

#Initialize OpenSpec ใน Project

สมมติ Project ชื่อ

task-api

เข้า Directory

cd task-api

แล้วรัน

openspec init

OpenSpec จะให้เลือก AI Coding Assistant ที่ต้องการใช้งาน

ตัวอย่างเช่น

Claude Code
Cursor
Codex
GitHub Copilot
Gemini CLI

หรือระบุ Tool ผ่าน Command Line ได้

openspec init --tools claude,cursor

ถ้าต้องการสร้างเฉพาะโครงสร้าง OpenSpec

openspec init --tools none

หลังจากนั้น Project จะมี Directory เช่น

task-api/
├── src/
├── tests/
├── package.json
└── openspec/
    ├── config.yaml
    ├── specs/
    └── changes/
        └── archive/

#การตั้งค่า openspec/config.yaml

ไฟล์ openspec/config.yaml ใช้บอก Context ของ Project ให้ AI เข้าใจมาตรฐานของระบบ

ตัวอย่าง

schema: spec-driven

context: |
  Tech stack:
  - TypeScript
  - Node.js
  - Express
  - PostgreSQL

  API conventions:
  - REST API
  - JSON response
  - /api/v1 prefix

  Testing:
  - Vitest for unit testing
  - Playwright for API testing

  Code style:
  - ESLint
  - Prettier

ข้อดีคือเราไม่จำเป็นต้องบอกข้อมูลเหล่านี้ซ้ำทุก Prompt

#ขั้นตอนที่ 1: Explore Requirement

ถ้ายังไม่แน่ใจว่าควรออกแบบ Feature อย่างไร ให้เริ่มด้วย

/opsx:explore

ตัวอย่าง Prompt

I want to build a Task Management REST API.

The system should support:

- create task
- list tasks
- update task
- delete task
- mark task as completed

Analyze missing requirements, edge cases,
validation rules, API behavior and testing strategy.

Do not implement code yet.

AI อาจช่วยค้น Requirement ที่ยังไม่ชัด เช่น

Task title required?
Maximum title length?
Pagination?
Authentication?
Soft delete or hard delete?
Can completed tasks be edited?
Who owns each task?
What happens when a task does not exist?

นี่คือข้อได้เปรียบของ Explore Mode เพราะเรายังไม่เสียเวลาไปกับ Implementation

#ขั้นตอนที่ 2: Propose Change

เมื่อ Requirement ชัดเจนขึ้น ให้สร้าง Change

/opsx:propose create task management REST API

OpenSpec จะสร้าง Directory

openspec/
└── changes/
    └── create-task-management-api/

ภายในอาจมี

proposal.md
design.md
tasks.md
specs/

ตัวอย่าง

openspec/
└── changes/
    └── create-task-management-api/
        ├── proposal.md
        ├── design.md
        ├── tasks.md
        └── specs/
            └── task-management/
                └── spec.md

#proposal.md คืออะไร

proposal.md อธิบายว่า

Why
What Changes
Capabilities
Impact

ตัวอย่าง

# Task Management API

## Why

The application requires an API that allows users
to create and manage personal tasks.

## What Changes

- Add task creation
- Add task listing
- Add task update
- Add task deletion
- Add task completion

## Capabilities

- task-management

Proposal ควรตอบคำถามว่า

ทำไมเราจึงต้องทำ Change นี้ และ Scope ของ Change คืออะไร

#Specification คือหัวใจของ OpenSpec

Specification ไม่ควรเป็นเพียงคำอธิบายทั่วไป แต่ควรเป็น Behavior Contract

ตัวอย่าง

## ADDED Requirements

### Requirement: Create task

The system SHALL allow an authenticated user
to create a task.

#### Scenario: Create task successfully

- **WHEN** the user submits a valid task title
- **THEN** the system creates a new task
- **THEN** the API returns HTTP 201

#### Scenario: Empty title

- **WHEN** the user submits an empty task title
- **THEN** the request is rejected
- **THEN** the API returns HTTP 422

Notice ว่า Requirement ไม่ได้บอกว่า

ใช้ Controller ชื่ออะไร
ใช้ ORM ตัวไหน
สร้าง Function ชื่ออะไร

เพราะสิ่งเหล่านั้นเป็น Implementation Detail

Specification ควรบอก Behavior

#Requirement ที่ดีควร Testable

ตัวอย่าง Requirement ที่ไม่ดี

The API should be fast.

คำว่า Fast ไม่สามารถตรวจสอบได้อย่างชัดเจน

ควรเขียนเป็น

The API MUST respond within 500 ms
for 95% of requests under the defined test load.

Requirement ที่ดีควรสามารถแปลงเป็น Automated Test ได้

Requirement
    ↓
Scenario
    ↓
Acceptance Test

#ADDED / MODIFIED / REMOVED Requirements

OpenSpec ใช้ Delta Specification เพื่ออธิบายการเปลี่ยนแปลง

#เพิ่ม Requirement

## ADDED Requirements

ตัวอย่าง

## ADDED Requirements

### Requirement: Refresh token

The system SHALL allow a valid refresh token
to request a new access token.

#แก้ Requirement

## MODIFIED Requirements

ตัวอย่าง

## MODIFIED Requirements

### Requirement: Login protection

The system SHALL temporarily lock an account
after five consecutive failed login attempts.

#### Scenario: Account is locked

- **WHEN** authentication fails five consecutive times
- **THEN** the account is temporarily locked

#ยกเลิก Requirement

## REMOVED Requirements

ใช้ในกรณีที่ Feature หรือ Behavior นั้นไม่ควรอยู่ในระบบแล้ว

#ขั้นตอนที่ 3: Design

ถ้า Change มีความซับซ้อน ควรมี design.md

ตัวอย่าง

# Design

## Architecture

Client
  |
REST API
  |
Service
  |
Repository
  |
PostgreSQL

## API Endpoints

POST   /api/v1/tasks
GET    /api/v1/tasks
GET    /api/v1/tasks/{id}
PUT    /api/v1/tasks/{id}
DELETE /api/v1/tasks/{id}

## Data Model

Task

- id
- user_id
- title
- description
- status
- created_at
- updated_at

## Validation

title:
- required
- max 255 characters

status:
- pending
- completed

ความแตกต่างระหว่าง Spec กับ Design คือ

spec.md
WHAT the system must do

design.md
HOW the system will be built

#ขั้นตอนที่ 4: Tasks

tasks.md ทำหน้าที่แบ่ง Implementation ออกเป็นงานย่อย

ตัวอย่าง

# Tasks

## Database

- [ ] Create tasks table
- [ ] Create Task model
- [ ] Create repository

## API

- [ ] Implement POST /tasks
- [ ] Implement GET /tasks
- [ ] Implement PUT /tasks/{id}
- [ ] Implement DELETE /tasks/{id}

## Testing

- [ ] Create task tests
- [ ] Add validation tests
- [ ] Add update tests
- [ ] Add delete tests

จุดสำคัญคือ Task State ถูกเก็บในไฟล์ Markdown

ดังนั้นถ้า AI Session ถูกปิด เราสามารถเปิด Session ใหม่แล้วทำงานต่อจาก

- [x] Completed
- [ ] Not completed

ได้

#ขั้นตอนที่ 5: Review ก่อน Implementation

ก่อนใช้ /opsx:apply ควรตรวจสอบอย่างน้อย

Requirement
    ↓
ครบหรือไม่
    ↓
Scenario
    ↓
มี Happy Path หรือไม่
    ↓
มี Error Case หรือไม่
    ↓
Security
    ↓
มี Requirement ด้าน Security หรือไม่
    ↓
Testing
    ↓
สามารถสร้าง Test จาก Scenario ได้หรือไม่

ตัวอย่าง Prompt

Review this OpenSpec change.

Check for:

- missing requirements
- ambiguous behavior
- edge cases
- security problems
- API consistency
- testability

Do not implement code yet.

การแก้ Requirement ตอนที่ยังเป็น Markdown มีต้นทุนต่ำกว่าการแก้ Code หลังพัฒนาไปแล้วมาก

#ขั้นตอนที่ 6: Apply

เมื่อ Review Artifact แล้ว ให้ AI เริ่ม Implementation

/opsx:apply

หรือระบุ Change

/opsx:apply create-task-management-api

AI จะอ่าน

proposal.md
spec.md
design.md
tasks.md

จากนั้นทำงานตาม Tasks

Task 1
   ↓
Implement
   ↓
Test
   ↓
Mark Complete
   ↓
Task 2

ตัวอย่างสถานะ

- [x] Create tasks table
- [x] Create Task model
- [x] Implement POST /tasks
- [ ] Implement GET /tasks
- [ ] Add API tests

ถ้า Session หยุด สามารถกลับมาใช้ /opsx:apply เพื่อทำงานต่อได้

#ขั้นตอนที่ 7: Validate

OpenSpec มี CLI สำหรับตรวจสอบ Specification และ Change

openspec validate

ดู Change ที่กำลังทำงาน

openspec list

ดู Specification

openspec list --specs

เปิด Dashboard

openspec view

แนวทางหนึ่งคือเพิ่ม Validation เข้า CI/CD Pipeline

Pull Request
    ↓
OpenSpec Validate
    ↓
Unit Test
    ↓
Integration Test
    ↓
Security Scan
    ↓
Build

#ตัวอย่าง GitHub Actions

name: OpenSpec Validation

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install OpenSpec
        run: npm install -g @fission-ai/openspec@latest

      - name: Validate OpenSpec
        run: openspec validate

เราสามารถเพิ่มขั้นตอนอื่นต่อได้ เช่น

OpenSpec Validate
       ↓
npm test
       ↓
Playwright Test
       ↓
SonarQube
       ↓
Docker Build
       ↓
Deploy

#ขั้นตอนที่ 8: Verify

สำหรับ Expanded Workflow สามารถเปิดใช้คำสั่ง

/opsx:verify

เพื่อตรวจสอบว่า Implementation ตรงกับ Artifact หรือไม่

แนวคิดคือ

Specification
      ↓
Implementation
      ↓
Verification

ซึ่งช่วยลดปัญหาที่ Task ถูก Mark ว่าเสร็จ แต่ Behavior จริงของระบบยังไม่ตรง Specification

#ขั้นตอนที่ 9: Sync

OpenSpec มีคำสั่ง

/opsx:sync

สำหรับ Merge Delta Spec ของ Change เข้าสู่ Main Spec

แนวคิด

openspec/changes/<change>/specs/
             ↓
           Sync
             ↓
openspec/specs/

Sync มีประโยชน์ใน Change ที่ใช้เวลานาน หรือมีหลาย Change ทำงานขนานกัน

สำหรับ Change ปกติ อาจไม่จำเป็นต้องสั่ง Sync เอง เพราะ Archive สามารถจัดการขั้นตอนนี้ได้

#ขั้นตอนที่ 10: Archive

เมื่อ Implementation และ Testing เสร็จแล้ว

/opsx:archive

OpenSpec จะตรวจสอบ Artifact และ Task ก่อน Archive

จากนั้น Change จะถูกย้ายจาก

openspec/changes/add-authentication/

ไปเป็น

openspec/changes/archive/
└── YYYY-MM-DD-add-authentication/

และ Specification ที่เกี่ยวข้องจะถูก Merge เข้า Main Specs

ก่อน Archive

openspec/
├── specs/
└── changes/
    └── add-authentication/

หลัง Archive

openspec/
├── specs/
│   └── authentication/
│       └── spec.md
└── changes/
    └── archive/
        └── YYYY-MM-DD-add-authentication/

ดังนั้น

openspec/specs/

จะกลายเป็น Source of Truth สำหรับ Behavior ปัจจุบันของระบบ

#Workflow แบบสั้น

ถ้า Feature มีขนาดเล็กถึงกลางและ Requirement ชัด สามารถใช้

/opsx:propose add-logout
       ↓
Review
       ↓
/opsx:apply
       ↓
Test
       ↓
/opsx:archive

นี่เป็น Workflow ที่เหมาะกับงานทั่วไป

#Workflow แบบละเอียด

ถ้าต้องการควบคุม Artifact ทีละขั้น สามารถใช้ Expanded Workflow

ตั้งค่า Profile

openspec config profile

จากนั้น Refresh generated commands

openspec update

Workflow อาจเป็น

/opsx:new
    ↓
/opsx:continue
    ↓
Review
    ↓
/opsx:continue
    ↓
Review
    ↓
/opsx:ff
    ↓
/opsx:apply
    ↓
/opsx:verify
    ↓
/opsx:archive

เหมาะกับ

  • Feature ขนาดใหญ่
  • Architecture Change
  • ระบบที่มีความเสี่ยงสูง
  • Requirement ซับซ้อน
  • ต้องการ Review Artifact ทีละขั้น

#OpenSpec กับ Automated Testing

OpenSpec เหมาะกับ Automated Testing เพราะ Scenario ใน Spec สามารถ map ไปเป็น Test Case ได้โดยตรง

ตัวอย่าง Specification

#### Scenario: Login succeeds

- **WHEN** a user submits valid credentials
- **THEN** the API returns HTTP 200
- **THEN** the response contains an access token

สามารถแปลงเป็น Test

POST /login
    ↓
HTTP 200
    ↓
JSON.access_token exists

จากนั้น implement ด้วย

  • Playwright
  • Postman/Newman
  • pytest
  • JUnit
  • PHPUnit/Pest
  • Robot Framework

ได้

แนวทางที่ดีคือ

Requirement
     ↓
Scenario
     ↓
Test Case
     ↓
Automated Test
     ↓
CI Pipeline

#OpenSpec กับ Test-Driven Development

OpenSpec และ TDD ไม่ได้แทนที่กัน

แต่สามารถทำงานร่วมกันได้

OpenSpec
   ↓
Requirement + Scenario
   ↓
Write Failing Test
   ↓
Implement Code
   ↓
Pass Test
   ↓
Refactor

OpenSpec ช่วยตอบว่า

ต้องสร้าง Behavior อะไร

TDD ช่วยตอบว่า

เราจะพิสูจน์ Behavior นั้นด้วย Test อย่างไร

#OpenSpec กับ Git Workflow

สามารถกำหนดหนึ่ง Change ต่อหนึ่ง Feature Branch

ตัวอย่าง

Git Branch

feature/add-jwt-authentication

สัมพันธ์กับ

openspec/changes/add-jwt-authentication/

Workflow

Issue
  ↓
OpenSpec Change
  ↓
Feature Branch
  ↓
Implementation
  ↓
Automated Test
  ↓
Pull Request
  ↓
Review Spec + Code
  ↓
Merge
  ↓
Archive

การ Version Spec ไปพร้อม Source Code ทำให้สามารถตรวจสอบย้อนหลังได้ว่า

Code นี้เกิดจาก Requirement ใด

และ

Requirement นี้ถูก Implement ผ่าน Change ใด

#OpenSpec กับ Claude Code

หลัง openspec init หากเลือก Claude Code OpenSpec จะสร้าง Skill/Command files ที่ Claude Code สามารถใช้ได้

Workflow ตัวอย่าง

/opsx:explore

ตามด้วย

/opsx:propose add-user-authentication

จากนั้น

/opsx:apply

และ

/opsx:archive

#OpenSpec กับ Codex

OpenSpec รองรับ Codex เช่นกัน แต่ชื่อ Invocation อาจแตกต่างจาก Canonical /opsx:*

ตัวอย่างที่เอกสารระบุสำหรับ Codex คือ

$openspec-propose

ดังนั้นหลัง openspec init ควรใช้รูปแบบคำสั่งที่ CLI แสดงสำหรับ Codex โดยตรง

แนวทางการทำงานยังเหมือนเดิม

Explore
   ↓
Propose
   ↓
Review
   ↓
Apply
   ↓
Verify
   ↓
Archive

#OpenSpec กับ Cursor

สำหรับ Cursor คำสั่งบางชุดอาจถูกสร้างในรูปแบบ

/opsx-propose
/opsx-apply
/opsx-archive

แทน Canonical Syntax

/opsx:propose

ดังนั้นไม่ควรจำ Syntax เพียงแบบเดียว แต่ควรดูคำสั่งที่ openspec init สร้างสำหรับ Tool ที่ใช้งาน

#ตัวอย่างระบบ Authentication

สมมติต้องการสร้าง JWT Authentication

เริ่มจาก

/opsx:explore

Prompt

Analyze authentication requirements for a REST API.

Requirements:

- login with email/password
- access token
- refresh token
- logout
- protected routes
- rate limiting
- failed login protection

Identify missing security requirements and edge cases.

Do not implement code.

จากนั้น

/opsx:propose add JWT authentication

AI อาจสร้าง

openspec/changes/add-jwt-authentication/
├── proposal.md
├── design.md
├── tasks.md
└── specs/
    └── authentication/
        └── spec.md

ตัวอย่าง Spec

## ADDED Requirements

### Requirement: User authentication

The system SHALL authenticate registered users
using email and password.

#### Scenario: Successful authentication

- **WHEN** valid credentials are submitted
- **THEN** the API returns HTTP 200
- **THEN** an access token is returned

#### Scenario: Invalid credentials

- **WHEN** invalid credentials are submitted
- **THEN** the API returns HTTP 401

### Requirement: Refresh token

The system SHALL issue a refresh token
after successful authentication.

#### Scenario: Valid refresh token

- **WHEN** a valid refresh token is submitted
- **THEN** a new access token is issued

จากนั้น Review

Security?
Token expiration?
Refresh rotation?
Logout?
Revocation?
Rate limiting?
Brute force protection?

เมื่อ Specification ชัดเจนจึงใช้

/opsx:apply

#OpenSpec กับระบบขนาดใหญ่

สำหรับระบบที่มีหลาย Module ไม่ควรสร้าง Change เดียวว่า

build-complete-enterprise-system

ควรแบ่งเป็น Capability

add-authentication
add-user-profile
add-product-catalog
add-order-management
add-payment
add-notification

แต่ละ Change มี Scope ชัดเจน

Capability
    ↓
Requirements
    ↓
Scenarios
    ↓
Tasks
    ↓
Implementation

ช่วยลด Context ที่ AI ต้องประมวลผลในแต่ละครั้ง

#Best Practices

#1. ใช้ Explore ก่อนถ้า Requirement ยังไม่ชัด

อย่าเริ่มจาก

Build the entire system.

ถ้ายังไม่รู้ Behavior ที่ชัดเจน

ใช้

/opsx:explore

เพื่อให้ AI ช่วยวิเคราะห์ Requirement ก่อน

#2. เขียน Spec เป็น Behavior

ไม่ควรเขียน

Create AuthController and JwtService.

เพราะเป็น Implementation Detail

ควรเขียน

The system SHALL return an access token
after successful authentication.

#3. ทุก Requirement ควรมี Scenario

ตัวอย่าง

### Requirement: Delete task

The system SHALL allow the owner to delete a task.

#### Scenario: Owner deletes task

- **WHEN** the owner deletes an existing task
- **THEN** the task is removed

#### Scenario: Other user attempts deletion

- **WHEN** another user attempts to delete the task
- **THEN** the request is rejected

#4. Review ก่อน Apply

Workflow ที่แนะนำ

Propose
   ↓
Review Proposal
   ↓
Review Spec
   ↓
Review Design
   ↓
Review Tasks
   ↓
Apply

อย่าใช้

Propose
   ↓
Apply ทันที

โดยไม่ตรวจ Artifact สำหรับ Change ที่มีผลกระทบสำคัญ

#5. Commit OpenSpec เข้า Git

ควร Version Control

openspec/

ไปพร้อม Source Code

เพราะเป็นส่วนหนึ่งของ Engineering Knowledge ของ Project

#6. แบ่ง Change ให้เล็กพอ

Change ที่ดีควร

สามารถอธิบาย Scope ได้ชัด
Review ได้
Test ได้
Implement ได้เป็นลำดับ

ถ้า tasks.md มีหลายสิบงานใหญ่ ควรพิจารณาแยก Change

#7. ผูก Scenario กับ Test

ทุก Scenario สำคัญควรมี Test รองรับ

Spec Scenario
      ↓
Test
      ↓
CI

ทำให้ Specification ไม่กลายเป็นเอกสารที่ไม่มีใครตรวจสอบ

#ตัวอย่าง Development Loop ที่แนะนำ

1. Explore
      ↓
2. Propose
      ↓
3. Review Requirements
      ↓
4. Review Design
      ↓
5. Review Tasks
      ↓
6. Apply
      ↓
7. Automated Testing
      ↓
8. Verify / Validate
      ↓
9. Sync
      ↓
10. Archive

หรือสรุปสั้น ๆ

Think
  ↓
Specify
  ↓
Review
  ↓
Build
  ↓
Test
  ↓
Archive

#เปรียบเทียบ Prompt-Driven กับ Spec-Driven Development

ประเด็น Prompt-Driven OpenSpec / Spec-Driven
Requirement อยู่ใน Chat อยู่ใน Repository
Review ก่อน Coding ทำได้ยาก ทำได้ชัดเจน
AI Context พึ่ง Conversation พึ่ง Artifact
Traceability ต่ำ สูง
Automated Testing อาจเพิ่มภายหลัง Mapping จาก Scenario ได้
ทำงานต่อ Session ใหม่ Context อาจหาย อ่าน Spec/Tasks ต่อได้
Change History อยู่ใน Git เฉพาะ Code เก็บ Spec + Change
เหมาะกับระบบใหญ่ เสี่ยง Context Drift จัดการ Scope ได้ดีกว่า

#เมื่อไรควรใช้ OpenSpec

OpenSpec เหมาะกับ

REST API
Microservices
SaaS
Enterprise Application
AI-assisted Development
Refactoring
Large Existing Codebase
Feature Development
Security-sensitive Change
Systems with Automated Testing

อาจไม่จำเป็นสำหรับงานเล็กมาก เช่น

แก้ typo
เปลี่ยนสี CSS เล็กน้อย
แก้ข้อความหนึ่งบรรทัด

แต่ถ้า Change มีผลต่อ Behavior ของระบบ การมี Specification จะเริ่มมีประโยชน์ทันที

#OpenSpec ใน Software Engineering Workflow

เมื่อรวม OpenSpec กับเครื่องมืออื่น เราจะได้ Workflow เช่น

flowchart TD
    A[Requirement]
    B[OpenSpec Explore]
    C[Proposal + Specification]
    D[Human Review]
    E[AI Coding Assistant]
    F[Unit Test]
    G[API / Integration Test]
    H[OpenSpec Validate]
    I[CI/CD]
    J[Deployment]
    K[Archive]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I
    I --> J
    J --> K

นี่คือจุดที่ OpenSpec มีคุณค่ามาก เพราะมันทำหน้าที่เป็น Interface ระหว่าง Requirement, Human Review และ AI Implementation

#Quick Start

สำหรับผู้ที่ต้องการทดลองอย่างรวดเร็ว

#1. ตรวจสอบ Node.js

node --version

ต้องเป็น

>= 20.19.0

#2. ติดตั้ง OpenSpec

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

#3. เข้า Project

cd my-project

#4. Initialize

openspec init

#5. สำรวจ Requirement

ใน AI Coding Assistant

/opsx:explore

#6. สร้าง Change

/opsx:propose add authentication

#7. Review

ตรวจ

proposal.md
spec.md
design.md
tasks.md

#8. Implement

/opsx:apply

#9. Validate

ใน Terminal

openspec validate

#10. Archive

ใน AI Coding Assistant

/opsx:archive

#สรุป

OpenSpec ช่วยเปลี่ยนการพัฒนาระบบด้วย AI จากแนวทาง

Prompt
   ↓
Generate Code
   ↓
แก้ไปเรื่อย ๆ

ไปเป็น

Requirement
    ↓
Specification
    ↓
Review
    ↓
Implementation
    ↓
Automated Testing
    ↓
Verification
    ↓
Archive

หัวใจสำคัญไม่ใช่เพียงการมีเอกสารเพิ่ม แต่คือการทำให้ Human และ AI ใช้ Requirement ชุดเดียวกัน

ผลลัพธ์ที่ได้คือ

  • Requirement ชัดขึ้น
  • ลดการตีความผิดของ AI
  • Review ก่อนเขียน Code ได้
  • มี Source of Truth
  • ทำงานต่อข้าม AI Session ได้ง่าย
  • เชื่อม Requirement กับ Automated Test ได้
  • เก็บประวัติ Change ใน Git ได้
  • ลด Context Drift
  • เหมาะกับการพัฒนาระบบด้วย AI Coding Agent

ถ้าทีมกำลังใช้ Claude Code, Codex, Cursor หรือ AI Coding Assistant เป็นส่วนหนึ่งของ Software Development Lifecycle การนำ OpenSpec เข้ามาช่วยจัดการ Requirement และ Change จะช่วยยกระดับจาก Prompt-Driven Development ไปสู่ Spec-Driven Development ที่ตรวจสอบและทำซ้ำได้มากขึ้น

#References

  1. OpenSpec Documentation
    https://openspec.dev/

  2. OpenSpec Installation
    https://openspec.dev/docs/installation

  3. OpenSpec GitHub Repository
    https://github.com/Fission-AI/OpenSpec

  4. OpenSpec Commands
    https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md

  5. How OpenSpec Commands Work
    https://github.com/Fission-AI/OpenSpec/blob/main/docs/how-commands-work.md

  6. OpenSpec Examples and Recipes
    https://github.com/Fission-AI/OpenSpec/blob/main/docs/examples.md