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

OpenSpec: chốt yêu cầu 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

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 →

OpenSpec: chốt yêu cầu 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) thêm lớp đặc tả nhẹ cho các trợ lý AI viết code: bạn và AI chốt kế hoạch bằng file Markdown rồi mới viết code. Cài bằng một dòng lệnh hoặc npm (cần Node.js 22.12 trở lên), sau đó chạy openspec init trong dự án. Cài đặt không khó, nhưng bạn cần đã có sẵn một công cụ AI viết code như Claude Code hay Codex.

OpenSpec là một công cụ dòng lệnh giúp bạn và trợ lý AI viết code thống nhất với nhau về việc cần làm, bằng các file đặc tả (spec) viết dưới dạng Markdown, trước khi có bất kỳ dòng code nào được tạo ra. Tác giả mô tả nó là «spec-driven development» (phát triển dựa trên đặc tả) dành cho các trợ lý AI viết code. Repo viết bằng TypeScript, dùng giấy phép MIT, hiện có khoảng 74.700 sao và 5.100 fork.

Vấn đề nó giải quyết rất quen thuộc: bạn bảo AI «thêm chế độ tối cho app», nó làm một đằng, bạn muốn một nẻo, rồi hai bên cãi nhau trong khung chat. Yêu cầu nằm lẫn trong lịch sử trò chuyện nên rất dễ lệch. OpenSpec bắt đầu bằng việc để AI viết ra kế hoạch thành file, bạn đọc và chỉnh, đồng ý rồi mới cho AI làm.

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 dùng AI để viết code và muốn kết quả bớt «trúng mánh». Điểm đáng giá nhất theo README: nó nhẹ, không có các cổng chặn cứng theo từng giai đoạn, 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 quen thuộc.

CLI

Fission-AI/OpenSpec

OpenSpec là công cụ dòng lệnh giúp bạn và trợ lý AI viết code thống nhất bản đặc tả (spec) bằng Markdown trước khi bắt tay làm, hỗ trợ hơn 30 công cụ AI.

★ 75kTypeScriptMIT
Xem repo trên GitHub

I.OpenSpec làm được gì

A.Mỗi thay đổi có một thư mục riêng

Khi bạn yêu cầu một tính năng mới, OpenSpec tạo thư mục riêng cho thay đổi đó 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ề mặt kỹ thuật) và tasks.md (danh sách việc cần làm). Lợi ích thực tế: bạn mở một thư mục là hiểu toàn bộ một tính năng, không phải lật lại cuộc chat dài.

B.Đặc tả viết bằng Markdown thường

Không có cú pháp lạ phải học. Yêu cầu được viết thành câu bình thường kèm các kịch bản cụ thể theo dạng WHEN (khi) và THEN (thì). AI là bên viết, còn bạn là bên đọc duyệt kế hoạch trước khi code được tạo ra. Người không rành lập trình vẫn đọc hiểu được.

C.Các lệnh slash để đi từng bước

Bản mặc định có bốn kỹ năng (skill) chính:

  • /openspec-explore: «người bạn suy nghĩ» không áp lực. AI đọc code của bạn, cân nhắc các hướng, giúp định hình kế hoạch.
  • /openspec-propose: tạo luôn đề xuất cùng spec, thiết kế và danh sách việc.
  • /openspec-apply-change: AI làm theo danh sách việc.
  • /openspec-archive-change: lưu trữ thay đổi đã xong và cập nhật spec.

Ngoài ra có hồ sơ mở rộng với thêm openspec-new-change, openspec-continue-change, openspec-ff-change, openspec-verify-change, openspec-bulk-archive-change và openspec-onboard.

D.Làm linh hoạt, hợp cả dự án đã có sẵn

Triết lý của dự án: 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à xây cho cả dự án đã có sẵn code (brownfield) chứ không chỉ dự án làm mới từ đầu. Bạn có thể sửa bất kỳ tài liệu nào bất cứ lúc nào.

E.Stores: lập kế hoạch ở một repo riêng (beta)

Với nhóm làm việc, một tính năng có thể trải qua nhiều repo (máy chủ API, ứng dụng web, thư viện dùng chung). «Stores» cho phép đặt kế hoạch trong một repo riêng, chia sẻ bằng git push như bình thường. README ghi rõ tính năng này đang ở bản beta. Nếu bạn làm một mình, có thể bỏ qua phần này.

II.Cần chuẩn bị gì

  • Node.js 22.12.0 trở lên nếu bạn cài bằng npm (package.json yêu cầu >=22.12.0).
  • Một terminal: macOS hoặc Linux dùng terminal thường, Windows dùng PowerShell. README có lệnh cài riêng cho cả hai.
  • Một công cụ AI viết code đã được hỗ trợ. README nói hỗ trợ hơn 30 công cụ, danh sách đầy đủ nằm ở trang Supported Tools của openspec.dev. Mình chưa có thông tin chi tiết hơn về từng công cụ ngoài việc Codex dùng cú pháp $openspec-propose, các công cụ khác thường dùng /openspec-propose.
  • Một thư mục dự án để chạy openspec init.
  • Mô hình AI mạnh về suy luận: README khuyến nghị Codex 5.5 và Opus 4.7 cho cả lập kế hoạch lẫn viết code.

README không nhắc tới tài khoản riêng hay API key của OpenSpec. Chi phí dùng AI phụ thuộc vào công cụ AI bạn đang dùng.

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

  1. Cài OpenSpecChạy một dòng lệnh phù hợp hệ điều hành, hoặc dùng npm / Homebrew
  2. Mở thư mục dự áncd vào dự án bạn muốn dùng AI viết code
  3. Khởi tạoChạy openspec init và chọn công cụ AI bạn dùng
  4. Bắt đầu với AIGõ /openspec-explore hoặc /openspec-propose trong công cụ AI

A.Bước 1: Cài OpenSpec

Chọn một trong các cách dưới đây, đừng chạy hết cả ba.

Trên macOS hoặc Linux, mở terminal rồi chạy:

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

Lệnh này tải script cài đặt từ trang của dự án và chạy luôn. Nếu bạn không thoải mái với kiểu «tải về rồi chạy ngay», hãy chọn cách npm hoặc Homebrew bên dưới.

Trên Windows, mở PowerShell rồi chạy:

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

Nếu thích dùng trình quản lý gói, README cho hai lựa chọn. Với npm (cần Node.js 22.12.0 trở lên):

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

Hoặc với Homebrew:

Terminal
brew install openspec

README cũng nói công cụ chạy được với pnpm, yarn, bun và Nix, chi tiết xem ở trang installation của openspec.dev.

Các lệnh dạng «tải script rồi chạy» (curl ... | sh, irm ... | iex) sẽ chạy mã từ internet trên máy bạn. Chỉ dùng khi bạn tin nguồn, hoặc chọn npm/Homebrew nếu muốn kiểm soát hơn.

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

Bạn phải đứng trong thư mục của dự án thì OpenSpec mới tạo đúng chỗ. Ví dụ:

Terminal
cd your-project

Hãy thay your-project bằng tên thư mục thật của bạn. Người mới hay vấp ở đây: mở terminal xong nhưng vẫn đang ở thư mục khác, nên file bị tạo sai chỗ.

C.Bước 3: Khởi tạo

Terminal
openspec init

Lệnh này thiết lập OpenSpec cho dự án và cài các skill cho công cụ AI bạn chọn. Sau khi chạy xong, nó in ra đúng cú pháp lệnh cho từng công cụ bạn đã chọn (ví dụ /openspec-propose hay $openspec-propose). Hãy đọc kỹ phần in ra này.

Nếu muốn nhờ chính AI làm giúp, README có nói bạn có thể dán «setup prompt» (có ở trang installation của openspec.dev) vào trợ lý AI. Nó sẽ cài CLI, chạy openspec init và kiểm tra kết quả.

D.Bước 4: Nói chuyện với AI

Mở công cụ AI trong dự án đó, rồi chọn một trong hai hướng:

  • Chưa biết nên làm gì: gõ /openspec-explore.
  • Đã biết mình muốn gì: gõ /openspec-propose <điều bạn muốn làm>.

Nếu muốn dùng bộ lệnh mở rộng, chọn hồ sơ bằng lệnh sau, rồi áp dụng:

Terminal
openspec config profile
openspec update

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

README không đưa ra một lệnh kiểm tra riêng, nhưng có vài dấu hiệu rõ ràng:

  1. Sau openspec init, terminal in ra cú pháp lệnh cho các công cụ bạn đã chọn.
  2. Trong dự án xuất hiện thư mục openspec/.
  3. Trong công cụ AI, gõ /openspec-explore (hoặc $openspec-explore với Codex) thì AI phản hồi bằng câu hỏi kiểu «Bạn muốn khám phá điều gì?».
  4. Khi chạy /openspec-propose tên-thay-đổi, AI tạo thư mục openspec/changes/tên-thay-đổi/ với các file proposal.md, specs/, design.md, tasks.md.

Nếu thấy đủ các dấu hiệu trên là bạn cài thành công.

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

Các tình huống dưới đây bám theo quy trình README mô tả. Câu lệnh ví dụ lấy từ README hoặc là cách gọi lại theo cùng mẫu.

A.Chủ shop muốn thêm chế độ tối cho website

Bạn có một website bán hàng nhỏ do một lập trình viên làm hoặc do AI viết, và muốn thêm chế độ tối nhưng chưa biết làm gọn thế nào. Hãy bắt đầu bằng khám phá:

text
/openspec-explore
I want dark mode but I'm not sure how to do it cleanly.

AI đọc cách trang đang được tạo kiểu, rồi đề xuất hướng gọn nhất (ví dụ trong README: biến CSS cộng một bộ quản lý giao diện nhỏ, có nhận diện cài đặt hệ thống, không thêm thư viện mới). Khi đồng ý, bạn chuyển sang:

text
/openspec-propose add-dark-mode

Bạn nhận được thư mục thay đổi với đủ bốn thành phần để đọc duyệt trước khi AI viết code.

Bạn đọc kế hoạch một lần, rẻ hơn nhiều so với sửa code sai năm lần.

Ông T

B.Nhân viên văn phòng duyệt yêu cầu trước khi dev làm

Bạn là người làm sản phẩm, không viết code nhưng cần chắc rằng tính năng đúng ý. Sau khi AI tạo specs/, bạn chỉ cần mở file Markdown và đọc các yêu cầu cùng kịch bản. Ví dụ README cho thấy yêu cầu «Theme selection» kèm kịch bản: 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. Nếu thiếu trường hợp nào, bạn bảo AI sửa spec ngay, lúc này chưa tốn công viết code.

C.Lập trình viên làm tính năng trên dự án có sẵn

Bạn đã có một dự án chạy được và muốn thêm tính năng mà không phá phần cũ. Quy trình gọn nhất là đi trọn vòng:

text
/openspec-propose <tính-năng-bạn-muốn>
/openspec-apply-change
/openspec-archive-change

Bước thứ hai AI làm lần lượt theo danh sách việc trong tasks.md và đánh dấu từng việc đã xong. Bước thứ ba lưu thay đổi vào thư mục lưu trữ và cập nhật spec, 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 triển khai, để AI làm việc trên nền sạch.

D.Nhóm làm nhiều repo cùng lúc

Khi một tính năng đụng tới máy chủ API, app web và một thư viện dùng chung, bạn có thể thử tính năng Stores (đang beta): đặt kế hoạch ở một repo riêng, mọi người và mọi trợ lý AI cùng đọc một nguồn. README mô tả lợi ích là một thay đổi, một kế hoạch, dù code nằm ở ba repo. Mình chưa có thông tin về các lệnh cụ thể, hãy xem hướng dẫn Stores trên openspec.dev.

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

A.Cài bằng npm báo lỗi hoặc cảnh báo phiên bản

Gói yêu cầu Node.js 22.12.0 trở lên. Nếu máy bạn dùng Node cũ hơn, hãy nâng cấp Node rồi cài lại. Hoặc dùng cách cài bằng script / Homebrew mà README đưa ra, các cách đó không đòi bạn cài Node theo cách của npm.

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

Thường do terminal cũ chưa nhận lệnh mới. Hãy đóng terminal, mở lại rồi thử lại. Nếu vẫn lỗi, chạy lại bước cài đặt và đọc kỹ thông báo cuối cùng nó in ra. README chưa ghi riêng mục xử lý lỗi này, nên hãy xem trang installation của openspec.dev.

C.Gõ /openspec-... mà AI không hiểu

Có hai nguyên nhân dễ gặp. Một là cú pháp khác nhau theo công cụ: Codex dùng $openspec-propose, hầu hết công cụ khác dùng /openspec-propose; lệnh openspec init đã in ra đúng dạng cho công cụ bạn chọn. Hai là chưa nạp skill: hãy chạy lệnh dưới đây trong dự án để làm mới hướng dẫn cho AI, rồi mở lại phiên làm việc mới.

Terminal
openspec update

Bạn cũng có thể nói thẳng bằng lời thường, vì README cho biết có thể yêu cầu công việc bằng ngôn ngữ tự nhiên.

D.Kế hoạch AI viết ra mơ hồ, code làm ra lệch

README lưu ý OpenSpec chạy tốt nhất với mô hình có khả năng suy luận cao, và nên giữ ngữ cảnh sạch. Hãy đổi sang mô hình mạnh hơn, mở phiên mới trước khi cho AI triển khai, và bổ sung kịch bản cụ thể vào specs/ trước khi chạy /openspec-apply-change.

E.Không muốn gửi số liệu sử dụng ẩn danh

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, và tự tắt khi chạy trong CI. Muốn tắt, README cho hai cách (chỉ cần một):

Terminal
openspec config set telemetry.enabled false
Terminal
export OPENSPEC_TELEMETRY=0

Biến DO_NOT_TRACK=1 cũng có tác dụng tương tự. Lệnh export dùng cho macOS/Linux, README chưa ghi cách tương đương cho Windows.

VII.Có nên dùng không

Điểm mạnh. OpenSpec nhẹ và dễ đọc: toàn bộ kế hoạch là file Markdown thường, bạn xem và sửa được bằng bất kỳ trình soạn thảo nào. Nó không khoá bạn vào một trình soạn thảo riêng, chạy với hơn 30 công cụ AI, cho phép sửa tài liệu bất cứ lúc nào, và hợp cả dự án đã có sẵn code. Chính dự án cũng được xây bằng OpenSpec, nên bạn có thể xem các spec thật trong repo làm ví dụ. Giấy phép MIT, dự án vẫn được cập nhật trong vài tháng gần đây.

Giới hạn. Công cụ này không thay thế công cụ AI: bạn vẫn cần một trợ lý viết code. Chất lượng kế hoạch phụ thuộc nhiều vào mô hình AI bạn dùng. Với một việc rất nhỏ (sửa một dòng chữ, đổi màu một nút), dựng cả đề xuất, spec và danh sách việc có thể là thừa. Tính năng Stores còn ở bản beta. Ngoài ra OpenSpec có thu thập số liệu ẩn danh theo mặc định, dù tắt được.

Khi nào chọn cách khác. README so sánh với Spec Kit của GitHub (kỹ hơn nhưng nặng, nhiều cổng chặn theo giai đoạn, cần cài Python) và Kiro của AWS (mạnh nhưng gắn với IDE riêng và giới hạn ở mô hình Claude). Nếu bạn cần quy trình thật chặt chẽ theo từng giai đoạn, hãy cân nhắc các công cụ đó. Còn nếu bạn muốn một lớp đặc tả gọn, đi cùng công cụ AI đang dùng, OpenSpec là lựa chọn đáng thử trước.

3.9/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 mã nguồn mở và dùng tự do. README không nhắc tới phí của OpenSpec. Tuy vậy bạn vẫn phải trả chi phí cho công cụ hoặc mô hình AI mà bạn dùng cùng nó, tuỳ gói của từng công cụ.

OpenSpec chạy được trên Windows không?

Được. README có lệnh cài riêng cho Windows bằng PowerShell: irm https://openspec.dev/cli/install.ps1 | iex. Ngoài ra bạn có thể cài bằng npm nếu có Node.js 22.12.0 trở lên.

Có cần GPU hay máy cấu hình mạnh không?

README không nêu yêu cầu phần cứng nào. OpenSpec là công cụ dòng lệnh và các file Markdown, phần tính toán nặng do trợ lý AI bạn dùng đảm nhiệm. Chi tiết thêm mình chưa có thông tin.

OpenSpec khác gì Spec Kit hoặc Kiro?

Theo README, Spec Kit của GitHub kỹ nhưng nặng, nhiều cổng chặn theo giai đoạn, cần cài 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, cho sửa tài liệu tự do và chạy với các công cụ bạn đã dùng.

OpenSpec hỗ trợ những công cụ AI nào?

README nói 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. Lệnh openspec init sẽ in ra cú pháp phù hợp cho các công cụ bạn chọn, ví dụ Codex dùng $openspec-propose còn đa số công cụ khác dùng /openspec-propose.

Dữ liệu và code của tôi có bị gửi đi đâu không?

README nói OpenSpec chỉ thu thập thống kê ẩn danh 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 biến OPENSPEC_TELEMETRY=0 hay DO_NOT_TRACK=1. Còn dữ liệu bạn gửi cho trợ lý AI thì tuỳ chính sách của công cụ đó.

Nên dùng mô hình AI nào với OpenSpec?

README khuyên dùng mô hình có khả năng suy luận cao, cụ thể là Codex 5.5 và Opus 4.7 cho cả lập kế hoạch lẫn triển khai. Nó cũng khuyên giữ ngữ cảnh sạch, tức là xoá ngữ cảnh trước khi bắt đầu phần triển khai.

Chuyển nhanh tới mục

  1. I.OpenSpec làm được gì
    1. A.Mỗi thay đổi có một thư mục riêng
    2. B.Đặc tả viết bằng Markdown thường
    3. C.Các lệnh slash để đi từng bước
    4. D.Làm linh hoạt, hợp cả dự án đã có sẵn
    5. E.Stores: lập kế hoạch ở một repo riêng (beta)
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Bước 1: Cài OpenSpec
    2. B.Bước 2: Vào thư mục dự án
    3. C.Bước 3: Khởi tạo
    4. D.Bước 4: Nói chuyện với AI
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Chủ shop muốn thêm chế độ tối cho website
    2. B.Nhân viên văn phòng duyệt yêu cầu trước khi dev làm
    3. C.Lập trình viên làm tính năng trên dự án có sẵn
    4. D.Nhóm làm nhiều repo cùng lúc
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Cài bằng npm báo lỗi hoặc cảnh báo phiên bản
    2. B.Gõ openspec báo không tìm thấy lệnh
    3. C.Gõ /openspec-... mà AI không hiểu
    4. D.Kế hoạch AI viết ra mơ hồ, code làm ra lệch
    5. E.Không muốn gửi số liệu sử dụng ẩn danh
  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ỏ.