Spec-Driven Development Skill

Plan first, then build. สร้าง Requirements → Design → Tasks ก่อน แล้วค่อย Code

Skill เป็น workflow ที่เน้นการวางแผนอย่างเป็นระบบ ก่อนเขียน code ทุกครั้ง ลดความผิดพลาด ลดการทำซ้ำ และสร้าง documentation

Features

• Structured Planning — 3 เฟสชัดเจน: Requirements → Design → Tasks
• GIVEN/WHEN/THEN — Acceptance criteria แบบ Gherkin ที่ทดสอบได้
• Mermaid Diagrams — Architecture และ Sequence diagrams อัตโนมัติ
• Traceability — ทุก task อ้างอิงกลับไปหา requirement
• Progress Tracking — [ ] [/] [x] สำหรับ track progress
• Human-in-the-Loop — ต้อง approve ก่อนไปเฟสถัดไป
• 3 Workflow Variants — Requirements-First, Design-First, Bugfix Mode
• Agent-Compatible — ใช้ได้กับ AI agent ทุกตัว

โครงสร้าง Skill

spec-driven-dev/
├── SKILL.md                              # คำสั่งหลัก (AI Agent อ่านไฟล์นี้)
├── README.md                             # คู่มือนี้
├── templates/
│   ├── requirements.template.md          # เทมเพลต: กำหนดว่า "ทำอะไร"
│   ├── design.template.md                # เทมเพลต: กำหนดว่า "ทำยังไง"
│   └── tasks.template.md                 # เทมเพลต: แผนการทำงาน
├── examples/
│   ├── example-requirements.md           # ตัวอย่าง: Shopping Cart requirements
│   ├── example-design.md                 # ตัวอย่าง: Shopping Cart design
│   └── example-tasks.md                  # ตัวอย่าง: Shopping Cart tasks
└── scripts/
    ├── init-spec.sh                      # Script สร้าง spec ใหม่ (Linux/Mac)
    └── init-spec.bat                     # Script สร้าง spec ใหม่ (Windows)

การติดตั้ง

วิธีที่ 1: ติดตั้งผ่าน npx (แนะนำ)

รันคำสั่งเดียวที่ root ของ project:

npx spec-driven-dev

ระบบจะถามว่าต้องการติดตั้งลง IDE ตัวไหน แล้วคัดลอกไฟล์ให้อัตโนมัติ

ถ้าต้องการระบุ IDE เลย ใช้ --target:

# ติดตั้งลง Gemini CLI / Antigravity
npx spec-driven-dev --target gemini

# ติดตั้งลง Cursor
npx spec-driven-dev --target cursor

# ติดตั้งลง Windsurf
npx spec-driven-dev --target windsurf

# ติดตั้งลง GitHub Copilot
npx spec-driven-dev --target copilot

# ติดตั้งลง path ที่กำหนดเอง
npx spec-driven-dev --target ./my-custom-path

สร้าง spec ใหม่สำหรับ feature:

npx spec-driven-dev --init user-authentication

วิธีที่ 2: คัดลอกด้วยตัวเอง

คัดลอกโฟลเดอร์ spec-driven-dev ไปวางในโฟลเดอร์ skills ของเครื่องมือที่ใช้:

# Gemini CLI / Antigravity
Copy-Item -Recurse "spec-driven-dev" ".gemini\skills\spec-driven-dev"

# Cursor
Copy-Item -Recurse "spec-driven-dev" ".cursor\skills\spec-driven-dev"

# Windsurf
Copy-Item -Recurse "spec-driven-dev" ".windsurf\skills\spec-driven-dev"

เครื่องมืออื่นๆ

ชี้ให้ AI agent อ่านไฟล์ SKILL.md โดยตรง หรือ copy เนื้อหาเข้า system prompt

วิธีใช้งาน

วิธีที่ 1: บอก AI Agent โดยตรง

พิมพ์ประโยคแบบนี้ใน chat:

สร้าง spec สำหรับ feature ระบบ login

ช่วย spec feature ตะกร้าสินค้า ตาม spec-driven-dev skill

Start a spec for user-authentication using the spec-driven-dev skill

Agent จะเริ่มทำตาม workflow 3 เฟสอัตโนมัติ

วิธีที่ 2: ใช้ Script สร้างโครงสร้างก่อน

# Windows
.\scripts\init-spec.bat user-authentication

# Linux / Mac
bash scripts/init-spec.sh user-authentication

จะได้โครงสร้าง:

.specs/user-authentication/
├── requirements.md    <- เทมเพลตพร้อมแก้ไข
├── design.md          <- เทมเพลตพร้อมแก้ไข
└── tasks.md           <- เทมเพลตพร้อมแก้ไข

แล้วบอก agent: "ช่วยเติม spec ใน .specs/user-authentication/"

Workflow 3 เฟส

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│    Phase 1      │      │    Phase 2      │      │    Phase 3      │
│  REQUIREMENTS   │ -->  │     DESIGN      │ -->  │     TASKS       │
│                 │      │                 │      │                 │
│  กำหนดว่า       │      │  กำหนดว่า       │      │  แผนการทำงาน    │
│  "ทำอะไร"       │      │  "ทำยังไง"      │      │  ทีละขั้นตอน     │
│                 │      │                 │      │                 │
│  - User Stories │      │  - Architecture │      │  - Task List    │
│  - GIVEN/WHEN/  │      │  - Components   │      │  - Phases       │
│    THEN         │      │  - Data Models  │      │  - Verification │
│  - Edge Cases   │      │  - API Contracts│      │  - Status [x]   │
└────────┬────────┘      └────────┬────────┘      └────────┬────────┘
         │                        │                        │
    คุณ approve              คุณ approve              คุณ approve
                                                           │
                                                      เริ่ม code!

เฟส 1 — Requirements (requirements.md)

กำหนด "ทำอะไร" จากมุมมองผู้ใช้

# Feature: ระบบ Login

## User Story
**As a** ผู้ใช้ทั่วไป,
**I want to** เข้าสู่ระบบด้วย email และ password,
**so that** ฉันสามารถเข้าถึงข้อมูลส่วนตัวของฉันได้.

## Acceptance Criteria

### AC-1.1: เข้าสู่ระบบสำเร็จ
**Given** ผู้ใช้อยู่ที่หน้า login
**And** มีบัญชีอยู่แล้วในระบบ
**When** กรอก email และ password ที่ถูกต้อง แล้วกดปุ่ม "Login"
**Then** ระบบพาไปหน้า dashboard
**And** แสดงชื่อผู้ใช้ที่มุมบนขวา

### AC-1.2: กรอก password ผิด
**Given** ผู้ใช้อยู่ที่หน้า login
**When** กรอก email ถูกต้อง แต่ password ผิด
**Then** แสดงข้อความ "อีเมลหรือรหัสผ่านไม่ถูกต้อง"
**And** ไม่บอกว่าผิดอันไหน (เพื่อความปลอดภัย)

คุณรีวิว -> แก้ไข -> approve -> ไปเฟส 2

เฟส 2 — Design (design.md)

กำหนด "ทำยังไง" ในเชิงเทคนิค

## Architecture
┌──────────┐     ┌──────────┐     ┌──────────┐
│  React   │ --> │  Express │ --> │ Postgres │
│  Frontend│     │  API     │     │ Database │
└──────────┘     └──────────┘     └──────────┘

## Component: AuthService
- Responsibility: จัดการ login, logout, token refresh
- Location: src/server/services/AuthService.ts

## API Contract
POST /api/auth/login
Request:  { "email": "string", "password": "string" }
Response: { "token": "jwt", "user": { "id", "name" } }

คุณรีวิว -> แก้ไข -> approve -> ไปเฟส 3

เฟส 3 — Tasks (tasks.md)

แผนการทำงานเป็น checklist

## Phase 1: Database
- [x] Task 1.1: สร้าง users table migration
- [x] Task 1.2: สร้าง User model

## Phase 2: Backend API
- [/] Task 2.1: สร้าง POST /api/auth/login     <- กำลังทำ
- [ ] Task 2.2: สร้าง JWT middleware
- [ ] Task 2.3: สร้าง rate limiting

## Phase 3: Frontend
- [ ] Task 3.1: สร้าง LoginForm component
- [ ] Task 3.2: สร้าง auth context/store
- [ ] Task 3.3: สร้าง protected route

## Phase 4: Testing
- [ ] Task 4.1: Unit tests สำหรับ AuthService
- [ ] Task 4.2: E2E test login flow

คุณ approve -> Agent เริ่ม code ทีละ task

Workflow Variants

1. Requirements-First (ค่าเริ่มต้น)

เหมาะกับ feature ใหม่ ที่เน้น business logic

requirements.md -> design.md -> tasks.md

ใช้เมื่อ: สร้างฟีเจอร์ใหม่ตั้งแต่ต้น

2. Design-First

เหมาะกับ ระบบซับซ้อน ที่มีข้อจำกัดทางเทคนิค

design.md -> requirements.md (derived) -> tasks.md

ใช้เมื่อ: มี architecture constraints, performance requirements, หรือต้อง integrate กับระบบเดิม

3. Bugfix Mode

เหมาะกับ bug ที่ซับซ้อน ต้องวิเคราะห์ root cause

bugfix.md -> design.md (root cause + fix) -> tasks.md

ใช้เมื่อ: Bug ที่ reproduce ยาก หรือเกี่ยวข้องหลาย component

ตัวอย่างคำสั่งสำหรับ AI Agent

| สถานการณ์ | พูดกับ Agent ว่า | |----------|-----------------| | เริ่ม feature ใหม่ | "สร้าง spec สำหรับ feature [ชื่อ]" | | Fix bug ซับซ้อน | "สร้าง bugfix spec สำหรับ [ปัญหา]" | | มี design อยู่แล้ว | "เริ่มจาก design-first สำหรับ [ชื่อ]" | | Approve เฟส | "approve แล้ว ไปเฟสถัดไป" | | เริ่ม code | "approve tasks แล้ว เริ่ม execute ได้เลย" | | แก้ requirement | "แก้ AC-1.2 เป็น... แล้ว sync ลง tasks" | | ดูตัวอย่าง | "ดูตัวอย่าง requirements จาก examples" | | สร้างจากเทมเพลต | "สร้าง requirements จาก template" |

Output ที่ได้

เมื่อใช้ skill นี้กับ project จะได้โครงสร้าง:

your-project/
├── .specs/
│   ├── user-authentication/
│   │   ├── requirements.md       <- Approved
│   │   ├── design.md             <- Approved
│   │   └── tasks.md              <- In Progress (12/15 tasks done)
│   │
│   ├── shopping-cart/
│   │   ├── requirements.md       <- Approved
│   │   ├── design.md             <- Draft
│   │   └── tasks.md              <- Not Started
│   │
│   └── payment-integration/
│       └── requirements.md       <- Draft
│
├── src/
│   └── ...                       <- code ที่สร้างจาก tasks
└── ...

หลักการสำคัญ

| หลักการ | คำอธิบาย | |---------|---------| | Plan First | วางแผนก่อน code เสมอ | | Traceability | ทุก task อ้างอิงกลับไป requirement | | Human-in-the-Loop | คนต้อง approve ก่อนทุกเฟส | | Small Tasks | แต่ละ task เล็กพอทำจบได้ในรอบเดียว | | Living Documentation | Spec อัปเดตตาม code ที่เปลี่ยน | | Verify Often | ทุกเฟสมี verification step |

ไฟล์ Reference

| ไฟล์ | คำอธิบาย | |------|---------| | SKILL.md | คำสั่งหลักที่ AI Agent อ่าน | | templates/requirements.template.md | เทมเพลต requirements | | templates/design.template.md | เทมเพลต design | | templates/tasks.template.md | เทมเพลต tasks | | examples/example-requirements.md | ตัวอย่าง requirements (Shopping Cart) | | examples/example-design.md | ตัวอย่าง design (Shopping Cart) | | examples/example-tasks.md | ตัวอย่าง tasks (Shopping Cart) |

Compatibility

| เครื่องมือ | รองรับ | วิธีติดตั้ง | |-----------|-------|-----------| | Google Antigravity / Gemini CLI | Yes | .gemini/skills/ | | Cursor | Yes | .cursor/skills/ | | Windsurf | Yes | .windsurf/skills/ | | Claude (Anthropic) | Yes | ใส่ SKILL.md ใน system prompt | | ChatGPT / GPT-4 | Yes | ใส่ SKILL.md ใน system prompt | | GitHub Copilot | Yes | .github/copilot/skills/ | | อื่นๆ | Yes | อ้างอิง SKILL.md โดยตรง |