OpenSpec: Phương pháp spec-driven development giúp AI coding agent viết code đúng ngay từ đầu

Tóm tắt nhanh (Key Takeaways)

• OpenSpec là CLI framework mã nguồn mở (MIT) do Fission AI phát triển, áp dụng spec-driven development (SDD) để buộc con người và AI thống nhất yêu cầu trước khi viết bất kỳ dòng code nào.
• Chỉ cần ba lệnh cốt lõi: /opsx:propose tạo đặc tả, /opsx:apply triển khai, /opsx:archive lưu trữ và hợp nhất spec, đủ để vận hành toàn bộ vòng đời một tính năng.
• OpenSpec hỗ trợ hơn 25 AI coding assistant phổ biến, bao gồm Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI – không bị ràng buộc vào bất kỳ một vendor hay IDE nào.
• Hệ thống delta spec (ADDED / MODIFIED / REMOVED) là điểm mạnh đặc thù, thiết kế riêng cho brownfield codebase – phù hợp với thực tế phần lớn công việc là sửa đổi hệ thống hiện có, không phải xây mới từ đầu.
• Cài đặt và khởi chạy chỉ mất vài phút: npm install -g @fission-ai/openspec@latest rồi openspec init trong thư mục dự án.

Khi AI coding assistant trở nên đủ mạnh để tự viết hàng trăm dòng code theo một prompt đơn giản, vấn đề không còn nằm ở “AI có làm được không” – mà nằm ở “AI có làm đúng thứ bạn muốn không”. Vòng lặp quen thuộc của nhiều developer hiện nay là: mô tả yêu cầu trong chat, nhận về code, phát hiện sai, mô tả lại, nhận về code khác, lại sai theo cách khác. Lịch sử cuộc hội thoại không phải là tài liệu kỹ thuật, và AI không có bộ nhớ đủ để nhất quán qua nhiều phiên làm việc.

OpenSpec ra đời để giải quyết đúng vấn đề đó. Đây không phải một AI model, không phải một IDE plugin – mà là một lớp quy trình mỏng giữa developer và AI agent, buộc cả hai phía thống nhất đặc tả trước khi bất kỳ dòng code nào được sinh ra.

OpenSpec là gì và tại sao nó tồn tại?

OpenSpec là một CLI framework mã nguồn mở, triển khai phương pháp spec-driven development (SDD) cho AI coding assistant. Dự án do Fission AI phát triển, phát hành theo giấy phép MIT và có mặt trên npm dưới tên @fission-ai/openspec.

Triết lý thiết kế của OpenSpec gói gọn trong bốn nguyên tắc:

• Fluid, không cứng nhắc: không có phase gate, bạn có thể cập nhật bất kỳ artifact nào vào bất kỳ lúc nào.
• Iterative, không waterfall: yêu cầu thay đổi khi hiểu biết sâu hơn, OpenSpec chấp nhận điều đó.
• Đơn giản, không phức tạp: khởi tạo trong vài giây, không cần cấu hình nặng nề.
• Brownfield-first: được thiết kế để làm việc với codebase đang tồn tại, không chỉ dự án mới xây từ đầu.

Điểm khác biệt cốt lõi so với cách làm thông thường: thay vì để yêu cầu tồn tại dưới dạng lịch sử chat dễ mất và khó truy vết, OpenSpec tạo ra một thư mục openspec/ trong dự án, lưu trữ toàn bộ đặc tả dưới dạng file Markdown có cấu trúc rõ ràng, đọc được bởi cả con người lẫn AI.

Cài đặt OpenSpec

Yêu cầu duy nhất là Node.js 20.19.0 trở lên.

Bước 1: Cài đặt CLI global

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

Bước 2: Khởi tạo trong dự án

cd your-project
openspec init

Lệnh openspec init sẽ hỏi bạn muốn cấu hình cho những AI tool nào. OpenSpec tự động tạo các file skill và slash command tương ứng vào đúng thư mục mà từng tool mong đợi.

Nếu muốn cấu hình không tương tác (cho CI/CD):

# Chỉ cấu hình cho Claude Code và Cursor
openspec init --tools claude,cursor

# Cấu hình cho tất cả tool được hỗ trợ
openspec init --tools all

Cập nhật khi có phiên bản mới:

npm install -g @fission-ai/openspec@latest
openspec update   # Tái tạo file hướng dẫn AI trong dự án

Cấu trúc thư mục và khái niệm cốt lõi

Sau khi openspec init, dự án của bạn có thêm thư mục openspec/ với cấu trúc:

openspec/
  specs/              # Source of truth - hành vi hiện tại của hệ thống
    <domain>/
      spec.md
  changes/            # Các thay đổi đang đề xuất
    <change-name>/
      proposal.md     # Tại sao và thay đổi gì
      design.md       # Giải pháp kỹ thuật
      tasks.md        # Checklist triển khai
      specs/          # Delta specs (thay đổi so với spec gốc)

Hai thư mục quan trọng nhất:

• specs/ là nguồn sự thật duy nhất, mô tả hệ thống đang hoạt động như thế nào.
• changes/ chứa các thay đổi đang được đề xuất, mỗi thay đổi một thư mục riêng, tách biệt hoàn toàn và có thể làm song song mà không xung đột.

Delta specs: điểm khác biệt quan trọng

Thay vì viết lại toàn bộ spec mỗi lần thay đổi, OpenSpec dùng delta spec – chỉ mô tả phần thay đổi so với spec hiện tại, theo ba nhóm rõ ràng:

## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.

## MODIFIED Requirements
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)

## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA)

Khi archive, OpenSpec tự động hợp nhất delta này vào specs/ chính xác theo từng loại: ADDED thêm vào, MODIFIED ghi đè, REMOVED xóa đi.

Hướng dẫn sử dụng: luồng làm việc thực tế

Luồng cốt lõi (3 lệnh)

Đây là luồng mặc định, đủ dùng cho hầu hết mọi trường hợp:

1. Đề xuất thay đổi

/opsx:propose add-dark-mode

AI tạo ngay toàn bộ thư mục openspec/changes/add-dark-mode/ với proposal.md, design.md, tasks.md và delta spec. Bạn đọc, chỉnh sửa, thống nhất nội dung trước khi làm bất cứ điều gì tiếp theo.

2. Triển khai

/opsx:apply

AI đi qua từng task trong tasks.md, tích checkbox khi hoàn thành. Nếu phát hiện cần điều chỉnh thiết kế, bạn cập nhật design.md và tiếp tục mà không phải bắt đầu lại.

3. Lưu trữ và hợp nhất

/opsx:archive

Delta spec hợp nhất vào specs/, thư mục change chuyển sang openspec/changes/archive/ với tiền tố ngày tháng để tra cứu sau này.

Luồng mở rộng (cho dự án phức tạp hơn)

Khi cần kiểm soát chi tiết hơn, bật luồng mở rộng:

openspec config profile   # Chọn profile mở rộng
openspec update           # Tái tạo các slash command

Luồng mở rộng cho phép dùng thêm: /opsx:new, /opsx:ff (fast-forward tạo toàn bộ artifact), /opsx:continue (tạo từng bước), /opsx:verify (kiểm tra code đã triển khai khớp spec chưa), /opsx:sync, /opsx:onboard.

Các lệnh CLI hữu ích

openspec list                     # Xem các change đang hoạt động
openspec show add-dark-mode       # Xem chi tiết một change
openspec validate add-dark-mode   # Kiểm tra cấu trúc spec
openspec view                     # Mở dashboard tương tác

Các AI tool được hỗ trợ

OpenSpec hiện hỗ trợ hơn 25 AI coding assistant, bao gồm:

OpenSpec khuyến nghị dùng các model reasoning cao như Claude Opus 4.5 hoặc GPT 5.2 để đạt kết quả tốt nhất ở bước lập kế hoạch lẫn triển khai.

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

Điểm mạnh thực sự của OpenSpec là tính agnostic: cùng một workflow, cùng một file spec, dùng được với Cursor hôm nay và Claude Code ngày mai mà không cần cấu hình lại từ đầu. Đây là thứ Kiro không thể cung cấp vì nó gắn chặt vào IDE của Amazon.

Vô hiệu hóa telemetry

OpenSpec thu thập dữ liệu sử dụng ẩn danh (chỉ tên lệnh và phiên bản, không thu thập nội dung hay đường dẫn file). Để tắt:

export OPENSPEC_TELEMETRY=0
# hoặc
export DO_NOT_TRACK=1

Telemetry tự động bị tắt trong môi trường CI.

OpenSpec đặt ra một câu hỏi đơn giản nhưng quan trọng: tại sao chúng ta lại tin tưởng AI viết code cho mình nhưng không tin tưởng vào việc đọc một tài liệu đặc tả rõ ràng trước khi làm? Spec-driven development không phải khái niệm mới, nhưng OpenSpec là công cụ đầu tiên đưa nó vào workflow AI coding theo cách thực sự nhẹ nhàng, không ràng buộc vendor và hoạt động tốt với codebase đang tồn tại.

Nếu bạn đang dùng bất kỳ AI coding assistant nào và thường xuyên phải sửa đi sửa lại vì AI “không hiểu đúng ý”, openspec init là bước tiếp theo đáng thử ngay hôm nay.