OpenSpec: viết spec trước, để AI code sau — spec-driven development gọn nhẹ

Giao cho coding agent một câu “làm tính năng đăng nhập bằng Google” thì nó sẽ làm — nhưng làm theo cách nó hiểu. Sai lệch giữa ý bạn và ý agent thường chỉ lộ ra khi đọc diff vài nghìn dòng. Spec-driven development (SDD) đảo thứ tự: người và AI thống nhất làm gì bằng một bản spec ngắn trước, rồi mới viết code. OpenSpec của Fission AI là một framework SDD gọn nhẹ, chạy trên chính các công cụ bạn đang dùng.

OpenSpec là gì?

OpenSpec thêm một lớp spec nhẹ vào repo, để cả bạn và agent đọc cùng một nguồn sự thật. Giấy phép MIT, hoạt động với hơn 30 trợ lý AI như Claude Code, Cursor, GitHub Copilot, Codex… mà không cần API key riêng. Triết lý được nêu trong README:

• Linh hoạt, không cứng nhắc; lặp nhanh, không kiểu thác nước.
• Dễ dùng, không phức tạp.
• Thiết kế cho codebase đang chạy (brownfield), không chỉ dự án mới.
• Mở rộng được từ dự án cá nhân tới doanh nghiệp.

Cài đặt

# Node.js 20.19.0 trở lên
npm install -g @fission-ai/openspec@latest
# hoặc: brew install openspec

cd your-project
openspec init      # chọn công cụ AI bạn dùng, sinh lệnh và hướng dẫn cho agent
openspec update    # làm mới hướng dẫn và slash command sau khi nâng cấp

Cấu trúc thư mục

openspec/
├── specs/                      # spec hiện hành của hệ thống
└── changes/
    ├── add-google-login/       # mỗi thay đổi một thư mục
    │   ├── proposal.md         # vì sao làm, thay đổi gì
    │   ├── specs/              # yêu cầu + kịch bản (WHEN/THEN)
    │   ├── design.md           # hướng tiếp cận kỹ thuật
    │   └── tasks.md            # checklist triển khai
    └── archive/                # thay đổi đã xong, đánh dấu ngày

Spec là Markdown thuần. Yêu cầu được viết theo dạng có kịch bản kiểm chứng, ví dụ:

## ADDED Requirements
### Requirement: Đăng nhập bằng Google
Người dùng có thể đăng nhập bằng tài khoản Google.

#### Scenario: Lần đầu đăng nhập
- WHEN người dùng chọn "Tiếp tục với Google" và cấp quyền
- THEN hệ thống tạo tài khoản mới và chuyển tới trang chào mừng

Vòng đời một thay đổi

Cú pháp lệnh khác nhau theo công cụ: /opsx:propose là dạng chuẩn, Cursor và Copilot dùng /opsx-propose, Codex dùng $openspec-propose. Profile mở rộng (bật qua openspec config profile) có thêm /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard.

So với các lựa chọn khác

Đây là so sánh do chính OpenSpec đưa ra — cách tốt nhất là thử cả hai trên một feature nhỏ rồi chọn.

Mẹo dùng hiệu quả

• Xoá context trước khi apply: README khuyên dọn context sau bước lên kế hoạch để agent tập trung vào spec, không bị nhiễu bởi cuộc thảo luận trước.
• Dùng model mạnh cho bước propose — sai ở spec sẽ nhân lên ở code.
• Stores (beta): giữ phần lập kế hoạch trong một repo dùng chung, nhiều repo tham chiếu — hợp tính năng xuyên nhiều service.
• Telemetry: chỉ thu tên lệnh và phiên bản, tự tắt trong CI; tắt hẳn bằng openspec config set telemetry.enabled false hoặc DO_NOT_TRACK=1.

Vì sao PM nên quan tâm?

• proposal.md + kịch bản WHEN/THEN chính là “ticket có acceptance criteria” mà agent đọc được và bạn review được.
• Review spec vài trăm dòng nhanh hơn nhiều so với review diff vài nghìn dòng — và sai sót được bắt sớm hơn.
• Spec nằm trong repo, đi cùng code → giảm “kiến thức truyền miệng”; người mới đọc openspec/specs là hiểu hệ thống đang làm gì.

Áp dụng thế nào?

• Dev: Chọn một feature nhỏ tiếp theo, chạy /opsx:propose, sửa spec cho đúng ý, rồi mới /opsx:apply. So sánh số vòng sửa với cách giao việc thông thường.
• Tech Lead: Đưa bước “review proposal” vào quy trình — PR không có change spec tương ứng thì không merge với các thay đổi lớn.
• PM: Viết phần “vì sao” và kịch bản WHEN/THEN trong proposal cùng team. Đây là nơi tốt nhất để PM góp ý trước khi tốn token và công sức vào code.