# OpenSpec: viết spec trước khi AI code, bớt làm sai — hướng dẫn cài đặt và dùng

> OpenSpec là công cụ dòng lệnh (CLI) giúp làm việc kiểu spec-driven development với trợ lý AI lập trình: bạn và AI chốt đề xuất, yêu cầu, thiết kế, danh sách việc bằng file Markdown rồi mới code. Cài bằng một lệnh hoặc npm/Homebrew, sau đó chạy openspec init trong dự án. Người mới dùng được ngay, miễn là đã có một trợ lý AI lập trình được hỗ trợ.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-16 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/openspec-spec-driven-development-cho-tro-ly-ai-lap-trinh

OpenSpec là một công cụ dòng lệnh giúp bạn làm việc có kế hoạch với trợ lý AI lập trình. Thay vì gõ một yêu cầu mơ hồ vào khung chat rồi cầu may, bạn và AI cùng viết ra "spec" (bản mô tả cần làm gì) bằng Markdown, đọc lại, chốt xong mới bắt đầu code.

Vấn đề repo giải quyết rất quen thuộc: yêu cầu chỉ nằm trong lịch sử chat, chat dài ra là AI quên hoặc làm lệch ý. OpenSpec đặt mỗi thay đổi vào một thư mục riêng, có đề xuất, yêu cầu, thiết kế và danh sách việc. Bạn xem kế hoạch trước khi có dòng code nào được viết.

Repo này hợp với lập trình viên mới, người làm freelance, và cả nhóm đang dùng AI để code trên dự án có sẵn. Điểm đáng giá nhất là nó nhẹ: không có cổng duyệt cứng, bạn sửa tài liệu lúc nào cũng được, và chạy được với hơn 30 công cụ AI theo README. Hiện có khoảng 74.756 sao và 5.125 fork, giấy phép MIT.

```repo
- repo | Fission-AI/OpenSpec
- kind | CLI
- desc | OpenSpec thêm một lớp spec bằng Markdown để bạn và trợ lý AI lập trình thống nhất cần làm gì trước khi viết code.
- stars | 75k
- lang | TypeScript
- license | MIT
```

## OpenSpec làm được gì

### Chốt yêu cầu trước khi code

Mỗi thay đổi (ví dụ "thêm chế độ tối") có một thư mục riêng trong `openspec/changes/`. Bên trong có bốn thứ: `proposal.md` (vì sao làm, đổi gì), thư mục `specs/` (yêu cầu và kịch bản), `design.md` (cách làm về kỹ thuật) và `tasks.md` (danh sách việc). Nhờ vậy bạn đọc được kế hoạch như đọc một bản nháp, thay vì đoán AI định làm gì.

### Spec là Markdown thường

Bạn không phải học cú pháp lạ. Yêu cầu viết bằng chữ, kèm kịch bản cụ thể theo kiểu "KHI người dùng bấm nút → THÌ giao diện đổi". AI viết giúp, bạn chỉ cần duyệt. Người không chuyên code vẫn đọc hiểu được.

### Bộ lệnh ngắn cho cả quy trình

Bản mặc định có hai lệnh chính. `/openspec-explore` là chỗ nghĩ thoải mái: AI đọc code của bạn, cân nhắc các hướng, chưa đụng vào gì. `/openspec-propose <việc cần làm>` tạo luôn cả gói đề xuất. Sau đó có bước làm theo danh sách việc và bước lưu trữ khi xong. Bạn cần mở rộng thì chọn hồ sơ mở rộng, có thêm các lệnh như `openspec-new-change`, `openspec-continue-change`, `openspec-ff-change`, `openspec-verify-change`, `openspec-bulk-archive-change`, `openspec-onboard`.

### Hợp với dự án đã có sẵn

Triết lý của tác giả là "linh hoạt, không cứng nhắc; lặp dần, không thác nước; dễ, không phức tạp; làm cho dự án cũ chứ không chỉ dự án mới". Bạn không cần dựng lại dự án từ đầu mới dùng được.

### Làm việc nhiều repo (Stores, đang beta)

Với nhóm, một tính năng có thể trải ra máy chủ API, web và thư viện dùng chung. "Stores" cho phép đặt phần lập kế hoạch vào một repo riêng, dùng chung bằng `git push` như mọi thứ khác. README nêu ba lợi ích: một kế hoạch cho tính năng chạm nhiều repo, yêu cầu dùng chung do một nhóm sở hữu, và lập kế hoạch trước khi có code. Tính năng này đang ở bản beta nên bạn cần cân nhắc khi dùng cho việc quan trọng.

### Dùng được với nhiều công cụ AI

README nói hỗ trợ hơn 30 công cụ và còn tăng. Đa số công cụ gọi bằng `/openspec-propose`, riêng Codex gọi bằng `$openspec-propose`. Bạn cũng có thể chỉ cần nói bằng lời thường. Lệnh `openspec init` sẽ in ra đúng cách gọi cho các công cụ bạn chọn.

## Cần chuẩn bị gì

- **Terminal:** macOS hoặc Linux dùng terminal; Windows dùng PowerShell.
- **Node.js 22.12.0 trở lên:** chỉ cần nếu bạn cài bằng npm. File `package.json` của repo cũng yêu cầu Node từ 22.12.0.
- **Một trợ lý AI lập trình được hỗ trợ:** OpenSpec là lớp spec đặt cạnh công cụ AI bạn đang dùng. Danh sách đầy đủ ở trang Supported Tools trên trang chủ dự án.
- **Một thư mục dự án** để chạy `openspec init`.
- **Mô hình mạnh:** README khuyên dùng mô hình suy luận tốt, cụ thể là Codex 5.5 và Opus 4.7, cho cả lập kế hoạch lẫn viết code.

Tư liệu không nói OpenSpec cần GPU, API key riêng hay tài khoản riêng. Chi phí AI phụ thuộc vào công cụ bạn dùng, chưa có thông tin cụ thể về giá.

## Cài đặt từng bước

```steps
- Mở terminal | Dùng terminal (macOS/Linux) hoặc PowerShell (Windows)
- Cài OpenSpec | Chạy lệnh cài một dòng, hoặc dùng npm / Homebrew
- Vào thư mục dự án | cd vào dự án của bạn
- Khởi tạo | Chạy openspec init và chọn công cụ AI
- Gọi trợ lý AI | Gõ /openspec-explore hoặc /openspec-propose
```

### Bước 1: Cài OpenSpec

Chọn một cách, tuỳ máy của bạn. Trên macOS hoặc Linux, mở terminal và chạy:

```bash
curl -fsSL https://openspec.dev/cli/install.sh | sh
```

Trên Windows, mở PowerShell và chạy:

```powershell
irm https://openspec.dev/cli/install.ps1 | iex
```

Cả hai lệnh tải script cài đặt từ trang chủ dự án rồi chạy luôn. Nếu bạn thích kiểm tra trước khi chạy, hãy mở địa chỉ đó trên trình duyệt đọc qua.

Nếu quen dùng trình quản lý gói, README cũng ghi hai cách khác. Với npm (cần Node.js 22.12.0 trở lên):

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

Với Homebrew:

```bash
brew install openspec
```

README còn nói OpenSpec chạy được với pnpm, yarn, bun và Nix; chi tiết xem trang installation trên openspec.dev, README chưa ghi lệnh cụ thể cho các cách này.

### Bước 2: Vào thư mục dự án

Đây là chỗ người mới hay vấp: phải mở terminal đúng thư mục dự án, không phải thư mục nào cũng được. Nếu bạn chưa có dự án, hãy tạo hoặc tải về một dự án trước.

```bash
cd your-project
```

Thay `your-project` bằng tên thư mục thật của bạn.

### Bước 3: Khởi tạo OpenSpec

```bash
openspec init
```

Lệnh này thiết lập OpenSpec trong dự án và hỏi bạn đang dùng công cụ AI nào. Sau khi xong, nó in ra cách gọi lệnh phù hợp với các công cụ bạn đã chọn. Hãy đọc kỹ dòng này, vì cách gọi (`/` hay `$`) khác nhau giữa các công cụ.

```note
README còn gợi ý một cách lười: dán "setup prompt" (có ở mục installation trên openspec.dev) vào trợ lý AI, nó sẽ tự cài CLI, chạy openspec init và kiểm tra kết quả. Dù vậy, bạn nên đọc xem AI định chạy lệnh gì trước khi cho phép.
```

### Bước 4: Nói chuyện với trợ lý AI

Mở trợ lý AI trong chính dự án đó. Chưa biết mình muốn gì thì gõ `/openspec-explore`. Đã rõ thì gõ thẳng `/openspec-propose <việc-muốn-làm>`. Nếu bạn dùng Codex, đổi `/` thành `$`.

Muốn dùng bộ lệnh mở rộng, chọn hồ sơ rồi áp dụng:

```bash
openspec config profile
openspec update
```

## Kiểm tra đã chạy được chưa

README không ghi một lệnh kiểm tra phiên bản riêng, nên mình chỉ nêu những dấu hiệu có trong tư liệu:

- Gõ `openspec init` không báo "không tìm thấy lệnh", và nó hỏi bạn về công cụ AI rồi in ra cách gọi lệnh.
- Trong dự án xuất hiện thư mục `openspec/` (đúng cấu trúc `openspec/changes/...` như ví dụ của README).
- Khi bạn gõ `/openspec-propose ten-viec` trong trợ lý AI, nó tạo thư mục `openspec/changes/ten-viec/` với `proposal.md`, `specs/`, `design.md`, `tasks.md`.

Nếu thấy thư mục thay đổi cùng bốn mục này, bạn đã cài thành công.

## Dùng vào việc thật

### Chủ shop muốn thêm chế độ tối cho trang web

Bạn có website bán hàng nhỏ và nhờ AI sửa. Chưa biết cách làm gọn, bạn mở `/openspec-explore` và nói: "Mình muốn có chế độ tối nhưng chưa biết làm sao cho sạch." AI đọc cách bạn đang dựng giao diện rồi đề xuất hướng làm. Ví dụ trong README: dùng biến CSS và một thành phần quản lý giao diện sáng/tối, không thêm thư viện mới. Khi bạn đồng ý, gõ:

```text
/openspec-propose add-dark-mode
```

Kết quả là thư mục `openspec/changes/add-dark-mode/` có đủ đề xuất, spec, thiết kế và danh sách việc. Bạn đọc spec trước, thấy sai thì sửa luôn, chưa tốn công code nào.

> Bạn duyệt kế hoạch trước khi có dòng code nào được viết, thay vì đi sửa code sai sau đó.
>
> — Ông T

### Lập trình viên mới học làm việc với AI

Bạn nhờ AI làm một tính năng nhưng hay bị nó làm lệch ý. Hãy để AI viết spec theo kiểu kịch bản: "KHI người dùng bấm nút chuyển giao diện, THÌ ứng dụng chuyển sang chế độ tối và nhớ lựa chọn." Sau khi bạn duyệt, gọi bước làm việc `/openspec-apply-change` để AI làm lần lượt từng mục trong `tasks.md`. Xong thì dùng `/openspec-archive-change` để cất thay đổi vào thư mục lưu trữ và cập nhật spec chính. Bạn vừa có code, vừa có tài liệu ghi lại vì sao làm vậy.

### Dự án cũ đang chạy, cần sửa mà ngại làm hỏng

Bạn nhận lại một dự án có sẵn, không ai nhớ rõ nó hoạt động thế nào. Vì OpenSpec được thiết kế cho dự án cũ, bạn chạy `openspec init` ngay trong thư mục đó, rồi bắt đầu bằng `/openspec-explore` để AI đọc code và nói lại cách phần cần sửa đang chạy. Sau đó mỗi thay đổi đi qua một gói riêng, nên bạn dễ theo dõi cái gì đang làm dở, cái gì đã xong.

### Nhóm có nhiều repo, một tính năng chạm cả ba

Trưởng nhóm muốn một tính năng đi qua máy chủ API, ứng dụng web và thư viện chung. Với Stores (beta), bạn đặt kế hoạch ở một repo riêng có cấu trúc `openspec/` giống bình thường, rồi chia sẻ bằng `git push`. Nhóm nền tảng giữ spec dùng chung, các nhóm sản phẩm đọc lại để trợ lý AI của họ làm đúng. Vì còn là bản beta, bạn nên thử trên một tính năng nhỏ trước, và đọc hướng dẫn Stores trên openspec.dev để biết cách thiết lập.

## Lỗi hay gặp và cách xử lý

### Gõ openspec báo không tìm thấy lệnh

Thường do terminal đang mở từ trước khi cài. Hãy đóng terminal, mở cửa sổ mới rồi thử lại. Nếu vẫn lỗi, kiểm tra xem bạn đã cài bằng cách nào (script, npm hay Homebrew) và chạy lại đúng cách đó. README chưa ghi cách xử lý riêng cho lỗi này.

### Cài bằng npm thất bại vì Node cũ

Gói yêu cầu Node.js 22.12.0 trở lên. Nếu máy bạn có bản cũ hơn, hãy nâng cấp Node rồi chạy lại lệnh `npm install -g`. Hoặc dùng lệnh cài một dòng hay Homebrew thay cho npm.

### Gõ /openspec-propose mà AI không hiểu

Có hai nguyên nhân hay gặp. Một là công cụ của bạn dùng cú pháp khác: Codex dùng `$openspec-propose`. Hai là kỹ năng chưa được cài vào công cụ đó. Hãy đọc lại kết quả của `openspec init` để biết cách gọi đúng, và chạy lại lệnh sau trong dự án để làm mới hướng dẫn cho AI:

```bash
openspec update
```

Nếu công cụ của bạn không có trong danh sách hỗ trợ, bạn có thể nhờ AI làm theo các bước bằng lời thường.

### Lệnh sai tên sau khi nâng cấp từ bản 1.x

README nhắc rằng bản 1.x dùng các lệnh `/opsx:*`. Nếu bạn nâng lên 2.0, xem trang Upgrade to 2.0 trên openspec.dev để biết cách chuyển.

### AI làm lệch hoặc quên ý giữa chừng

Theo README, OpenSpec hoạt động tốt khi cửa sổ ngữ cảnh sạch. Hãy xoá ngữ cảnh trước khi bắt đầu phần làm việc, và giữ cuộc trò chuyện gọn. Dùng mô hình suy luận mạnh như README khuyên cũng giúp giảm sai lệch.

## Có nên dùng không

**Điểm mạnh:** nhẹ, spec là Markdown thường nên ai cũng đọc được, và bạn sửa tài liệu lúc nào cũng được vì không có cổng duyệt cứng. Nó chạy với nhiều công cụ AI thay vì bắt bạn dùng một trình soạn thảo riêng. Giấy phép MIT, và repo vẫn được cập nhật trong 3 tháng gần đây.

**So sánh theo README:** Spec Kit của GitHub kỹ nhưng nặng, có cổng duyệt cứng, nhiều Markdown và cần cài Python. Kiro của AWS mạnh nhưng gắn với IDE riêng và chỉ dùng được mô hình Claude. OpenSpec nhẹ hơn và dùng được với công cụ bạn đang có. Đây là cách tác giả tự so sánh, bạn nên thử thực tế rồi tự đánh giá.

**Giới hạn:** OpenSpec không thay AI viết code; nó chỉ giúp bạn quản lý yêu cầu. Chất lượng kết quả vẫn phụ thuộc vào mô hình bạn dùng, và README khuyên mô hình mạnh. Với việc rất nhỏ, như đổi một dòng chữ, dựng cả gói đề xuất là thừa. Stores còn ở bản beta. Tư liệu cũng chưa nói rõ về chi phí hay yêu cầu phần cứng.

**Cập nhật và quyền riêng tư:** để nâng cấp, chạy lại lệnh cài đặt tương ứng. Nếu cài bằng npm:

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

Nếu cài bằng Homebrew:

```bash
brew upgrade openspec
```

Rồi chạy `openspec update` trong từng dự án để làm mới hướng dẫn cho AI. README cho biết OpenSpec thu thập thống kê sử dụng ẩn danh, chỉ gồm tên lệnh và phiên bản, không có tham số, đường dẫn, nội dung hay thông tin cá nhân, và tự tắt trong môi trường CI. Muốn tắt, dùng một trong các cách sau:

```bash
openspec config set telemetry.enabled false
```

```bash
export OPENSPEC_TELEMETRY=0
```

Nhìn chung, nếu bạn hay nhờ AI code mà kết quả cứ lệch ý, OpenSpec đáng để thử trên một dự án nhỏ. Nếu bạn chỉ làm việc vặt một lần rồi bỏ, có lẽ không cần.

## Câu hỏi thường gặp

### OpenSpec có miễn phí không?

Repo dùng giấy phép MIT nên dùng tự do. Bạn cài bằng script, npm hoặc Homebrew mà README không nhắc đến phí. Chi phí dùng trợ lý AI phụ thuộc công cụ bạn chọn, tư liệu chưa có thông tin cụ thể về giá.

### OpenSpec có chạy trên Windows không?

Có. README có lệnh cài riêng cho Windows bằng PowerShell, ngoài ra còn cách cài bằng npm với Node.js 22.12.0 trở lên. Sau khi cài, bạn chạy openspec init trong thư mục dự án như bình thường.

### Tôi có cần GPU hay máy mạnh không?

README không nói gì về yêu cầu GPU. OpenSpec là công cụ dòng lệnh quản lý file Markdown, còn phần nặng do trợ lý AI bạn dùng đảm nhận. Tư liệu chỉ khuyên dùng mô hình suy luận mạnh như Codex 5.5 hoặc Opus 4.7.

### OpenSpec dùng được với công cụ AI nào?

README nói hỗ trợ hơn 30 công cụ và còn tăng. Danh sách đầy đủ ở trang Supported Tools trên openspec.dev. Phần lớn công cụ gọi lệnh bằng /openspec-propose, riêng Codex dùng $openspec-propose.

### Dữ liệu của tôi có được gửi đi đâu không?

README cho biết OpenSpec thu thập thống kê ẩn danh, chỉ gồm tên lệnh và phiên bản, không có tham số, đường dẫn, nội dung hay thông tin cá nhân. Nó tự tắt trong CI. Bạn có thể tắt bằng openspec config set telemetry.enabled false hoặc đặt biến OPENSPEC_TELEMETRY=0.

### OpenSpec khác Spec Kit và Kiro thế nào?

Theo README, Spec Kit của GitHub kỹ nhưng nặng, có cổng duyệt cứng và cần cài Python. Kiro của AWS gắn với IDE riêng và chỉ dùng mô hình Claude. OpenSpec được tác giả mô tả là nhẹ hơn, cho phép sửa tự do và dùng với công cụ bạn đã có.

### Làm sao nâng cấp OpenSpec?

Nếu cài bằng npm, chạy lại npm install -g @fission-ai/openspec@latest. Nếu cài bằng Homebrew thì dùng brew upgrade openspec. Sau đó chạy openspec update trong từng dự án để làm mới hướng dẫn và kỹ năng cho AI.
