Bỏ qua tới nội dung
Ông T.vn

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

11 phút đọcCập nhật
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.

CLI

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.

★ 75kTypeScriptMIT
Xem repo trên GitHub

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.json và 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

  1. Cài OpenSpecChạy một dòng lệnh cài đặt phù hợp hệ điều hành
  2. Vào thư mục dự ánMở terminal ngay tại dự án bạn muốn dùng
  3. Khởi tạoChạy openspec init và chọn công cụ AI của bạn
  4. Gọi lệnh trong AIDùng /openspec-explore hoặc /openspec-propose
  5. 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:

Terminal
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

Nế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):

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

Hoặc dùng Homebrew:

Terminal
brew install openspec

Ngườ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:

Terminal
cd your-project
openspec init

cd 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:

Terminal
openspec config profile
openspec update

E.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:

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

Nếu cài bằng Homebrew:

Terminal
brew upgrade openspec

Sau đó, 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:

Terminal
openspec update

IV.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 init chạ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-explore vớ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ục openspec/changes/add-dark-mode/ với proposal.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õ:

text
/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õ:

text
/openspec-propose add-dark-mode

AI 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.

4.3/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

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.

Chuyển nhanh tới mục

  1. I.OpenSpec làm được gì
    1. A.Mỗi thay đổi một thư mục riêng
    2. B.Đặc tả là Markdown thường
    3. C.Khám phá trước khi quyết định
    4. D.Quy trình ngắn gọn mặc định
    5. E.Chạy với hơn 30 công cụ AI
    6. F.Stores cho làm việc nhóm (beta)
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Cài OpenSpec
    2. B.Vào thư mục dự án và khởi tạo
    3. C.Gọi lệnh trong trợ lý AI
    4. D.Muốn dùng quy trình mở rộng
    5. E.Cập nhật về sau
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Thêm chế độ tối cho website nhưng chưa biết làm sao
    2. B.Biến ý tưởng thành gói kế hoạch đủ bộ
    3. C.Cho AI làm theo danh sách việc và lưu lại
    4. D.Lập kế hoạch cho tính năng trải qua nhiều repo
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Gõ lệnh gạch chéo mà AI không phản hồi
    2. B.Báo thiếu hoặc sai phiên bản Node khi cài bằng npm
    3. C.Lệnh openspec không được nhận sau khi cài
    4. D.Kết quả AI lộn xộn hoặc lệch kế hoạch
    5. E.Kỹ năng không còn mới sau khi nâng cấp
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.