OpenSpec: chốt spec với AI trước khi viết code — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về Fission-AI/OpenSpec — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: OpenSpec: chốt kế hoạch với AI trước khi viết code — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
OpenSpec là một công cụ dòng lệnh (CLI) giúp bạn và trợ lý AI lập trình thống nhất yêu cầu bằng các file Markdown trước khi viết code. Nó hoạt động với hơn 30 công cụ AI qua các lệnh kiểu /openspec-propose. Cài đặt không khó: một dòng lệnh, rồi chạy openspec init trong dự án.
OpenSpec là một công cụ dòng lệnh giúp bạn làm việc với trợ lý AI lập trình theo kiểu "chốt kế hoạch trước, viết code sau". Thay vì dặn AI bằng những câu chat rời rạc rồi mong nó đoán đúng, bạn để nó viết ra một bộ tài liệu Markdown gồm lý do, yêu cầu, thiết kế và danh sách việc cần làm. Bạn đọc, sửa, đồng ý, rồi AI mới bắt đầu code.
Repo này dành cho lập trình viên (kể cả người mới) đang dùng các công cụ như Claude Code, Codex hay các trợ lý AI khác. Tác giả nói OpenSpec hỗ trợ hơn 30 công cụ. Nó cũng hợp với người làm sản phẩm, làm kinh doanh muốn kiểm soát AI đang định làm gì, vì phần "spec" viết bằng chữ thường, dễ đọc.
Điểm đáng giá nhất là sự nhẹ nhàng. Triết lý của dự án là linh hoạt thay vì cứng nhắc, lặp dần thay vì thác nước, dễ thay vì phức tạp, và dùng được cho cả dự án đã có sẵn code. Hiện repo có khoảng 74.700 sao và 5.100 fork trên GitHub, giấy phép MIT.
Fission-AI/OpenSpec
OpenSpec là công cụ dòng lệnh thêm lớp đặc tả (spec) cho trợ lý AI viết code: thống nhất cần làm gì trước, rồi mới để AI code.
I.OpenSpec làm được gì
Thống nhất trước khi code. Bạn và AI cùng đọc một bản kế hoạch trước khi có dòng code nào. Việc này giảm cảnh AI làm một đằng, bạn muốn một nẻo, phải chat đi chat lại để sửa.
Mỗi thay đổi một thư mục riêng. Khi bạn đề xuất một tính năng, OpenSpec tạo thư mục openspec/changes/<tên-thay-đổi>/ gồm bốn thứ:
proposal.md: vì sao làm, thay đổi gì.specs/: các yêu cầu và kịch bản.design.md: cách làm về mặt kỹ thuật.tasks.md: danh sách việc cần thực hiện.
Nhờ vậy lịch sử của từng tính năng gọn gàng, không lẫn vào nhau.
Spec là Markdown thường. Không có cú pháp lạ phải học. Mỗi yêu cầu đi kèm kịch bản cụ thể theo dạng WHEN (khi) và THEN (thì). Bạn không cần tự viết, vì AI viết, còn bạn là người duyệt.
Làm việc linh hoạt. Bạn có thể sửa bất kỳ tài liệu nào bất kỳ lúc nào, không có cổng phê duyệt cứng giữa các giai đoạn.
Có chế độ khám phá. Nếu chưa biết nên làm thế nào, lệnh /openspec-explore mở một cuộc trao đổi không áp lực. AI đọc code của bạn, cân nhắc các hướng đi và gợi ý phạm vi trước khi bạn quyết định.
Stores (bản beta). Với nhóm làm việc, một tính năng có thể trải trên nhiều repo, ví dụ máy chủ API, ứng dụng 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, chia sẻ bằng git push như mọi thứ khác. Tính năng này còn ở dạng beta, nên cân nhắc khi dùng vào việc quan trọng.
II.Cần chuẩn bị gì
Theo tư liệu của repo, bạn cần:
- Một dự án có sẵn (hoặc thư mục dự án mới) để chạy
openspec initbên trong. - Một trợ lý AI lập trình nằm trong danh sách được hỗ trợ. Bạn xem danh sách đầy đủ ở trang Supported Tools trên trang chủ openspec.dev.
- Node.js 22.12.0 trở lên, nếu bạn cài bằng npm.
package.jsoncủa repo cũng yêu cầu>=22.12.0. Cách cài bằng dòng lệnh có sẵn (script) hay Homebrew thì README không nêu yêu cầu Node riêng. - Hệ điều hành: README có lệnh cài riêng cho macOS/Linux (terminal) và Windows (PowerShell). Ngoài ra còn có npm, Homebrew, pnpm, yarn, bun và Nix.
Tư liệu không nói OpenSpec cần API key hay phần cứng đặc biệt. Bản thân OpenSpec không phải là AI. Chi phí và tài khoản (nếu có) là của công cụ AI mà bạn đang dùng.
Về mô hình, tác giả khuyên dùng mô hình có khả năng suy luận cao. Họ nhắc Codex 5.5 và Opus 4.7 cho cả bước lên kế hoạch lẫn bước viết code.
III.Cài đặt từng bước
- Cài OpenSpecChạy một dòng lệnh phù hợp hệ điều hành của bạn
- Mở thư mục dự ánDùng cd để vào đúng dự án cần làm việc
- Khởi tạoChạy openspec init và chọn công cụ AI bạn dùng
- Nói chuyện với AIGõ /openspec-explore hoặc /openspec-propose trong trợ lý AI
A.Cài OpenSpec
Chọn đúng một cách. Trên macOS hoặc Linux, mở terminal và chạy:
curl -fsSL https://openspec.dev/cli/install.sh | shTrên Windows, mở PowerShell và chạy:
irm https://openspec.dev/cli/install.ps1 | iexCả hai lệnh đều tải một đoạn script từ trang chủ rồi chạy luôn. Nếu bạn muốn tự xem script trước khi chạy, hãy mở địa chỉ đó trong trình duyệt.
Nếu bạn quen dùng trình quản lý gói, README ghi hai cách khác. Cách npm cần Node.js 22.12.0 trở lên:
npm install -g @fission-ai/openspec@latestHoặc dùng Homebrew:
brew install openspecREADME còn nói OpenSpec chạy được với pnpm, yarn, bun và Nix. Bạn xem chi tiết ở trang Installation trên openspec.dev.
Người mới hay vấp ở đây: sau khi cài xong, hãy đóng và mở lại cửa sổ terminal rồi mới gõ lệnh openspec. Việc này mình khuyên làm chung cho mọi công cụ dòng lệnh, README không nhắc riêng.
B.Mở thư mục dự án
Lệnh cd đưa terminal vào thư mục dự án của bạn. Thay your-project bằng tên thư mục thật:
cd your-projectNếu dự án chưa có trên máy, bạn lấy về trước bằng git clone https://github.com/<chủ-repo>/<tên-repo>.git rồi cd vào thư mục vừa tạo.
C.Khởi tạo OpenSpec trong dự án
openspec initLệnh này cài các "skill" (kỹ năng) để trợ lý AI hiểu các lệnh của OpenSpec. README cho biết openspec init sẽ in ra đúng dạng lệnh cho những công cụ bạn đã chọn. Hãy đọc kỹ phần in ra, vì cách gọi lệnh khác nhau giữa các công cụ. Phần mô tả đầy đủ những gì được cài nằm ở trang Set up your project trên openspec.dev.
D.Để chính AI cài giúp (tuỳ chọn)
README có một "setup prompt" trên trang Installation (mục cài bằng trợ lý AI). Bạn dán prompt đó vào trợ lý AI, nó sẽ cài CLI, chạy openspec init và kiểm tra kết quả. Nội dung prompt nằm trên trang đó nên mình không chép lại ở đây.
E.Chọn bộ lệnh
Bộ lệnh mặc định gồm /openspec-explore và /openspec-propose. Nếu muốn bộ mở rộng (openspec-new-change, openspec-continue-change, openspec-ff-change, openspec-verify-change, openspec-bulk-archive-change, openspec-onboard), bạn chọn bằng lệnh:
openspec config profileSau đó áp dụng bằng:
openspec updateIV.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. Bạn có thể xác nhận theo các dấu hiệu sau, đều bám vào tư liệu:
openspec initchạy xong, không báo lỗi, và in ra cách gọi lệnh cho công cụ AI bạn đã chọn.- Trong dự án xuất hiện thư mục
openspec/. - Mở trợ lý AI trong dự án, gõ
/openspec-explore(với Codex thì là$openspec-explore). Nếu AI hỏi lại "bạn muốn khám phá điều gì?" thì skill đã nhận.
Nếu AI không phản hồi theo kiểu đó, hãy xem phần Lỗi hay gặp bên dưới.
V.Dùng vào việc thật
A.Dev làm tính năng mới mà chưa biết cách làm
Bạn đang có một ứng dụng web và muốn thêm chế độ tối (dark mode) nhưng ngại làm rối giao diện. Hãy mở trợ lý AI trong thư mục dự án và gõ:
/openspec-exploreSau đó mô tả: "Mình muốn có dark mode nhưng chưa rõ làm thế nào cho gọn." Theo ví dụ trong README, AI sẽ xem cách bạn đang làm giao diện, đưa ra hướng đi gọn nhất (ví dụ biến CSS cộng một theme context, có nhận diện cài đặt của hệ thống) và hỏi bạn có chốt phạm vi không. Kết quả là bạn có hướng đi rõ ràng mà chưa tốn một dòng code nào.
B.Dev đã biết rõ mình muốn gì
Khi yêu cầu đã rõ, bạn đi thẳng vào đề xuất:
/openspec-propose add-dark-modeAI tạo thư mục openspec/changes/add-dark-mode/ với proposal.md, specs/, design.md và tasks.md. Bạn mở từng file đọc. Nếu thấy thiếu hoặc sai, bạn bảo AI sửa. Khi hài lòng, bạn gõ:
/openspec-apply-changeAI làm lần lượt từng việc trong tasks.md và đánh dấu hoàn thành. Làm xong, bạn gõ /openspec-archive-change để lưu thay đổi vào kho lưu trữ và cập nhật spec chính.
Bạn duyệt kế hoạch trước, AI mới viết code. Sửa một dòng chữ rẻ hơn sửa một nghìn dòng code.
Ông T
C.Người làm sản phẩm đọc và duyệt yêu cầu
Bạn không rành code nhưng muốn chắc AI hiểu đúng ý. Mở file trong specs/, bạn sẽ thấy yêu cầu viết bằng chữ thường. Ví dụ trong README:
## ADDED Requirements
### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.
#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choiceBạn chỉ cần kiểm tra: kịch bản có đúng điều mình muốn không, còn thiếu trường hợp nào không. Có thể nhờ dev hoặc AI giải thích nếu có từ khó.
D.Nhóm nhiều repo cùng làm một tính năng
Tính năng mới đụng cả API, web và thư viện dùng chung. Với Stores (beta), nhóm đặt kế hoạch trong một repo riêng có cùng cấu trúc openspec/, chia sẻ bằng git như thường. Nhóm nền tảng giữ các spec dùng chung, nhóm sản phẩm tham chiếu chỉ để đọc. README mô tả đây là cách để tránh tình trạng wiki mỗi nơi một kiểu. Cách thiết lập chi tiết nằm ở trang Stores trên openspec.dev, mình khuyên bạn đọc kỹ trước khi áp dụng vì tính năng còn beta.
VI.Lỗi hay gặp và cách xử lý
A.Gõ openspec báo không tìm thấy lệnh
Thường do terminal chưa nạp lại đường dẫn sau khi cài. Hãy đóng hẳn terminal, mở lại và thử lại. Nếu cài bằng npm, kiểm tra Node.js đang dùng có phải 22.12.0 trở lên không (node --version). Phiên bản thấp hơn có thể gây lỗi khi cài hoặc chạy.
B.Gõ /openspec-propose mà AI không hiểu
Có thể bạn chưa chạy openspec init trong đúng thư mục dự án, hoặc đang mở trợ lý AI ở thư mục khác. Ngoài ra, Codex dùng dạng $openspec-propose chứ không phải dấu gạch chéo. Hãy xem lại phần openspec init in ra, hoặc bạn cứ nói bằng lời thường như "hãy đề xuất thay đổi cho việc…" vì README cho biết bạn có thể yêu cầu bằng lời.
C.Không thấy các lệnh mở rộng
Các lệnh như openspec-new-change hay openspec-verify-change không nằm trong bộ mặc định. Bạn chạy openspec config profile để chọn bộ mở rộng, rồi openspec update để áp dụng.
D.Từ bản 1.x lên 2.0, lệnh cũ không còn
Nếu trước đây bạn dùng các lệnh /opsx:* của bản 1.x, README hướng dẫn xem trang Upgrade to 2.0 trên openspec.dev. Hãy làm theo đó thay vì đoán.
E.AI làm lan man, bỏ sót yêu cầu
Tác giả khuyên giữ ngữ cảnh sạch: xoá ngữ cảnh (bắt đầu phiên mới) trước khi bắt tay vào làm, và giữ phiên làm việc gọn gàng. Dùng mô hình suy luận mạnh cũng giúp ích.
OpenSpec thu thập số liệu sử dụng ẩn danh (chỉ 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 môi trường CI. Muốn tắt hẳn: chạy openspec config set telemetry.enabled false, hoặc đặt biến môi trường OPENSPEC_TELEMETRY=0 hoặc DO_NOT_TRACK=1.
VII.Có nên dùng không
Điểm mạnh:
- Nhẹ, không bắt buộc quy trình cứng. Bạn sửa tài liệu lúc nào cũng được.
- Spec là Markdown nên đọc được, lưu bằng git được, nhóm cùng xem.
- Chạy với hơn 30 công cụ AI, không bị khoá vào một IDE.
- Dùng được cho dự án có sẵn code, không chỉ dự án mới.
- Mã nguồn mở, giấy phép MIT, repo được cập nhật trong vài tháng gần đây.
Giới hạn:
- Bạn vẫn phải bỏ thời gian đọc và duyệt spec. Nếu chỉ sửa một lỗi nhỏ vài dòng, quy trình này có thể thừa.
- Chất lượng phụ thuộc vào mô hình AI bạn dùng.
- Stores còn ở dạng beta.
- Tư liệu có nhắc thu thập số liệu ẩn danh. Bạn nên tắt nếu công ty có quy định riêng.
So với cách khác: README tự so sánh OpenSpec với Spec Kit của GitHub (đầy đủ nhưng nặng, nhiều bước cứng và cần Python) và với Kiro của AWS (mạnh nhưng gắn với IDE riêng). Đó là nhận định của chính tác giả, nên bạn cứ thử và tự so. Nếu việc của bạn chỉ là câu hỏi nhanh hoặc sửa nhỏ, cứ chat với AI như bình thường. Còn khi làm tính năng vừa và lớn, hoặc làm theo nhóm, OpenSpec đáng để thử một lần.
Để cập nhật về sau: dùng openspec install nếu bạn cài bằng script, chạy lại npm install -g @fission-ai/openspec@latest nếu cài bằng npm, hoặc brew upgrade openspec với Homebrew. Rồi chạy openspec update trong từng dự án để làm mới hướng dẫn cho AI.
Câu hỏi thường gặp
OpenSpec có miễn phí không?
Có. Repo dùng giấy phép MIT và là mã nguồn mở. Tư liệu không nói OpenSpec tính phí. Tuy nhiên công cụ AI mà bạn dùng cùng nó có thể có chi phí riêng, tuỳ gói của bạn.
Cần GPU hay cấu hình máy mạnh không?
Tư liệu không nêu yêu cầu phần cứng nào. OpenSpec là công cụ dòng lệnh tạo và quản lý các file Markdown. Phần xử lý AI do trợ lý lập trình của bạn đảm nhiệm.
Chạy được trên Windows không?
Được. README có lệnh cài riêng cho Windows chạy trong PowerShell. Bạn cũng có thể cài bằng npm (cần Node.js 22.12.0 trở lên) hoặc các trình quản lý gói khác.
OpenSpec dùng được với công cụ AI nào?
README nói hỗ trợ hơn 30 công cụ và tăng dần. Hầu hết gọi lệnh dạng /openspec-propose, riêng Codex dùng $openspec-propose. Danh sách đầy đủ nằm ở trang Supported Tools trên openspec.dev.
Dữ liệu của mình có bị gửi đi đâu không?
Spec nằm trong thư mục openspec/ ngay trong dự án của bạn. OpenSpec thu thập số liệu ẩ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 CI. Bạn có thể tắt bằng openspec config set telemetry.enabled false hoặc đặt OPENSPEC_TELEMETRY=0 hoặc DO_NOT_TRACK=1.
OpenSpec khác gì Spec Kit hay Kiro?
Theo README, Spec Kit của GitHub đầy đủ nhưng nặng, có các cổng giai đoạn cứng và cần Python. Kiro của AWS mạnh nhưng gắn với IDE riêng và giới hạn ở mô hình Claude. OpenSpec nhẹ hơn và chạy với các công cụ bạn đã dùng. Đây là so sánh của tác giả, tư liệu chưa có đánh giá độc lập.
Nên dùng mô hình AI nào cho tốt?
Tác giả khuyên dùng mô hình suy luận mạnh, cụ thể là Codex 5.5 và Opus 4.7 cho cả lập kế hoạch lẫn viết code. Họ cũng khuyên xoá ngữ cảnh trước khi bắt đầu làm và giữ ngữ cảnh gọn trong cả phiên.


