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) theo hướng spec-driven development: bạn và trợ lý AI thống nhất đặc tả bằng Markdown trước khi AI viết code. Công cụ cài bằng một dòng lệnh, chạy openspec init trong dự án rồi gọi các lệnh như /openspec-propose. Cài không khó, nhưng cần Node.js 22.12.0 trở lên nếu cài qua npm.
OpenSpec là một công cụ dòng lệnh giúp bạn và trợ lý lập trình AI thống nhất “sẽ làm gì” trước khi AI động vào code. Mỗi thay đổi có một thư mục riêng, gồm đề xuất, đặc tả, thiết kế và danh sách việc, tất cả là file Markdown thường. Tác giả mô tả đây là spec-driven development (phát triển dựa trên đặc tả) cho các trợ lý lập trình AI.
Vấn đề nó giải quyết rất quen thuộc. Khi yêu cầu chỉ nằm trong khung chat, AI dễ làm lệch ý, quên điều bạn đã dặn, và kết quả khó đoán. OpenSpec thêm một lớp đặc tả nhẹ ở giữa. Bạn đọc và sửa kế hoạch trước, khi chưa có dòng code nào được viết.
Ai nên dùng? Lập trình viên mới, người làm sản phẩm, hoặc chủ dự án nhỏ đang nhờ AI viết code và muốn kiểm soát hơn. Đội nhóm nhiều repo cũng là đối tượng của công cụ này. Điểm đáng giá nhất là tính “linh hoạt chứ không cứng nhắc”: bạn được sửa bất kỳ tài liệu nào bất kỳ lúc nào, không bị khoá theo các giai đoạn. Repo hiện có khoảng 74.700 sao và khoảng 5.100 fork, giấy phép MIT.
Fission-AI/OpenSpec
OpenSpec là công cụ dòng lệnh giúp bạn và AI viết đề xuất, đặc tả, thiết kế, danh sách việc trước khi code, dùng được với hơn 30 trợ lý lập trình AI.
I.OpenSpec làm được gì
A.Mỗi thay đổi một thư mục riêng
Khi bạn yêu cầu một tính năng, AI tạo thư mục trong openspec/changes/. Trong đó có bốn thứ: proposal.md (vì sao làm, thay đổi gì), 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 cần làm). Lợi ích thực tế là bạn có một chỗ duy nhất để xem lại “AI định làm gì” thay vì lục lại cả cuộc chat dài.
B.Đặc tả là Markdown thường
Yêu cầu được viết thành các mục có kịch bản cụ thể, kiểu “KHI người dùng bấm nút thì ứng dụng chuyển sang chế độ tối”. Không có cú pháp đặc biệt nào phải học. AI viết, bạn đọc và duyệt. Người không rành code vẫn đọc hiểu được.
C.Khám phá trước khi quyết định
Lệnh /openspec-explore là một “người cùng suy nghĩ” không áp lực. Nó đọc code của bạn, cân nhắc các hướng đi và giúp bạn định hình kế hoạch trước khi viết gì. Hợp khi bạn chưa chắc nên làm thế nào.
D.Quy trình ngắn gọn mặc định
Profile mặc định có bốn bước chính: explore (khám phá), propose (đề xuất), apply-change (thực hiện) và archive-change (lưu trữ). Khi xong, thay đổi được lưu vào thư mục archive và đặc tả chung được cập nhật. Nếu cần quy trình mở rộng, README nhắc các lệnh như openspec-new-change, openspec-continue-change, openspec-ff-change, openspec-verify-change, openspec-bulk-archive-change và openspec-onboard.
E.Chạy với hơn 30 công cụ AI
OpenSpec hoạt động qua các “skill” nên dùng được với hơn 30 trợ lý AI, không bắt bạn đổi công cụ. README so sánh: Spec Kit của GitHub thì kỹ lưỡng nhưng nặng và cần Python, còn Kiro của AWS thì bạn phải dùng IDE riêng. OpenSpec nhẹ hơn và dùng được với công cụ bạn đang có.
F.Stores cho làm việc nhóm (beta)
Khi một tính năng trải dài qua nhiều repo (máy chủ API, ứng dụng web, thư viện chung), bạn có thể đặt phần kế hoạch trong một repo riêng gọi là Store. Cấu trúc openspec/ vẫn như cũ và chia sẻ bằng git push. README ghi rõ tính năng này đang ở bản beta.
II.Cần chuẩn bị gì
- Một terminal: macOS hoặc Linux dùng terminal, Windows dùng PowerShell.
- Nếu cài bằng npm: Node.js 22.12.0 trở lên (theo
package.jsonvà README). - Một trợ lý lập trình AI bạn đang dùng, nằm trong danh sách hơn 30 công cụ được hỗ trợ. README chỉ tới trang Supported Tools trên openspec.dev để xem danh sách đầy đủ.
- Một thư mục dự án để chạy
openspec init. - README khuyên dùng mô hình suy luận mạnh. Tác giả đề xuất Codex 5.5 và Opus 4.7 cho cả lập kế hoạch lẫn viết code.
Tư liệu không nhắc đến yêu cầu GPU, API key riêng của OpenSpec hay phần cứng cụ thể. Bạn chỉ cần tài khoản và quyền dùng của chính trợ lý AI mình chọn.
III.Cài đặt từng bước
- Cài OpenSpecChạy một dòng lệnh cài đặt phù hợp hệ điều hành
- Vào thư mục dự ánMở terminal ngay tại dự án bạn muốn dùng
- Khởi tạoChạy openspec init và chọn công cụ AI của bạn
- Gọi lệnh trong AIDùng /openspec-explore hoặc /openspec-propose
- Cập nhật về sauNâng cấp CLI và chạy openspec update
A.Cài OpenSpec
README đưa ra vài cách. Chọn một cách thôi. 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 | iexNếu bạn thích dùng trình quản lý gói, có thể cài bằng npm (cần Node.js 22.12.0 trở lên):
npm install -g @fission-ai/openspec@latestHoặc dùng Homebrew:
brew install openspecNgười mới hay vấp ở chỗ: lệnh npm chỉ chạy được khi máy đã có Node.js. Nếu báo không tìm thấy npm hoặc phiên bản Node cũ, hãy dùng cách cài bằng một dòng lệnh phía trên.
Các lệnh curl và irm tải một đoạn script từ internet rồi chạy ngay. Chỉ chạy khi bạn tin nguồn. Muốn chắc ăn, hãy mở địa chỉ script trên trình duyệt để đọc trước, hoặc chọn cách cài bằng npm hay Homebrew.
README còn nói bạn có thể dán một “setup prompt” vào trợ lý AI để nó tự cài CLI, chạy openspec init và kiểm tra kết quả. Prompt này nằm ở trang Installation trên openspec.dev, không có trong README nên mình không chép lại ở đây.
B.Vào thư mục dự án và khởi tạo
Mở terminal tại dự án của bạn rồi chạy:
cd your-project
openspec initcd your-project nghĩa là đi vào thư mục dự án, bạn đổi your-project thành tên thư mục thật của mình. Đây là chỗ nhiều người vấp: nếu chạy openspec init sai thư mục, các file sẽ được tạo nhầm chỗ.
Lệnh openspec init cài các skill vào dự án cho những công cụ AI bạn chọn. Khi xong, nó in ra đúng cách gọi lệnh cho công cụ đó. Hầu hết công cụ gọi là /openspec-propose, riêng Codex gọi là $openspec-propose.
C.Gọi lệnh trong trợ lý AI
Bây giờ bạn mở trợ lý AI trong dự án và nói chuyện với nó. README gợi ý hai đường:
- Chưa biết nên làm gì: bắt đầu bằng
/openspec-explore. - Đã biết mình muốn gì: gọi thẳng
/openspec-propose <điều-bạn-muốn-làm>.
Nếu công cụ của bạn không gõ được dạng lệnh gạch chéo, README nói bạn có thể yêu cầu bằng lời thường.
D.Muốn dùng quy trình mở rộng
Profile mặc định chỉ có explore và propose cùng các bước thực hiện, lưu trữ. Để dùng thêm các lệnh như openspec-new-change hay openspec-verify-change, chọn profile mở rộng rồi áp dụng:
openspec config profile
openspec updateE.Cập nhật về sau
Với bản cài một dòng lệnh, README ghi chạy openspec install. Nếu bạn cài bằng npm:
npm install -g @fission-ai/openspec@latestNếu cài bằng Homebrew:
brew upgrade openspecSau đó, trong mỗi dự án, chạy lệnh này để làm mới hướng dẫn cho AI và các skill đã cài:
openspec updateIV.Kiểm tra đã chạy được chưa
README không ghi 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:
- Lệnh
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 trợ lý AI, bạn gõ
/openspec-explore(hoặc$openspec-explorevới Codex) thì AI hỏi lại bạn muốn khám phá điều gì. - Sau khi chạy
/openspec-propose add-dark-mode(tên thay đổi do bạn đặt), AI báo đã tạo thư mụcopenspec/changes/add-dark-mode/vớiproposal.md,specs/,design.md,tasks.md.
Nếu AI không nhận lệnh, xem lại cách gọi mà openspec init đã in ra, vì mỗi công cụ có thể khác nhau.
V.Dùng vào việc thật
A.Thêm chế độ tối cho website nhưng chưa biết làm sao
Bạn làm web bán hàng nhỏ và muốn thêm dark mode, nhưng không rõ nên làm sạch sẽ thế nào. Mở AI trong dự án rồi gõ:
/openspec-explore
I want dark mode but I'm not sure how to do it cleanly.Theo ví dụ trong README, AI xem cách bạn đang tạo kiểu giao diện, rồi đề xuất hướng đi gọn: dùng biến CSS và một theme context nhỏ, tự nhận theo thiết lập hệ thống, không thêm thư viện mới. Bạn đồng ý thì chuyển sang bước đề xuất. Kết quả là bạn có hướng đi rõ ràng mà chưa tốn dòng code nào.
Bạn duyệt kế hoạch trước khi có code, thay vì sửa code sau khi AI đã làm lệch.
Ông T
B.Biến ý tưởng thành gói kế hoạch đủ bộ
Bạn đã biết mình cần gì, chẳng hạn một nút chuyển giao diện. Gõ:
/openspec-propose add-dark-modeAI tạo thư mục thay đổi với bốn file. Trong specs/, mỗi yêu cầu có kịch bản cụ thể, ví dụ “khi người dùng bấm nút chuyển giao diện thì app chuyển sang chế độ tối và nhớ lựa chọn”. Bạn mở các file này đọc như đọc tài liệu thường, sửa chỗ chưa đúng ý, rồi mới cho làm tiếp. Nhân viên văn phòng không code vẫn tham gia duyệt được vì toàn chữ.
C.Cho AI làm theo danh sách việc và lưu lại
Sau khi kế hoạch ổn, bạn gõ /openspec-apply-change. AI làm lần lượt các mục trong tasks.md và đánh dấu từng việc đã xong (như thêm theme context, tạo nút chuyển, thêm biến CSS). Khi xong hết, gõ /openspec-archive-change. Thay đổi được chuyển vào thư mục lưu trữ và đặc tả chung được cập nhật, sẵn sàng cho tính năng kế tiếp. README khuyên xoá sạch ngữ cảnh (context) của AI trước khi bắt đầu phần thực hiện để kết quả tốt hơn.
D.Lập kế hoạch cho tính năng trải qua nhiều repo
Bạn là dev trong một đội có API, web app và thư viện chung. Tính năng mới chạm cả ba nơi. Dùng Stores (đang beta), bạn giữ một kế hoạch duy nhất trong repo riêng, đội nền tảng sở hữu đặc tả, các đội sản phẩm đọc lại ở chế độ chỉ đọc. Mình không có hướng dẫn chi tiết từng lệnh của Stores trong README, nên bạn xem trang Stores guide trên openspec.dev trước khi áp dụng.
VI.Lỗi hay gặp và cách xử lý
A.Gõ lệnh gạch chéo mà AI không phản hồi
Có thể bạn chưa chạy openspec init trong đúng thư mục dự án, hoặc đang dùng sai cách gọi. Hầu hết công cụ dùng /openspec-propose, còn Codex dùng $openspec-propose. Hãy chạy lại openspec init trong thư mục dự án và đọc kỹ dòng hướng dẫn nó in ra. Nếu vẫn không được, thử yêu cầu bằng lời thường.
B.Báo thiếu hoặc sai phiên bản Node khi cài bằng npm
Cài qua npm cần Node.js 22.12.0 trở lên. Nếu máy bạn dùng bản cũ hơn, lệnh có thể lỗi hoặc không chạy đúng. Hãy nâng Node lên đúng phiên bản yêu cầu, hoặc đổi sang cách cài bằng một dòng lệnh hay Homebrew.
C.Lệnh openspec không được nhận sau khi cài
Sau khi cài, hãy đóng terminal rồi mở lại để máy nạp lại đường dẫn lệnh. Nếu vẫn không thấy, chạy lại bước cài. README chưa ghi chi tiết cách xử lý trường hợp này, nên xem trang Installation trên openspec.dev.
D.Kết quả AI lộn xộn hoặc lệch kế hoạch
README lưu ý OpenSpec chạy tốt nhất với mô hình suy luận mạnh và cần ngữ cảnh sạch. Hãy xoá ngữ cảnh trước khi bắt đầu phần thực hiện, dùng mô hình mạnh hơn nếu có thể, và đọc kỹ proposal.md, specs/ trước khi cho AI làm.
E.Kỹ năng không còn mới sau khi nâng cấp
Sau khi nâng cấp CLI, các skill trong dự án có thể còn là bản cũ. Hãy chạy openspec update trong từng dự án để làm mới. Nếu bạn đến từ bản 1.x với các lệnh /opsx:*, README chỉ tới trang Upgrade to 2.0 trên openspec.dev.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh, đặc tả viết bằng Markdown thường nên ai cũng đọc được. Công cụ không khoá bạn vào một IDE hay một hãng AI, vì hỗ trợ hơn 30 công cụ. Cách làm linh hoạt: sửa tài liệu lúc nào cũng được, không bị phân giai đoạn cứng. Tác giả còn dùng chính OpenSpec để phát triển OpenSpec, nên bạn có thể xem ví dụ thật ngay trong repo.
Giới hạn. Tính năng Stores còn ở bản beta. Chất lượng kết quả phụ thuộc nhiều vào mô hình AI bạn dùng; README khuyên mô hình suy luận mạnh. Công cụ thêm bước lập kế hoạch, nên với việc rất nhỏ (sửa một dòng chữ) thì có thể thừa. Bạn vẫn cần tự đọc và duyệt đặc tả, không thể giao hết cho AI.
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 gồm đối số, đường dẫn hay nội dung, và tự tắt trong môi trường CI. Muốn tắt, chạy openspec config set telemetry.enabled false, hoặc đặt biến môi trường OPENSPEC_TELEMETRY=0 hay DO_NOT_TRACK=1.
Khi nào chọn cách khác. Nếu bạn chỉ làm script ngắn dùng một lần, việc nhờ AI trực tiếp là đủ. Nếu đội bạn đã gắn chặt với một quy trình khác, hãy cân nhắc trước khi đổi. Còn nếu bạn hay bực vì AI làm lệch ý, hoặc cần một kế hoạch rõ để cả nhóm cùng đọc, OpenSpec đáng thử trên một dự án nhỏ trước.
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 bạn dùng và sửa đổi tự do. Tư liệu không nói OpenSpec thu phí gì. Tuy vậy, trợ lý AI bạn kết nối vào có thể có chi phí riêng theo gói của nó.
Cài OpenSpec có cần Node.js không?
Nếu cài bằng npm thì cần Node.js 22.12.0 trở lên. README còn có cách cài một dòng lệnh cho macOS, Linux và Windows, cùng cách dùng Homebrew. Tư liệu không nói rõ cách một dòng lệnh có cần Node hay không.
OpenSpec chạy được trên Windows không?
Được. README có lệnh cài riêng cho Windows chạy trong PowerShell. Cách cài bằng npm cũng dùng được nếu máy có Node.js đúng phiên bản.
OpenSpec có cần GPU hay API key không?
Tư liệu không nhắc yêu cầu GPU hay API key riêng cho OpenSpec. Công cụ chạy cùng trợ lý AI bạn đang dùng, nên bạn chỉ cần quyền dùng của trợ lý đó.
Dữ liệu của tôi có an toàn 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 gồm đối số, đường dẫn, nội dung hay thông tin cá nhân. Bạn có thể tắt bằng lệnh openspec config set telemetry.enabled false hoặc biến môi trường OPENSPEC_TELEMETRY=0 hay DO_NOT_TRACK=1. Cách trợ lý AI của bạn xử lý dữ liệu thì nằm ngoài tư liệu này.
OpenSpec khác gì Spec Kit hay Kiro?
Theo README, Spec Kit của GitHub thì kỹ lưỡng nhưng nặng, có các cổng giai đoạn cứng, nhiều Markdown và cần cài Python. Kiro của AWS thì bạn phải dùng IDE của họ và bị giới hạn ở các mô hình Claude. OpenSpec nhẹ hơn, cho sửa tự do và chạy với công cụ bạn đã có.
Công cụ AI của tôi có được hỗ trợ không?
README ghi OpenSpec hỗ trợ hơn 30 công cụ và đang tăng. Danh sách đầy đủ nằm ở trang Supported Tools trên openspec.dev. Sau khi chạy openspec init, công cụ sẽ in ra đúng cách gọi lệnh cho các công cụ bạn chọn.


